Notificações do usuário

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.

Depois de receber uma notificação, os usuários podem ingressar na experiência diretamente pelo botão Participar e spawnar de acordo com seus dados de lançamento.

Para mais informações sobre recursos, requisitos de elegibilidade, diretrizes de uso e a API da Engine correspondente, consulte o guia de Experiências.

Implementação

O recurso UserNotification permite que você envie notificações de experiências para os usuários. Antes de usá-lo, você deve gerar uma chave de API ou configurar OAuth 2.0 para seu aplicativo. Os exemplos nesta página usam chaves de API.

Para enviar uma notificação de experiência a um usuário:

1. Crie uma string de notificação no Painel do Criador (essa etapa deve ser feita no Painel do Criador; não há API do Open Cloud para isso).
2. Forme a solicitação:

   1. Copie a chave de API para o cabeçalho da solicitação x-api-key.
   2. Copie o ID do ativo da string de notificação como o valor da propriedade payload.message_id.
   3. Defina payload.type como "MOMENT".
   4. Defina source.universe como a URL do recurso do universo "universes/${UniverseID}".

curl --location 'https://apis.roblox.com/cloud/v2/users/${UserId}/notifications' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{
	"source": {
		"universe": "universes/${UniverseID}"
	},
	"payload": {
		"message_id": "${AssetID}",
		"type": "MOMENT"
	}
}'

Exemplo de resposta que retorna o ID da notificação no campo id:

{
  "path": "users/505306092/notifications/6ca4d981-36fa-4255-82a1-14d95c116889",
  "id": "6ca4d981-36fa-4255-82a1-14d95c116889"
}

Customize notificações usando parâmetros

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

Adicione os parâmetros userId-friend e points no script:

curl --location 'https://apis.roblox.com/cloud/v2/users/${UserId}/notifications' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{
	"source": {
		"universe": "universes/${UniverseID}"
	},
	"payload": {
		"message_id": "${AssetID}",
		"type": "MOMENT",
		"parameters": {
			"userId-friend": {"int64_value": 3702832553},
			"points": {"string_value": "5"}
		}
	}
}'

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, útil para cenários como direcionar usuários a uma localização coordenada ou personalizar a experiência de ingresso. Além disso, você pode incluir dados de análise para segmentar o desempenho de diferentes categorias de notificações.

curl --location 'https://apis.roblox.com/cloud/v2/users/${UserId}/notifications' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{
	"source": {
		"universe": "universes/${UniverseID}"
	},
	"payload": {
		"message_id": "${AssetID}",
		"type": "MOMENT"
	},
	"join_experience": {
		"launch_data": "Test_Launch_Data"
	},
	"analytics_data": {
		"category": "Test_Analytics_Category"
	}
}'

Limites de taxa e entrega

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.

Existem muitas outras razões pelas quais uma notificação pode não ser entregue. Para mais informações, consulte Sistema de entrega no guia da Engine.