Notifications d'expérience

Les notifications d'expérience sont un moyen pour les utilisateurs ayant opté pour cette option âgés de 13 ans et plus de suivre leurs jeux préférés grâce à des notifications personnalisées et opportunes. En tant que développeur, vous pouvez déterminer quels types d'activités dans le jeu sont les plus importants à notifier à vos utilisateurs, ainsi que définir le contenu des notifications.

Le système de notification d'expérience comprend les éléments suivants :

• Notifications personnalisables avec paramètres — Flexibilité totale pour personnaliser le message de notification avec des paramètres, par exemple :

  Votre œuf d'oie en or a éclos !

  Allie @LaterSk8er1 vient de battre votre record sur le circuit Tokyo Tour !

• Données de lancement — Incluez des données de lancement optionnelles qui peuvent être lues via Player:GetJoinData() lorsque le destinataire de la notification rejoint. Cela pourrait impliquer de diriger un utilisateur vers un emplacement de coordonnées ou de personnaliser son expérience de bienvenue.

• Support analytique — Suivez votre audience atteignable et la performance de vos notifications dans le Tableau de bord Créateur.

Exigences d'éligibilité

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.

Directives d'utilisation

Implémentation

L'implémentation des notifications d'expérience commence par la création d'une chaîne de notification et l'inclusion du package dans votre projet. Une fois ces éléments en place, vous pouvez envoyer des notifications avec des paramètres personnalisés optionnels.

Alternativement, vous pouvez utiliser l'Open Cloud API pour déclencher des notifications via des requêtes API libre.

Créer une chaîne de notification

As with Player Invite Prompts, you must create and edit your notification strings in the Creator Dashboard. Il n'y a pas de chaîne de notification par défaut pour le jeu, donc cette étape est requise.

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.

   Exemple de chaînes de notification :

   Il vous reste {numQuests} quêtes pour compléter le défi hebdomadaire !

   Votre {eggName} a éclos ! Venez rencontrer votre nouvel animal de compagnie.

   Vous avez gagné {numRaces} courses cette semaine et débloqué le circuit {racetrackName} !

   {userId-friend} vient de battre votre record sur le circuit Tokyo Tour ! Prêt pour la revanche ?

   Avant d'écrire des chaînes de notification, veuillez consulter les directives pour l'utilisation du système.

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.

Inclure le package

Pour implémenter des notifications d'expérience, vous devez obtenir le package Luau dans le Creator Store.

1. Dans le menu Fenêtre de Studio ou la barre d'outils de l'onglet Accueil, ouvrez le Toolbox et sélectionnez l'onglet Creator Store.

   

2. Assurez-vous que le tri par Modèles est sélectionné, puis cliquez sur le bouton Voir Tout pour Catégories.

   

3. Trouvez et cliquez sur le carreau Packages.

4. Trouvez le module Open Cloud et cliquez dessus, ou faites-le glisser dans la vue 3D.

   

5. Dans la fenêtre Explorateur, déplacez le modèle OpenCloud entier dans ServerScriptService.

Envoyer une notification d'expérience

Une fois que vous avez créé une chaîne de notification et inclus le package dans votre projet, vous pouvez envoyer des notifications depuis des scripts côté serveur. Les notifications seront délivrées aux utilisateurs de 13 ans et plus qui ont accepté via leur flux de notifications Roblox, à quel point ils peuvent rejoindre l'expérience directement via le bouton Rejoindre sur la notification et se spawn selon vos données de lancement.

Pour envoyer une notification de base à un utilisateur spécifique, incluez l'ID d'actif de la chaîne de notification dans le champ messageId de la charge utile, puis appelez la fonction createUserNotification avec le Player.UserId du destinataire et les données de la requête.

local ServerScriptService = game:GetService("ServerScriptService")

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

-- Dans la charge utile, "messageId" est la valeur de l'ID d'actif de la notification
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

Personnaliser les notifications à l'aide de paramètres

Pour personnaliser la notification pour chaque destinataire, vous pouvez inclure des paramètres dans la chaîne de notification, puis personnaliser les paramètres lors de l'appel de l'API. Par exemple, vous pouvez définir la chaîne de notification comme suit :

Ensuite, définissez les paramètres userId-friend et points dans le script :

local ServerScriptService = game:GetService("ServerScriptService")

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

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

-- Dans la charge utile, "messageId" est la valeur de l'ID d'actif de la notification
-- Dans cet exemple, la chaîne de notification est "{userId-friend} a battu votre meilleur score de {points} points ! Il est temps de monter en niveau ?"
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

Inviter les utilisateurs à activer les notifications

Pour encourager les utilisateurs à activer les notifications pour votre expérience, vous pouvez afficher une invite de permission au sein de l'expérience pour les utilisateurs âgés de 13 ans et plus en utilisant la méthode ExperienceNotificationService:PromptOptIn().

Vous pouvez déclencher l'invite dans tout contexte approprié de votre expérience qui nécessite une notification future. Le texte de l'invite n'est pas personnalisable et est standardisé à travers toutes les expériences.

La fenêtre modale n'apparaîtra pas si l'utilisateur :

• A moins de 13 ans.
• A déjà activé les notifications pour votre expérience.
• A déjà vu l'invite de permission pour votre expérience au cours des 30 derniers jours.

Pour inviter les utilisateurs à activer les notifications, vous devez d'abord déterminer si l'utilisateur est éligible. Une fois confirmé, vous pouvez afficher l'invite de permission à l'utilisateur.

1. Appelez ExperienceNotificationService:CanPromptOptInAsync(), enveloppé dans un pcall() car c'est un appel réseau asynchrone qui peut échouer occasionnellement.
2. Si l'utilisateur peut être invité, appelez ExperienceNotificationService:PromptOptIn().

local ExperienceNotificationService = game:GetService("ExperienceNotificationService")

-- Fonction pour vérifier si le joueur peut être invité à activer les notifications
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

-- Écoutez l'événement de fermeture de l'invite d'opt-in
ExperienceNotificationService.OptInPromptClosed:Connect(function()
	print("Invite d'opt-in fermée")
end)

Inclure des données de lancement et des données analytiques

Pour améliorer encore l'expérience utilisateur, vous pouvez inclure des données de lancement dans la notification, utiles pour des scénarios tels que diriger les utilisateurs vers un emplacement de coordonnées ou personnaliser l'expérience de bienvenue. De plus, vous pouvez inclure des données analytiques pour segmenter la performance des différentes catégories de notifications. Veuillez également consulter l'exemple des invites d'invitation des joueurs sur la façon dont les données de lancement peuvent être définies et utilisées.

local ServerScriptService = game:GetService("ServerScriptService")

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

-- Dans la charge utile, "messageId" est la valeur de l'ID d'actif de la notification
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

Système de livraison

Un système de prévention de spam existe pour garantir la qualité des notifications pour les utilisateurs et protéger le canal de notification partagé pour tous les développeurs. En raison de cela, la livraison des notifications n'est pas garantie. Ce système de prévention de spam est directement informé par l'engagement des utilisateurs : plus les utilisateurs interagissent avec vos notifications, plus elles atteindront un large public. Vous pouvez suivre de manière transparente les métriques d'engagement dans le tableau de bord analytique, comme expliqué ci-dessous.

Les notifications d'expérience ont une limite de throttle statique ; chaque utilisateur peut recevoir une notification par jour d'une expérience donnée, et vous recevez un retour transparent lorsque la limite de throttle d'un utilisateur est atteinte.

De plus, la liste suivante décrit certains des cas particuliers qui peuvent entraîner la non-livraison d'une notification :

• Les exigences d'éligibilité de l'expérience ne sont pas remplies.
• Le destinataire n'est pas inscrit aux notifications de votre expérience.
• La limite de throttle du destinataire pour votre expérience a été atteinte.
• La limite de throttle quotidienne agrégée du destinataire a été atteinte.
• Paramètres de requête manquants ou invalides.
• La chaîne de notification a été modérée.
• Pour les notifications avec mentions d'utilisateur, la non-livraison se produit si l'une de ces conditions est remplie :

  • Le destinataire et l'utilisateur mentionné ne sont pas amis.
  • L'utilisateur mentionné a sélectionné Non pour "Informer les amis de mon activité ?" sous Confidentialité → Autres Paramètres dans les paramètres de compte Roblox.

Analytique

Performance de vos notifications et audience notifiable sont affichées dans l'onglet Analytics de la page Notifications où vous configurez les chaînes de notification (il suffit de passer de Créations à Analytics).

1. Naviguez vers le Tableau de bord du créateur.
2. Similar à badges, les chaînes de notification sont liées à un jeu spécifique. Localisez la miniature de ce jeu et cliquez dessus.
3. Dans la colonne de gauche, sous Engagement, cliquez sur Notifications.
4. Sur la page cible, cliquez sur l'onglet Analytics pour passer au tableau de bord analytique.

Résumé des notifications

La section résumé sert de aperçu des performances agrégées de vos notifications. Un minimum de 100 impressions agrégées est requis pour afficher les statistiques de performance.

Statistiques détaillées

La table des Notifications d'Expérience affiche des statistiques de performance détaillées pour chaque notification avec au moins 100 impressions, ordonnées par la date de première impression de cette notification.

La colonne Nom est l'identifiant clé pour la notification. Par défaut, le nom correspond au nom de l'identifiant que vous avez spécifié lors de la création de la chaîne de notification, mais vous pouvez le remplacer par le champ category dans vos appels d'API, auquel cas category remplace le nom. Changer le nom de la chaîne dans le Tableau de bord du Créateur ou changer la chaîne à laquelle fait référence votre ID de message dans l'appel API générera une nouvelle ligne dans la table.

Si vous souhaitez tester les performances de différentes chaînes en A/B, il est recommandé de créer une toute nouvelle chaîne de notification avec un nom similaire, par exemple :

• EggHatchA — "Votre œuf d'or a éclos ! Venez rencontrer votre nouvel animal de compagnie."
• EggHatchB — "C'est l'heure de l'éclosion ! Venez rencontrer votre nouvel animal de compagnie."

Référence API

Fonctions

createUserNotification

Envoie une notification depuis un script côté serveur. Nécessite le Player.UserId du destinataire et un UserNotification. Retourne un UserNotificationResult.

local ServerScriptService = game:GetService("ServerScriptService")

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

-- Dans la charge utile, "messageId" est la valeur de l'ID d'actif de la notification
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

Types

UserNotification

Table contenant les détails sur la notification à envoyer à l'utilisateur. Doit contenir une table payload avec des chaînes messageId et type requises, ainsi que des tables parameters, joinExperience et analyticsData optionnelles.

UserNotificationResult

Un objet d'encapsulation qui contient la réponse d'une notification envoyée. Contient les paires clé-valeur suivantes :