Notifikasi pengalaman

Notifikasi pengalaman adalah cara bagi pengguna yang berpartisipasi berusia 13 tahun ke atas untuk tetap terhubung dengan game favorit mereka melalui notifikasi yang cepat dan dipersonalisasi. Sebagai pengembang, Anda dapat menentukan jenis aktivitas dalam permainan yang paling penting untuk diberitahukan kepada pengguna Anda, serta mendefinisikan konten notifikasi.

Sistem notifikasi pengalaman memiliki fitur berikut:

• Notifikasi yang dapat disesuaikan dengan parameter — Fleksibilitas penuh untuk menyesuaikan pesan notifikasi dengan parameter, misalnya:

  Telur emas Anda telah menetas!

  Allie @LaterSk8er1 baru saja mengalahkan rekor Anda di trek Tokyo Tour!

• Data Peluncuran — Sertakan data peluncuran opsional yang dapat dibaca melalui Player:GetJoinData() ketika penerima notifikasi bergabung. Ini bisa melibatkan pengarahan pengguna ke lokasi koordinat atau mempersonalisasi pengalaman bergabung mereka.

• Dukungan Analitik — Lacak audiens yang dapat dijangkau dan kinerja notifikasi Anda di Dasbor Kreator.

Persyaratan kelayakan

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

• Minimum 100 visits since launch.
• The game must not be under moderation.
• You as the developer must have permission to manage the game.

Pedoman penggunaan

Implementasi

Menerapkan notifikasi pengalaman dimulai dengan membuat string notifikasi dan menyertakan paket dalam proyek Anda. Setelah ini diatur, Anda dapat mengirim notifikasi dengan parameter kustom opsional.

Sebagai alternatif, Anda dapat menggunakan Open Cloud API untuk memicu notifikasi melalui permintaan API bebas bentuk.

Membuat string notifikasi

Sebagaimana dengan Player Invite Prompts, Anda harus membuat dan mengedit string notifikasi Anda di Creator Dashboard. Tidak ada string notifikasi game default, jadi langkah ini diperlukan.

1. Arahkan ke Creator Dashboard.

2. Mirip dengan badge, string notifikasi terikat pada game tertentu. Temukan thumbnail game tersebut dan klik di atasnya.

3. Di kolom sebelah kiri, di bawah Keterlibatan, klik Notifikasi.

4. Di wilayah tengah, klik tombol Buat String Notifikasi.

5. Isi nama pengenal (hanya terlihat oleh Anda) dan string notifikasi kustom; ini dibatasi hingga 99 karakter dan dapat menyertakan parameter kustom tanpa batas. Notifikasi akan secara otomatis menggunakan judul game Anda sebagai judul notifikasi, tetapi Anda juga dapat menggunakan {experienceName} untuk merujuk game Anda dalam teks badan notifikasi.

   Contoh string notifikasi:

   Anda {numQuests} misi lagi untuk menyelesaikan tantangan mingguan!

   {eggName} Anda menetas! Datang dan temui hewan peliharaan baru Anda.

   Anda memenangkan {numRaces} balapan minggu ini dan membuka trek {racetrackName}!

   {userId-friend} baru saja mengalahkan rekor Anda di trek Tokyo Tour! Saatnya untuk balas dendam?

   Sebelum menulis string notifikasi, silakan tinjau pedoman untuk menggunakan sistem ini.

6. Ketika sudah siap, klik tombol Buat String Notifikasi.

7. Di halaman notifikasi, dalam tabel notifikasi, klik tombol ⋯ di kolom Aksi dan pilih Salin ID Aset.

8. Gunakan ID yang disalin untuk nilai kunci messageId dalam tabel payload seperti yang diperlihatkan dalam skrip contoh.

Sertakan paket

Untuk menerapkan notifikasi pengalaman, Anda harus mendapatkan paket Luau dari Toko Kreator.

1. Dari menu Jendela Studio atau bilah alat tab Beranda, buka Toolbox dan pilih tab Toko Kreator.

   

2. Pastikan pemeringkatan Model dipilih, lalu klik tombol Lihat Semua untuk Kategori.

   

3. Temukan dan klik ubin Paket.

4. Temukan modul Open Cloud dan klik, atau tarik‑dan‑jatuhkan ke tampilan 3D.

   

5. Di jendela Eksplorator, pindahkan model OpenCloud ke dalam ServerScriptService.

