體驗通知

體驗通知是讓已選擇加入的年齡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. 在 payload 表中使用複製的 ID 作為 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 = "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

傳遞系統

A spam prevention system exists to ensure the quality of notifications for users and protect the shared notification channel for all developers. Because of this, delivery of notifications is not guaranteed. This spam prevention system is directly informed by user engagement: the more users engage with your notifications, the more reach they'll receive. You can transparently track engagement metrics in the analytics dashboard, as explained below.

Experience notifications have a static throttle limit; each user can receive one notification per day from a given experience, and you receive transparent feedback when a user's throttle limit is reached.

Additionally, the following list outlines some of the special cases which may result in non‑delivery of a notification:

• Experience 資格要求 are not met.
• Recipient is not opted in to notifications from your experience.
• Recipient's throttle limit for your experience has been reached.
• Recipient's aggregate daily throttle limit has been reached.
• Missing or invalid request parameters.
• Notification string was moderated.
• For notifications with user mentions, non-delivery occurs if either of these conditions are met:

  • The receiver and mentioned user are not friends.
  • The mentioned user has 否 selected for "Update friends about my activity?" under 隱私 → 其他 設置 in their Roblox account settings.

分析

您的通知性能和可通知受眾顯示在通知頁面的分析標籤中，您可以在此配置通知字符串（只需從創作頁面切換到分析頁面）。

1. 瀏覽至 創作者儀表板。
2. 類似於徽章，通知字符串與特定遊戲關聯。找到該遊戲的縮略圖並點擊它。
3. 在左側欄中，點擊參與度下的通知。
4. 在目標頁面，點擊分析標籤以切換到分析儀表板。

通知摘要

摘要部分作為您通知總體表現的快照。顯示性能統計需要至少 100 次的總體展示次數。

詳細統計

經驗通知表顯示每個至少有 100 次曝光的通知的詳細績效統計，按該通知的第一次曝光日期排序。

名稱列是通知的關鍵標識符。默認情況下，名稱與您在創建通知字符串時指定的標識符名稱匹配，但您可以通過 API 調用中的 category 欄位覆蓋它，在這種情況下 category 會覆蓋名稱。在創作者儀表板中更改字符串名稱或更改您的消息 ID 參考的字符串將在表中生成一個新行。

如果您想對不同字符串的績效進行 A/B 測試，建議您創建一個全新的通知字符串，並使用類似的名稱，例如：

• 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

包含有關要發送給用戶的通知詳細信息的表。必須包含一個 payload 表，其中包含所需的 messageId 和 type 字符串，以及可選的 parameters、joinExperience 和 analyticsData 表。

UserNotificationResult

一個包裝對象，保存從發送的通知的響應。包含以下鍵-值對：