Notifikasi pengalaman

Pemberitahuan pengalaman adalah cara bagi pengguna yang memilih pengguna berusia 13+ tahun untuk tetap mengikuti pengalaman favorit mereka melalui pemberitahuan tepat waktu dan personalisasi.Sebagai pengembang, Anda dapat menentukan jenis aktivitas dalam pengalaman mana yang paling penting untuk memberi tahu pengguna Anda, serta menentukan konten pemberitahuan.

Sistem pemberitahuan pengalaman memiliki fitur mengikuti:

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

  Your gold goose egg has hatched!

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

• Luncurkan Data — Termasuk data peluncuran opsional data peluncuran yang dapat dibaca melalui Player:GetJoinData() ketika penerima notifikasi bergabung.Ini bisa melibatkan rute pengguna ke lokasi koordinat atau menyesuaikan pengalaman bergabung mereka.

• Dukungan Analisis — Pelacakan audiens yang dapat dijangkau dan kinerja notifikasi Anda di Dashboard Pencipta.

Persyaratan kelayakan

Untuk menggunakan API untuk mengirim pemberitahuan, pengalaman harus memenuhi kriteria dasar berikut:

• Minimal 100 kunjungan sejak mulai.
• Pengalaman tidak boleh dibatasi.
• Anda sebagai pengembang harus memiliki izin untuk mengelola pengalaman.

Panduan penggunaan

Implementasi

Pemberitahuan pengalaman implementasi dimulai dengan membuat string pemberitahuan dan termasuk paket di proyek Anda.Setelah ini dibiarkan, Anda dapat mengirim pemberitahuan dengan parameter khusus opsional .

Alternatifnya, Anda dapat menggunakan API Cloud Terbuka untuk memicu notifikasi melalui permintaan API berbentuk bebas.

Buat string pemberitahuan

Seperti dengan Undangan Pemain, Anda harus membuat dan mengedit string pemberitahuan Anda di Dashboard Pencipta. Tidak ada string pemberitahuan pengalaman default, jadi langkah ini diperlukan.

1. Navigasikan ke Dashboard Pencipta.

2. Mirip dengan lencana , string notifikasi terikat ke pengalaman tertentu . Temukan thumbnail pengalaman itu dan klik di atasnya.

3. Di kolom kiri, di bawah Keterlibatan , klik Pemberitahuan .

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

5. Isi nama identifikasi (hanya terlihat oleh Anda) dan string pemberitahuan khusus; ini terbatas pada 99 karakter dan dapat mencakup parameter kustom tak terbatas .Notifikasi akan secara otomatis menggunakan judul pengalaman Anda sebagai judul notifikasi, tetapi Anda juga dapat menggunakan experienceName untuk merujuk pengalaman Anda di teks tubuh notifikasi.

   Contoh string pemberitahuan:

   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?

   Sebelum menulis string pemberitahuan, silakan tinjau panduan untuk menggunakan sistem.

6. Saat siap, klik tombol Buat String Notifikasi .

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

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

Termasuk paket

Untuk menerapkan pemberitahuan pengalaman, Anda harus mendapatkan paket Luau dari Toko Pencipta.

1. Dari tab Pandangan, buka Kotak Alat dan pilih tab Toko Pencipta .

   

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

   

3. Temukan dan klik ubin Modul Pengembang .

   

4. Temukan modul Buka Cloud dan klik, atau seret dan lepaskan ke dalam tampilan 3D.

   

5. Di jendela Explorer, pindahkan seluruh model OpenCloud ke ServerScriptService .

   

Kirim pemberitahuan notifikasi

Setelah Anda membuat string pemberitahuan dan menyertakan paket di proyek Anda, Anda dapat mengirim pemberitahuan dari skrip sisi server.Notifikasi akan dikirim ke opt-in pengguna berusia 13+ melalui streamnotifikasi Roblox, pada saat itu mereka dapat bergabung dengan pengalaman langsung melalui tombol Join pada notifikasi dan muncul sesuai dengan data peluncuran Anda .

Untuk mengirim pemberitahuan dasar ke pengguna tertentu, termasuk ID aset string notifikasi di bidang messageId pengiriman, lalu panggil fungsi createUserNotification dengan data penerima Player.UserId dan data permintaan.

Kirim pemberitahuan notifikasi
local ServerScriptService = game:GetService("ServerScriptService")

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

-- Dalam payload, "messageId" adalah nilai 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 pemberitahuan menggunakan parameter

Untuk menyesuaikan pemberitahuan untuk setiap penerima, Anda dapat menambahkan parameter dalam string pemberitahuan, kemudian sesuaikan parameter saat memanggil API.Sebagai contoh, Anda dapat mendefinisikan string pemberitahuan sebagai:

Kemudian, atur parameter userId-friend dan points dalam skrip:

Sesuaikan Notifikasi Menggunakan Parafrasa
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 ID aset notifikasi
-- Dalam contoh ini, string pemberitahuan adalah "{userId-friend} mengalahkan skor tertinggi Anda dengan {points} poin! Waktu 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

Minta pengguna untuk mengaktifkan notifikasi

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

Anda dapat memicu prompt di konteks yang sesuai dalam pengalaman Anda yang memerlukan notifikasidepan.Teks perintah tidak dapat disesuaikan dan dis standarisasi di semua pengalaman.

Modal tidak akan tidak muncul jika pengguna:

• Berada di bawah usia 13.
• Sudah mengaktifkan notifikasi untuk pengalaman Anda.
• Sudah melihat perintah izin untuk pengalaman Anda dalam 30 hari terakhir.

Untuk mendorong pengguna untuk mengaktifkan notifikasi, Anda harus terlebih dahulu menentukan apakah pengguna memenuhi syarat.Setelah dikonfirmasi, Anda dapat menampilkan prompt izin kepada pengguna.

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

Skrip Lokal - Implementasi Izin Notifikasi
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 peristiwa opt-in prompt ditutup
ExperienceNotificationService.OptInPromptClosed:Connect(function()
	print("Opt-in prompt closed")
end)

Termasuk data peluncuran dan analisis

Untuk meningkatkan pengalaman pengguna lebih lanjut, Anda dapat menyertakan data peluncuran dalam pemberitahuan, berguna untuk skenario seperti merute pengguna ke lokasi koordinat atau menyesuaikan pengalaman bergabung.Selain itu, Anda dapat menyertakan data analisis untuk membagi kinerja kategori notifikasi yang berbeda.Silakan juga merujuk ke contoh undangan pemain tentang cara data peluncur dapat ditetapkan dan digunakan.

Terdiri dari Data Peluncuran dan Data Analisis
local ServerScriptService = game:GetService("ServerScriptService")

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

-- Dalam payload, "messageId" adalah nilai 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 notifikasi untuk pengguna dan melindungi saluran notifikasi bersama untuk semua pengembang.Karena ini, pengiriman notifikasi tidak dijamin.Sistem pencegahan spam ini secara langsung diberitahu oleh interaksipengguna: semakin banyak pengguna terlibat dengan notifikasi Anda, semakin banyak jangkauan yang akan mereka terima.Anda dapat melacak metrik keterlibatan secara transparan di dashboard analisis, seperti yang dijelaskan di bawah ini.

Notifikasi pengalaman memiliki batas pengaturan statis; setiap pengguna dapat menerima satu notifikasi per hari dari pengalaman tertentu, dan Anda menerima umpan balas transparan saat batas pengaturan pengguna tercapai.

Selain itu, daftar berikut menjelaskan beberapa kasus khusus yang dapat menyebabkan tidak pengiriman notifikasi:

• Pengalaman persyaratan kelayakan tidak dipenuhi.
• Penerima tidak memilih untuk tidak menerima notifikasi dari pengalaman Anda.
• Batas pengaturan kecepatan penerima untuk pengalaman Anda telah tercapai.
• Batas pengurangan harian agregat penerima telah tercapai.
• Parameter permintaan yang hilang atau tidak valid.
• String notifikasi disaring.
• Untuk pemberitahuan dengan menyebutkan pengguna, non-pengiriman terjadi jika salah satu dari kondisi ini dipenuhi:

  • Penerima dan pengguna yang disebutkan tidak berteman.
  • Pengguna yang disebutkan memiliki Tidak dipilih untuk "Perbarui teman tentang aktivitas saya?" di bawah Privasi → Pengaturan lainnya di pengaturan akun Roblox mereka.

Analitik

Performa notifikasi dan audiens yang dapat diberitahu ditampilkan di tab Analisis dari halaman Notifikasi di mana Anda konfigurasi string notifikasi (hanya tab dari Kreasi ke Analisis ).

1. Navigasikan ke Dashboard Pencipta.
2. Mirip dengan lencana , string notifikasi terikat ke pengalaman tertentu . Temukan thumbnail pengalaman itu dan klik di atasnya.
3. Di kolom kiri, di bawah Keterlibatan , klik Pemberitahuan .
4. Di halaman target, klik tab Analitik untuk beralih ke dasbor analitik.

Ringkasan ringkasan

Bagian ringkasan berfungsi sebagai snapshot dari kinerja agregat notifikasi Anda.Sebanyak minimal 100 impresi agregat diperlukan untuk menampilkan statistik kinerja.

Statistik terbagi item

Tabel Notifikasi Pengalaman menampilkan statistik kinerja terperinci untuk setiap notifikasi dengan setidaknya 100 impresi, diurutkan berdasarkan tanggal kesan pertama untuk notifikasi itu.

Kolom Nama adalah identifikasi kunci untuk pemberitahuan.Secara default, nama sesuai dengan nama identifikasi yang Anda spesifikasikan saat membuat string notifikasi , tetapi Anda dapat menggantikannya melalui bidang category di panggilan API Anda, di mana kasusnya category menggantikan nama.Mengubah nama string di Dashboard Pencipta atau mengubah string referensi pesan ID Anda di panggilan API akan menghasilkan baris baru di tabel.

Jika Anda ingin menguji A/B kinerja berbagai string, disarankan untuk membuat string notifikasi baru sepenuhnya dengan nama serupa, misalnya:

• EggHatchA — "Telur emas Anda telah menetas! Datanglah bertemu hewan peliharaan baru Anda."
• EggHatchB — "Sudah waktunya menetas! Datanglah bertemu hewan peliharaan barumu."

Referensi API

Fungsi

buatNotifikasi Pengguna

Mengirim pemberitahuan dari skrip sisi server.Membutuhkan Player.UserId penerima dan Pemberitahuan Pengguna.Kembalikan Hasil Pemberitahuan Pengguna.

Kirim pemberitahuan notifikasi
local ServerScriptService = game:GetService("ServerScriptService")

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

-- Dalam payload, "messageId" adalah nilai 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

Jenis

Notifikasi Pengguna

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

Hasil Pemberitahuan Pengguna

Objek pembungkus yang menyimpan respons dari notifikasiyang dikirim. Berisi pas kunci-nilai berikut: