Guida all'uso della messaggistica

L'API del Servizio di Messaggistica è l'equivalente Open Cloud di MessagingService dell'Engine, che ti consente di comunicare tra i server e i client del tuo gioco. L'API dell'Engine consente solo di scrivere e aggiornare manualmente gli script in Studio per pubblicare messaggi, ma l'API Open Cloud ti permette di inviare messaggi ai server live tramite strumenti esterni per automatizzare e migliorare i tuoi flussi di lavoro operativi.

Utilizzo

Ci sono diversi strumenti utili che puoi creare supportando la comunicazione tra server con l'API del Servizio di Messaggistica, tra cui:

• Portali di Annuncio: Un portale web può essere utile per supportare l'invio di annunci a tutti gli utenti nei diversi server del tuo gioco, come annunciare un evento imminente, un aggiornamento e il vincitore di una competizione. Sul portale, puoi modificare un messaggio e fare clic su un pulsante che chiama l'API per inviare il messaggio a tutti gli utenti o a utenti selezionati.

• Sistema di Moderazione: Un sistema di moderazione può aiutare a mantenere il tuo gioco sicuro. Quando si rileva un utente con comportamenti inappropriati, puoi pubblicare un messaggio per avvisare o bannare il specifico utente. Puoi anche utilizzare i data store nel sistema di moderazione per aggiungere gli account utente a una lista nera che ne impedisce il reintegro.

• Dashboard LiveOps: Le dashboard LiveOps sono strumenti utili per gestire eventi live, come una festa di Halloween. Sulla dashboard, puoi pre-codificare un evento, aggiornare i messaggi dell'evento, attivare l'evento quando è pronto e premiare gli utenti selezionati con oggetti speciali come una corona virtuale senza aggiornare alcun codice del gioco.

Limiti

L'API del Servizio di Messaggistica segue gli stessi limiti dell'Engine MessagingService. I limiti di frequenza sono condivisi tra entrambe le API e l'uso di entrambe le API viene conteggiato contro gli stessi limiti.

Configurare un argomento per la messaggistica

Prima di poter pubblicare un messaggio sui server live del tuo gioco, devi configurare un argomento, che è un canale di messaggistica personalizzato accessibile da più server. Dopo aver definito un argomento, iscrivi gli utenti all'argomento per ricevere i tuoi messaggi in arrivo.

Attualmente, puoi definire un argomento solo in Studio e utilizzare l'API Luau MessagingService:SubscribeAsync() per iscrivere gli utenti. Il seguente esempio di codice iscrive qualsiasi utente a un argomento quando entra nel gioco:

Configura e Iscrivi Utenti a un Argomento
local MessagingService = game:GetService("MessagingService")
local Players = game:GetService("Players")

local function onPlayerAdded(player)
	-- Definisci e iscriviti all'argomento
	local topic = "YourTopic"
	local connection = MessagingService:SubscribeAsync(topic, function(message)
		print(message.Data)
	end)

	player.AncestryChanged:Connect(function()
		-- Disiscrivi dall'argomento in caso di cambiamento dell'ancestria del giocatore
		connection:Disconnect()
	end)
end

Players.PlayerAdded:Connect(onPlayerAdded)

Pubblica messaggi sui server live

Dopo aver configurato un argomento, pubblica un messaggio sui server live del tuo gioco:

1. Crea una chiave API sul Creator Dashboard e copiala in un luogo sicuro. Assicurati di eseguire le seguenti impostazioni:

   1. Aggiungi messaging-service a Access Permissions.
   2. Seleziona un gioco e aggiungi l'operazione universe-messaging-service:publish.

2. Ottieni l'ID dell'Universo per il tuo gioco:

   1. Naviga al Creator Dashboard.

   2. Trova il gioco a cui desideri pubblicare i tuoi messaggi.

   3. Passa il mouse sopra la miniatura di un gioco, fai clic sul pulsante ⋯ e seleziona Copia l'ID Universo.

      

3. Aggiungi la chiave API e l'universo a una richiesta POST, come in questo esempio:

   Esempio di Richiesta per Pubblicare un Messaggio
   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": "your-topic",
    "message": "Ciao a tutti!"
   }'

4. Invia la richiesta HTTP per pubblicare il messaggio.

   Se la tua richiesta ha successo, restituisce HTTP 200 con un corpo di risposta vuoto.

Aggiungi l'API del Servizio di Messaggistica alle app OAuth 2.0

Puoi creare applicazioni OAuth 2.0 che consentono ai tuoi utenti di pubblicare messaggi sui propri server live.

Per utilizzare l'API del Servizio di Messaggistica per la tua applicazione e richiedere i permessi dai tuoi utenti, esegui le seguenti impostazioni:

1. Quando registri la tua applicazione, sotto Permissions, seleziona l'ambito universe-messaging-service:publish.

2. Quando implementi il flusso di autorizzazione, includi universe-messaging-service:publish nel parametro scope dell'URL di autorizzazione che reindirizza gli utenti di nuovo alla tua applicazione, come nel seguente esempio:

   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. Richiedi l'accesso a universeId del gioco a cui l'utente desidera pubblicare i propri messaggi. La tua applicazione può inviare una richiesta POST all'endpoint delle risorse di token con il token di accesso, l'ID client e il segreto o il code challenge, a seconda della tua implementazione del tuo flusso di autorizzazione, come parametri di richiesta per ottenere un elenco di universeIds dei giochi a cui l'utente ha concesso accesso:

   Esempio di Richiesta
   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>'

   Questo endpoint restituisce un elenco di universeIds come il seguente esempio di risposta:

   Esempio di Risposta
   {
     "resource_infos": [
       {
         "owner": {
           "id": "1516563360",
           "type": "User"
         },
         "resources": {
           "universe": {
             "ids": ["3828411582"]
           }
         }
       }
     ]
   }

4. La tua applicazione può ora inviare messaggi a qualsiasi gioco a cui un utente ha concesso permessi. Quando invii la richiesta, includi il token di accesso nell'intestazione di autorizzazione e l'universeId e l'argomento nella URI della richiesta nel seguente formato:

   Esempio di Richiesta
   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": "some-topic","message":"messaggio da pubblicare"}'

Utilizzo con HTTPService

Questa API è uno dei punti finali Open Cloud supportati da HttpService. Puoi usarla per pubblicare messaggi tra diversi giochi all'interno di un gioco.