Notificações de experiência

Notificações de experiência são uma maneira para opt-in usuários com idade 13+ manterem-se atualizados com suas experiências favoritas através de notificações personalizadas e oportunas.Como desenvolvedor, você pode determinar que tipos de atividades na experiência são mais importantes para notificar seus usuários e definir o conteúdo da notificação.

O sistema de notificação de experiência apresenta o seguindo:

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

  Your gold goose egg has hatched!

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

• Dados de lançamento — Inclua dados de lançamento opcionais que podem ser lidos através de quando o receptor de notificação se juntar.Isso pode envolver encaminhar um usuário para uma localização de coordenadas ou personalizar sua experiência de adesão.

• Suporte de análise — Acompanhe sua audiência alcançável e o desempenho de suas notificações no Painel do Criador.

Requisitos de elegibilidade

Para usar as APIs para enviar notificações, a experiência deve atender aos seguintes critérios de base:

• Mínimo de 100 visitas desde o iniciar.
• A experiência não deve estar sob moderação.
• Você como desenvolvedor deve ter permissão para gerenciar a experiência.

Diretrizes de uso

Implementação

A implementação de notificações de experiência começa com criar uma string de notificação e incluir o pacote em seu projeto.Uma vez que eles são configurados, você pode enviar notificações com parâmetros opcionais personalizados.

Alternativamente, você pode usar a API de Nuvem Aberta para disparar notificações através de solicitações de API de formulário livre.

Crie uma string / cadeia / textode notificação

Assim como com Convites de Jogador, você deve criar e editar suas cordas de notificação no Painel do Criador. Não há string / cadeia / textode notificação de experiência padrão, então este passo é necessário.

1. Navegue até o Painel do Criador.

2. Semelhante a insígnias, as cordas de notificação estão ligadas a uma experiência específica . Localize a miniatura dessa experiência e clique nela.

3. Na coluna da 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 (apenas visível para você) e a string / cadeia / textode notificação personalizada; isso é limitado a 99 caracteres e pode incluir parâmetros personalizados ilimitados custom.Notificações usarão automaticamente o título da sua experiência como título da notificação, mas você pode usar adicionalmente experienceName para referenciar a sua experiência no corpo do texto da notificação.

   Exemplos de strings de notificação:

   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?

   Antes de escrever cordões 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 de recurso .

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

Inclua o pacote

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

1. Da aba Ver, abra a Caixa de Ferramentas e selecione a aba Loja do Criador .

   

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

   

3. Localize e clique no tijolo Dev Modules .

   

4. Localize o módulo Abrir Nuvem e clique nele, ou arraste e solte-o na ver3D.

   

5. Na janela Explorer, mova todo o modelo OpenCloud para Serviço de Script de Servidor .

   

Envie uma notificaçõesde experiência

Uma vez que você criou uma string de notificação e incluiu o pacote em seu projeto, você pode enviar notificações de scripts do lado do servidor.Notificações serão entregues a opt-in usuários com idade 13+ através de seu streamde notificação do Roblox, momento em que eles podem se juntar à experiência diretamente através do botão Entrar na notificação e aparecer de acordo com seus dados de lançamento .

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

Envie uma notificaçõesde experiência
local ServerScriptService = game:GetService("ServerScriptService")

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

-- No corpo da solicitação, "messageId" é o valor do ID do recurso de 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

Personalize notificações usando parâmetros

Para personalizar a notificação para cada destinatário, você pode incluir parâmetros na corda de notificação, então personalize os parâmetros ao chamar a API (Interface de Programação para Aplicações).Por exemplo, você pode definir a string de notificação como:

Então, defina os parâmetros userId-friend e points no script:

Personalize Notificação Usando Parâmetros
local ServerScriptService = game:GetService("ServerScriptService")

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

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

-- No corpo da solicitação, "messageId" é o valor do ID do recurso de notificação
-- Neste exemplo, a string de notificação é "{userId-friend} bateu sua pontuação máxima 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

Incentive os usuários a habilitar notificações

Para incentivar os usuários a habilitar notificações para sua experiência, você pode exibir um prompt de permissão na experiência para usuários com idade 13+ usando o método ExperienceNotificationService:PromptOptIn().

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

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

• Tem menos de 13 anos.
• Já habilitou notificações para a sua experiência.
• Já viu o prompt de permissão para a sua experiência nos últimos 30 dias.

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

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

LocalScript - Implementação de solicitação de permissão de notificação
local ExperienceNotificationService = game:GetService("ExperienceNotificationService")

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

-- Ouça o evento de confirmação de opção fechada
ExperienceNotificationService.OptInPromptClosed:Connect(function()
	print("Opt-in prompt closed")
end)

Inclua dados de lançamento e análise

Para melhorar a experiência do usuário ainda mais, você pode incluir dados de lançamento na notificação, úteis para cenários como encaminhar usuários para uma localização de coordenadas ou personalizar a experiência de junção.Além disso, você pode incluir análises de dados para segmentar o desempenho de diferentes categorias de notificações.Por favor, também consulte o exemplo de convites de jogador sobre como os dados de lançamento podem ser definidos e usados.

Incluir Dados de Lançamento e Dados de Análise
local ServerScriptService = game:GetService("ServerScriptService")

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

-- No corpo da solicitação, "messageId" é o valor do ID do recurso de 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ção compartilhado para todos os desenvolvedores.Devido a isso, a entrega de notificações não é garantida.Este sistema de prevenção de spam é diretamente informado pelo engajamento do usuário: quanto mais usuários interagem com suas notificações, mais alcance eles receberão.Você pode rastrear transparentemente métricas de engajamento no painel de análise analytics, como explicado abaixo.

As notificações de experiência têm um limite de aceleração estática; cada usuário pode receber uma notificação por dia de uma experiência dada e você recebe feedback transparente quando o limite de aceleração de um usuário é atingido.

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

• Os requisitos de elegibilidade de experiência não são atendidos.
• O destinatário não optou por não receber notificações da sua experiência.
• O limite de aceleração do destinatário para sua experiência foi atingido.
• O limite de velocidade diária agregada do destinatário foi atingido.
• Parâmetros de solicitação ausentes ou inválidos.
• A corda de notificação foi moderada.
• Para notificações com menções de usuário, 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 tem Não selecionado para "Atualizar amigos sobre minha atividade?" sob Privacidade → Outras Configurações em suas configurações de conta do Roblox.

Análises

O desempenho de suas notificações e público notificável é exibido na aba Análise da página Notificações , onde você configura cordões de notificação (simplesmente tab de Criações para Análise ).

1. Navegue até o Painel do Criador.
2. Semelhante a insígnias, as cordas de notificação estão ligadas a uma experiência específica . Localize a miniatura dessa experiência e clique nela.
3. Na coluna da esquerda, sob Engajamento , clique em Notificações .
4. Na página alvo, clique na aba Análise para mudar para o painel de análise.

Sumário resumonotificações

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

Estatísticas itemizadas

A tabela 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ções.

A coluna Nome é o identificador-chave da notificações.Por padrão, o nome corresponde ao nome do identificador que você especificou ao criar a corda de notificação , mas você pode substituí-lo através do campo na sua chamada de API, caso em que substitui o nome.Mudar o nome da string no Painel do Criador ou mudar a string que seu ID de mensagem se refere na chamada da API gerará uma nova linha na tabela.

Se você quiser testar A/B o desempenho de diferentes cordas, é recomendado que você crie uma nova corda de notificação totalmente nova com um nome semelhante, por exemplo:

• EggHatchA — "Seu ovo dourado chocou! Venha conhecer seu novo animal de estimação."
• EggHatchB — "É hora de chocar! Venha conhecer seu novo animal de estimação."

Referência da API

Funções

criarNotificação de Usuário

Envia uma notificação de um script do lado do servidor.Requer o do destinatário e uma Notificação de Usuário .Retorna um Resultado de Notificação de Usuário.

Envie uma notificaçõesde experiência
local ServerScriptService = game:GetService("ServerScriptService")

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

-- No corpo da solicitação, "messageId" é o valor do ID do recurso de 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

Notificação de Usuário

Tabela que contém detalhes sobre a notificação a ser enviada ao usuário.Deve conter uma tabela payload com strings necessárias messageId e type e tabelas opcionais parameters , joinExperience e analyticsData.

Resultado de Notificação de Usuário

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