Mengirim notifikasi pengalaman

Setelah Anda membuat string notifikasi dan menyertakan paket dalam proyek Anda, Anda dapat mengirim notifikasi dari skrip sisi server. Notifikasi akan dikirim kepada pengguna yang telah memilih untuk menerima notifikasi berusia 13+ melalui aliran notifikasi Roblox mereka, dan pada titik ini mereka dapat bergabung dengan pengalaman langsung melalui tombol Bergabung di notifikasi dan muncul sesuai dengan data peluncuran Anda.

Untuk mengirim notifikasi dasar kepada pengguna tertentu, sertakan ID aset string notifikasi dalam bidang messageId payload, kemudian panggil fungsi createUserNotification dengan Player.UserId penerima dan data permintaan.

local ServerScriptService = game:GetService("ServerScriptService")

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

-- Dalam payload, "messageId" adalah nilai dari ID aset notifikasi
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

Sesuaikan notifikasi menggunakan parameter

Untuk menyesuaikan notifikasi untuk setiap penerima, Anda dapat menyertakan parameter dalam string notifikasi, kemudian sesuaikan parameter tersebut saat memanggil API. Misalnya, Anda dapat mendefinisikan string notifikasi sebagai:

Kemudian, setel parameter userId-friend dan points di skrip:

local ServerScriptService = game:GetService("ServerScriptService")

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

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

-- Dalam payload, "messageId" adalah nilai dari ID aset notifikasi
-- Dalam contoh ini, string notifikasi adalah "{userId-friend} mengalahkan skor tertinggi Anda dengan {points} poin! Saatnya untuk naik level?"
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

Ajak pengguna untuk mengaktifkan notifikasi

Untuk mendorong pengguna mengaktifkan notifikasi untuk pengalaman Anda, Anda dapat menampilkan permintaan izin dalam pengalaman kepada pengguna berusia 13+ menggunakan metode ExperienceNotificationService:PromptOptIn().

Anda dapat memicu permintaan di konteks mana pun dalam pengalaman Anda yang memerlukan notifikasi di masa depan. Teks dari permintaan tidak dapat disesuaikan dan distandarisasi di seluruh pengalaman.

Modal tidak akan muncul jika pengguna:

• Berusia di bawah 13 tahun.
• Telah mengaktifkan notifikasi untuk pengalaman Anda.
• Telah melihat permintaan izin untuk pengalaman Anda dalam 30 hari terakhir.

Untuk meminta pengguna agar mengaktifkan notifikasi, Anda harus terlebih dahulu menentukan apakah pengguna memenuhi syarat. Setelah dikonfirmasi, Anda dapat menampilkan permintaan izin kepada pengguna.

1. Panggil ExperienceNotificationService:CanPromptOptInAsync(), dibungkus dalam pcall() karena ini adalah panggilan jaringan asinkron yang mungkin kadang-kadang gagal.
2. Jika pengguna bisa diminta, panggil ExperienceNotificationService:PromptOptIn().

local ExperienceNotificationService = game:GetService("ExperienceNotificationService")

-- Fungsi untuk memeriksa apakah pemain dapat diminta untuk mengaktifkan notifikasi
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

-- Dengarkan acara permintaan opt-in ditutup
ExperienceNotificationService.OptInPromptClosed:Connect(function()
	print("Permintaan opt-in ditutup")
end)

Sertakan data peluncuran dan analitik

Untuk lebih meningkatkan pengalaman pengguna, Anda dapat menyertakan data peluncuran dalam notifikasi, berguna untuk skenario seperti mengarahkan pengguna ke lokasi koordinat atau mempersonalisasi pengalaman bergabung. Selain itu, Anda dapat menyertakan data analitik untuk menyegmentasikan kinerja kategori notifikasi yang berbeda. Silakan juga lihat contoh Permintaan undangan Pemain tentang cara mengatur dan menggunakan data peluncuran.

local ServerScriptService = game:GetService("ServerScriptService")

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

-- Dalam payload, "messageId" adalah nilai dari ID aset notifikasi
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

Sistem pengiriman

Sistem pencegahan spam ada untuk memastikan kualitas pemberitahuan bagi pengguna dan melindungi saluran pemberitahuan bersama untuk semua pengembang. Karena hal ini, pengiriman pemberitahuan tidak dijamin. Sistem pencegahan spam ini secara langsung diinformasikan oleh keterlibatan pengguna: semakin banyak pengguna terlibat dengan pemberitahuan Anda, semakin banyak jangkauan yang akan mereka terima. Anda dapat melacak metrik keterlibatan secara transparan di dasbor analitik, seperti yang dijelaskan di bawah ini.

Pemberitahuan pengalaman memiliki batas throttle statis; setiap pengguna dapat menerima satu pemberitahuan per hari dari pengalaman tertentu, dan Anda menerima umpan balik yang transparan ketika batas throttle pengguna tercapai.

Selain itu, daftar berikut menggambarkan beberapa kasus khusus yang dapat mengakibatkan tidak terkirimnya pemberitahuan:

• Persyaratan kelayakan pengalaman tidak terpenuhi.
• Penerima tidak ikut serta dalam pemberitahuan dari pengalaman Anda.
• Batas throttle penerima untuk pengalaman Anda telah tercapai.
• Batas throttle harian agregat penerima telah tercapai.
• Parameter permintaan hilang atau tidak valid.
• String pemberitahuan telah dimoderasi.
• Untuk pemberitahuan dengan penyebutan pengguna, tidak terkirim terjadi jika salah satu dari kondisi berikut terpenuhi:

  • Penerima dan pengguna yang disebutkan bukan teman.
  • Pengguna yang disebutkan telah memilih Tidak untuk "Perbarui teman tentang aktivitas saya?" di bawah Privasi → Pengaturan Lainnya dalam pengaturan akun Roblox mereka.

Analitik

Kinerja notifikasi Anda dan audiens yang dapat diberitahukan ditampilkan di tab Analitik pada halaman Notifikasi di mana Anda mengonfigurasi string notifikasi (cukup beralih dari Kreasi ke Analitik).

1. Navigasikan ke Dasbor Creator.
2. Mirip dengan lencana, string notifikasi terikat pada permainan tertentu. Temukan thumbnail permainan itu dan klik di atasnya.
3. Di kolom kiri, di bawah Keterlibatan, klik Notifikasi.
4. Di halaman tujuan, klik tab Analitik untuk beralih ke dasbor analitik.

Ringkasan notifikasi

Bagian ringkasan berfungsi sebagai gambaran umum kinerja agregat dari notifikasi Anda. Diperlukan minimal 100 tayangan agregat untuk menampilkan statistik kinerja.

Statistik terperinci

The Tabel Notifikasi Pengalaman menampilkan statistik kinerja terperinci untuk setiap notifikasi dengan setidaknya 100 tayangan, diurutkan berdasarkan tanggal tayangan pertama untuk notifikasi tersebut.

Kolom Nama adalah pengidentifikasi kunci untuk notifikasi. Secara default, nama tersebut cocok dengan nama pengidentifikasi yang Anda tentukan saat membuat string notifikasi, tetapi Anda dapat menimpanya melalui field kategori dalam panggilan API Anda, di mana kategori akan menggantikan nama. Mengubah nama string di Dasbor Kreator atau mengubah string yang dirujuk oleh ID pesan Anda dalam panggilan API akan menghasilkan baris baru di tabel.

Jika Anda ingin melakukan uji A/B pada kinerja string yang berbeda, disarankan agar Anda membuat string notifikasi yang sepenuhnya baru dengan nama yang serupa, misalnya:

• EggHatchA — "Telur emas Anda telah menetas! Ayo temui hewan peliharaan baru Anda."
• EggHatchB — "Saatnya menetas! Ayo temui hewan peliharaan baru Anda."

Referensi API

Fungsi

createUserNotification

Mengirim notifikasi dari skrip sisi server. Memerlukan Player.UserId penerima dan UserNotification. Mengembalikan UserNotificationResult.

local ServerScriptService = game:GetService("ServerScriptService")

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

-- Dalam payload, "messageId" adalah nilai dari ID aset notifikasi
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

Tipe

UserNotification

Tabel yang berisi detail tentang notifikasi yang akan dikirim kepada pengguna. Harus berisi tabel payload dengan string messageId dan type yang diperlukan, serta tabel opsional parameters, joinExperience, dan analyticsData.

UserNotificationResult

Sebuah objek pembungkus yang menyimpan respons dari notifikasi yang dikirim. Berisi pasangan kunci‑nilai berikut: