Thông báo trải nghiệm

Thông báo trải nghiệm là cách để người dùng đã đăng ký từ 13 tuổi trở lên theo dõi các trò chơi yêu thích của họ thông qua các thông báo kịp thời và cá nhân hóa. Là nhà phát triển, bạn có thể xác định những loại hoạt động trong trò chơi quan trọng nhất để thông báo cho người dùng của bạn, cũng như định nghĩa nội dung thông báo.

Hệ thống thông báo trải nghiệm có những tính năng sau:

• Thông báo có thể tùy chỉnh với tham số — Toàn bộ tính linh hoạt để tùy chỉnh thông báo với các tham số, ví dụ:

  Trứng vàng của bạn đã nở!

  Allie @LaterSk8er1 vừa đánh bại kỷ lục của bạn trên đường đua Tokyo Tour!

• Dữ liệu khởi động — Bao gồm dữ liệu khởi động tùy chọn có thể được đọc thông qua Player:GetJoinData() khi người nhận thông báo tham gia. Điều này có thể liên quan đến việc hướng dẫn người dùng đến một tọa độ cụ thể hoặc cá nhân hóa trải nghiệm tham gia của họ.

• Hỗ trợ phân tích — Theo dõi khán giả có thể tiếp cận và hiệu suất của các thông báo trong Bảng điều khiển Người sáng tạo.

Yêu cầu đủ điều kiện

In order to use the APIs to send notifications, the game must meet the following base criteria:

• Tối thiểu 100 lượt truy cập kể từ khi ra mắt.
• Trò chơi không được đang trong tình trạng kiểm duyệt.
• Bạn, với tư cách là nhà phát triển, phải có quyền quản lý trò chơi.

Hướng dẫn sử dụng

Triển khai

Việc triển khai thông báo trải nghiệm bắt đầu với tạo ra một chuỗi thông báo và bao gồm gói trong dự án của bạn. Sau khi những điều này đã được thiết lập, bạn có thể gửi thông báo với tham số tùy chỉnh tùy chọn.

Ngoài ra, bạn có thể sử dụng Open Cloud API để kích hoạt thông báo thông qua các yêu cầu API tự do.

Tạo một chuỗi thông báo

Như với Lời mời từ người chơi, bạn cần tạo và chỉnh sửa chuỗi thông báo của mình trong Bảng điều khiển Người sáng tạo. Không có chuỗi thông báo trò chơi mặc định, vì vậy bước này là bắt buộc.

1. Điều hướng đến Bảng điều khiển Người sáng tạo.

2. Tương tự như huy hiệu, chuỗi thông báo được liên kết với một trò chơi cụ thể. Tìm biểu tượng của trò chơi đó và nhấp vào nó.

3. Ở cột bên trái, dưới mục Gắn kết, nhấp vào Thông báo.

4. Trong vùng trung tâm, nhấp vào nút Tạo Chuỗi Thông báo.

5. Điền vào tên định danh (chỉ hiển thị cho bạn) và chuỗi thông báo tùy chỉnh; điều này bị giới hạn trong 99 ký tự và có thể bao gồm các tham số tùy chỉnh không giới hạn. Thông báo sẽ tự động sử dụng tiêu đề của trò chơi bạn làm tiêu đề thông báo, nhưng bạn cũng có thể sử dụng {experienceName} để tham chiếu đến trò chơi của bạn trong văn bản thân thông báo.

   Ví dụ về chuỗi thông báo:

   Bạn còn {numQuests} nhiệm vụ nữa để hoàn thành thử thách hàng tuần!

   Mũ {eggName} của bạn đã nở! Hãy đến gặp thú cưng mới của bạn.

   Bạn đã thắng {numRaces} cuộc đua trong tuần này và mở khóa đường đua {racetrackName}!

   {userId-friend} vừa phá kỷ lục của bạn trên đường đua Tokyo Tour! Đến lúc báo thù?

   Trước khi viết chuỗi thông báo, vui lòng xem lại hướng dẫn để sử dụng hệ thống.

6. Khi đã sẵn sàng, nhấp vào nút Tạo Chuỗi Thông báo.

7. Trên trang thông báo, trong bảng thông báo, nhấp vào nút ⋯ trong cột Hành động và chọn Sao chép ID Tài sản.

8. Sử dụng ID đã sao chép cho giá trị khóa messageId trong bảng payload như được chứng minh trong kịch bản ví dụ.

Bao gồm gói

Để triển khai thông báo trải nghiệm, bạn phải lấy gói Luau từ Cửa hàng Người sáng tạo.

1. Từ menu Cửa sổ của Studio hoặc thanh công cụ Trang chủ, mở Hộp công cụ và chọn tab Cửa hàng Người sáng tạo.

   

2. Đảm bảo rằng sắp xếp Mô hình đang được chọn, sau đó nhấn nút Xem Tất cả cho Danh mục.

   

3. Tìm và nhấp vào ô Gói.

4. Tìm mô-đun Open Cloud và nhấp vào nó, hoặc kéo và thả nó vào chế độ xem 3D.

   

5. Trong cửa sổ Khám phá, di chuyển toàn bộ mô hình OpenCloud vào ServerScriptService.

Gửi thông báo trải nghiệm

Khi bạn đã tạo một chuỗi thông báo và bao gồm gói trong dự án của mình, bạn có thể gửi thông báo từ các script phía máy chủ. Thông báo sẽ được gửi đến các người dùng đã đăng ký từ 13 tuổi trở lên thông qua luồng thông báo Roblox của họ, vào lúc đó họ có thể tham gia trải nghiệm trực tiếp thông qua nút Tham gia trên thông báo và xuất hiện theo dữ liệu khởi động.

Để gửi thông báo cơ bản đến một người dùng cụ thể, hãy bao gồm ID tài sản của chuỗi thông báo trong trường messageId của payload, sau đó gọi hàm createUserNotification với Player.UserId của người nhận và dữ liệu yêu cầu.

local ServerScriptService = game:GetService("ServerScriptService")

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

-- Trong payload, "messageId" là giá trị của ID tài sản thông báo
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

Tùy chỉnh thông báo bằng các tham số

Để tùy chỉnh thông báo cho từng người nhận, bạn có thể bao gồm các tham số trong chuỗi thông báo, sau đó tùy chỉnh các tham số khi gọi API. Ví dụ, bạn có thể xác định chuỗi thông báo như sau:

Sau đó, đặt các tham số userId-friend và points trong script:

local ServerScriptService = game:GetService("ServerScriptService")

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

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

-- Trong payload, "messageId" là giá trị của ID tài sản thông báo
-- Trong ví dụ này, chuỗi thông báo là "{userId-friend} đã đánh bại điểm cao nhất của bạn với {points} điểm! Đã đến lúc nâng cấp?"
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

Khuyến khích người dùng bật thông báo

Để khuyến khích người dùng bật thông báo cho trải nghiệm của bạn, bạn có thể hiển thị một thông báo yêu cầu quyền trong trải nghiệm cho người dùng từ 13 tuổi trở lên bằng cách sử dụng phương thức ExperienceNotificationService:PromptOptIn().

Bạn có thể kích hoạt thông báo trong bất kỳ ngữ cảnh phù hợp nào trong trải nghiệm của bạn thích hợp với thông báo trong tương lai. Văn bản của thông báo không thể tùy chỉnh và được tiêu chuẩn hóa cho tất cả các trải nghiệm.

Thông báo sẽ không xuất hiện nếu người dùng:

• Dưới 13 tuổi.
• Đã bật thông báo cho trải nghiệm của bạn.
• Đã thấy thông báo yêu cầu quyền cho trải nghiệm của bạn trong 30 ngày qua.

Để khuyến khích người dùng bật thông báo, bạn nên trước tiên xác định xem người dùng có đủ điều kiện hay không. Khi đã xác nhận, bạn có thể hiển thị thông báo yêu cầu quyền cho người dùng.

1. Gọi ExperienceNotificationService:CanPromptOptInAsync(), được bọc trong pcall() vì đây là một cuộc gọi mạng không đồng bộ có thể thỉnh thoảng gặp sự cố.
2. Nếu người dùng có thể được yêu cầu, gọi ExperienceNotificationService:PromptOptIn().

local ExperienceNotificationService = game:GetService("ExperienceNotificationService")

-- Hàm để kiểm tra xem người chơi có thể được yêu cầu bật thông báo không
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

-- Lắng nghe sự kiện thông báo yêu cầu đã đóng
ExperienceNotificationService.OptInPromptClosed:Connect(function()
	print("Thông báo yêu cầu đã đóng")
end)

Bao gồm dữ liệu khởi động và phân tích

Để cải thiện trải nghiệm người dùng, bạn có thể bao gồm dữ liệu khởi động trong thông báo, hữu ích cho các tình huống như hướng dẫn người dùng đến một địa điểm cụ thể hoặc cá nhân hóa trải nghiệm tham gia. Thêm vào đó, bạn có thể bao gồm dữ liệu phân tích để phân loại hiệu suất của các loại thông báo khác nhau. Vui lòng tham khảo ví dụ về Thông báo mời người chơi về cách thiết lập và sử dụng dữ liệu khởi động.

local ServerScriptService = game:GetService("ServerScriptService")

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

-- Trong payload, "messageId" là giá trị của ID tài sản thông báo
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

Hệ thống phân phối

Hệ thống ngăn chặn spam tồn tại để đảm bảo chất lượng thông báo cho người dùng và bảo vệ kênh thông báo chung cho tất cả nhà phát triển. Vì lý do này, việc gửi thông báo không được đảm bảo. Hệ thống ngăn chặn spam này được thông báo trực tiếp bởi mức độ tương tác của người dùng: càng nhiều người dùng tương tác với thông báo của bạn, họ càng nhận được nhiều lượt tiếp cận. Bạn có thể theo dõi các chỉ số tương tác một cách minh bạch trong bảng điều khiển phân tích, như được giải thích dưới đây.

Thông báo trải nghiệm có một giới hạn throttling tĩnh; mỗi người dùng có thể nhận một thông báo mỗi ngày từ một trải nghiệm nhất định, và bạn nhận được phản hồi minh bạch khi giới hạn throttling của người dùng được đạt đến.

Ngoài ra, danh sách sau đây liệt kê một số trường hợp đặc biệt có thể dẫn đến không giao một thông báo:

• Các yêu cầu đủ điều kiện của trải nghiệm không được đáp ứng.
• Người nhận không đồng ý nhận thông báo từ trải nghiệm của bạn.
• Giới hạn throttling của người nhận cho trải nghiệm của bạn đã được đạt đến.
• Giới hạn throttling hàng ngày tổng hợp của người nhận đã được đạt đến.
• Thiếu hoặc không hợp lệ các tham số yêu cầu.
• Chuỗi thông báo đã bị kiểm duyệt.
• Đối với các thông báo có đề cập đến người dùng, việc không giao xảy ra nếu một trong những điều kiện sau đây được thỏa mãn:

  • Người nhận và người được đề cập không phải là bạn bè.
  • Người được đề cập đã chọn Không cho "Cập nhật bạn bè về hoạt động của tôi?" dưới mục Quyền riêng tư → Cài đặt khác trong cài đặt tài khoản Roblox của họ.

Phân tích

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.

Tóm tắt thông báo

Phần tóm tắt phục vụ như một cái nhìn tổng quát về hiệu suất tổng hợp của thông báo của bạn. Cần tối thiểu 100 lượt hiển thị tổng hợp để hiển thị các thống kê hiệu suất.

Thống kê chi tiết

Bảng Thông báo Trải nghiệm hiển thị các số liệu hiệu suất chi tiết cho từng thông báo có ít nhất 100 lượt hiển thị, được sắp xếp theo ngày hiển thị lần đầu của thông báo đó.

Cột Tên là định danh chính cho thông báo. Theo mặc định, tên sẽ trùng với tên định danh mà bạn đã chỉ định khi tạo chuỗi thông báo, nhưng bạn có thể ghi đè nó thông qua trường category trong các cuộc gọi API của bạn, trong trường hợp đó category sẽ ghi đè tên. Thay đổi tên chuỗi trong Bảng điều khiển Tạo hoặc thay đổi chuỗi mà ID tin nhắn của bạn tham chiếu trong cuộc gọi API sẽ tạo ra một hàng mới trong bảng.

Nếu bạn muốn thử nghiệm A/B hiệu suất của các chuỗi khác nhau, chúng tôi khuyên bạn nên tạo một chuỗi thông báo hoàn toàn mới với tên tương tự, ví dụ:

• EggHatchA — "Quả trứng vàng của bạn đã nở! Hãy đến gặp thú cưng mới của bạn."
• EggHatchB — "Đã đến lúc nở! Hãy đến gặp thú cưng mới của bạn."

Tham chiếu API

Các hàm

createUserNotification

Gửi một thông báo từ một script phía máy chủ. Cần ID Player.UserId của người nhận và một UserNotification. Trả về một UserNotificationResult.

local ServerScriptService = game:GetService("ServerScriptService")

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

-- Trong payload, "messageId" là giá trị của ID tài sản thông báo
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

Các loại

UserNotification

Bảng chứa thông tin về thông báo sẽ được gửi đến người dùng. Phải chứa một bảng payload với các chuỗi messageId và type yêu cầu, và các bảng tùy chọn parameters, joinExperience, và analyticsData.

UserNotificationResult

Một đối tượng bao bọc giữ phản hồi từ một thông báo đã gửi. Chứa các cặp khóa-giá trị sau: