Panoramica
Le notifiche di gioco di Steam sono un sistema di notifiche offline per gli utenti ideate per i giochi che offrono possibilità multigiocatore in asincrono, come gli scacchi.
Lo scopo di questa API è di notificare agli utenti che è necessaria un'azione nella sessione di gioco in corso. Nell'esempio degli scacchi, lo stato della sessione di gioco viene aggiornato dopo ogni mossa del giocatore. Steam invierà quindi notifiche agli utenti in base allo stato della sessione per avvisarli che il gioco è in attesa del loro turno.
Elementi gestiti dal gioco
Un tipico gioco offline è responsabile della gestione della sessione di gioco, che deve essere condotta aggiornando lo stato di ciascun giocatore. Tale stato, a sua volta, attiva l'invio di una notifica all'utente per informarlo sulla necessità di avviare il gioco ed eseguire un'azione. Nel momento in cui l'utente avvia il programma ed esegue le azioni richieste, il gioco aggiorna nuovamente la sessione assieme agli stati di tutti i giocatori partecipanti.
Elementi gestiti da Steam
Steam si occupa della gestione delle notifiche agli utenti nella sessione di gioco, sulla base degli stati forniti dal gioco stesso e a seconda delle impostazioni specifiche selezionate dall'utente. Quando un gioco richiede un'azione, verrà visualizzato un avviso nel client di Steam e nel browser web dell'utente.
Requisiti
L'API delle notifiche di gioco è fornita tramite i metodi API Web e richiede una chiave dell'editore valida. Le chiamate del metodo API Web devono provenire da un server ospitato che sia separato dal client di gioco. È di fondamentale importanza non fornire la chiave dell'editore insieme ai codici di gioco del client.
Autenticazione e account di terze parti
Per procedere con la chiamata alle API delle notifiche di gioco, è necessario innanzitutto stabilire l'identità dell'utente di Steam che ha effettuato l'accesso. Puoi verificarla in due modi: se il gioco è basato sul client puoi generare un ticket di sessione per l'autenticazione e passarlo nuovamente al tuo server, mentre se è basato sul web puoi ottenere la verifica dell'identità dell'utente per mezzo di OpenID. Nella sezione
Collegamento di account di terze parti ad account di Steam sono disponibili tutte le istruzioni necessarie. È importante non fare affidamento sui messaggi relativi all'identità dell'utente inviati direttamente dal client di gioco al server, in quanto tali messaggi possono essere falsificati.
Per i giochi che utilizzano account di terze parti, utilizza le istruzioni fornite in precedenza ma carica nella cache del tuo sistema lo SteamID dell'utente.
API delle notifiche di gioco
Panoramica tecnica
L'API delle notifiche di gioco è scritta ed esposta tramite l'API Web e richiede 4 parametri passati in ciascun metodo:
- appid (l'ID dell'applicazione del gioco)
- format (il formato del risultato. Si consiglia JSON come valore di ritorno)
- input_json (codifica JSON di tutti i parametri richiesti per un metodo)
- key (la chiave dell'editore da passare con tutte le chiamate)
In caso di operazione corretta, l'API restituirà un codice di stato HTTP di 200 con i dettagli nel corpo del messaggio (se applicabile).
Valori costanti
UserState
Un valore di stringa definito che può assumere le forme di seguito:
- waiting: l'utente è in attesa di altri giocatori e non sta bloccando alcuna azione. Non verrà inviata alcuna notifica all'utente in quanto questo è in attesa.
- ready: l'utente è pronto. La sessione di gioco è in attesa di una risposta dall'utente. Verrà inviata una notifica all'utente fino a quando questo stato non verrà rimosso.
- done: per questo utente il gioco termina qui. L'utente verrà avvisato che il gioco è finito, ma non sarà necessaria alcuna azione.
Strutture dei dati (JSON)
Tutte le strutture dei dati sono rappresentate in formato JSON.
Variable
{
"key": "key_name", // string
"value": "value_of_key" // string
}
LocalizedText
{
"token": "value", // stringa che indirizza a un token di localizzazione
"variables":
[
// Array di "Variable" (sopra)
]
}
UserStatus
{
"steamid": "76561197960265729", // uint64
"state": // Una delle costanti "UserState" (descritta sopra),
"title": // Un oggetto "LocalizedText" (descritto sopra),
"message": // Un oggetto "LocalizedText" (descritto sopra)
}
Session
{
"sessionid": "1", // uint64
"title": // A "LocalizedText" oggetto (sopra),
"time_created": "100000", // Epoca Unix (orario dal 1° gennaio 1970).
"time_updated": "200000", // Epoca Unix (orario dal 1° gennaio 1970).
// Valore a 64 bit fornito dallo sviluppatore al momento della creazione della sessione che verrà passato al gioco al momento dell'avvio.
// Questo ti consente di legare facilmente l'oggetto della sessione al tuo oggetto back-end e non viene utilizzato internamente da Steam.
"context": "31415926",
"user_status":
[
// Matrice di "UserStatus" oggetti (descritti sopra)
]
}
RequestedSession
{
"sessionid": "1", // uint64
"include_all_user_messages": "0" // bool
}
API comuni disponibili
Per l'elenco completo, consulta
IGameNotificationsService.
Avvio di sessioni di gioco specifiche
Gli utenti potranno visualizzare tutte le sessioni di gioco attive sulla propria pagina del profilo della Comunità in Steam. Insieme allo stato di gioco, è presente un pulsante per avviare un gioco da Steam con specifici parametri che definiscono la sessione di gioco. Avviando un gioco in questo modo si fornisce il parametro di avvio "_sessionid". Puoi ricevere questo parametro utilizzando
ISteamApps::GetLaunchQueryParam.
Come in questo esempio:
const char *pchSessionID = ISteamApps()->GetLaunchQueryParam("_sessionid");
Un gioco che supporta questo tipo di avvio diretto effettua la chiamata a questa interfaccia all'avvio, determina se la stringa dell'ID della sessione è presente e valida per l'utente che ha effettuato l'accesso e infine carica il gioco direttamente.
Localizzazione
La localizzazione viene fornita dallo sviluppatore del gioco tramite un apposito strumento che fa parte della configurazione dell'applicazione. È responsabilità dello sviluppatore impostare la traduzione di ciascuna lingua per ogni stringa immessa nello strumento di traduzione. Tutte le stringhe non tradotte nella lingua di un giocatore verranno visualizzate in lingua inglese.
Ciascuna delle seguenti proprietà delle notifiche di gioco può essere tradotta:
Ogni
testo tradotto è composto da due elementi:
Un token è una chiave che inizia con il simbolo "#" e rappresenta una stringa tradotta in diverse lingue mediante lo strumento di traduzione fornito nella configurazione dell'applicazione. Un singolo token può contenere più istanze variabili che possono essere sostituite all'avvio in base al contesto del gioco al momento della generazione del testo. Un esempio per l'inglese sarebbe
#InvitationText = "{{user}} has invited you to play a game of Chess."Nell'esempio qui sopra, la traduzione inglese per #InvitationText (testo dell'invito) contiene una singola variabile denominata "user" (utente). Se desideri che un utente visualizzi questo messaggio di testo quando viene invitato da un altro giocatore "SteamUserName" a unirsi a una partita, è necessario aggiornare l'oggetto contenente la traduzione LocalizationText con le seguenti proprietà:
"message":
{
"token": "#InvitationText",
"variables":
[
{ "key": "user", "value": "Michael" }
]
}
Quando un giocatore controlla il suo stato, vedrà questo messaggio (nella sua lingua): "Michael ti ha invitato a giocare a scacchi."
I token di localizzazione possono essere caricati sulla sezione ''Localizzazione asincrona", che si trova nella scheda Comunità delle impostazioni di Steamworks della tua applicazione.
Ogni lingua può essere caricata individualmente tramite file in formato VDF che hanno questo aspetto:
"lang"
{
"Language" "english"
"Tokens"
{
"TheNameOfTheToken" "Il testo tradotto associato al token"
"TheNameOfAnotherToken" "Il testo tradotto associato al secondo token"
}
}
In alternativa, i token per tutte le lingue possono essere caricati in un unico file come questo:
"lang"
{
"english"
{
"Tokens"
{
"TheNameOfTheToken" "Il testo tradotto associato al token"
"TheNameOfAnotherToken" "Il testo tradotto associato al secondo token"
}
}
"spanish"
{
"Tokens"
{
"TheNameOfTheToken" "El texto localizado asociado con el token"
"TheNameOfAnotherToken" "El texto localizado asociado con el segundo token"
}
}
}
