Notificaciones de experiencia

Las notificaciones de experiencia son una forma para que los usuarios que han optado por participar de 13 años o más se mantengan al tanto de sus juegos favoritos mediante notificaciones personalizadas y oportunas. Como desarrollador, puedes determinar qué tipos de actividades dentro del juego son más importantes para notificar a tus usuarios, así como definir el contenido de la notificación.

El sistema de notificaciones de experiencia incluye lo siguiente:

• Notificaciones personalizables con parámetros — Total flexibilidad para personalizar el mensaje de notificación con parámetros, por ejemplo:

  ¡Tu huevo de ganso dorado ha eclosionado!

  ¡Allie @LaterSk8er1 acaba de superar tu récord en la pista de Tokyo Tour!

• Datos de lanzamiento — Incluye datos de lanzamiento opcionales que pueden ser leídos a través de Player:GetJoinData() cuando el destinatario de la notificación se une. Esto podría implicar llevar a un usuario a una ubicación de coordenadas o personalizar su experiencia de ingreso.

• Soporte de analíticas — Rastrea tu audiencia alcanzable y el rendimiento de tus notificaciones en el Panel del creador.

Requisitos de elegibilidad

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.

Directrices de uso

Implementación

La implementación de las notificaciones de experiencia comienza con crear una cadena de notificación e incluir el paquete en tu proyecto. Una vez que estos estén configurados, puedes enviar notificaciones con parámetros personalizados opcionales.

Alternativamente, puedes usar la API de Open Cloud para activar notificaciones a través de solicitudes API en formato libre.

Crear una cadena de notificación

As with Player Invite Prompts, you must create and edit your notification strings in the Creator Dashboard. No hay ninguna cadena de notificación de juego predeterminada, así que este paso es obligatorio.

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. In the center region, click the Create a Notification String button.

5. Fill in an identifier name (only visible to you) and the custom notification string; this is limited to 99 characters and can include unlimited custom parameters. Notifications will automatically use the title of your game as the notification title, but you can additionally use {experienceName} to reference your game in the notification body text.

   Example notification strings:

   ¡Estás a {numQuests} misiones de completar el desafío semanal!

   ¡Tu {eggName} ha eclosionado! Ven a conocer a tu nueva mascota.

   ¡Ganaste {numRaces} carreras esta semana y desbloqueaste la pista {racetrackName}!

   {userId-friend} acaba de superar tu récord en la pista Tokyo Tour! ¿Es hora de la venganza?

   Before writing notification strings, please review the guidelines for using the system.

6. When ready, click the Create Notification String button.

7. On the notifications page, in the table of notifications, click the ⋯ button in the Actions column and select Copy Asset ID.

8. Use the copied ID for the messageId key value in the payload table as demonstrated in the example script.

Incluir el paquete

Para implementar las notificaciones de experiencia, debes obtener el paquete de Luau de la Tienda de Creadores.

1. Desde el menú Ventana de Studio o la barra de herramientas de la pestaña Inicio, abre la Caja de Herramientas y selecciona la pestaña Tienda de Creadores.

   

2. Asegúrate de que la clasificación de Modelos esté seleccionada, luego haz clic en el botón Ver Todos para Categorías.

   

3. Localiza y haz clic en el mosaico Paquetes.

4. Localiza el módulo Open Cloud y haz clic en él, o arrástralo y suéltalo en la vista en 3D.

   

5. En la ventana del Explorador, mueve el modelo completo OpenCloud a ServerScriptService.

Enviar una notificación de experiencia

Una vez que hayas creado una cadena de notificación e incluido el paquete en tu proyecto, puedes enviar notificaciones desde scripts del lado del servidor. Las notificaciones se entregarán a usuarios de más de 13 años que optaron por recibirlas a través de su flujo de notificaciones de Roblox, momento en el cual pueden unirse a la experiencia directamente a través del botón Unirse en la notificación y aparecer según tus datos de lanzamiento.

Para enviar una notificación básica a un usuario específico, incluye el ID del activo de la cadena de notificación en el campo messageId del payload, luego llama a la función createUserNotification con el Player.UserId del destinatario y los datos de la solicitud.

local ServerScriptService = game:GetService("ServerScriptService")

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

-- En el payload, "messageId" es el valor del ID del activo de la notificación
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 notificaciones usando parámetros

Para personalizar la notificación para cada destinatario, puedes incluir parámetros en la cadena de notificación, luego personalizar los parámetros al llamar a la API. Por ejemplo, puedes definir la cadena de notificación como:

Luego, establece los parámetros userId-friend y points en el script:

local ServerScriptService = game:GetService("ServerScriptService")

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

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

-- En el payload, "messageId" es el valor del ID del activo de la notificación
-- En este ejemplo, la cadena de notificación es "{userId-friend} ¡superó tu puntuación más alta por {points} puntos! ¿Es hora de subir de nivel?"
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

Pedir a los usuarios que habiliten notificaciones

Para animar a los usuarios a habilitar notificaciones para tu experiencia, puedes mostrar un aviso de permiso dentro de la experiencia a usuarios de 13 años o más usando el método ExperienceNotificationService:PromptOptIn().

Puedes activar el aviso en cualquier contexto adecuado dentro de tu experiencia que justifique una notificación futura. El texto del aviso no es personalizable y es estandarizado en todas las experiencias.

El modal no aparecerá si el usuario:

• Es menor de 13 años.
• Ya ha habilitado notificaciones para tu experiencia.
• Ya ha visto el aviso de permiso para tu experiencia en los últimos 30 días.

Para pedir a los usuarios que habiliten notificaciones, primero debes determinar si el usuario es elegible. Una vez confirmado, puedes mostrar el aviso de permiso al usuario.

1. Llama a ExperienceNotificationService:CanPromptOptInAsync(), envuelto en un pcall() ya que es una llamada de red asincrónica que puede fallar ocasionalmente.
2. Si el usuario puede ser avisado, llama a ExperienceNotificationService:PromptOptIn().

local ExperienceNotificationService = game:GetService("ExperienceNotificationService")

-- Función para verificar si el jugador puede ser avisado para habilitar notificaciones
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

-- Escuchar el evento de cierre del aviso de opt-in
ExperienceNotificationService.OptInPromptClosed:Connect(function()
	print("Aviso de opt-in cerrado")
end)

Incluir datos de lanzamiento y analíticas

Para mejorar aún más la experiencia del usuario, puedes incluir datos de lanzamiento en la notificación, útil para escenarios como llevar a los usuarios a una ubicación de coordenadas o personalizar la experiencia de ingreso. Además, puedes incluir datos de analíticas para segmentar el rendimiento de diferentes categorías de notificaciones. Por favor, consulta también el ejemplo de Avisos de invitación al jugador sobre cómo establecer y usar los datos de lanzamiento.

local ServerScriptService = game:GetService("ServerScriptService")

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

-- En el payload, "messageId" es el valor del ID del activo de la notificación
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

Un sistema de prevención de spam existe para garantizar la calidad de las notificaciones para los usuarios y proteger el canal de notificación compartido para todos los desarrolladores. Debido a esto, la entrega de notificaciones no está garantizada. Este sistema de prevención de spam se informa directamente por el compromiso de los usuarios: cuanto más interactúan los usuarios con tus notificaciones, mayor alcance recibirán. Puedes rastrear de manera transparente las métricas de compromiso en el panel de análisis, como se explica a continuación.

Las notificaciones de experiencias tienen un límite de throttling estático; cada usuario puede recibir una notificación por día de una experiencia dada, y recibes comentarios transparentes cuando se alcanza el límite de throttling de un usuario.

Además, la siguiente lista detalla algunos de los casos especiales que pueden resultar en no entrega de una notificación:

• No se cumplen los requisitos de elegibilidad de la experiencia.
• El destinatario no ha aceptado recibir notificaciones de tu experiencia.
• Se ha alcanzado el límite de throttling del destinatario para tu experiencia.
• Se ha alcanzado el límite de throttling diario agregado del destinatario.
• Faltan o son inválidos los parámetros de solicitud.
• La cadena de notificación fue moderada.
• Para las notificaciones con menciones de usuario, la no entrega ocurre si se cumple alguna de estas condiciones:

  • El receptor y el usuario mencionado no son amigos.
  • El usuario mencionado ha seleccionado No para "¿Actualizar a amigos sobre mi actividad?" en Privacidad → Otras Configuraciones en su configuración de cuenta de Roblox.

Analíticas

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.

Resumen de notificaciones

La sección de resumen sirve como una instantánea del rendimiento agregado de tus notificaciones. Se requiere un mínimo de 100 impresiones agregadas para mostrar las estadísticas de rendimiento.

Estadísticas desglosadas

La tabla de Notificaciones de Experiencia muestra estadísticas detalladas de rendimiento para cada notificación con al menos 100 impresiones, ordenadas por la fecha de la primera impresión de esa notificación.

La columna Nombre es el identificador clave para la notificación. De forma predeterminada, el nombre coincide con el nombre del identificador que especificaste al crear la cadena de notificación, pero puedes anularlo a través del campo category en tus llamadas a la API, en cuyo caso category anula el nombre. Cambiar el nombre de la cadena en el Creator Dashboard o cambiar la cadena a la que hace referencia el ID de mensaje en la llamada a la API generará una nueva fila en la tabla.

Si deseas realizar pruebas A/B sobre el rendimiento de diferentes cadenas, se recomienda que crees una cadena de notificación completamente nueva con un nombre similar, por ejemplo:

• EggHatchA — "¡Tu huevo dorado ha eclosionado! Ven a conocer a tu nueva mascota."
• EggHatchB — "¡Es hora de la eclosión! Ven a conocer a tu nueva mascota."

Referencia de API

Funciones

createUserNotification

Envía una notificación desde un script del lado del servidor. Requiere el Player.UserId del destinatario y una UserNotification. Devuelve un UserNotificationResult.

local ServerScriptService = game:GetService("ServerScriptService")

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

-- En el payload, "messageId" es el valor del ID del activo de la notificación
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

Tabla que contiene detalles sobre la notificación que se enviará al usuario. Debe contener una tabla payload con cadenas messageId y type requeridas, y tablas opcionales parameters, joinExperience y analyticsData.

UserNotificationResult

Un objeto envuelto que contiene la respuesta de una notificación enviada. Contiene los siguientes pares clave-valor: