Aller au contenu principal
Développeurs Game SDK

Montrer à quoi quelqu’un joue

Laisse ton jeu dire à mssgs ce que fait un joueur. Ses amis voient « Joue à » sous son nom, ouvrent les détails et appuient sur Rejoindre pour arriver dans la même partie. Ton jeu peut aussi vérifier si un joueur fait partie de ta communauté.

Ce que tu peux faire

  • Publier un statut de jeuLe jeu, ce que fait le joueur, son rôle et le nombre de places prises dans le groupe.
  • Ajouter un bouton RejoindreLes amis rejoignent la même partie, le même serveur ou le même lobby en un appui.
  • Vérifier l’appartenanceDemande si un joueur fait partie de ta communauté, et avec quels rôles.
  • Ordinateur, navigateur ou téléphoneLes jeux natifs passent par le pont local ; les jeux sur navigateur et sur mobile passent par ton backend.

Dans l’app

daniJoue à Space Raiders
Space RaidersJoué par dani
Sector 7
En raid
3 sur 4 dans le groupe · depuis 12 min
Artilleur

Le statut sous un nom, et les détails qu’il ouvre. Le jeu a publié un seul bloc JSON ; l’application s’occupe du reste.

Présentation

L’application de bureau mssgs fait tourner un petit pont HTTP local auquel un jeu sur la même machine s’adresse. Ton jeu ne parle jamais à nos serveurs, ne voit jamais le mot de passe ni le jeton d’un compte, et ne peut jamais publier au nom du joueur. Il s’adresse à l’application mssgs sur laquelle le joueur est déjà connecté, et c’est elle qui décide quoi répondre.

Ce que tu peux en faire :

  • Détecter que mssgs est installé et que quelqu’un est connecté.
  • Savoir qui est le joueur : user_guid, nom d’utilisateur, avatar.
  • Demander « ce joueur est-il dans la communauté X ? » et quel rôle il y occupe.
  • Publier un statut « Joue à … » avec un bouton Rejoindre pour les autres.
  • Recevoir l’événement Rejoindre quand quelqu’un appuie sur ce bouton.

Deux points d’entrée

Un jeu de bureau natif s’adresse au pont local ; c’est ce que décrivent les sections suivantes. Un jeu dans un navigateur ou sur un téléphone ne peut pas atteindre ce pont. Pour ces jeux-là, c’est ton propre backend qui publie, pour les joueurs qui ont relié leur compte mssgs via un code QR ou un code à huit caractères : voir Jeux sur navigateur et mobile, avec CozyCity comme premier exemple. Le statut de jeu lui-même est le même bloc dans les deux cas.

Divulgation minimale, par défaut

Les scopes sont volontairement inégaux. Si tout ce dont tu as besoin est de savoir « cette personne est-elle dans notre communauté ? », tu demandes membership.query et tu indiques toi-même le server_guid : tu obtiens oui ou non, ainsi que ses rôles dans cette communauté, et tu n’apprends rien sur le reste de ses communautés. La liste complète se trouve derrière un scope distinct, plus élevé, que le joueur doit approuver à part.

Trouver le client

Le pont écoute uniquement sur 127.0.0.1, sur le premier port libre d’une petite plage. Essaie-les dans l’ordre jusqu’à ce que l’un réponde : 7440, 7441, 7442, 7443. Les versions de développement de mssgs écoutent plutôt sur 7540–7543, pour qu’une version de test ne réponde jamais aux appels d’un vrai jeu.

GET http://127.0.0.1:7440/mssgs/v1/hello

Aucun jeton n’est nécessaire, et la réponse ne dit rien du joueur : seulement que mssgs est là et si quelqu’un est connecté.

Réponse
{
  "product": "mssgs",
  "api": 1,
  "client": "desktop",
  "version": "14.2.20015",
  "platform": "darwin",
  "signed_in": true,
  "scopes": ["identity", "staff", "membership.query", "servers.list", "presence.write"]
}

Vérifie product === "mssgs" et api avant d’aller plus loin. Si aucun des quatre ports ne répond, mssgs ne tourne pas. Lance simplement ton jeu comme d’habitude, sans faire attendre le joueur.

Demander la permission

Tout sauf /hello nécessite un jeton, et un jeton n’existe qu’une fois que le joueur a approuvé ton jeu dans une boîte de dialogue de l’application. Ne demande que les scopes que tu utilises vraiment : le joueur les voit un par un, chacun avec son explication, et peut les décocher individuellement.

1. Demander la permission
curl -X POST http://127.0.0.1:7440/mssgs/v1/authorize \
  -H "Content-Type: application/json" \
  -d '{
    "game_id": "com.acme.spacegame",
    "name": "Space Raiders",
    "scopes": ["identity", "membership.query", "presence.write"]
  }'

Tu reçois {"status":"pending","request_id":"…","poll_after_ms":1000} et le joueur voit la boîte de dialogue. Interroge ensuite le pont à intervalles réguliers jusqu’à ce que le joueur réponde (la demande expire au bout de 3 minutes) :

2. Attendre la réponse
curl http://127.0.0.1:7440/mssgs/v1/authorize/<request_id>

# {"status":"approved","token":"…","scopes":["identity","presence.write"],"game_id":"com.acme.spacegame"}

Vérifie toujours ce que tu as réellement obtenu

Les scopes de la réponse peuvent être moins nombreux que ceux que tu as demandés : le joueur est libre d’en décocher certains. Dans l’exemple ci-dessus, membership.query a été refusé. Base-toi sur ce que dit la réponse, pas sur ce que tu as demandé, sinon tu tomberas sur un 403 MISSING_SCOPE que tu n’avais pas prévu.

Conserve le jeton et envoie-le sous la forme Authorization: Bearer <token>. Il reste valable après un redémarrage : le joueur approuve ton jeu une seule fois, pas à chaque session. Si tu redemandes plus tard l’autorisation avec des scopes déjà accordés, tu récupères directement le même jeton, sans boîte de dialogue.

Scopes et confidentialité

Les cinq scopes ne révèlent pas du tout la même quantité d’informations. Ce n’est pas un hasard, c’est tout le principe. Demande le moins possible : pars du haut de ce tableau et ne descends que si nécessaire.

Scope Ce qu’il permet Ce que le joueur dévoile
presence.write Montrer à quoi il joue Rien. Ce scope ne fait qu’écrire ; il ne lit aucune donnée du compte.
identity Qui est le joueur user_guid, nom d’utilisateur, nom affiché, URL de l’avatar.
staff Indicateurs équipe / modérateur Deux booléens, en plus d’identity. Un scope à part, car un jeu qui affiche un nom n’a pas à savoir que le joueur modère des communautés.
membership.query Vérifier une communauté que tu connais déjà Pour un server_guid que tu indiques : oui/non, son nom et les rôles que ce joueur y détient. Rien sur aucune autre communauté.
servers.list Toutes les communautés dont il fait partie La liste complète : guids, noms, icônes et rôles. C’est le plus coûteux : ne le demande que si tu en as vraiment besoin.

La plupart des jeux en ont besoin de deux

identity et presence.write couvrent « qui es-tu » et « montre à quoi tu joues », ce qui correspond à presque toutes les intégrations. Ajoute membership.query si tu veux lier une récompense à l’appartenance à ta communauté. Tu n’as presque jamais besoin de servers.list, et le joueur le voit signalé en rouge.

Vérifier l’appartenance

C’est l’alternative à « donne-moi toute la liste ». Tu indiques le server_guid de ta propre communauté (que tu connais déjà) et tu obtiens une réponse pour elle seule.

Une communauté
curl -H "Authorization: Bearer $TOKEN" \
  "http://127.0.0.1:7440/mssgs/v1/membership?server_guid=ca94ecc…f4g02"

# membre :
# {"server_guid":"ca94ecc…","member":true,"name":"Acme Fans","is_owner":false,
#  "roles":[{"guid":"0aa32…","name":"Pro"}]}

# pas membre, et rien d’autre :
# {"server_guid":"…","member":false}

Un « non » veut dire exactement cela, rien de plus. Tu peux passer jusqu’à 10 guids par appel (répète server_guid ou sépare-les par des virgules), ce qui renvoie un tableau results. Le groupe @everyone n’est jamais dans roles : il s’applique à tous les membres, donc il ne t’apprend rien.

Publier un statut de jeu

Un seul PUT place la ligne « Joue à … » sous le nom du joueur, partout où ses communautés le voient.

PUT /mssgs/v1/activity
{
  "name":    "Space Raiders",
  "details": "Sector 7",
  "state":   "In a raid",
  "role":    "Gunner",
  "started_at": 1755859200000,
  "party":   { "size": 3, "max": 4, "kind": "party" },
  "join":    { "secret": "raid-42" }
}

Seul name est obligatoire. La réponse t’indique combien de temps le statut reste actif et à quelle fréquence envoyer un heartbeat :

Réponse
{ "ok": true, "expires_in_ms": 90000, "heartbeat_every_ms": 30000 }

Un heartbeat, sinon le statut disparaît

Un statut sans signe de vie pendant 90 secondes est effacé automatiquement. C’est voulu : si ton jeu plante, le joueur ne reste pas « en train de jouer » pendant des heures. Envoie un POST /mssgs/v1/activity/heartbeat toutes les 30 secondes, et DELETE /mssgs/v1/activity lors d’un arrêt propre.

Nombre de joueurs et rôle

party.kind détermine la phrase affichée, car les deux mêmes nombres ne veulent pas dire la même chose. Une escouade de quatre n’est pas un serveur sur lequel jouent quatre personnes.

kind Affichage Pour
party (par défaut)3 sur 4 dans le groupeune escouade, une équipe ou un groupe
server4/100 joueursun serveur de jeu (FiveM, un serveur communautaire)
lobby4/100 joueursun lobby avant le début de la partie
match4/100 joueursune partie ou une manche en cours

role (jusqu’à 48 caractères) est ce que le joueur incarne : un métier, une classe ou un personnage. Il a son propre champ plutôt qu’une phrase de plus dans state, car il s’affiche comme une étiquette à côté du nombre de joueurs.

details et state sont limités à 128 caractères chacun, name à 64. Les sauts de ligne et les caractères de contrôle sont supprimés. Une URL d’icône n’est volontairement pas prise en charge : elle serait chargée par chaque client qui affiche la ligne, ce qui transformerait un statut en mouchard signalant à ton serveur chaque membre de chaque communauté dont le joueur fait partie.

Le bouton Rejoindre

Mets un bloc join dans ton activité et les autres membres voient un bouton Rejoindre à côté du statut. Il y a deux façons de faire, et tu peux les combiner.

1. Un secret (pour les jeux natifs)

Définis {"join":{"secret":"raid-42"}}. Quand quelqu’un appuie sur Rejoindre, ce secret est remis à sa propre copie de ton jeu, sur sa propre machine, reconnue grâce au même game_id. Aucune URL n’est ouverte et aucun gestionnaire de protocole n’est invoqué. Ton jeu le récupère avec :

GET /mssgs/v1/events
{
  "events": [
    { "seq": 1, "type": "join", "secret": "raid-42",
      "from": { "user_guid": "62e377…", "username": "dani" } }
  ],
  "cursor": 1
}

Interroge avec ?since=<cursor> pour voir chaque événement une seule fois. Si le jeu de la personne qui a appuyé ne tourne pas, rien n’est remis, ce qui est une bonne raison de proposer aussi une URL.

2. Une URL https (pour les jeux web et les liens de lobby)

Définis {"join":{"url":"https://play.example.com/s/abc"}} et le bouton ouvre ce lien. Seul https est accepté. Un schéma d’URL personnalisé (steam://, mygame://, file://) est refusé : ce bloc s’affiche sur l’écran de chaque membre, et une telle URL permettrait de faire lancer, sur la machine de quelqu’un d’autre, un gestionnaire local avec des arguments de ton choix.

Tout le contenu de join est public

Le bloc join est diffusé à toutes les personnes qui peuvent voir le statut du joueur ; c’est tout l’intérêt d’un bouton Rejoindre. Traite-le donc comme un code de lobby, pas comme un identifiant de connexion. N’y mets jamais rien qui doive rester secret, et fais expirer tes codes.

FiveM

Le runtime Lua côté client de FiveM n’a pas de HTTP : une ressource s’adresse donc au pont via NUI, une vue CEF, qui envoie un en-tête Origin. Le pont accepte explicitement ces origines : https://cfx-nui-<resource> et l’ancienne forme nui://<resource>. Les pages web ordinaires restent refusées, et une page publique ne peut pas usurper cette origine : c’est le navigateur lui-même qui la fixe.

client.lua : demander à la NUI de publier
-- La page NUI fait la requête HTTP ; Lua ne lui envoie que les données.
CreateThread(function()
  while true do
    SendNUIMessage({
      action  = 'mssgs:publish',
      players = GetActivePlayers and #GetActivePlayers() or 0,
      maxPlayers = GetConvarInt('sv_maxclients', 100),
      job     = exports['qb-core'] and 'Police' or nil
    })
    Wait(30000) -- heartbeat : le statut expire après 90 s
  end
end)
nui.js
const BASE = 'http://127.0.0.1:7440/mssgs/v1';   // essaie 7440-7443
let token = null;

async function authorize () {
  const res = await fetch(`${BASE}/authorize`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      game_id: 'fivem.lossantos.rp',
      name: 'Los Santos Roleplay',
      scopes: ['presence.write']          // rien de plus n’est nécessaire ici
    })
  });
  const started = await res.json();
  if (started.status === 'approved') { return started.token; }

  // Le joueur voit maintenant la demande d’autorisation dans mssgs.
  for (let i = 0; i < 180; i += 1) {
    await new Promise((r) => { setTimeout(r, 1000); });
    const poll = await (await fetch(`${BASE}/authorize/${started.request_id}`)).json();
    if (poll.status === 'approved') { return poll.token; }
    if (poll.status !== 'pending') { return null; }
  }
  return null;
}

window.addEventListener('message', async (event) => {
  if (event.data.action !== 'mssgs:publish') { return; }
  if (!token) { token = await authorize(); }
  if (!token) { return; }

  await fetch(`${BASE}/activity`, {
    method: 'PUT',
    headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}` },
    body: JSON.stringify({
      name: 'FiveM',
      details: 'Los Santos Roleplay',
      role: event.data.job,                       // "Police"
      party: { size: event.data.players, max: event.data.maxPlayers, kind: 'server' },
      join: { url: 'https://cfx.re/join/abc123' } // ton lien cfx.re
    })
  });
});

Le résultat : Joue à FiveM · Los Santos Roleplay · 4/100 joueurs · Police, avec un bouton Rejoindre qui ouvre ton lien cfx.re.

Demande seulement presence.write

Un statut de jeu n’a besoin de rien d’autre : ce scope ne lit absolument rien. Si tu veux lier une récompense en jeu à l’appartenance à ta communauté mssgs, ajoute membership.query et indique ton propre server_guid ; tu n’apprends toujours rien sur les autres communautés du joueur.

Un serveur sur lequel tu joues n’est pas automatiquement de confiance

N’importe quel serveur FiveM peut exécuter des ressources client, donc n’importe quel serveur que quelqu’un rejoint peut demander la permission. C’est justement pour cela qu’une boîte de dialogue s’intercale, en nommant la ressource : c’est le joueur qui décide, pas le serveur.

Jeux sur navigateur et mobile : la liaison via ton backend

Un jeu dans un onglet de navigateur ou sur un téléphone ne peut pas atteindre le pont décrit plus haut. Le pont tourne sur l’ordinateur du joueur, et trois obstacles se dressent entre les deux : le pont refuse toute requête qui porte un Origin de navigateur, Chrome affiche une demande d’autorisation quand une page publique interroge 127.0.0.1 et Safari refuse tout net, et un téléphone n’a aucun moyen d’atteindre l’adresse de bouclage (loopback) d’un ordinateur.

Le sens s’inverse donc. Ton propre backend sait déjà qui joue, et c’est lui qui le dit à mssgs, pour les joueurs qui ont relié leur compte mssgs à ton jeu. La liaison est approuvée dans l’application mssgs, jamais dans ton jeu, et elle crée un lien, jamais une session : rien de ce qui suit ne permet de connecter qui que ce soit ni d’agir au nom du joueur. Ton client de jeu ne voit jamais de clé et ne parle jamais à mss.gs. Le premier jeu sur cette voie est CozyCity, un jeu de construction de ville disponible en page WebGL et en app iPhone, sans version de bureau ; les exemples ci-dessous sont les siens.

1. Enregistre ton jeu

Enregistre le jeu sur la page d’enregistrement du Game SDK : ton game_id (par exemple com.deverence.cozycity), le nom et l’icône que le joueur voit sur la fiche d’approbation, et les noms d’hôte de ton backend. Nous l’examinons sur cette page et, une fois le jeu approuvé, ta clé de backend t’y attend, affichée une seule fois ; nous n’en gardons qu’une empreinte. La clé a sa place sur ton serveur et nulle part ailleurs. Tu peux la renouveler sur cette page à tout moment, et l’ancienne reste valable 24 heures pour qu’un déploiement puisse se faire progressivement.

Enregistrer ton jeu

Le nom et l’icône de la fiche viennent toujours de l’enregistrement, jamais de la requête. Sinon, un lien d’hameçonnage pourrait faire passer une demande de liaison pour celle de n’importe quel jeu. Les noms d’hôte limitent les destinations possibles d’un join.url, voir plus bas.

2. Relie un joueur

Le joueur choisit Connecter mssgs dans ton jeu. Ton jeu s’adresse à ton backend, qui nous envoie la demande :

POST /game-sdk/v1/link/start
curl -X POST https://gateway.mss.gs/game-sdk/v1/link/start \
  -H "Authorization: Bearer $BACKEND_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "player_ref": "player-8812", "player_name": "René\u2019s city" }'

# {"link_code":"K7PQ2XM4","device_code":"…","qr_url":"https://mss.gs/gl/K7PQ2XM4",
#  "deep_link":"mssgs://link-game/K7PQ2XM4","expires_in":600,"interval":5}

player_ref est ton propre identifiant stable pour ce joueur (jusqu’à 128 caractères), pas pour une session ni une partie ; player_name (jusqu’à 64) est ce que la fiche affiche après « Joueur : ». Ne transmets à ton client de jeu que link_code, qr_url et deep_link. device_code te sert à interroger le statut et reste sur le serveur.

Ton jeu affiche alors trois choses à la fois, car le joueur peut se trouver n’importe où :

  • Le code QR de qr_url. Un téléphone avec mssgs l’ouvre directement sur la fiche d’approbation de l’application. Sans l’application, il arrive sur une page de mss.gs qui affiche le code et propose le téléchargement.
  • Un bouton « Ouvrir dans mssgs » avec deep_link, pour un navigateur utilisé sur le même ordinateur que l’application de bureau. C’est la seule URL externe que ton jeu aura jamais besoin d’ouvrir.
  • Le code lui-même, en deux groupes de quatre, à saisir dans Réglages → Activité de jeu → Lier un jeu. L’alphabet n’a ni 0/O ni 1/I, donc la saisie se passe rarement mal.

Ce que le joueur voit dans mssgs, affiché par l’application à partir de l’enregistrement :

Connecter CozyCity à ton compte mssgs ?

CozyCity pourra montrer à quoi tu joues dans ton statut mssgs. Il ne verra pas tes messages, tes amis ni tes serveurs, et ne pourra pas publier en ton nom.
Joueur : La ville de René · Connecter / Pas maintenant

Pendant ce temps, ton backend interroge toutes les interval secondes (si tu vas plus vite, la réponse est 429 SLOW_DOWN) jusqu’à ce que le statut change. Un code ne sert qu’une fois et expire au bout de dix minutes :

POST /game-sdk/v1/link/poll
curl -X POST https://gateway.mss.gs/game-sdk/v1/link/poll \
  -H "Authorization: Bearer $BACKEND_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "device_code": "…" }'

# {"status":"pending"}
# {"status":"denied"}      # le joueur a choisi Pas maintenant
# {"status":"expired"}
# {"status":"linked","link_guid":"…","user":{"user_guid":"62e377…"}}

Associe link_guid à ton joueur ; c’est désormais l’adresse à laquelle tu publies pour lui. La réponse ne contient que le user_guid ; un username n’est ajouté que si ton enregistrement détient le scope identity.link, et il n’y a rien au-delà. Une deuxième approbation pour le même player_ref remplace la liaison précédente, donc un joueur de ton jeu correspond à un compte mssgs. Un même compte mssgs peut être relié à plusieurs jeux et à plusieurs player_ref d’un même jeu (un iPad familial).

3. Publie le statut de jeu

Le même bloc que sur le pont, avec les mêmes règles et les mêmes limites, mais cette fois par liaison et avec ta clé de backend :

PUT /game-sdk/v1/links/{link_guid}/activity
{
  "activity": {
    "name":       "CozyCity",
    "details":    "Lantern Hollow",
    "state":      "Day 12 · 34 residents",
    "started_at": 1788901000000,
    "party":      { "size": 6, "max": 40, "kind": "server" },
    "join":       { "url": "https://cozycity.net/game/?share=…" }
  }
}
Réponses
200 {"published":true,"changed":true}     # le bloc a changé et a été diffusé
200 {"published":true,"changed":false}    # identique à ce qui était enregistré ; seul le TTL a été rafraîchi
204                                        # enregistré, mais le joueur n’est pas en ligne dans mssgs en ce moment
410 {"error":"LINK_REVOKED"}               # le joueur a déconnecté le jeu : abandonne la liaison

Traite 200 et 204 de la même façon : enregistré. { "activity": null } efface le bloc, envoie-le quand le joueur quitte la partie. Une différence avec le pont : l’hôte de join.url doit être l’un de tes backends enregistrés (ou un sous-domaine de l’un d’eux), sinon tu reçois 400 INVALID_PAYLOAD. Un backend ne peut donc pas placer sur le statut d’un joueur un bouton Rejoindre qui mène quelque part où ce joueur n’a jamais joué.

Un heartbeat toutes les 60 secondes, TTL 120

Un statut publié reste affiché 120 secondes sans nouveau message, puis disparaît tout seul. Renvoie donc le même bloc toutes les 60 secondes ; un bloc inchangé ne coûte rien et ne fait que rafraîchir le TTL. Si ton heartbeat s’arrête, la ligne « Joue à … » disparaît aussi, et c’est exactement le but.

Avec des centaines de joueurs en ligne, envoie le heartbeat en un seul appel, jusqu’à 100 éléments à la fois. Chaque élément reçoit son propre statut, donc un joueur qui a déconnecté ton jeu dans mssgs ne bloque jamais les quatre-vingt-dix-neuf autres :

POST /game-sdk/v1/activity/batch
{ "items": [ { "link_guid": "…", "activity": { "name": "CozyCity", "details": "Lantern Hollow" } },
             { "link_guid": "…", "activity": null } ] }

// → 200 { "results": [ { "link_guid": "…", "status": 200, "changed": false },
//                      { "link_guid": "…", "status": 410 } ] }

Comment le statut s’affiche

  • Identique à un statut publié via le pont : Joue à CozyCity · Lantern Hollow · 6/40 joueurs, avec Rejoindre quand il y a un join.url. Le bloc est marqué via: "backend" côté serveur, donc un client peut ajouter « Partagé par le serveur du jeu ».
  • Seulement tant que le joueur est en ligne dans mssgs. Sans client mssgs ouvert, le compte est hors ligne et le reste ; ton backend ne peut pas faire passer quelqu’un pour présent. Cela empêche aussi cette voie de devenir un mouchard « René est-il devant son ordinateur ? ».
  • Priorité : un jeu intégré à l’application > un jeu sur le pont > ton backend. Si le joueur se lance dans une partie d’échecs dans mssgs pendant que ton backend continue d’envoyer des heartbeats, ce sont les échecs qui l’emportent, pas le dernier à avoir écrit.

Déconnexion

Le joueur voit chaque liaison dans Réglages → Activité de jeu → Jeux liés, avec ton icône et ton nom, le nom de joueur venant de ton jeu, la date de la liaison et de la dernière publication, et un bouton Déconnecter. Après cela, ta publication suivante reçoit la réponse 410 LINK_REVOKED ; c’est ainsi que ton jeu l’apprend. Abandonne le link_guid et propose à nouveau « Connecter mssgs ». De ton côté, mets fin à une liaison avec DELETE /game-sdk/v1/links/{link_guid}.

Limites

Par liaison, un changement compte au plus toutes les 2 secondes ; un heartbeat inchangé est gratuit. Par clé, il y a 600 requêtes par minute, les éléments d’un lot étant comptés individuellement : envoyer un heartbeat pour 300 joueurs toutes les 60 secondes en consomme 5 sur 600.

Référence des points d’accès : le pont

URL de base http://127.0.0.1:<port>. Tous les points d’accès sauf les trois premiers exigent Authorization: Bearer <token>.

Méthode Chemin Scope Ce qu’il fait
GET /mssgs/v1/hello aucun Indique si mssgs est là, quelle version de l’API il parle et si quelqu’un est connecté. La seule route qui ne demande pas de jeton, et elle ne dit rien du joueur.
POST /mssgs/v1/authorize aucun Demande la permission au joueur. Ouvre une boîte de dialogue dans l’application et renvoie un request_id à interroger.
GET /mssgs/v1/authorize/:request_id aucun pending, approved (avec le jeton), denied ou expired.
GET /mssgs/v1/me identity Le joueur connecté. Ajoute is_staff / is_moderator uniquement avec le scope staff.
GET /mssgs/v1/membership membership.query L’appartenance aux server_guid que tu passes (jusqu’à 10, répétés ou séparés par des virgules).
GET /mssgs/v1/servers servers.list Toutes les communautés dont le joueur fait partie, avec ses rôles. Les messages privés ne sont jamais inclus.
PUT /mssgs/v1/activity presence.write Publie le bloc « Joue à … ». Renvoie le TTL et la fréquence du heartbeat.
POST /mssgs/v1/activity/heartbeat presence.write Garde l’activité publiée active sans la renvoyer.
DELETE /mssgs/v1/activity presence.write L’efface immédiatement, pour un arrêt propre.
GET /mssgs/v1/events presence.write Les événements Rejoindre destinés à ton jeu. Interroge avec ?since=<cursor>.
GET /mssgs/v1/session aucun Ce que ce jeton détient : game_id, scopes accordés, si quelqu’un est connecté.
DELETE /mssgs/v1/session aucun Rend la permission. Même effet que si le joueur la révoquait dans les Réglages.

Référence des points d’accès : backends liés

URL de base https://gateway.mss.gs (qui t’oriente vers le hub le plus proche). Chaque route exige Authorization: Bearer <backend key> et le scope activity.write sur ton enregistrement ; les réponses partent avec Cache-Control: no-store. Appelle-les depuis ton serveur, jamais depuis le client de jeu.

Méthode Chemin Ce qu’il fait
POST /game-sdk/v1/link/start Lance une liaison pour l’un de tes joueurs ({ player_ref, player_name ? }). Renvoie link_code, device_code, qr_url, deep_link, expires_in et interval.
POST /game-sdk/v1/link/poll { device_code } → pending, denied, expired, ou linked avec link_guid et user.
DELETE /game-sdk/v1/links/{link_guid} Met fin à une liaison de ton côté. Le joueur peut faire de même depuis les Réglages.
PUT /game-sdk/v1/links/{link_guid}/activity Publie le bloc « Joue à … » pour un joueur ; { "activity": null } l’efface.
POST /game-sdk/v1/activity/batch La même chose, pour jusqu’à 100 joueurs en un seul appel. Chaque élément répond séparément.

Codes d’erreur

Les erreurs reviennent sous la forme {"error":"CODE","message":"…"} avec le statut HTTP correspondant.

Code Signification
401 UNAUTHORIZEDJeton manquant ou inconnu ; demande d’abord l’autorisation.
403 MISSING_SCOPELe joueur n’a pas accordé cette permission. Il l’a peut-être décochée.
403 ORIGIN_NOT_ALLOWEDLa requête portait un Origin de navigateur. Voir « Jeux natifs uniquement » plus bas.
409 NOT_SIGNED_INmssgs tourne mais personne n’est connecté.
429 RATE_LIMITEDPlus de 120 requêtes en une minute depuis un même jeu.
400 INVALID_GAME_IDgame_id doit être composé de lettres, chiffres, points, tirets ou tirets bas.
400 TOO_MANY_GUIDSAu maximum 10 valeurs server_guid par appel d’appartenance.

Backends liés

Les routes du backend utilisent la même forme. Dans un lot, le statut revient par élément dans results, donc une liaison terminée ne fait jamais échouer tout l’appel.

Code Signification
401 INVALID_BACKEND_KEYClé inconnue, ou renouvelée il y a plus de 24 heures.
403 SCOPE_NOT_GRANTEDTon enregistrement ne détient pas le scope dont cette route a besoin.
400 INVALID_PAYLOADCorps mal formé, plus de 100 éléments dans un lot, ou un join.url dont l’hôte n’est pas l’un de tes backends enregistrés.
400 INVALID_ACTIVITYPlus aucun name utilisable après normalisation.
410 LINK_REVOKEDLa liaison a pris fin, d’un côté ou de l’autre. Abandonne-la et propose à nouveau « Connecter mssgs ».
429 SLOW_DOWNTu as interrogé link/poll plus vite que interval.
429 RATE_LIMITEDUn changement sur une liaison moins de 2 secondes après le précédent, ou plus de 600 requêtes en une minute sur ta clé.
503 LINK_STORE_UNAVAILABLEProblème temporaire de notre côté. Réessaie au prochain heartbeat.

Sécurité

Jeux natifs uniquement

Les requêtes qui portent un Origin de page web sont refusées avec 403 ORIGIN_NOT_ALLOWED. Qu’une page web quelconque puisse détecter que tu utilises mssgs et faire apparaître une demande d’autorisation ouvrirait la porte au fingerprinting et à l’hameçonnage : ce n’est pas une fonctionnalité. Un jeu natif n’envoie aucun Origin, il n’est donc pas concerné, et le navigateur intégré d’un jeu est autorisé nommément, voir FiveM. Si tu développes un jeu sur navigateur ou sur mobile, tu ne t’adresses pas au pont : ton propre backend publie pour les joueurs liés, voir Jeux sur navigateur et mobile.

Ce que le joueur garde en main

  • Le joueur peut désactiver le pont dans Réglages → Activité de jeu, après quoi aucun jeu ne peut plus voir mssgs.
  • Chaque jeu approuvé y est listé avec exactement les permissions qu’il détient, sa dernière activité et un bouton Retirer. Le retrait est immédiat : le jeton est aussitôt invalidé.
  • Un jeu lié, sur navigateur ou sur mobile, est listé sous Jeux liés avec un bouton Déconnecter. La déconnexion est elle aussi immédiate : la publication suivante de ce backend reçoit un 410.
  • Le pont écoute uniquement sur 127.0.0.1, jamais sur le réseau.
  • Les messages privés ne sont jamais divulgués, pas même avec servers.list.
  • Chaque jeu dispose d’un budget de 120 requêtes par minute.

Les bonnes pratiques

  • Demande les scopes quand tu en as besoin, pas tous d’un coup au premier lancement.
  • Fais fonctionner ton jeu sans mssgs : le joueur n’est pas obligé de l’avoir.
  • Efface ton statut quand la partie s’arrête au lieu d’attendre le TTL.
  • Traite un scope refusé comme un résultat normal, pas comme une erreur.

Pour aller plus loin