体验通知

体验通知是为选择加入的 13岁及以上用户提供的一种方式，使他们通过及时、个性化的通知保持与他们最喜欢的游戏的联系。作为开发者，您可以确定哪些游戏内活动最重要需要通知您的用户，以及定义通知内容。

体验通知系统具有以下特点：

• 可定制的通知参数 — 完全灵活性，可以根据参数定制 通知消息，例如：

  您的金蛋已经孵化了！

  Allie @LaterSk8er1 刚刚打破了您在东京巡回赛曲目的记录！

• 启动数据 — 包括可选的 启动数据，收件人在加入时可以通过 Player:GetJoinData() 读取。这可能涉及将用户引导到某个坐标位置或个性化他们的加入体验。

• 分析支持 — 在 创作者仪表板 中跟踪您可达的受众及您通知的表现。

资格要求

为了使用 API 发送通知，游戏必须满足以下基本条件：

• 自发布以来至少有 100 次访问。
• 游戏不能处于审核中。
• 作为开发者的你必须拥有管理游戏的权限。

使用指南

实现

实现体验通知的第一步是 创建通知字符串 并在您的项目中包含 包。一旦这些设置完成，您可以使用可选的 自定义参数 发送通知。

或者，您可以使用 开放云 API 通过自由表单 API 请求触发通知。

创建通知字符串

与 玩家邀请提示 一样，您必须在 创作者仪表板 中创建和编辑您的通知字符串。没有默认的游戏通知字符串，因此此步骤是必需的。

1. 导航到 创作者仪表板。

2. 与 徽章 类似，通知字符串与 特定游戏 相关联。找到该游戏的缩略图并单击它。

3. 在左列中，在 互动 下，点击 通知。

4. 在中心区域，点击 创建通知字符串 按钮。

5. 填写一个标识符名称（仅对您可见）和自定义通知字符串；此字符串限制为 99 个字符，并可以包含无限制的自定义参数。通知将自动使用您的游戏标题作为通知标题，但您可以额外使用 {experienceName} 引用您在通知正文文本中的游戏。

   示例通知字符串：

   您还有 {numQuests} 个任务就可以完成每周挑战！

   您的 {eggName} 孵化了！快来见见您的新宠物。

   您本周赢得了 {numRaces} 场比赛并解锁了 {racetrackName} 赛道！

   {userId-friend} 刚刚打破了您在东京巡回赛赛道上的记录！该是报仇的时候了吗？

   在编写通知字符串之前，请查看使用系统的 指南。

6. 准备好后，点击 创建通知字符串 按钮。

7. 在通知页面的通知表中，点击 ⋯ 按钮在 动作 列中，并选择 复制资产 ID。

8. 使用复制的 ID 作为 payload 表中 messageId 键的值，如示例脚本中所示。

包包含

要实现体验通知，您必须从 创作者商店 获取 Luau 包。

1. 从 Studio 的 窗口 菜单或 首页 标签工具栏中，打开 工具箱，并选择 创作者商店 标签。

   

2. 确保选择了 模型 排序，然后点击 查看全部 按钮以获取 类别。

   

3. 找到并点击 包 瓦片。

4. 找到 开放云 模块并点击它，或将其拖放到 3D 视图中。

   

5. 在 资源管理器 窗口中，将整个 OpenCloud 模型移到 ServerScriptService 中。

发送体验通知

一旦您 创建了通知字符串 并在项目中包含了 包，您就可以从服务器端脚本发送通知。通知将通过 Roblox 通知流发送给年龄在 13 岁及以上的 已选择加入 用户，此时他们可以通过通知上的 加入 按钮直接加入体验，并根据您的 启动数据 生成。

要向特定用户发送基本通知，请在有效负载的 messageId 字段中包括 通知字符串 资产 ID，然后调用 createUserNotification 函数，传入收件人的 Player.UserId 和请求数据。

local ServerScriptService = game:GetService("ServerScriptService")

local OCUserNotification = require(ServerScriptService.OpenCloud.V2.UserNotification)
local recipientPlayerID = 505306092

-- 在有效负载中，“messageId”是通知资产 ID 的值
local userNotification = {
	payload = {
		messageId = "5dd7024b-68e3-ac4d-8232-4217f86ca244",
		type = "MOMENT"
	}
}

local result = OCUserNotification.createUserNotification(recipientPlayerID, userNotification)

if result.statusCode ~= 200 then
	print(result.statusCode)
	print(result.error.code)
	print(result.error.message)
end

使用参数自定义通知

要为每个收件人自定义通知，您可以在 通知字符串 中包含 参数，然后在调用 API 时自定义这些参数。例如，您可以将通知字符串定义为：

然后，在脚本中设置 userId-friend 和 points 参数：

local ServerScriptService = game:GetService("ServerScriptService")

local OCUserNotification = require(ServerScriptService.OpenCloud.V2.UserNotification)
local recipientPlayerID = 505306092

local userIdFriendParam = {int64Value = 3702832553}
local pointsParam = {stringValue = "5"}

-- 在有效负载中，“messageId”是通知资产 ID 的值
-- 在这个例子中，通知字符串是 "{userId-friend} 超过了您的高分 {points} 分！该升级了？"
local userNotification = {
	payload = {
		messageId = "ef0e0790-e2e8-4441-9a32-93f3a5783bf1",
		type = "MOMENT",
		parameters = {
			["userId-friend"] = userIdFriendParam,
			["points"] = pointsParam
		}
	}
}

local result = OCUserNotification.createUserNotification(recipientPlayerID, userNotification)

if result.statusCode ~= 200 then
	print(result.statusCode)
	print(result.error.code)
	print(result.error.message)
end

提示用户启用通知

为了鼓励用户为您的体验启用通知，您可以使用 ExperienceNotificationService:PromptOptIn() 方法向年满 13 岁的用户显示一个体验内的权限提示。

您可以在您的体验中触发提示，以适当的上下文作为未来通知的理由。提示的文本是不可定制的，并在所有体验中标准化。

如果用户：

• 不满 13 岁。
• 已经为您的体验启用通知。
• 在过去 30 天内已看到您体验的权限提示。

则 不会 显示此模态框。

要提示用户启用通知，您应首先确定用户是否符合资格。一旦确认，您可以向用户显示权限提示。

1. 调用 ExperienceNotificationService:CanPromptOptInAsync()，将其包装在 pcall() 中，因为这是一个可能偶尔失败的异步网络调用。
2. 如果用户可以被提示，则调用 ExperienceNotificationService:PromptOptIn()。

local ExperienceNotificationService = game:GetService("ExperienceNotificationService")

-- 检查玩家是否可以被提示启用通知的函数
local function canPromptOptIn()
	local success, canPrompt = pcall(function()
		return ExperienceNotificationService:CanPromptOptInAsync()
	end)
	return success and canPrompt
end

local canPrompt = canPromptOptIn()
if canPrompt then
	local success, errorMessage = pcall(function()
		ExperienceNotificationService:PromptOptIn()
	end)
end

-- 监听选择加入提示关闭事件
ExperienceNotificationService.OptInPromptClosed:Connect(function()
	print("选择加入提示已关闭")
end)

包括启动和分析数据

为了进一步改善用户体验，您可以在通知中包含 启动数据，这对于将用户引导到坐标位置或个性化加入体验等场景非常有用。此外，您可以包括 分析 数据，以分隔不同类别通知的性能。请参考 玩家邀请提示 示例，了解如何设置和使用启动数据。

local ServerScriptService = game:GetService("ServerScriptService")

local OCUserNotification = require(ServerScriptService.OpenCloud.V2.UserNotification)
local recipientPlayerID = 505306092

-- 在有效负载中，“messageId”是通知资产 ID 的值
local userNotification = {
	payload = {
		messageId = "5dd7024b-68e3-ac4d-8232-4217f86ca244",
		type = "MOMENT",
		joinExperience = {
			launchData = "测试_启动_数据"
		},
		analyticsData = {
			category = "测试_分析_类别"
		}
	}
}

local result = OCUserNotification.createUserNotification(recipientPlayerID, userNotification)

if result.statusCode ~= 200 then
	print(result.statusCode)
	print(result.error.code)
	print(result.error.message)
end

交付系统

存在一个防止垃圾邮件的系统，以确保用户通知的质量并保护所有开发者共享的通知渠道。因此，通知的送达不能得到保证。该防止垃圾邮件的系统直接受到用户参与度的影响：用户与你的通知互动越多，他们的覆盖范围就越大。你可以在分析仪表盘中透明地跟踪参与度指标，具体如下所述。

体验通知有一个静态的限制；每个用户每天可以从特定体验接收一次通知，当用户的限制达到时，你将收到透明的反馈。

此外，以下列表列出了可能导致通知未送达的一些特殊情况：

• 未满足体验资格要求。
• 接收者未选择接收来自你体验的通知。
• 接收者的体验限制已达到。
• 接收者的每日总限制已达到。
• 请求参数缺失或无效。
• 通知字符串已被审核。
• 对于包含用户提及的通知，如果满足以下任一条件，则会发生未送达：

  • 接收者和被提及的用户不是朋友。
  • 被提及的用户在其 Roblox 账户设置的隐私 → 其他设置 下对“更新朋友我的活动？”选择了否。

分析

Performance of your notifications and notifiable audience are displayed in the Analytics tab of the Notifications page where you configure notification strings (simply tab from Creations to Analytics).

1. Navigate to the Creator Dashboard.
2. Similar to badges, notification strings are tied to a specific game. Locate that game's thumbnail and click on it.
3. In the left column, under Engagement, click Notifications.
4. On the target page, click the Analytics tab to switch to the analytics dashboard.

通知摘要

摘要部分作为您通知的聚合性能快照。显示性能统计数据需要至少 100 次聚合展示。

项目统计

The Experience Notifications table displays detailed performance statistics for each notification with at least 100 impressions, ordered by the date of first impression for that notification.

The Name column is the key identifier for the notification. By default, the name matches the identifier name you specified when creating the notification string, but you can override it through the category field in your API calls, in which case category overrides the name. Changing the string name in the Creator Dashboard or changing the string your message ID references in the API call will generate a new row in the table.

If you'd like to A/B test the performance of different strings, it's recommended that you create an entirely new notification string with a similar name, for example:

• EggHatchA — "您的金蛋已经孵化！来见见您的新宠物。"
• EggHatchB — "孵化时间到了！来见见您的新宠物。"

API 参考

函数

createUserNotification

从服务器端脚本发送通知。需要收件人的 Player.UserId 和一个 UserNotification。返回一个 UserNotificationResult。

local ServerScriptService = game:GetService("ServerScriptService")

local OCUserNotification = require(ServerScriptService.OpenCloud.V2.UserNotification)
local recipientPlayerID = 505306092

-- 在有效负载中，“messageId”是通知资产 ID 的值
local userNotification = {
	payload = {
		messageId = "5dd7024b-68e3-ac4d-8232-4217f86ca244",
		type = "MOMENT"
	}
}

local result = OCUserNotification.createUserNotification(recipientPlayerID, userNotification)

if result.statusCode ~= 200 then
	print(result.statusCode)
	print(result.error.code)
	print(result.error.message)
end

类型

UserNotification

包含要发送给用户的通知的详细信息的表。必须包含一个具有必需的 messageId 和 type 字符串的 payload 表，以及可选的 parameters、joinExperience 和 analyticsData 表。

UserNotificationResult

一个包装对象，持有发送通知的响应。包含以下键值对：