Notifiche dell'esperienza

Le notifiche delle esperienze sono un modo per gli utenti che hanno accettato di oltre 13 anni di rimanere aggiornati sui loro giochi preferiti attraverso notifiche tempestive e personalizzate. Come sviluppatore, puoi determinare quali tipi di attività in-game sono più importanti da comunicare ai tuoi utenti, oltre a definire il contenuto delle notifiche.

Il sistema di notifiche dell'esperienza presenta le seguenti caratteristiche:

• Notifiche personalizzabili con parametri — Massima flessibilità per personalizzare il messaggio di notifica con parametri, ad esempio:

  Il tuo uovo d'oro è schiuso!

  Allie @LaterSk8er1 ha appena battuto il tuo record sul percorso Tokyo Tour!

• Dati di avvio — Includi i dati di avvio opzionali che possono essere letti tramite Player:GetJoinData() quando il destinatario della notifica si unisce. Questo potrebbe comportare il reindirizzamento di un utente a una posizione di coordinate o la personalizzazione della sua esperienza di ingresso.

• Supporto analitico — Monitora il tuo pubblico raggiungibile e le prestazioni delle tue notifiche nel Creator Dashboard.

Requisiti di idoneità

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.

Linee guida sull'uso

Implementazione

Implementare le notifiche dell'esperienza inizia con la creazione di una stringa di notifica e includendo il pacchetto nel tuo progetto. Una volta impostati, puoi inviare notifiche con parametri personalizzati opzionali.

In alternativa, puoi utilizzare l'API Open Cloud per attivare notifiche tramite richieste API libere.

Crea una stringa di notifica

As with Player Invite Prompts, you must create and edit your notification strings in the Creator Dashboard. Non esiste una stringa di notifica predefinita per il gioco, quindi questo passaggio è obbligatorio.

1. Navigate to the Creator Dashboard.

2. Similar to badges, le stringhe delle notifiche sono legate a un gioco specifico. Trova la miniatura di quel gioco e cliccaci sopra.

3. Nella colonna di sinistra, sotto Coinvolgimento, clicca su Notifiche.

4. Nella regione centrale, clicca sul pulsante Crea una Stringa di Notifica.

5. Compila un nome identificativo (visibile solo a te) e la stringa di notifica personalizzata; questo è limitato a 99 caratteri e può includere parametri personalizzati illimitati. Le notifiche utilizzeranno automaticamente il titolo del tuo gioco come titolo della notifica, ma puoi anche usare {experienceName} per fare riferimento al tuo gioco nel testo del corpo della notifica.

   Esempi di stringhe di notifica:

   Sei {numQuests} sfide lontano dal completare la sfida settimanale!

   Il tuo {eggName} è nato! Vieni a conoscere il tuo nuovo animale domestico.

   Hai vinto {numRaces} gare questa settimana e hai sbloccato il tracciato {racetrackName}!

   {userId-friend} ha appena battuto il tuo record nel tracciato Tokyo Tour! È ora di vendetta?

   Prima di scrivere le stringhe di notifica, ti preghiamo di rivedere le linee guida per l'uso del sistema.

6. Quando sei pronto, clicca sul pulsante Crea Stringa di Notifica.

7. Nella pagina delle notifiche, nella tabella delle notifiche, clicca sul pulsante ⋯ nella colonna Azioni e seleziona Copia ID Risorsa.

8. Usa l'ID copiato per il valore della chiave messageId nella tabella payload come dimostrato nello script di esempio.

Includi il pacchetto

Per implementare le notifiche dell'esperienza, devi ottenere il pacchetto Luau dal Creator Store.

1. Dal menu Finestra di Studio o dalla barra degli strumenti della scheda Home, apri il Toolbox e seleziona la scheda Creator Store.

   

2. Assicurati che la selezione sia su Modelli, quindi fai clic sul pulsante Vedi Tutti per Categorie.

   

3. Trova e fai clic sulla tessera Pacchetti.

4. Trova il modulo Open Cloud e fai clic su di esso, oppure trascinalo nel panorama 3D.

   

5. Nella finestra Explorer, sposta l'intero modello OpenCloud in ServerScriptService.

Invia una notifica dell'esperienza

Una volta che hai creato una stringa di notifica e incluso il pacchetto nel tuo progetto, puoi inviare notifiche da script lato server. Le notifiche saranno consegnate agli utenti iscritti di età superiore ai 13 anni tramite il loro flusso di notifiche Roblox, a questo punto possono unirsi all'esperienza direttamente tramite il pulsante Unisciti sulla notifica e spawnare secondo i tuoi dati di avvio.

Per inviare una notifica base a un utente specifico, includi l'ID asset della stringa di notifica nel campo messageId del payload, quindi chiama la funzione createUserNotification con il Player.UserId del destinatario e i dati della richiesta.

Invia una notifica dell'esperienza
local ServerScriptService = game:GetService("ServerScriptService")

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

-- Nel payload, "messageId" è il valore dell'ID asset della notifica
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

Personalizza le notifiche utilizzando parametri

Per personalizzare la notifica per ciascun destinatario, puoi includere parametri nella stringa di notifica, quindi personalizzare i parametri quando chiami l'API. Ad esempio, puoi definire la stringa di notifica come:

Quindi, imposta i parametri userId-friend e points nello script:

Personalizza la Notifica Usando Parametri
local ServerScriptService = game:GetService("ServerScriptService")

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

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

-- Nel payload, "messageId" è il valore dell'ID asset della notifica
-- In questo esempio, la stringa di notifica è "{userId-friend} ha battuto il tuo punteggio massimo di {points} punti! È tempo di salire di livello?"
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

Chiedi agli utenti di abilitare le notifiche

Per incoraggiare gli utenti ad abilitare le notifiche per la tua esperienza, puoi mostrare un prompt di autorizzazione all'interno dell'esperienza agli utenti di età superiore ai 13 anni utilizzando il metodo ExperienceNotificationService:PromptOptIn().

Puoi attivare il prompt in qualsiasi contesto adatto all'interno della tua esperienza che giustifichi una futura notifica. Il testo del prompt non è personalizzabile ed è standardizzato in tutte le esperienze.

Il modulo non apparirà se l'utente:

• È sotto i 13 anni.
• Ha già abilitato le notifiche per la tua esperienza.
• Ha già visto il prompt di autorizzazione per la tua esperienza negli ultimi 30 giorni.

Per chiedere agli utenti di abilitare le notifiche, dovresti prima determinare se l'utente è idoneo. Una volta confermato, puoi mostrare il prompt di autorizzazione all'utente.

1. Chiama ExperienceNotificationService:CanPromptOptInAsync(), racchiuso in un pcall() poiché è una chiamata di rete asincrona che potrebbe occasionalmente non riuscire.
2. Se l'utente può essere invitato, chiama ExperienceNotificationService:PromptOptIn().

LocalScript - Implementazione del Prompt di Permesso Notifiche
local ExperienceNotificationService = game:GetService("ExperienceNotificationService")

-- Funzione per controllare se il giocatore può essere invitato ad abilitare le notifiche
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

-- Ascolta l'evento di chiusura del prompt di opt-in
ExperienceNotificationService.OptInPromptClosed:Connect(function()
	print("Prompt di opt-in chiuso")
end)

Includi dati di avvio e analitici

Per migliorare ulteriormente l'esperienza utente, puoi includere dati di avvio nella notifica, utili per scenari come il reindirizzamento degli utenti a una posizione di coordinate o la personalizzazione dell'esperienza di ingresso. Inoltre, puoi includere dati di analitica per segmentare le prestazioni delle diverse categorie di notifiche. Ti preghiamo di fare riferimento anche all'esempio sui prompt di invito dei giocatori su come i dati di avvio possono essere impostati e utilizzati.

Includi Dati di Avvio e Dati Analitici
local ServerScriptService = game:GetService("ServerScriptService")

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

-- Nel payload, "messageId" è il valore dell'ID asset della notifica
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

Sistema di consegna

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:

• I requisiti di idoneità dell'esperienza non sono soddisfatti.
• Il destinatario non è iscritto alle notifiche della tua esperienza.
• Il limite di attenuazione del destinatario per la tua esperienza è stato raggiunto.
• Il limite di attenuazione aggregato giornaliero del destinatario è stato raggiunto.
• Parametri di richiesta mancanti o non validi.
• La stringa di notifica è stata moderata.
• Per le notifiche con menzioni di utenti, la non consegna si verifica se si verifica una di queste condizioni:

  • Il ricevente e l'utente menzionato non sono amici.
  • L'utente menzionato ha selezionato No per "Aggiornare gli amici sulla mia attività?" nelle Impostazioni della Privacy → Altre Impostazioni nelle impostazioni del suo account Roblox.

Analitica

Performance delle tue notifiche e del pubblico notificabile sono visualizzate nella scheda Analisi della pagina Notifiche dove puoi configurare le stringhe di notifica (basta passare da Creazioni a Analisi).

1. Naviga al Creator Dashboard.
2. Simile ai badge, le stringhe di notifica sono legate a un gioco specifico. Trova la miniatura di quel gioco e clicca su di essa.
3. Nella colonna sinistra, sotto Coinvolgimento, clicca su Notifiche.
4. Nella pagina di destinazione, clicca sulla scheda Analisi per passare al cruscotto analitico.

Riepilogo delle notifiche

La sezione di riepilogo funge da istantanea delle prestazioni aggregate delle tue notifiche. È richiesto un minimo di 100 impressioni aggregate per visualizzare le statistiche delle prestazioni.

Statistiche dettagliate

La tabella delle Notifiche dell'Esperienza visualizza statistiche dettagliate sulle prestazioni di ogni notifica con almeno 100 visualizzazioni, ordinate per data della prima visualizzazione di quella notifica.

La colonna Nome è l'identificatore chiave per la notifica. Per impostazione predefinita, il nome corrisponde al nome dell'identificatore che hai specificato durante la creazione della stringa di notifica, ma puoi sovrascriverlo attraverso il campo category nelle tue chiamate API, nel qual caso category sovrascrive il nome. Modificare il nome della stringa nel Creator Dashboard o cambiare la stringa a cui fa riferimento il tuo ID messaggio nella chiamata API genererà una nuova riga nella tabella.

Se desideri effettuare un test A/B sulle prestazioni di diverse stringhe, è consigliabile creare una nuova stringa di notifica completamente nuova con un nome simile, ad esempio:

• EggHatchA — "Il tuo uovo d'oro è schiuso! Vieni a incontrare il tuo nuovo animale domestico."
• EggHatchB — "È ora di schiudere! Vieni a incontrare il tuo nuovo animale domestico."

Riferimenti API

Funzioni

createUserNotification

Invia una notifica da uno script lato server. Richiede il Player.UserId del destinatario e un UserNotification. Restituisce un UserNotificationResult.

Invia una notifica dell'esperienza
local ServerScriptService = game:GetService("ServerScriptService")

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

-- Nel payload, "messageId" è il valore dell'ID asset della notifica
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

Tipi

UserNotification

Tabella contenente i dettagli sulla notifica da inviare all'utente. Deve contenere una tabella payload con le stringhe messageId e type richieste, e tabelle parameters, joinExperience e analyticsData opzionali.

UserNotificationResult

Un oggetto wrapper che contiene la risposta da una notifica inviata. Contiene le seguenti coppie chiave-valore: