Erlebnisbenachrichtigungen

Erfahrungsbenachrichtigungen sind eine Möglichkeit für abgemeldete Nutzer, die 13 Jahre oder älter sind, um über ihre Lieblingsspiele durch rechtzeitige, personalisierte Benachrichtigungen auf dem Laufenden zu bleiben. Als Entwickler kannst du bestimmen, welche Arten von Aktivitäten im Spiel für deine Nutzer am wichtigsten sind, sowie den Inhalt der Benachrichtigungen festlegen.

Das Erlebnis-Benachrichtigungssystem bietet Folgendes:

• Anpassbare Benachrichtigungen mit Parametern — Vollständige Flexibilität, um die Benachrichtigungsnachricht mit Parametern anzupassen, zum Beispiel:

  Ihr Gold-Gans-Ei ist geschlüpft!

  Allie @LaterSk8er1 hat gerade Ihren Rekord auf der Tokyo Tour Strecke geschlagen!

• Startdaten — Fügen Sie optionale Startdaten hinzu, die beim Betreten des Benachrichtigungsempfängers über Player:GetJoinData() gelesen werden können. Dies könnte beinhalten, einen Benutzer zu einem Koordinatenstandort zu leiten oder sein Erlebnis beim Beitritt zu personalisieren.

• Analytik-Support — Verfolgen Sie Ihr erreichbares Publikum und die Leistung Ihrer Benachrichtigungen im Creator Dashboard.

Zulassungsvoraussetzungen

Um die APIs zum Senden von Benachrichtigungen nutzen zu können, muss das Spiel die folgenden Grundkriterien erfüllen:

• Mindestens 100 Besuche seit dem Start.
• Das Spiel darf sich nicht in der Moderation befinden.
• Sie als Entwickler müssen die Erlaubnis haben, das Spiel zu verwalten.

Nutzungsrichtlinien

Implementierung

Die Implementierung von Erlebnisbenachrichtigungen beginnt mit der Erstellung einer Benachrichtigungszeichenfolge und dem Einfügen des Pakets in Ihr Projekt. Sobald diese eingerichtet sind, können Sie Benachrichtigungen senden mit optionalen benutzerdefinierten Parametern.

Alternativ können Sie die Open Cloud API verwenden, um Benachrichtigungen über Freiform-API-Anfragen auszulösen.

Erstellen einer Benachrichtigungszeichenfolge

Wie bei Spielereinladungsaufforderungen müssen Sie Ihre Benachrichtigungsstrings im Creator Dashboard erstellen und bearbeiten. Es gibt keinen Standard-Spielbenachrichtigungsstring, daher ist dieser Schritt erforderlich.

1. Navigieren Sie zum Creator Dashboard.

2. Ähnlich wie bei Abzeichen sind Benachrichtigungsstrings an ein bestimmtes Spiel gebunden. Suchen Sie das Thumbnail dieses Spiels und klicken Sie darauf.

3. Klicken Sie in der linken Spalte unter Engagement auf Benachrichtigungen.

4. Klicken Sie im zentralen Bereich auf die Schaltfläche Benachrichtigungsstring erstellen.

5. Füllen Sie einen Identifikationsnamen aus (nur für Sie sichtbar) und den benutzerdefinierten Benachrichtigungsstring; dieser ist auf 99 Zeichen begrenzt und kann unbegrenzt benutzerdefinierte Parameter enthalten. Benachrichtigungen verwenden automatisch den Titel Ihres Spiels als Benachrichtigungstitel, aber Sie können zusätzlich {experienceName} verwenden, um Ihr Spiel im Textkörper der Benachrichtigung zu referenzieren.

   Beispielbenachrichtigungsstrings:

   Du bist {numQuests} Quests davon entfernt, die wöchentliche Herausforderung abzuschließen!

   Dein {eggName} ist geschlüpft! Komm und triff dein neues Haustier.

   Du hast in dieser Woche {numRaces} Rennen gewonnen und die Strecke {racetrackName} freigeschaltet!

   {userId-friend} hat gerade deinen Rekord auf der Strecke Tokyo Tour geschlagen! Zeit für Rache?

   Bitte überprüfen Sie die Richtlinien für die Verwendung des Systems, bevor Sie Benachrichtigungsstrings schreiben.

6. Wenn Sie bereit sind, klicken Sie auf die Schaltfläche Benachrichtigungsstring erstellen.

7. Auf der Benachrufungsseite, in der Tabelle der Benachrichtigungen, klicken Sie auf die Schaltfläche ⋯ in der Spalte Aktionen und wählen Sie Asset-ID kopieren.

8. Verwenden Sie die kopierte ID für den Wert des Schlüssels messageId in der payload-Tabelle, wie im Beispielskript dargestellt.

Paket einfügen

Um Erlebnisbenachrichtigungen zu implementieren, müssen Sie das Luau-Paket aus dem Creator Store beziehen.

1. Öffnen Sie im Studio-Menü Fenster oder in der Symbolleiste des Start-Tabs die Toolbox und wählen Sie den Creator Store-Tab.

   

2. Stellen Sie sicher, dass die Sortierung Modelle ausgewählt ist, und klicken Sie dann auf die Schaltfläche Alle anzeigen für Kategorien.

   

3. Suchen Sie die Kachel Pakete und klicken Sie darauf.

4. Suchen Sie das Open Cloud-Modul und klicken Sie darauf, oder ziehen Sie es in die 3D-Darstellung.

   

5. Verschieben Sie im Explorer-Fenster das gesamte OpenCloud-Modell in ServerScriptService.

Senden einer Erlebnisbenachrichtigung

Nachdem Sie eine Benachrichtigungszeichenfolge erstellt und das Paket in Ihr Projekt eingefügt haben, können Sie Benachrichtigungen von serverseitigen Skripten aus senden. Benachrichtigungen werden an opt-in Benutzer ab 13 Jahren über ihren Roblox-Benachrichtigungsstream gesendet, woraufhin sie direkt über die Schaltfläche Beitreten in der Benachrichtigung dem Erlebnis beitreten und gemäß Ihren Startdaten spawnen können.

Um eine grundlegende Benachrichtigung an einen bestimmten Benutzer zu senden, fügen Sie die Benachrichtigungszeichenfolgen-Asset-ID in das messageId-Feld der Payload ein und rufen Sie dann die createUserNotification-Funktion mit der Player.UserId des Empfängers und den Anforderungsdaten auf.

Senden einer Erlebnisbenachrichtigung
local ServerScriptService = game:GetService("ServerScriptService")

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

-- In der Payload ist "messageId" der Wert der Benachrichtigungs-Asset-ID
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

Benachrichtigungen mit Parametern anpassen

Um die Benachrichtigung für jeden Empfänger anzupassen, können Sie Parameter in die Benachrichtigungszeichenfolge einfügen und dann die Parameter beim Aufruf der API anpassen. Sie können die Benachrichtigungszeichenfolge zum Beispiel wie folgt definieren:

Setzen Sie dann die Parameter userId-friend und points im Skript:

Benachrichtigung mit Parametern anpassen
local ServerScriptService = game:GetService("ServerScriptService")

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

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

-- In der Payload ist "messageId" der Wert der Benachrichtigungs-Asset-ID
-- In diesem Beispiel lautet die Benachrichtigungszeichenfolge "{userId-friend} hat Ihren Höchstwert um {points} Punkte geschlagen! Zeit aufzuleveln?"
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

Benutzer auffordern, Benachrichtigungen zu aktivieren

Um Benutzer zu ermutigen, Benachrichtigungen für Ihr Erlebnis zu aktivieren, können Sie eine Erlaubnisaufforderung innerhalb des Erlebnisses an Benutzer ab 13 Jahren mithilfe der Methode ExperienceNotificationService:PromptOptIn() anzeigen.

Sie können die Aufforderung in jedem geeigneten Kontext innerhalb Ihres Erlebnisses auslösen, der eine zukünftige Benachrichtigung rechtfertigt. Der Text der Aufforderung ist nicht anpassbar und ist in allen Erlebnissen standardisiert.

Das Modal wird nicht angezeigt, wenn der Benutzer:

• Unter 13 Jahre alt ist.
• Bereits Benachrichtigungen für Ihr Erlebnis aktiviert hat.
• Die Erlaubnisaufforderung für Ihr Erlebnis in den letzten 30 Tagen bereits gesehen hat.

Um Benutzer zur Aktivierung von Benachrichtigungen aufzufordern, sollten Sie zunächst feststellen, ob der Benutzer berechtigt ist. Nachdem dies bestätigt wurde, können Sie die Erlaubnisaufforderung dem Benutzer anzeigen.

1. Rufen Sie ExperienceNotificationService:CanPromptOptInAsync() auf, umgeben von einem pcall(), da es sich um einen asynchronen Netzwerkaufruf handelt, der gelegentlich fehlschlagen kann.
2. Wenn der Benutzer aufgefordert werden kann, rufen Sie ExperienceNotificationService:PromptOptIn() auf.

LocalScript - Implementierung der Benachrichtigungsberechtigungsaufforderung
local ExperienceNotificationService = game:GetService("ExperienceNotificationService")

-- Funktion zur Überprüfung, ob der Spieler zur Aktivierung von Benachrichtigungen aufgefordert werden kann
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

-- Auf das Schließen der Opt-in-Aufforderung hören
ExperienceNotificationService.OptInPromptClosed:Connect(function()
	print("Opt-in-Aufforderung geschlossen")
end)

Start- und Analysedaten einbeziehen

Um das Benutzererlebnis weiter zu verbessern, können Sie Startdaten in der Benachrichtigung einfügen, die nützlich sind für Szenarien wie das Leiten von Benutzern zu einem Koordinatenstandort oder das Personalisieren des Beitritts. Zusätzlich können Sie Analyse-daten einfügen, um die Leistung verschiedener Kategorien von Benachrichtigungen zu segmentieren. Bitte sehen Sie sich auch das Beispiel zu Spielereinladungsaufforderungen an, wie Startdaten gesetzt und verwendet werden können.

Startdaten und Analysedaten einbeziehen
local ServerScriptService = game:GetService("ServerScriptService")

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

-- In der Payload ist "messageId" der Wert der Benachrichtigungs-Asset-ID
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

Liefersystem

Ein Spam-Präventionssystem existiert, um die Qualität der Benachrichtigungen für Benutzer sicherzustellen und den gemeinsamen Benachrichtigungskanal für alle Entwickler zu schützen. Wegen dieses Systems ist die Zustellung von Benachrichtigungen nicht garantiert. Dieses Spam-Präventionssystem wird direkt durch das Engagement der Benutzer informiert: Je mehr Benutzer mit Ihren Benachrichtigungen interagieren, desto mehr Reichweite erhalten sie. Sie können Engagement-Metriken transparent im Analysedashboard verfolgen, wie unten erklärt.

Erlebnisbenachrichtigungen haben ein statisches Drossellimit; jeder Benutzer kann von einem gegebenen Erlebnis einmal pro Tag eine Benachrichtigung erhalten, und Sie erhalten transparentes Feedback, wenn das Drossellimit eines Benutzers erreicht ist.

Zusätzlich skizziert die folgende Liste einige der Sonderfälle, die zu einer Nichtzustellung einer Benachrichtigung führen können:

• Die Eignungsanforderungen für das Erlebnis sind nicht erfüllt.
• Der Empfänger hat sich nicht für Benachrichtigungen von Ihrem Erlebnis angemeldet.
• Das Drossellimit des Empfängers für Ihr Erlebnis wurde erreicht.
• Das gesamte tägliche Drossellimit des Empfängers wurde erreicht.
• Fehlende oder ungültige Anforderungsparameter.
• Der Benachrichtigungstext wurde moderiert.
• Bei Benachrichtigungen mit Benutzererwähnungen tritt eine Nichtzustellung ein, wenn eine dieser Bedingungen erfüllt ist:

  • Der Empfänger und der erwähnte Benutzer sind keine Freunde.
  • Der erwähnte Benutzer hat Nein für "Freunde über meine Aktivitäten informieren?" unter Datenschutz → Sonstige Einstellungen in seinen Roblox-Kontoeinstellungen ausgewählt.

Analytik

Performance 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. Navigieren Sie zum Creator Dashboard.
2. Ähnlich wie bei Abzeichen sind Benachrichtigungsstrings an ein bestimmtes Spiel gebunden. Suchen Sie das Thumbnail dieses Spiels und klicken Sie darauf.
3. Klicken Sie in der linken Spalte unter Engagement auf Benachrichtigungen.
4. Klicken Sie auf der Zielseite auf den Analytics-Tab, um zum Analysedashboard zu wechseln.

Benachrichtigungsübersicht

Der Zusammenfassungsabschnitt dient als Übersicht über die aggregierte Leistung Ihrer Benachrichtigungen. Es sind mindestens 100 aggregierte Impressionen erforderlich, um die Leistungsstatistiken anzuzeigen.

Detaillierte Statistiken

Die Erfahrungsbenachrichtigungen-Tabelle zeigt detaillierte Leistungsstatistiken für jede Benachrichtigung mit mindestens 100 Impressionen, sortiert nach dem Datum der ersten Impression für diese Benachrichtigung.

Die Name-Spalte ist der Schlüsselidentifikator für die Benachrichtigung. Standardmäßig entspricht der Name dem Identifikatornamen, den Sie beim Erstellen der Benachrichtigungskette angegeben haben, aber Sie können ihn über das category-Feld in Ihren API-Aufrufen überschreiben; in diesem Fall überschreibt category den Namen. Das Ändern des Stringnamens im Creator Dashboard oder das Ändern des Strings, auf den Ihre Nachrichten-ID in dem API-Aufruf verweist, erzeugt eine neue Zeile in der Tabelle.

Wenn Sie die Leistung verschiedener Strings A/B testen möchten, wird empfohlen, eine völlig neue Benachrichtigungskette mit einem ähnlichen Namen zu erstellen, zum Beispiel:

• EggHatchA — "Ihr goldenes Ei ist geschlüpft! Kommen Sie und treffen Sie Ihr neues Haustier."
• EggHatchB — "Es ist die Zeit des Schlüpfens! Kommen Sie und treffen Sie Ihr neues Haustier."

API-Referenz

Funktionen

createUserNotification

Sendet eine Benachrichtigung aus einem serverseitigen Skript. Erfordert die Player.UserId des Empfängers und eine UserNotification. Gibt einen UserNotificationResult zurück.

Senden einer Erlebnisbenachrichtigung
local ServerScriptService = game:GetService("ServerScriptService")

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

-- In der Payload ist "messageId" der Wert der Benachrichtigungs-Asset-ID
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

Typen

UserNotification

Tabelle, die Details zur zu sendenden Benachrichtigung enthält. Muss eine payload-Tabelle mit erforderlichen messageId- und type-Strings sowie optionalen parameters, joinExperience- und analyticsData-Tabellen enthalten.

UserNotificationResult

Ein Wrapper-Objekt, das die Antwort von einer gesendeten Benachrichtigung enthält. Enthält die folgenden Schlüssel-Wert-Paare: