Notificações de experiência

Notificações de experiência são uma forma de usuários opt-in com 13 anos ou mais acompanharem seus jogos favoritos por meio de notificações oportunas e personalizadas. Como desenvolvedor, você pode determinar quais tipos de atividades dentro do jogo são mais importantes para notificar seus usuários, bem como definir o conteúdo da notificação.

O sistema de notificações de experiência possui as seguintes características:

• Notificações personalizáveis com parâmetros — Flexibilidade total para personalizar a mensagem de notificação com parâmetros, por exemplo:

  Seu ovo de ganso dourado nasceu!

  Allie @LaterSk8er1 acabou de bater seu recorde na pista do Tokyo Tour!

• Dados de Lançamento — Inclua dados de lançamento opcionais que podem ser lidos através de Player:GetJoinData() quando o destinatário da notificação se junta. Isso pode envolver direcionar um usuário para uma localização específica ou personalizar sua experiência de entrada.

• Suporte de Análise — Acompanhe seu público alcançado e o desempenho de suas notificações no Painel do Criador.

Requisitos de elegibilidade

Para usar as APIs para enviar notificações, o jogo deve atender aos seguintes critérios básicos:

• Mínimo de 100 visitas desde o lançamento.
• O jogo não pode estar sob moderação.
• Você, como desenvolvedor, deve ter permissão para gerenciar o jogo.

Diretrizes de uso

Implementação

A implementação das notificações de experiência começa com a criação de uma string de notificação e a inclusão do pacote em seu projeto. Uma vez que esses itens estejam configurados, você pode enviar notificações com parâmetros personalizados opcionais.

Alternativamente, você pode usar a API Open Cloud para acionar notificações através de solicitações de API em formato livre.

Criar uma string de notificação

Assim como nos Prompts de Convite para Jogadores, você deve criar e editar suas strings de notificação no Painel do Criador. Não há uma string de notificação de jogo padrão, então esta etapa é obrigatória.

1. Navegue até o Painel do Criador.

2. Similar aos badges, as strings de notificação estão vinculadas a um jogo específico. Localize a miniatura desse jogo e clique nela.

3. Na coluna esquerda, sob Engajamento, clique em Notificações.

4. Na região central, clique no botão Criar uma String de Notificação.

5. Preencha um nome de identificador (visível apenas para você) e a string de notificação personalizada; isso é limitado a 99 caracteres e pode incluir parâmetros personalizados ilimitados. As notificações usarão automaticamente o título do seu jogo como o título da notificação, mas você também pode usar {experienceName} para referenciar seu jogo no texto do corpo da notificação.

   Exemplos de strings de notificação:

   Você está a {numQuests} quests de completar o desafio semanal!

   Seu {eggName} nasceu! Venha conhecer seu novo animal de estimação.

   Você ganhou {numRaces} corridas esta semana e desbloqueou a pista {racetrackName}!

   {userId-friend} acabou de bater seu recorde na pista Tokyo Tour! Hora da revanche?

   Antes de escrever strings de notificação, por favor revise as diretrizes para usar o sistema.

6. Quando estiver pronto, clique no botão Criar String de Notificação.

7. Na página de notificações, na tabela de notificações, clique no botão ⋯ na coluna Ações e selecione Copiar ID do Ativo.

8. Use o ID copiado para o valor da chave messageId na tabela payload, conforme demonstrado no script de exemplo.

Incluir o pacote

Para implementar notificações de experiência, você deve obter o pacote Luau na Loja do Criador.

1. No menu Janela do Studio ou na barra de ferramentas da aba Início, abra a Caixa de Ferramentas e selecione a aba Loja do Criador.

   

2. Certifique-se de que a classificação Modelos está selecionada, depois clique no botão Ver Todos para Categorias.

   

3. Localize e clique no bloco Pacotes.

4. Localize o módulo Open Cloud e clique nele, ou arraste e solte-o na visualização 3D.

   

5. Na janela Explorador, mova todo o modelo OpenCloud para ServerScriptService.

Enviar uma notificação de experiência

Uma vez que você tenha criado uma string de notificação e incluído o pacote em seu projeto, você pode enviar notificações a partir de scripts do lado do servidor. As notificações serão entregues aos usuários que aceitaram com 13 anos ou mais através de sua transmissão de notificações do Roblox, onde eles podem ingressar na experiência diretamente pelo botão Ingressar na notificação e aparecer de acordo com seus dados de lançamento.

Para enviar uma notificação básica a um usuário específico, inclua o ID do ativo da string de notificação no campo messageId do payload, depois chame a função createUserNotification com o Player.UserId do destinatário e os dados da solicitação.

local ServerScriptService = game:GetService("ServerScriptService")

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

-- No payload, "messageId" é o valor do ID do ativo da notificação
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

Personalizar notificações usando parâmetros

Para personalizar a notificação para cada destinatário, você pode incluir parâmetros na string de notificação, depois personalizar os parâmetros ao chamar a API. Por exemplo, você pode definir a string de notificação como:

Em seguida, defina os parâmetros userId-friend e points no script:

local ServerScriptService = game:GetService("ServerScriptService")

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

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

-- No payload, "messageId" é o valor do ID do ativo da notificação
-- Neste exemplo, a string de notificação é "{userId-friend} bateu seu recorde de pontuação por {points} pontos! Hora de subir de nível?"
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

Solicitar aos usuários que ativem as notificações

Para incentivar os usuários a ativarem as notificações para sua experiência, você pode exibir um prompt de permissão dentro da experiência para usuários com 13 anos ou mais usando o método ExperienceNotificationService:PromptOptIn().

Você pode acionar o prompt em qualquer contexto adequado dentro de sua experiência que justifique uma notificação futura. O texto do prompt não é personalizável e é padronizado em todas as experiências.

O modal não aparecerá se o usuário:

• Tiver menos de 13 anos.
• Já tiver ativado notificações para sua experiência.
• Já tiver visto o prompt de permissão para sua experiência nos últimos 30 dias.

Para solicitar aos usuários que ativem as notificações, você deve primeiro determinar se o usuário é elegível. Uma vez confirmado, você pode exibir o prompt de permissão ao usuário.

1. Chame ExperienceNotificationService:CanPromptOptInAsync(), envolto em um pcall() já que é uma chamada de rede assíncrona que pode ocasionalmente falhar.
2. Se o usuário puder ser solicitado, chame ExperienceNotificationService:PromptOptIn().

local ExperienceNotificationService = game:GetService("ExperienceNotificationService")

-- Função para verificar se o jogador pode ser solicitado a ativar notificações
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

-- Ouvir evento de fechamento do prompt de opt-in
ExperienceNotificationService.OptInPromptClosed:Connect(function()
	print("Prompt de opt-in fechado")
end)

Incluir dados de lançamento e análise

Para melhorar ainda mais a experiência do usuário, você pode incluir dados de lançamento na notificação, úteis para cenários como direcionar usuários para uma localização específica ou personalizar a experiência de entrada. Além disso, você pode incluir dados de análise para segmentar o desempenho de diferentes categorias de notificações. Por favor, consulte também o exemplo de Solicitações de convite de jogador sobre como os dados de lançamento podem ser configurados e utilizados.

local ServerScriptService = game:GetService("ServerScriptService")

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

-- No payload, "messageId" é o valor do ID do ativo da notificação
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

Sistema de entrega

Um sistema de prevenção de spam existe para garantir a qualidade das notificações para os usuários e proteger o canal de notificações compartilhado para todos os desenvolvedores. Por causa disso, a entrega de notificações não é garantida. Este sistema de prevenção de spam é diretamente informado pelo engajamento do usuário: quanto mais os usuários interagem com suas notificações, mais alcance elas terão. Você pode acompanhar as métricas de engajamento de forma transparente no painel de analytics, conforme explicado abaixo.

As notificações de experiências têm um limite de taxa estático; cada usuário pode receber uma notificação por dia de uma determinada experiência, e você recebe feedback transparente quando o limite de taxa de um usuário é alcançado.

Além disso, a lista a seguir descreve alguns dos casos especiais que podem resultar na não entrega de uma notificação:

• Requisitos de elegibilidade da experiência não são atendidos.
• O destinatário não está inscrito para receber notificações de sua experiência.
• O limite de taxa do destinatário para sua experiência foi alcançado.
• O limite de taxa aggregate diário do destinatário foi alcançado.
• Parâmetros de solicitação ausentes ou inválidos.
• A string da notificação foi moderada.
• Para notificações com menções a usuários, a não entrega ocorre se uma dessas condições for atendida:

  • O receptor e o usuário mencionado não são amigos.
  • O usuário mencionado selecionou Não para "Atualizar amigos sobre a minha atividade?" nas configurações de Privacidade → Outras Configurações em suas configurações de conta do Roblox.

Análise

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. Navegue até o Painel do Criador.
2. Semelhante aos badges, as strings de notificação estão vinculadas a um jogo específico. Localize a miniatura desse jogo e clique nela.
3. Na coluna da esquerda, sob Engagement, clique em Notifications.
4. Na página de destino, clique na guia Analytics para alternar para o painel de análises.

Resumo das notificações

A seção de resumo serve como uma instantânea do desempenho agregado das suas notificações. Um mínimo de 100 impressões agregadas é necessário para exibir as estatísticas de desempenho.

Estatísticas detalhadas

A tabela de Notificações de Experiência exibe estatísticas de desempenho detalhadas para cada notificação com pelo menos 100 impressões, ordenadas pela data da primeira impressão para essa notificação.

A coluna Nome é o identificador chave para a notificação. Por padrão, o nome corresponde ao nome do identificador que você especificou ao criar a string de notificação, mas você pode sobrescrevê-lo através do campo category em suas chamadas de API, caso em que category sobrescreve o nome. Alterar o nome da string no Painel do Criador ou alterar a string à qual seu ID de mensagem se refere na chamada da API gerará uma nova linha na tabela.

Se você gostaria de testar A/B o desempenho de diferentes strings, é recomendado que você crie uma nova string de notificação completamente nova com um nome semelhante, por exemplo:

• EggHatchA — "Seu ovo de ouro chocou! Venha conhecer seu novo pet."
• EggHatchB — "É hora de chocar! Venha conhecer seu novo pet."

Referência da API

Funções

createUserNotification

Envia uma notificação de um script do lado do servidor. Requer o Player.UserId do destinatário e uma UserNotification. Retorna um UserNotificationResult.

local ServerScriptService = game:GetService("ServerScriptService")

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

-- No payload, "messageId" é o valor do ID do ativo da notificação
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

Tipos

UserNotification

Tabela contendo detalhes sobre a notificação a ser enviada ao usuário. Deve conter uma tabela payload com strings requeridas messageId e type, e tabelas opcionais parameters, joinExperience e analyticsData.

UserNotificationResult

Um objeto wrapper que contém a resposta de uma notificação enviada. Contém os seguintes pares chave-valor: