Notifications d'expérience

Les notifications d'expérience sont un moyen pour les utilisateurs opt-in âgés de 13 ans et plus de suivre leurs expériences préférées grâce à des notifications personnalisées et opportunes.En tant que développeur, vous pouvez déterminer quelles sortes d'activités en expérience sont les plus importantes pour informer vos utilisateurs, ainsi que définir le contenu de la notification.

Le système de notification d'expérience comporte les éléments suivre:

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

  Your gold goose egg has hatched!

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

• Données de lancement — Inclure des données de lancement optionnelles qui peuvent être lues via lorsque le destinataire de notification rejoint.Cela pourrait impliquer la redirection d'un utilisateur vers une position de coordonnées ou la personnalisation de son expérience de raccord.

• Support d'analyses — Suivez votre audience accessible et les performances de vos notifications dans le tableau de bord du créateur.

Exigences d'éligibilité

Pour utiliser les API pour envoyer des notifications, l'expérience doit répondre aux critères de base suivants :

• Minimum de 100 visites depuis le lancer.
• L'expérience ne doit pas être modérée.
• Vous en tant que développeur devez avoir la permission de gérer l'expérience.

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 inclut le paquet dans votre projet.Une fois ces derniers configurés, vous pouvez envoyer des notifications avec des paramètres personnalisés optionnels .

Alternativement, vous pouvez utiliser la Open Cloud API pour déclencher des notifications via des demandes d'API en libre forme.

Créer une chaîne de notification

Comme avec invitations de joueurs, vous devez créer et modifier vos chaînes de notification dans le tableau de bord du créateur. Il n'y a pas de chaîne de notification d'expérience par défaut, donc cette étape est requise.

1. Accédez à la tableau de bord du créateur.

2. Semblable à badges, les chaînes de notification sont liées à une expérience spécifique . Localisez la vignette de cette expérience et cliquez dessus.

3. Dans la colonne de gauche, sous Engagement , cliquez sur Notifications .

4. Dans la région centrale, cliquez sur le bouton Créer une chaîne de notification .

5. Remplissez un nom d'identifiant (visible uniquement pour vous) et la chaîne de notification personnalisée ; cela est limité à 99 caractères et peut inclure des paramètres personnalisés illimités ..Les notifications utiliseront automatiquement le titre de votre expérience comme titre de notification, mais vous pouvez également utiliser experienceName pour référencer votre expérience dans le texte du corps de la notification.

   Exemples de chaînes de notification :

   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?

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

6. Lorsque vous êtes prêt, cliquez sur le bouton Créer une chaîne de notification .

7. Sur la page des notifications, dans la table des notifications, cliquez sur le bouton ⋯ dans la colonne Actions et sélectionnez Copier l'ID de la ressource .

8. Utilisez l'ID copié pour la valeur de clé messageId dans la table payload comme démontré dans le script d'exemple.

Inclure le paquet

Pour implémenter les notifications d'expérience, vous devez obtenir le paquet Luau auprès de la boutique des créateurs.

1. De l'onglet Affichage, ouvrez la boîte à outils et sélectionnez l'onglet boutique des créateurs .

   

2. Assurez-vous que le tri des modèles est sélectionné, puis cliquez sur le bouton Voir tout pour les catégories .

   

3. Localisez et cliquez sur la case modules de développement .

   

4. Localisez le module Ouvrir le cloud et cliquez dessus, ou glissez-déposez-le dans la voir3D.

   

5. Dans la fenêtre Explorateur, déplacez l'ensemble du modèle OpenCloud 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 à partir de scripts côté serveur.Les notifications seront livrées à opt-in utilisateurs âgés de 13 ans et plus via leur flux de notification Roblox, à ce moment-là, ils peuvent rejoindre l'expérience directement via le bouton Rejoindre sur la notification et apparaître selon vos données de lancement .

Pour envoyer une notification de base à un utilisateur spécifique, incluez l'ID de ressource de la chaîne de notification dans le champ du corps du message, puis appelez la fonction createUserNotification avec les données de demande du destinataire et les données de demande.

Envoyer une notification d'expérience
local ServerScriptService = game:GetService("ServerScriptService")

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

-- Dans le corps du message, "messageId" est la valeur de l'ID de la ressource de 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 en utilisant des paramètres

Pour personnaliser la notification pour chaque destinataire, vous pouvez inclure 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 :

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

Personnaliser la notification en utilisant des paramètres
local ServerScriptService = game:GetService("ServerScriptService")

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

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

-- Dans le corps du message, "messageId" est la valeur de l'ID de la ressource de notification
-- Dans cet exemple, la chaîne de notification est « {userId-friend} bat votre record de {points} points ! Il est temps de passer au niveau supérieur ? »
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

Invitez les utilisateurs à activer les notifications

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

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

La modalité ne 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 la demande d'autorisation pour votre expérience au cours des 30 derniers jours.

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

1. Appellez 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() .

LocalScript - Implémentation de la demande d'autorisation de notification
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

-- Écouter l'événement d'acceptation fermé
ExperienceNotificationService.OptInPromptClosed:Connect(function()
	print("Opt-in prompt closed")
end)

Inclure les données de lancement et d'analyse

Pour améliorer encore l'expérience utilisateur, vous pouvez inclure les données de lancement dans la notification, utiles pour des scénarios tels que l'orientation des utilisateurs vers un lieu coordonné ou la personnalisation de l'expérience de raccord.En outre, vous pouvez inclure des données d'analyse analytiques pour segmenter les performances de différentes catégories de notifications.Veuillez également vous référer à l'exemple invitations de joueur sur la façon dont les données de lancement peuvent être définies et utilisées.

Inclure les données de lancement et les données d'analyse
local ServerScriptService = game:GetService("ServerScriptService")

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

-- Dans le corps du message, "messageId" est la valeur de l'ID de la ressource de 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 du 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 de notifications n'est pas garantie.Ce système de prévention du spam est directement informé par l'participationdes utilisateurs : plus les utilisateurs interagissent avec vos notifications, plus ils recevront de portée.Vous pouvez suivre transparentement les métriques d'engagement dans le tableau de bord analytics, comme expliqué ci-dessous.

Les notifications d'expérience ont une limite de débit statique ; chaque utilisateur peut recevoir une notification par jour à partir d'une expérience donnée, et vous recevez des commentaires transparents lorsque la limite de débit d'un utilisateur est atteinte.

En outre, la liste suivante décrit quelques-uns des cas spéciaux pouvant entraîner non-livraison d'une notification :

• Les exigences d'éligibilité expérience ne sont pas respectées.
• Le destinataire n'a pas opté pour les notifications de votre expérience.
• La limite de débit du destinataire pour votre expérience a été atteinte.
• La limite globale de restriction quotidienne du destinataire a été atteinte.
• Paramètres de requête manquants ou non valides.
• Chaîne de notification modérée.
• Pour les notifications avec des mentions d'utilisateur, la non-livraison se produit si l'une de ces conditions est remplie :

  • Le récepteur et l'utilisateur mentionné ne sont pas amis.
  • L'utilisateur mentionné n'a pas Non sélectionné pour "Mettre à jour les amis sur mon activité?" sous Confidentialité → autres paramètres dans les paramètres de leur compte Roblox.

Analyses

Les performances de vos notifications et de votre audience notifiable sont affichées dans l'onglet Analytics de la page notifications où vous configurez les chaînes de notification (simplement tab de Créations à Analytics ).

1. Accédez à la tableau de bord du créateur.
2. Semblable à badges, les chaînes de notification sont liées à une expérience spécifique . Localisez la vignette de cette expérience 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 d'analyses.

sommairedes notifications

La section résumé sert de point de capture de la performance globale 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 notifications d'expérience affiche des statistiques de performance détaillées pour chaque notification avec au moins 100 impressions, triées par la date de la première impression pour cette notification.

La colonne Nom est l'identifiant clé de la notification.Par défaut, le nom correspond au nom d'identifiant que vous avez spécifié lors de la création de la chaîne de notification , mais vous pouvez l'annuler via le champ dans vos appels d'API, auquel cas remplace le nom.Changer le nom de la chaîne dans le tableau de bord du créateur ou modifier la chaîne à laquelle votre ID de message se réfère dans l'appel de l'API générera une nouvelle ligne dans la table.

Si vous souhaitez tester A/B la performance de différentes chaînes, il est recommandé de créer une nouvelle chaîne de notification entièrement nouvelle avec un nom similaire, par exemple :

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

Référence de l'API

Fonctions

créerNotification d'utilisateur

Envoie une notification à partir d'un script côté serveur.Nécessite le Player.UserId du destinataire et une notification d'utilisateur.Retourne un résultat de notification d'utilisateur.

Envoyer une notification d'expérience
local ServerScriptService = game:GetService("ServerScriptService")

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

-- Dans le corps du message, "messageId" est la valeur de l'ID de la ressource de 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

Les types

Notification d'utilisateur

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

Résultat de notification d'utilisateur

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