Présentation
Les notifications de jeu Steam sont un système permettant de fournir des notifications hors ligne aux utilisateurs pour les jeux multijoueurs asynchrones, comme les échecs.
Le but de cette API est de notifier les utilisateurs qu'une action est requise dans une session de jeu pour progresser. Dans l'exemple du jeu d'échecs, l'état de la session de jeu est mis à jour après le coup de chaque joueur. Steam va alors envoyer des notifications aux utilisateurs en fonction de l'état de la session de jeu pour les avertir lorsque le jeu attend leur coup.
Responsabilités du jeu
Un jeu en ligne typique gèrerait une session de jeu en mettant à jour le statut de chaque utilisateur avec des états qui, à leur tour, vont envoyer une notification à l'utilisateur pour qu'il sache qu'il doit lancer le jeu et effectuer une action. Lors du lancement et de l'exécution d'actions de jeu, le jeu est censé mettre à nouveau la session de jeu à jour avec des états à jour pour tous les utilisateurs de la session.
Ce que Steam va gérer
Steam s'occupe de notifier les utilisateurs qui sont dans une session de jeu en fonction des états fournis par le jeu et des paramètres spécifiques que l'utilisateur a choisis pour le jeu. Une alerte s'affichera dans le client Steam et le navigateur Web pour avertir l'utilisateur qu'une action est requise pour un jeu.
Exigences
L'API de notifications de jeu est fournie via les méthodes de l'API Web et nécessite une clé éditeur valide. Les appels de méthodes de l'API Web doivent provenir d'un serveur hébergé séparé du client de jeu. La clé de l'éditeur ne doit être livrée avec aucun code du client de jeu.
Authentification et comptes tiers
Pour appeler les API de notifications de jeu, vous devez d'abord établir l'identité de l'utilisateur Steam connecté à votre jeu. Vous pouvez le faire de deux façons : un client de jeu peut générer un ticket d'authentification de session et le repasser à votre serveur ou un jeu Web peut vérifier l'utilisateur en utilisant OpenID. Vous trouverez les instructions correspondantes dans
Lier des comptes tiers à des comptes Steam. Il est important que vous ne fassiez pas confiance à l'identité d'un utilisateur dans les messages envoyés directement depuis le client de jeu vers votre serveur de jeu, car ces messages peuvent être trafiqués.
Pour les jeux qui utilisent des comptes tiers, suivez les instructions fournies plus haut, mais mettez le SteamID de l'utilisateur en cache dans votre système.
API de notifications de jeu
Présentation technique
L'API des notifications de jeu est écrite et exposée via les API Web et nécessite de passer quatre paramètres dans chaque méthode :
- AppID (l'ID d'application de votre jeu)
- format (le format du résultat. Nous recommandons json comme valeur de retour)
- input_json (encodage json de tous les paramètres nécessaires à une méthode)
- key (votre clé éditeur à passer lors de chaque appel)
L'API renverra un code de statut HTTP de 200 en cas de réussite, avec les détails dans le corps du message (le cas échéant).
Constantes
UserState
C'est une chaine de caractères qui a l'une des valeurs suivantes :
- waiting : l'utilisateur attend d'autres joueurs et ne bloque aucune action. Aucune notification ne sera envoyée à l'utilisateur parce qu'il attend que quelque chose se produise.
- ready : l'utilisateur est prêt. La session de jeu attend une réponse de l'utilisateur. Une notification sera envoyée à l'utilisateur jusqu'à ce que cet état soit supprimé.
- done : la partie est terminée pour cet utilisateur. L'utilisateur sera notifié que la partie est terminée, mais aucune action n'est requise.
Structures de données (JSON)
Toutes les structures de données sont représentées au format JSON.
Variable
{
"key": "nom_de_clé", // chaine
"value": "valeur_de_la _clé" // chaine
}
LocalizedText
{
"token": "valeur", // chaine qui correspond à un jeton de localisation
"variables":
[
// Tableau de « Variable » (cf ci-dessus)
]
}
UserStatus
{
"steamid": "76561197960265729", // uint64
"state": // Une des constantes UserState décrites ci-dessus,
"title": // Un objet « LocalizedText » (décrit ci-dessus),
"message": // Un objet « LocalizedText » (décrit ci-dessus)
}
Session
{
"sessionid": "1", // uint64
"title": // Un objet « LocalizedText » (cf ci-dessus),
"time_created": "100000", // Heure Unix (temps écoulé depuis le 1er janvier 1970).
"time_updated": "200000", // Heure Unix (temps écoulé depuis le 1er janvier 1970).
// valeur 64 bits fournie par l'équipe de développement quand la session est créée et qui sera passée au jeu quand celui-ci sera lancé.
// Ceci vous permet de lier facilement l'objet session à votre propre objet backend, elle n'est pas utilisée en interne par Steam.
"context": "31415926",
"user_status":
[
// Tableau d'objets « UserStatus » (décrits ci-dessus)
]
}
RequestedSession
{
"sessionid": "1", // uint64
"include_all_user_messages": "0" // booléen
}
API communes disponibles.
Consultez
IGameNotificationsService pour obtenir la liste complète.
Lancer des sessions de jeu spécifiques
Les utilisateurs pourront voir toutes leurs sessions de jeu actives sur leur page de profil de la communauté dans Steam. En plus du statut du jeu, il y a un bouton pour indiquer à Steam de lancer le jeu avec des paramètres de lancement spécifiques pour définir la session de jeu. Quand un jeu est lancé de cette façon, un paramètre de lancement de « _sessionid » sera fourni au jeu. Vous pouvez recevoir ce paramètre à l'aide de
ISteamApps::GetLaunchQueryParam.
Ainsi :
const char *pchSessionID = ISteamApps()->GetLaunchQueryParam("_sessionid");
Un jeu compatible avec un lancement direct dans une partie de cette manière doit appeler cette interface lors du lancement du jeu, déterminer si la chaine d'ID de session est présente et valide pour l'utilisateur connecté et charger directement le jeu.
Localisation
La localisation est fournie par l'équipe de développement du jeu via un outil de localisation qui fait partie de la configuration de l'application. Vous devez vous charger de fournir la traduction dans chaque langue de chaque chaine saisie dans l'outil de localisation. Toute chaine non traduite dans la langue du joueur sera affichée en anglais.
Les propriétés suivantes des notifications de jeu peuvent être localisées :
Chaque élément de texte localisé
LocalizedText est composé de deux parties :
Un jeton est une clé qui commence par le symbole # et représente une chaine qui est localisée dans différentes langues via l'outil de localisation dans la configuration de votre application. Un jeton unique peut contenir plusieurs instances de Variable qui peuvent être remplacées lors de l'exécution du programme en fonction du contexte du jeu lorsque le texte doit être généré. Voici un exemple :
#InvitationText = "{{user}} vous a invité(e) à jouer aux échecs."Dans l'exemple ci-dessus, la traduction en français de #InvitationText contient une variable unique appelée « user ». Lorsque vous voudrez afficher ce message texte à un utilisateur quand « SteamUserName » l'invite à jouer une partie, vous mettrez à jour l'objet LocalizationText avec les propriétés suivantes :
"message":
{
"token": "#InvitationText",
"variables":
[
{ "key": "user", "value": "Michael" }
]
}
Quand le joueur regardera son statut, il verra ensuite ce message (dans sa langue) : « Michael vous a invité(e) à faire une partie d'échecs.
Les jetons de localisation peuvent être téléchargés dans la section « Notifications asynchrones » de l'onglet Communauté de la page des paramètres Steamworks de votre application.
Chaque langue peut être téléchargée individuellement dans des fichiers VDF qui ressemblent à ceci :
"lang"
{
"Language" "english"
"Tokens"
{
"TheNameOfTheToken" "The localized text associated with the token"
"TheNameOfAnotherToken" "The localized text associated with the second token"
}
}
Vous pouvez aussi télécharger les jetons pour toutes les langues dans un fichier unique qui se présente ainsi :
"lang"
{
"english"
{
"Tokens"
{
"TheNameOfTheToken" "The localized text associated with the token"
"TheNameOfAnotherToken" "The localized text associated with the second token"
}
}
"french"
{
"Tokens"
{
"NomDuJeton" "Texte localisé associé au jeton"
"NomD'unAutreJeton" "Texte localisé associé au 2e jeton"
}
}
}
