经验通知

经验通知 是一种方式让 已选择 年龄在 13 岁以上的用户通过及时、个性化的通知跟上他们最喜欢的体验。作为开发者，您可以确定通知用户最重要的体验活动类型，以及定义通知内容。

体验通知系统具有以关注中/正在关注功能：

• 可定制的参数通知 — 具有完全灵活性来定制 通知消息 的参数,例如：

  Your gold goose egg has hatched!

  Allie @LaterSk8er1 just beat your record on the Tokyo Tour track!

• 发射数据 — 包括可选的 发射数据，可以在通知接收者加入时通过 Player:GetJoinData() 阅读。这可能涉及将用户路由到坐标位置或个性化他们的加入体验。

• 分析支持 — 在 创建者仪表板 中跟踪您可到达的受众和您的通知的性能。

资格要求

为了使用 API 发送通知，体验必须满足以下基本要求：

• 发启动后至少有 100 次访问。
• 体验不得受到审核。
• 作为开发者，你必须拥有管理体验的权限。

使用指南

实现

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

或者，您可以使用 打开云 API 来通过免费形式的 API 请求触发通知。

创建通知字符串

与 玩家邀请提示 类似，您必须在 创建者面板 中创建和编辑通知字符串。 没有默认体验通知字符串，因此需要这一步。

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

2. 与徽章类似，通知字符串绑定到一个 特定体验 。找到该体验的缩略图并单击它。

3. 在左栏中，在 参与 下，单击 通知 。

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

5. 填写一个识别名称（仅向您可见）和自定义通知字符串；这限于 99 个字符，可以包含无限的 自定义参数 。通知将自动使用您的体验标题作为通知标题，但您可以额外使用 experienceName 来在通知体文本中引用您的体验。

   示例通知字符串：

   You're {numQuests} quests away from completing the weekly challenge!

   Your {eggName} hatched! Come meet your new pet.

   You won {numRaces} races this week and unlocked the {racetrackName} track!

   {userId-friend} just beat your record on the Tokyo Tour track! Time for revenge?

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

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

7. 在通知页面上，在通知表中，单击 ⋯ 按钮在 行动 栏中，然后选择 复制资产ID 。

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

包括包裹

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

1. 从视图选项卡打开工具箱并选择 创建者商店 选项卡。

   

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

   

3. 找到并单击 开发模块 瓦片。

   

4. 找到 打开云 模块并单击它，或拖放到 3D 视查看中。

   

5. 在 浏览器 窗口中，将整个 OpenCloud 模型移至 ServerScriptService 。

   

发送体验通知

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

要向特定用户发送基本通知，请在 payload 的 字段中包含 messageId 资产 ID，然后调用 createUserNotification 函数与接收收件人的 Player.UserId 和请求数据。

发送体验通知
local ServerScriptService = game:GetService("ServerScriptService")

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

-- 在 payload 中，"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"}

-- 在 payload 中，"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 岁以上的用户经验权限提示。

您可以在体验中的任何适当的上下文中触发提示，以便将来收到通知。提示的文本不可自定义，且在所有体验中都标准化。

如果用户： The modal will 不 出现，如果：

• 年龄在 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("Opt-in prompt closed")
end)

包括发射和分析数据

为了进一步提高用户体验，您可以在通知中包含 启动数据 ，用于场景，例如将用户路由到坐标位置或个性化加入体验。此外，您可以包含 分析 数据来分割不同类别通知的性能。请还参阅玩家邀请提示例，了解如何设置和使用启动数据。

包括发射数据和分析数据
local ServerScriptService = game:GetService("ServerScriptService")

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

-- 在 payload 中，"messageId" 是通知资产 ID 的值
local userNotification = {
	payload = {
		messageId = "5dd7024b-68e3-ac4d-8232-4217f86ca244",
		type = "MOMENT",
		joinExperience = {
			launchData = "Test_Launch_Data"
		},
		analyticsData = {
			category = "Test_Analytics_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 帐户设置的“更新朋友关于我的活1) 活动 2)动态(as in friend activity)？”下没有选择否，在其隐私设置下没有选择其他设置。

分析

您在 分析 选项卡的 通知页 中配置通知字符串时（只需从 创建 到 分析 ）显示您的通知和可接收受众的性能（请参阅文档“ 通知页 ”）。

1. 导航到 创建者仪表板。
2. 与徽章类似，通知字符串绑定到一个 特定体验 。找到该体验的缩略图并单击它。
3. 在左栏中，在 参与 下，单击 通知 。
4. 在目标页面上，单击 分析 选项卡切换到分析仪表板。

通知摘概括

摘要部分用作您通知的总体性能的快照。需要至少 100 个聚合印象来显示性能统数据。

分项统计数据

体验通知表显示每个通知的详细性能统计数据，至少有 100 次印象，按照该通知的第一次印象的日期排序。

名称 列 是通知的关键识别器。默认情况下，名称与您在 创建通知字符串 时指定的识别名称匹配，但您可以通过 API 调用中的 category 字段覆盖名称，在此情况下 category 将覆盖名称。在 创建者仪表板 更改字符串名称或在 API 调用中更改您的消息ID参考字符串将生成新的行在表中。

如果您想要 A/B 测试不同字符串的性能，建议您创建一个与类似名称的全新通知字符串，例如：

• 蛋孵化者 — “你的黄金蛋孵出来了！来见你的新宠物吧。”
• EggHatchB — “是时候孵化了！来见你的新宠物吧。”

API 参考

功能

创建用户通知

从服务器端脚本发送通知。需要接收收件人的 Player.UserId 和一个 用户通知。返回一个 用户通知结果。

发送体验通知
local ServerScriptService = game:GetService("ServerScriptService")

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

-- 在 payload 中，"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

类型

用户通知

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

用户通知结果

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