Deneyim bildirimleri

Deneyim bildirimleri, 13 yaş ve üzeri katılım sağlamış kullanıcıların en sevdikleri oyunlarla alakalı olarak zamanında, kişiselleştirilmiş bildirimlerle güncel kalmalarını sağlamak için bir yoldur. Geliştirici olarak, kullanıcılarınıza bildirim vermenin en önemli olduğu oyun içi etkinlik türlerini belirleyebilir ve bildirim içeriğini tanımlayabilirsiniz.

Deneyim bildirim sistemi aşağıdaki özellikleri içerir:

• Parametrelerle özelleştirilebilir bildirimler — Örneğin, bildirim mesajını parametrelerle tam olarak özelleştirme esnekliği:

  Altın yumurtanınız yumurtladı!

  Allie @LaterSk8er1, Tokyo Turu pistindeki rekorunuzu geçti!

• Başlangıç Verileri — Bildirim alıcısı oyuna katıldığında Player:GetJoinData() aracılığıyla okunabilen isteğe bağlı başlangıç verilerini ekleyin. Bu, bir kullanıcıyı belirli bir koordinata yönlendirmeyi veya katılım deneyimlerini kişiselleştirmeyi içerebilir.

• Analitik Desteği — Erişilebilir kitlenizi ve bildirimlerinizin performansını Yaratıcı Gösterge Tablosu üzerinde takip edin.

Uygunluk şartları

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

• Minimum 100 ziyaret, lansmandan bu yana.
• Oyun, moderasyon altında olmamalıdır.
• Geliştirici olarak oyunu yönetme iznine sahip olmalısınız.

Kullanım kuralları

Uygulama

Deneyim bildirimlerini uygulamak, bir bildirim dizesi oluşturma ve paketi projenize eklemekle başlar. Bunlar ayarlandığında, isteğe bağlı özel parametrelerle bildirim gönderebilirsiniz.

Alternatif olarak, bildirimleri serbest biçimli API istekleri ile tetiklemek için Open Cloud API kullanabilirsiniz.

Bir bildirim dizesi oluşturun

As with Player Invite Prompts, you must create and edit your notification strings in the Creator Dashboard. Varsayılan bir oyun bildirim dizesi yoktur, bu nedenle bu adım gereklidir.

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. In the center region, click the Create a Notification String button.

5. Fill in an identifier name (only visible to you) and the custom notification string; this is limited to 99 characters and can include unlimited custom parameters. Notifications will automatically use the title of your game as the notification title, but you can additionally use {experienceName} to reference your game in the notification body text.

   Örnek bildirim dizeleri:

   Sen {numQuests} görev tamamlamaktan haftalık meydan okumayı kazanmak için uzaktasın!

   Senin {eggName} yumurtan açıldı! Yeni evcil hayvanınla tanışmaya gel.

   Bu hafta {numRaces} yarışı kazandın ve {racetrackName} pistini açtın!

   {userId-friend} Tokyo Tur pisti üzerindeki rekorunu geçti! İntikam zamanı mı?

   Bildirim dizeleri yazmadan önce, lütfen sistem kullanımına ilişkin kılavuzları gözden geçirin.

6. When ready, click the Create Notification String button.

7. On the notifications page, in the table of notifications, click the ⋯ button in the Actions column and select Copy Asset ID.

8. Use the copied ID for the messageId key value in the payload table as demonstrated in the example script.

Paketi dahil et

Deneyim bildirimlerini uygulamak için, Yaratıcı Mağaza'dan Luau paketini almanız gerekmektedir.

1. Studio'daki Pencere menüsünden veya Ana Sayfa sekmesi araç çubuğundan Araç Kutusu'nu açın ve Yaratıcı Mağaza sekmesini seçin.

   

2. Modeller sıralamasının seçili olduğundan emin olun, ardından Kategorilere Göz At butonuna tıklayın.

   

3. Paketler kutucuğunu bulun ve tıklayın.

4. Open Cloud modülünü bulun ve üzerine tıklayın veya 3D görünümüne sürükleyip bırakın.

   

5. Explorer penceresinde, tüm OpenCloud modelini ServerScriptService içerisine taşıyın.

Bir deneyim bildirimi gönderin

Bir bildirim dizesi oluşturduktan ve paketi projenize ekledikten sonra, sunucu tarafı betiklerinden bildirimler gönderebilirsiniz. Bildirimler, 13 yaş ve üstü katılan kullanıcılara Roblox bildirim akışı üzerinden iletilecek; bu aşamada kullanıcı, bildirimdeki Katıl butonuna tıklayarak doğrudan deneyime katılabilir ve başlangıç verilerinize göre yerleşebilir.

Belirli bir kullanıcıya temel bir bildirim göndermek için, messageId alanına bildirim dizesini yüklemeye semaleler, ardından createUserNotification fonksiyonunu alıcının Player.UserId'sı ve istek verileri ile çağırın.

Bir deneyim bildirimi gönderin
local ServerScriptService = game:GetService("ServerScriptService")

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

-- Yüklemekte, "messageId" bildirim varlık ID'sinin değeridir
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

Parametreler ile bildirimleri özelleştirin

Her alıcı için bildirimi özelleştirmek üzere, bildirim dizesinde parametreler ekleyebilir ve API'yi çağırırken bu parametreleri özelleştirebilirsiniz. Örneğin, bildirim dizesini şu şekilde tanımlayabilirsiniz:

Ardından, betikte userId-friend ve points parametrelerini ayarlayın:

Parametre Kullanarak Bildirimi Özelleştirin
local ServerScriptService = game:GetService("ServerScriptService")

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

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

-- Yüklemekte, "messageId" bildirimin varlık ID'sinin değeridir
-- Bu örnekte, bildirim dizesi "{userId-friend} yüksek skoru {points} puanla geçti! Seviye atlama zamanı?"
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

Kullanıcıları bildirimleri etkinleştirmeye teşvik edin

Kullanıcıları deneyiminiz için bildirimleri etkinleştirmeye teşvik etmek amacıyla, 13 yaş ve üstündeki kullanıcılarla ExperienceNotificationService:PromptOptIn() yöntemini kullanarak deneyim içinde izin istemi görüntüleyebilirsiniz.

İstemi, gelecekteki bir bildirimle uygun göreceğiniz herhangi bir bağlamda tetikleyebilirsiniz. İstemin metni özelleştirilemez ve tüm deneyimlerde standarttır.

Modal, eğer kullanıcı:

• 13 yaşından küçükse.
• Zaten deneyiminiz için bildirimleri etkinleştirmişse.
• Geçtiğimiz 30 gün içinde deneyiminiz için izin istemini görmüşse ortaya çıkmayacaktır.

Kullanıcılara bildirimleri etkinleştirmelerini istemek için, önce kullanıcının uygun olup olmadığını belirlemelisiniz. Onaylandıktan sonra, kullanıcıya izin istemini gösterebilirsiniz.

1. ExperienceNotificationService:CanPromptOptInAsync() çağrısını yapın, bu çağrı asenkron bir ağ çağrısı olduğu için pcall() ile sarın; çünkü zaman zaman başarısız olabilir.
2. Kullanıcıya istenirse, ExperienceNotificationService:PromptOptIn() çağrısını yapın.

LocalScript - Bildirim İzni İstemi Uygulaması
local ExperienceNotificationService = game:GetService("ExperienceNotificationService")

-- Kullanıcının bildirimleri etkinleştirmesi için izin istemine açılabilirliğini kontrol eden fonksiyon
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

-- İzin isteminin kapatılması olayı dinleme
ExperienceNotificationService.OptInPromptClosed:Connect(function()
	print("İzin istemi kapatıldı")
end)

Başlangıç ve analitik verileri dahil et

Kullanıcı deneyimini daha da geliştirmek için, bildirimde başlangıç verilerini ekleyebilirsiniz; bu, kullanıcıları belirli bir koordinata yönlendirmek veya katılım deneyimlerini kişiselleştirmek gibi senaryolar için faydalıdır. Ayrıca, farklı bildirim kategorilerinin performansını bölümlendirmek için analitik verilerini ekleyebilirsiniz. Başlangıç verilerinin nasıl ayarlanıp kullanılabileceği ile ilgili örnek için lütfen Oyuncu davet istemleri örneğine de bakın.

Başlangıç Verisi ve Analitik Verisi Dahil Et
local ServerScriptService = game:GetService("ServerScriptService")

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

-- Yüklemekte, "messageId" bildirim varlık ID'sinin değeridir
local userNotification = {
	payload = {
		messageId = "5dd7024b-68e3-ac4d-8232-4217f86ca244",
		type = "MOMENT",
		joinExperience = {
			launchData = "Test_Baslangic_Verisi"
		},
		analyticsData = {
			category = "Test_Analitik_Kategorisi"
		}
	}
}

local result = OCUserNotification.createUserNotification(recipientPlayerID, userNotification)

if result.statusCode ~= 200 then
	print(result.statusCode)
	print(result.error.code)
	print(result.error.message)
end

Dağıtım sistemi

Bir spam önleme sistemi, kullanıcılar için bildirimlerin kalitesini sağlamak ve tüm geliştiriciler için paylaşılan bildirim kanalını korumak amacıyla mevcuttur. Bu nedenle, bildirimlerin teslimatı garanti edilmez. Bu spam önleme sistemi, kullanıcı etkileşimi ile doğrudan bilgilendirilir: kullanıcılar bildirimlerinizle ne kadar fazla etkileşime girerse, o kadar fazla erişim alırlar. Etkileşim metriklerini analitik kontrol panelinde şeffaf bir şekilde izleyebilirsiniz; bu, aşağıda açıklanmıştır.

Deneyim bildirimlerinin statik bir throttling limiti vardır; her kullanıcı, belirli bir deneyimden günde bir bildirim alabilir ve bir kullanıcının throttling limiti aşıldığında şeffaf bir geri bildirim alırsınız.

Ayrıca, aşağıdaki liste, bir bildirimin teslim edilmemesine yol açabilecek bazı özel durumu ortaya koymaktadır:

• Deneyim uygunluk gereksinimleri karşılanmamıştır.
• Alıcı, deneyiminizden bildirimlere abone olmamıştır.
• Alıcının deneyiminiz için throttling limiti dolmuştur.
• Alıcının toplam günlük throttling limiti dolmuştur.
• Eksik veya geçersiz istekte bulunan parametreler.
• Bildirim metni denetlenmiştir.
• Kullanıcı bahsi geçen bildirimler için, aşağıdaki koşullardan biri karşılandığında teslim edilmeme durumu oluşur:

  • Alıcı ve bahsedilen kullanıcı arkadaş değilse.
  • Bahsedilen kullanıcı, Roblox hesap ayarlarında Gizlilik → Diğer Ayarlar altında "Arkadaşlarımı aktivitelerim hakkında güncellesin mi?" için Hayır seçeneğini seçmişse.

Analitik

Performans 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.

Bildirimler özeti

Özet bölümü, bildirimlerinizin toplam performansının anlık görüntüsünü sağlar. Performans istatistiklerini göstermek için en az 100 toplam görüntüleme gereklidir.

Ayrıntılı istatistikler

The Deneyim Bildirimleri tablosu en az 100 gösterime sahip her bildirim için ayrıntılı performans istatistiklerini, o bildirimin ilk gösterim tarihine göre sıralanmış olarak görüntüler.

İsim sütunu, bildirimin ana tanımlayıcısıdır. Varsayılan olarak, isim, bildirim dizesini oluştururken belirttiğiniz tanımlayıcı adıyla eşleşir, ancak API çağrılarınızda category alanını kullanarak bunu geçersiz kılabilirsiniz; bu durumda category, ismin üzerine yazar. Yaratıcı Dashboard kısmında dize ismini değiştirmek veya API çağrısındaki mesaj ID'sinin referans verdiği dizeyi değiştirmek, tabloda yeni bir satır oluşturur.

Farklı dizelerin performansını A/B test etmek isterseniz, benzer bir isimle tamamen yeni bir bildirim dizesi oluşturmanız önerilir, örneğin:

• EggHatchA — "Altın yumurtanız çatladı! Yeni evcil hayvanınızla tanışın."
• EggHatchB — "Yumurtlama zamanı! Yeni evcil hayvanınızla tanışın."

API referansı

Fonksiyonlar

createUserNotification

Bir sunucu tarafı betiğinden bir bildirim gönderir. Alıcının Player.UserId'sini ve bir UserNotification'ı gerektirir. Bir UserNotificationResult döndürür.

Bir deneyim bildirimi gönderin
local ServerScriptService = game:GetService("ServerScriptService")

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

-- Yüklemekte, "messageId" bildirim varlık ID'sinin değeridir
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ürler

UserNotification

Kullanıcıya gönderilecek bildirimin ayrıntılarını içeren tablo. Zorunlu messageId ve type dize değerleri ile payload tablosu içermeli ve isteğe bağlı parameters, joinExperience, ve analyticsData tablolarını da içerebilir.

UserNotificationResult

Gönderilen bildirimden gelen yanıtı tutan bir sarmalayıcı nesne. Aşağıdaki anahtar-değer çiftlerini içerir: