Guía de uso de Mensajería

La API del Servicio de Mensajería es el equivalente en Open Cloud de MessagingService del motor, que te permite comunicarte a través de los servidores y clientes de tu juego. La API del motor solo te permite escribir y actualizar scripts manualmente en Studio para publicar mensajes, pero la API de Open Cloud te permite enviar mensajes a servidores en vivo desde herramientas externas para automatizar y mejorar tus flujos de trabajo operativos.

Uso

Hay varias herramientas útiles que puedes construir apoyando la comunicación entre servidores con la API del Servicio de Mensajería, incluyendo:

• Portales de Anuncios: Un portal web puede ser útil para enviar anuncios a todos los usuarios a través de los servidores de tu juego, como anunciar un evento próximo, una actualización y el ganador de una competición. En el portal, puedes editar un mensaje y hacer clic en un botón que llama a la API para enviar el mensaje a todos los usuarios o a usuarios seleccionados.

• Sistema de Moderación: Un sistema de moderación puede ayudar a mantener tu juego seguro. Al detectar a un usuario con comportamiento inapropiado, puedes publicar un mensaje para activar el servidor del juego y advertir o banear al usuario específico. También puedes usar almacenamientos de datos en el sistema de moderación para añadir cuentas de usuario a una lista de bloqueo que impide que se reincorporen.

• Tablero de LiveOps: Los tableros de LiveOps son herramientas útiles para gestionar eventos en vivo, como una fiesta de Halloween. En el tablero, puedes pre-codificar un evento, actualizar mensajes del evento, activar el evento cuando esté listo y recompensar a usuarios seleccionados con artículos especiales como una corona virtual sin actualizar el código del juego.

Límites

La API del Servicio de Mensajería sigue los mismos límites que MessagingService del motor. Los límites de tasa son compartidos entre ambas APIs, y el uso de ambas APIs se cuenta contra los mismos límites.

Configurar un tema para mensajería

Antes de poder publicar un mensaje en los servidores en vivo de tu juego, debes configurar un tema, que es un canal de mensaje personalizado que es accesible desde múltiples servidores. Después de definir un tema, puedes suscribir a los usuarios al tema para recibir tus mensajes entrantes.

Actualmente, solo puedes definir un tema en Studio y usar la API de Luau MessagingService:SubscribeAsync() para suscribir a los usuarios. El siguiente ejemplo de código suscribe a cualquier usuario a un tema cuando se une al juego:

Configurar y Suscribir Usuarios a un Tema
local MessagingService = game:GetService("MessagingService")
local Players = game:GetService("Players")

local function onPlayerAdded(player)
	-- Definir y suscribirse al tema
	local topic = "TuTema"
	local connection = MessagingService:SubscribeAsync(topic, function(message)
		print(message.Data)
	end)

	player.AncestryChanged:Connect(function()
		-- Anular suscripción del tema al cambiar la ascendencia del jugador
		connection:Disconnect()
	end)
end

Players.PlayerAdded:Connect(onPlayerAdded)

Publicar mensajes en servidores en vivo

Después de configurar un tema, publica un mensaje en los servidores en vivo de tu juego:

1. Crea una clave API en Creator Dashboard y cópiala en un lugar seguro. Asegúrate de realizar las siguientes configuraciones:

   1. Añadir mensajería-servicio a Permisos de Acceso.
   2. Seleccionar un juego y añadir la operación universo-mensajería-servicio:publicar.

2. Obtén el ID del Universo para tu juego:

   1. Navega a Creator Dashboard.

   2. Encuentra el juego al que deseas publicar tus mensajes.

   3. Pasa el cursor sobre la miniatura de un juego, haz clic en el botón ⋯ y selecciona Copiar ID del Universo.

      

3. Añade la clave API y el universo a una solicitud POST, como en este ejemplo:

   Ejemplo de Solicitud para Publicar un Mensaje
   curl -L -X POST 'https://apis.roblox.com/cloud/v2/universes/{universe}:publishMessage' \
   -H 'x-api-key: {api-key}' \
   -H 'Content-Type: application/json' \
   --data '{
    "topic": "tu-tema",
    "message": "¡Hola a todos!"
   }'

4. Envía la solicitud HTTP para publicar el mensaje.

   Si tu solicitud tiene éxito, devuelve HTTP 200 con un cuerpo de respuesta vacío.

Añadir la API del Servicio de Mensajería a aplicaciones OAuth 2.0

Puedes crear aplicaciones OAuth 2.0 que permitan a tus usuarios publicar mensajes en sus propios servidores en vivo.

Para usar la API del Servicio de Mensajería para tu aplicación y solicitar permisos a tus usuarios, realiza las siguientes configuraciones:

1. Al registrar tu aplicación, bajo Permisos, selecciona el ámbito universo-mensajería-servicio:publicar.

2. Al implementar el flujo de autorización, incluye universo-mensajería-servicio:publicar en el parámetro scope de la URL de autorización que redirige a los usuarios de vuelta a tu aplicación, como el siguiente ejemplo:

   https://apis.roblox.com/oauth/v1/authorize?client_id=816547628409595165403873012&redirect_uri=https://my-app.com/redirect&scope=openid+universe-messaging-service:publish&response_type=Code&prompts=login+consent&nonce=12345&state=6789

3. Solicita acceso al universeId del juego al que el usuario desea publicar sus mensajes. Tu aplicación puede enviar una solicitud POST al endpoint de recursos de token con el token de acceso, ID del cliente y secreto o el code challenge, dependiendo de tu implementación de tu flujo de autorización, como parámetros de solicitud para obtener una lista de universeIds de juegos a los que el usuario otorgó permiso:

   Ejemplo de Solicitud
   curl --location --request POST 'https://apis.roblox.com/oauth/v1/token/resources' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data-urlencode 'token=<access_token>' \
   --data-urlencode 'client_id=<client_id>' \
   --data-urlencode 'client_secret=<client_secret>'

   Este endpoint devuelve una lista de universeIds como la siguiente respuesta de ejemplo:

   Ejemplo de Respuesta
   {
     "resource_infos": [
       {
         "owner": {
           "id": "1516563360",
           "type": "User"
         },
         "resources": {
           "universe": {
             "ids": ["3828411582"]
           }
         }
       }
     ]
   }

4. Tu aplicación ahora puede enviar mensajes a cualquier juego al que un usuario haya otorgado permiso. Al enviar la solicitud, incluye el token de acceso en el encabezado de autorización y el universeId y el tema en la URI de la solicitud en el siguiente formato:

   Ejemplo de Solicitud
   curl --location --request POST 'https://apis.roblox.com/cloud/v2/universes/{universe}:publishMessage' \
   --header 'Authorization: Bearer <access_token>' \
   --header 'Content-Type: application/json' \
   --data-raw '{"topic": "algún-tema","message":"mensaje a publicar"}'

Usar con HTTPService

Esta API es uno de los endpoints de Open Cloud soportados por HttpService. Puedes usarla para publicar mensajes a través de diferentes juegos desde dentro de un juego.