Powiadomienia o doświadczeniach

Powiadomienia o doświadczeniach to sposób dla użytkowników, którzy wyrazili zgodę w wieku 13+, aby na bieżąco śledzić swoje ulubione gry poprzez terminowe, spersonalizowane powiadomienia. Jako deweloper, możesz określić, jakie rodzaje aktywności w grze są najważniejsze, aby powiadomić swoich użytkowników, a także zdefiniować treść powiadomień.

System powiadomień o doświadczeniach oferuje następujące funkcje:

• Konfigurowalne powiadomienia z parametrami — Pełna elastyczność w dostosowywaniu wiadomości powiadomienia za pomocą parametrów, na przykład:

  Twoje złote jajo gęsi się wykluło!

  Allie @LaterSk8er1 właśnie pobił Twój rekord na torze Tokijskim!

• Dane startowe — Dołącz opcjonalne dane startowe, które mogą być odczytane przez Player:GetJoinData(), gdy odbiorca powiadomienia dołączy. Może to obejmować kierowanie użytkownika do określonej lokalizacji lub personalizację jego doświadczenia.

• Wsparcie analityczne — Śledź swoją osiągalną publiczność i wydajność powiadomień w Kokpicie Twórcy.

Wymagania dotyczące kwalifikacji

Aby korzystać z interfejsów API do wysyłania powiadomień, gra musi spełniać następujące podstawowe kryteria:

• Minimum 100 wizyt od momentu uruchomienia.
• Gra nie może być w moderacji.
• Ty jako deweloper musisz mieć pozwolenie na zarządzanie grą.

Wytyczne dotyczące użytkowania

Implementacja

Wdrażanie powiadomień o doświadczeniach zaczyna się od stworzenia ciągu powiadomień i dołączenia pakietu do swojego projektu. Gdy te elementy są gotowe, możesz wysyłać powiadomienia z opcjonalnymi dostosowanymi parametrami.

Alternatywnie możesz użyć Open Cloud API, aby wywołać powiadomienia poprzez swobodne żądania API.

Stwórz ciąg powiadomień

Jak w przypadku Zachęt do zapraszania graczy, musisz utworzyć i edytować swoje ciągi powiadomień w Panelu Twórcy. Nie ma domyślnego ciągu powiadomienia gry, więc ten krok jest wymagany.

1. Przejdź do Panelu Twórcy.

2. Podobnie jak w przypadku odznak, ciągi powiadomień są powiązane z konkretną grą. Znajdź miniaturę tej gry i kliknij na nią.

3. W lewym kolumnie, w sekcji Zaangażowanie, kliknij Powiadomienia.

4. W środkowym obszarze kliknij przycisk Utwórz ciąg powiadomienia.

5. Wypełnij pole identyfikatora (widocznego tylko dla Ciebie) oraz własny ciąg powiadomienia; jest ograniczone do 99 znaków i może zawierać nieograniczoną liczbę niestandardowych parametrów. Powiadomienia automatycznie użyją tytułu Twojej gry jako tytułu powiadomienia, ale możesz dodatkowo użyć {experienceName}, aby odwołać się do swojej gry w treści powiadomienia.

   Przykładowe ciągi powiadomień:

   Jesteś {numQuests} misji od ukończenia tygodniowego wyzwania!

   Twój {eggName} wykluł się! Przyjdź i poznaj nowe zwierzę.

   Wygrałeś {numRaces} wyścigów w tym tygodniu i odblokowałeś tor {racetrackName}!

   {userId-friend} właśnie pobił Twój rekord na torze Tokyo Tour! Czas na odwet?

   Przed pisaniem ciągów powiadomień, zapoznaj się z wytycznymi dotyczącymi korzystania z systemu.

6. Kiedy będziesz gotowy, kliknij przycisk Utwórz ciąg powiadomienia.

7. Na stronie powiadomień, w tabeli powiadomień, kliknij przycisk ⋯ w kolumnie Akcje i wybierz Kopiuj identyfikator zasobu.

8. Użyj skopiowanego identyfikatora dla wartości klucza messageId w tabeli payload, jak pokazano w przykładowym skrypcie.

Dołącz pakiet

Aby wprowadzić powiadomienia o doświadczeniach, musisz uzyskać pakiet Luau z Sklepu Twórcy.

1. W menu Okno w Studio lub na pasku narzędzi karty Start, otwórz Zestaw narzędzi i wybierz kartę Sklep Twórcy.

   

2. Upewnij się, że wybrano sortowanie Modele, a następnie kliknij przycisk Zobacz wszystko dla Kategorii.

   

3. Znajdź i kliknij kafel Pakiety.

4. Znajdź moduł Open Cloud i kliknij go lub przeciągnij go do widoku 3D.

   

5. W oknie Eksploratora, przenieś cały model OpenCloud do ServerScriptService.

Wyślij powiadomienie o doświadczeniu

Gdy już stworzysz ciąg powiadomień i dołączysz pakiet do swojego projektu, możesz wysyłać powiadomienia z skryptów po stronie serwera. Powiadomienia będą dostarczane do użytkowników, którzy wyrazili zgodę (https://en.help.roblox.com/hc/en-us/articles/24769602332692-Out-of-Experience-Notifications) w wieku 13+, przez ich strumień powiadomień w Roblox, w którym to momencie mogą dołączyć do doświadczenia bezpośrednio za pomocą przycisku Dołącz w powiadomieniu i pojawić się zgodnie z Twoimi danymi startowymi.

Aby wysłać podstawowe powiadomienie do konkretnego użytkownika, dołącz identyfikator zasobu ciągu powiadomienia do pola messageId w ładunku, a następnie wywołaj funkcję createUserNotification z Player.UserId odbiorcy oraz danymi żądania.

Wyślij powiadomienie o doświadczeniu
local ServerScriptService = game:GetService("ServerScriptService")

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

-- W ładunku "messageId" to wartość identyfikatora zasobu powiadomienia
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

Dostosuj powiadomienia za pomocą parametrów

Aby dostosować powiadomienie dla każdego odbiorcy, możesz dołączyć parametry w ciągu powiadomień, a następnie dostosować te parametry podczas wywoływania API. Na przykład, możesz zdefiniować ciąg powiadomienia jako:

Następnie ustaw parametry userId-friend i points w skrypcie:

Dostosuj powiadomienie za pomocą parametrów
local ServerScriptService = game:GetService("ServerScriptService")

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

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

-- W ładunku "messageId" to wartość identyfikatora zasobu powiadomienia
-- W tym przykładzie ciąg powiadomienia brzmi "{userId-friend} pobił Twój wynik o {points} punktów! Czas na awans?"
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

Nakłaniaj użytkowników do włączenia powiadomień

Aby zachęcić użytkowników do włączenia powiadomień dla Twojego doświadczenia, możesz wyświetlić w grze prośbę o pozwolenie dla użytkowników w wieku 13+ za pomocą metody ExperienceNotificationService:PromptOptIn().

Możesz wywołać prośbę w każdej odpowiedniej okolicy w swojej grze, która uzasadnia przyszłe powiadomienie. Tekst prośby nie jest konfigurowalny i jest ustandaryzowany dla wszystkich doświadczeń.

Modal nie pojawi się, jeśli użytkownik:

• Jest poniżej 13. roku życia.
• Już włączył powiadomienia dla Twojego doświadczenia.
• Już widział prośbę o pozwolenie w Twoim doświadczeniu w ciągu ostatnich 30 dni.

Aby nakłonić użytkowników do włączenia powiadomień, należy najpierw ustalić, czy użytkownik jest kwalifikowalny. Po potwierdzeniu można wyświetlić prośbę o zezwolenie dla użytkownika.

1. Wywołaj ExperienceNotificationService:CanPromptOptInAsync(), owinąć w pcall(), ponieważ jest to asynchroniczne wywołanie sieciowe, które może czasami nie działać.
2. Jeśli użytkownik może być poproszony, wywołaj ExperienceNotificationService:PromptOptIn().

LocalScript - Implementacja prośby o pozwolenie na powiadomienia
local ExperienceNotificationService = game:GetService("ExperienceNotificationService")

-- Funkcja sprawdzająca, czy gracz może być poproszony o włączenie powiadomień
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

-- Nasłuchuj na zdarzenie zamknięcia prośby o zgodę
ExperienceNotificationService.OptInPromptClosed:Connect(function()
	print("Prośba o zgodę została zamknięta")
end)

Dołącz dane startowe i analityczne

Aby jeszcze bardziej poprawić doświadczenie użytkowników, możesz dołączyć dane startowe do powiadomienia, które są przydatne w scenariuszach, takich jak kierowanie użytkowników do konkretnej lokalizacji lub personalizacja doświadczenia związana z dołączeniem. Dodatkowo możesz dołączyć dane analityczne, aby segmentować wydajność różnych kategorii powiadomień. Proszę także odwołać się do przykładu Zaproszenia gracza na temat tego, jak można ustawić i wykorzystać dane startowe.

Dołącz dane startowe i dane analityczne
local ServerScriptService = game:GetService("ServerScriptService")

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

-- W ładunku "messageId" to wartość identyfikatora zasobu powiadomienia
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

System powiadomień

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:

• Experience wymagania dotyczące kwalifikowalności are not met.
• Recipient is not opted in to notifications from your experience.
• Recipient's throttle limit for your experience has been reached.
• Recipient's aggregate daily throttle limit has been reached.
• Missing or invalid request parameters.
• Notification string was moderated.
• For notifications with user mentions, non-delivery occurs if either of these conditions are met:

  • The receiver and mentioned user are not friends.
  • The mentioned user has Nie selected for "Update friends about my activity?" under Prywatność → Inne Ustawienia in their Roblox account settings.

Analityka

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. 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. On the target page, click the Analytics tab to switch to the analytics dashboard.

Podsumowanie powiadomień

Sekcja podsumowująca służy jako snapshot zbiorczej wydajności Twoich powiadomień. Wymagane jest minimum 100 zbiorczych wyświetleń, aby wyświetlić statystyki wydajności.

Szczegółowe statystyki

Tabela Powiadomienia doświadczeń wyświetla szczegółowe statystyki wydajności dla każdego powiadomienia z co najmniej 100 wyświetleniami, uporządkowane według daty pierwszego wyświetlenia tego powiadomienia.

Kolumna Nazwa jest kluczowym identyfikatorem dla powiadomienia. Domyślnie nazwa odpowiada nazwie identyfikatora, którą określiłeś podczas tworzenia ciągu powiadomienia, ale możesz ją nadpisać przez pole category w swoich wywołaniach API, w takim przypadku category nadpisuje nazwę. Zmiana nazwy ciągu w Kokpicie twórcy lub zmiana ciągu, do którego odnosi się identyfikator wiadomości w wywołaniu API, wygeneruje nowy wiersz w tabeli.

Jeśli chcesz przetestować wydajność różnych ciągów w teście A/B, zaleca się utworzenie całkowicie nowego ciągu powiadomienia o podobnej nazwie, na przykład:

• EggHatchA — "Twoje złote jajo się wykluło! Przyjdź i poznaj swoje nowe zwierzątko."
• EggHatchB — "Czas na wykluwanie! Przyjdź i poznaj swoje nowe zwierzątko."

Referencja API

Funkcje

createUserNotification

Wysyła powiadomienie z skryptu po stronie serwera. Wymaga Player.UserId odbiorcy i UserNotification. Zwraca UserNotificationResult.

Wyślij powiadomienie o doświadczeniu
local ServerScriptService = game:GetService("ServerScriptService")

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

-- W ładunku "messageId" to wartość identyfikatora zasobu powiadomienia
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

Typy

UserNotification

Tabela zawierająca szczegóły o powiadomieniu, które ma być wysłane do użytkownika. Musi zawierać tabelę payload z wymaganymi łańcuchami messageId i type, oraz opcjonalnymi tabelami parameters, joinExperience i analyticsData.

UserNotificationResult

Obiekt opakowujący, który zawiera odpowiedź z wysłanego powiadomienia. Zawiera następujące pary klucz-wartość: