Ervaringsmeldingen

Ervaringsmeldingen zijn een manier voor ingeschreven gebruikers van 13 jaar en ouder om op de hoogte te blijven van hun favoriete games via tijdige, gepersonaliseerde meldingen. Als ontwikkelaar kun je bepalen welke soorten in-game activiteiten het belangrijkst zijn om je gebruikers over te informeren, evenals de inhoud van de meldingen.

Het ervaringsmeldingssysteem heeft de volgende kenmerken:

• Aanpasbare meldingen met parameters — Volledige flexibiliteit om de meldingsboodschap aan te passen met parameters, bijvoorbeeld:

  Je gouden gans ei is uitgekomen!

  Allie @LaterSk8er1 heeft net jouw record op het Tokyo Tour-circuit verbroken!

• Startgegevens — Voeg optionele startgegevens toe die kunnen worden gelezen via Player:GetJoinData() wanneer de ontvanger van de melding zich aanmeldt. Dit kan inhouden dat een gebruiker naar een coördinaatlocatie wordt geleid of dat hun aanmeldervaring wordt gepersonaliseerd.

• Analytics-ondersteuning — Volg je bereikbare publiek en de prestaties van je meldingen in het Creator Dashboard.

Geschiktheidseisen

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.

Gebruik richtlijnen

Implementatie

Het implementeren van ervaringsmeldingen begint met het maken van een meldingsstring en het opnemen van het pakket in je project. Zodra deze zijn ingesteld, kun je meldingen verzenden met optionele aangepaste parameters.

Alternatief kun je de Open Cloud API gebruiken om meldingen te activeren via vrije API-aanroepen.

Maak een meldingsstring

As with Player Invite Prompts, you must create and edit your notification strings in the Creator Dashboard. Er is geen standaard game-meldingsstring, dus deze stap is vereist.

1. Navigeer naar het Creator Dashboard.

2. Net als bij badges zijn meldingsstrings gekoppeld aan een specifieke game. Zoek de thumbnail van die game en klik erop.

3. In de linker kolom, onder Betrokkenheid, klik op Meldingen.

4. In het middengebied, klik op de knop Maak een meldingsstring.

5. Vul een identificatienaam in (alleen zichtbaar voor jou) en de aangepaste meldingsstring; deze is beperkt tot 99 tekens en kan onbeperkte aangepaste parameters bevatten. Meldingen gebruiken automatisch de titel van je game als de meldingtitel, maar je kunt ook {experienceName} gebruiken om naar je game te verwijzen in de tekst van de melding.

   Voorbeeld meldingsstrings:

   Je bent {numQuests} quests verwijderd van het voltooien van de wekelijkse uitdaging!

   Je {eggName} is uitgekomen! Kom je nieuwe huisdier ontmoeten.

   Je hebt deze week {numRaces} races gewonnen en het {racetrackName} circuit ontgrendeld!

   {userId-friend} heeft net jouw record op het Tokyo Tour circuit verbroken! Tijd voor wraak?

   Voordat je meldingsstrings schrijft, bekijk de richtlijnen voor het gebruik van het systeem.

6. Wanneer je klaar bent, klik op de knop Maak meldingsstring.

7. Op de meldingenpagina, in de tabel met meldingen, klik op de ⋯ knop in de Acties kolom en selecteer Kopieer asset-ID.

8. Gebruik de gekopieerde ID voor de messageId sleutelwaarde in de payload tabel zoals gedemonstreerd in het voorbeeldscript.

Neem het pakket op

Om ervaringsmeldingen te implementeren, moet je het Luau-pakket verkrijgen uit de Creator Store.

1. Open vanuit het Venster-menu of de Start-tabbladwerkbalk de Toolbox en selecteer het tabblad Creator Store.

   

2. Zorg ervoor dat de sortering op Modellen is geselecteerd, klik vervolgens op de knop Zie Alles voor Categorieën.

   

3. Zoek en klik op de tegel Pakketten.

4. Zoek de Open Cloud-module en klik erop, of sleep het naar de 3D-weergave.

   

5. Verplaats in het Explorer-venster het hele OpenCloud-model naar ServerScriptService.

Stuur een ervaringsmelding

Zodra je een meldingsstring hebt gemaakt en het pakket in je project hebt opgenomen, kun je meldingen verzenden vanuit server-side scripts. Meldingen worden afgeleverd aan ingeschreven gebruikers van 13 jaar en ouder via hun Roblox-meldingsstroom, waarna ze zich rechtstreeks via de knop Deelnemen op de melding kunnen aanmelden en spawnen volgens jouw startgegevens.

Om een basismelding naar een specifieke gebruiker te sturen, neem je de meldingsstring asset ID op in het messageId-veld van de payload en roep je de createUserNotification functie aan met de Player.UserId van de ontvanger en de aanvraaggegevens.

local ServerScriptService = game:GetService("ServerScriptService")

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

-- In de payload is "messageId" de waarde van de meldingsasset 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

Pas meldingen aan met parameters

Om de melding voor elke ontvanger aan te passen, kun je parameters opnemen in de meldingsstring en vervolgens de parameters aanpassen bij het aanroepen van de API. Je kunt bijvoorbeeld de meldingsstring definiëren als:

Stel vervolgens de userId-vriend en punten parameters in het script in:

local ServerScriptService = game:GetService("ServerScriptService")

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

local userIdVriendParam = {int64Value = 3702832553}
local puntenParam = {stringValue = "5"}

-- In de payload is "messageId" de waarde van de meldingsasset ID
-- In dit voorbeeld is de meldingsstring "{userId-vriend} heeft jouw hoogste score met {punten} punten verbroken! Tijd om te levelen?"
local userNotification = {
	payload = {
		messageId = "ef0e0790-e2e8-4441-9a32-93f3a5783bf1",
		type = "MOMENT",
		parameters = {
			["userId-vriend"] = userIdVriendParam,
			["punten"] = puntenParam
		}
	}
}

local result = OCUserNotification.createUserNotification(recipientPlayerID, userNotification)

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

Vraag gebruikers om meldingen in te schakelen

Om gebruikers aan te moedigen meldingen voor jouw ervaring in te schakelen, kun je een toestemmingprompt binnen de ervaring weergeven aan gebruikers van 13 jaar en ouder met behulp van de ExperienceNotificationService:PromptOptIn()-methode.

Je kunt de prompt in elke geschikte context binnen jouw ervaring activeren die een toekomstige melding rechtvaardigt. De tekst van de prompt is niet aanpasbaar en is gestandaardiseerd voor alle ervaringen.

De modal verschijnt niet als de gebruiker:

• Jonger is dan 13 jaar.
• Al meldingen voor jouw ervaring heeft ingeschakeld.
• De toestemmingprompt voor jouw ervaring in de afgelopen 30 dagen al heeft gezien.

Om gebruikers om meldingen in te schakelen te vragen, moet je eerst bepalen of de gebruiker in aanmerking komt. Zodra dit is bevestigd, kun je de toestemmingprompt aan de gebruiker weergeven.

1. Roep ExperienceNotificationService:CanPromptOptInAsync() aan, ingepakt in een pcall() omdat het een asynchrone netwerkoproep is die af en toe kan mislukken.
2. Als de gebruiker kan worden gevraagd, roep dan ExperienceNotificationService:PromptOptIn() aan.

local ExperienceNotificationService = game:GetService("ExperienceNotificationService")

-- Functie om te controleren of de speler kan worden gevraagd om meldingen in te schakelen
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

-- Luister naar het evenement dat de opt-in prompt is gesloten
ExperienceNotificationService.OptInPromptClosed:Connect(function()
	print("Opt-in prompt gesloten")
end)

Neem start- en analyticsgegevens op

Om de gebruikerservaring verder te verbeteren, kun je startgegevens opnemen in de melding, nuttig voor scenario's zoals het leiden van gebruikers naar een coördinaatlocatie of het personaliseren van de aanmeldervaring. Daarnaast kun je analytics gegevens opnemen om de prestaties van verschillende categorieën meldingen te segmenteren. Raadpleeg ook het voorbeeld van Speler uitnodigingsprompts over hoe startgegevens kunnen worden ingesteld en gebruikt.

local ServerScriptService = game:GetService("ServerScriptService")

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

-- In de payload is "messageId" de waarde van de meldingsasset 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

Leveringssysteem

A spampreventiesysteem bestaat om de kwaliteit van meldingen voor gebruikers te waarborgen en het gedeelde meldingskanaal voor alle ontwikkelaars te beschermen. Vanwege dit systeem is de levering van meldingen niet gegarandeerd. Dit spampreventiesysteem wordt rechtstreeks beïnvloed door de betrokkenheid van gebruikers: hoe meer gebruikers betrokken zijn bij uw meldingen, hoe meer bereik ze zullen ontvangen. U kunt de betrokkenheidsstatistieken transparant volgen in het analysemenu, zoals hieronder uitgelegd.

Ervaringsmeldingen hebben een statische throttlinglimiet; elke gebruiker kan één melding per dag ontvangen van een bepaalde ervaring, en u ontvangt transparante feedback wanneer de throttlinglimiet van een gebruiker is bereikt.

Bovendien schetst de volgende lijst enkele van de speciale gevallen die kunnen leiden tot niet-levering van een melding:

• Er zijn niet voldaan aan de geschiktheidseisen voor de ervaring.
• De ontvanger heeft zich niet aangemeld voor meldingen van uw ervaring.
• De throttlinglimiet van de ontvanger voor uw ervaring is bereikt.
• De totale dagelijkse throttlinglimiet van de ontvanger is bereikt.
• Ontbrekende of ongeldige aanvraagparameters.
• De meldingsstring is gemodereerd.
• Voor meldingen met gebruikersvermeldingen vindt niet-levering plaats als aan een van deze voorwaarden is voldaan:

  • De ontvanger en de genoemde gebruiker zijn geen vrienden.
  • De genoemde gebruiker heeft Nee geselecteerd voor "Vrienden op de hoogte houden van mijn activiteit?" onder Privacy → Andere Instellingen in hun Roblox-accountinstellingen.

Analytics

Performance van uw meldingen en meldbare publiek worden weergegeven in het Analytics tabblad van de Notifications pagina waar u meldingsstrings configureert (simply tab van Creations naar Analytics).

1. Navigeer naar het Creator Dashboard.
2. Net als bij badges, zijn meldingsstrings gekoppeld aan een specifiek spel. Zoek de thumbnail van dat spel en klik erop.
3. In de linkerkolom, onder Engagement, klik op Notifications.
4. Op de doelpagina, klik op het Analytics tabblad om over te schakelen naar het analytics dashboard.

Meldingenoverzicht

De samenvattingssectie dient als een momentopname van de totale prestaties van uw meldingen. Een minimum van 100 totale impressies is vereist om de prestatiestatistieken weer te geven.

Gedetailleerde statistieken

De Ervaringsmeldingen tabel toont gedetailleerde prestatiestatistieken voor elke melding met ten minste 100 vertoningen, gesorteerd op de datum van de eerste vertoning voor die melding.

De Naam kolom is de belangrijkste identifier voor de melding. Standaard komt de naam overeen met de identifier naam die je hebt opgegeven bij het maken van de meldingsstring, maar je kunt deze overschrijven via het category veld in je API-aanroepen, in welk geval category de naam overschrijft. Het wijzigen van de stringnaam in het Creator Dashboard of het wijzigen van de string waar je bericht-ID naar verwijst in de API-aanroep zal een nieuwe rij in de tabel genereren.

Als je de prestaties van verschillende strings wilt A/B-testen, is het aan te raden om een geheel nieuwe meldingsstring te maken met een vergelijkbare naam, bijvoorbeeld:

• EggHatchA — "Je gouden ei is uitgekomen! Kom je nieuwe huisdier ontmoeten."
• EggHatchB — "Het is tijd om uit te komen! Kom je nieuwe huisdier ontmoeten."

API-referentie

Functies

createUserNotification

Verzendt een melding vanuit een server-side script. Vereist de Player.UserId van de ontvanger en een UserNotification. Retourneert een UserNotificationResult.

local ServerScriptService = game:GetService("ServerScriptService")

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

-- In de payload is "messageId" de waarde van de meldingsasset 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

Types

UserNotification

Tabel met details over de melding die naar de gebruiker moet worden verzonden. Moet een payload-tabel bevatten met vereiste messageId en type-strings, en optionele parameters, joinExperience en analyticsData-tabellen.

UserNotificationResult

Een wrapper-object dat de reactie van een verzonden melding bevat. Bevat de volgende sleutel-waarde paren: