Concepts clés

Projets, clés, sessions joueur, et la façon dont chaque SDK renvoie résultats et erreurs.

Les commentaires du code et les noms d'API restent en anglais pour correspondre aux SDK.

Sur cette page

Projets et clés
Joueurs et sessions
Des résultats plutôt que des exceptions
Nouvelles tentatives et limites de débit
ID de requête et journaux

Projets et clés#

Chaque jeu correspond à un projet. Ses clés identifient le projet, pas un joueur.

Identifiant	Où l'utiliser
Base URL	L'adresse de cette installation. L'API se trouve sous `/v1`.
Project ID	Dans chaque requête, en tant que `X-Project-ID`. Public.
Clé client `pk_live_…`	Builds du jeu et pages web, en tant que `X-Client-Key`. Publique : elle ne peut agir que pour des joueurs connectés.
Clé secrète `sk_live_…`	Uniquement sur vos propres serveurs, en tant que `X-Secret-Key`. Affichée une seule fois et stockée sous forme de hash ; donne accès aux endpoints réservés aux serveurs.

Ne mettez jamais la clé secrète (sk_live_…) dans un build du jeu ou une page web. Tout ce qui est distribué aux joueurs peut être lu.

Joueurs et sessions#

Les appels joueur nécessitent un jeton d'accès. La connexion en renvoie un (valable une heure) ainsi qu'un jeton de rafraîchissement (valable 30 jours).

Les SDK enregistrent la session sur l'appareil et la rafraîchissent avant son expiration : les joueurs restent connectés d'un lancement à l'autre.
Les jetons de rafraîchissement changent à chaque utilisation. Réutiliser un ancien jeton déconnecte cette session partout (détection de vol).
Chaque joueur commence en tant qu'invité et peut ensuite lier un compte e-mail ou Google ; la progression de l'invité est conservée. Voir Joueurs.

Des résultats plutôt que des exceptions#

Les appels SDK ne lèvent jamais d'exception en cas d'erreur réseau ou serveur. Ils renvoient un résultat avec ok, une valeur et une erreur comportant un code stable, un message et l'ID de requête.

var top = await Majacloud.Leaderboards.GetTopAsync("coins", 10);
if (top.Ok)
{
    foreach (var entry in top.Value.Entries)
        Debug.Log($"#{entry.Rank} {entry.PlayerName} {entry.Score}");
}
else if (top.Error.IsRetryable)
{
    // Network, timeout, 5xx or rate limit: try again later
    Debug.Log("Retry in " + top.Error.RetryAfterSeconds + " s");
}
else
{
    Debug.LogWarning(top.Error.Code + ": " + top.Error.Message + " (" + top.Error.RequestId + ")");
}

GDScript

var top := await Majacloud.leaderboards.get_top("coins", 10)
if top.ok:
	for entry in top.value.entries:
		print("#%d %s %d" % [entry.rank, entry.player_name, entry.score])
elif top.is_retryable():
	# Network, timeout, 5xx or rate limit: try again later
	print("Retry in ", top.retry_after, " s")
else:
	push_warning("%s: %s (%s)" % [top.error, top.message, top.request_id])

JavaScript

const top = await mc.leaderboards.getTop('coins', { limit: 10 });
if (top.ok) {
  for (const entry of top.value.entries) {
    console.log(`#${entry.rank} ${entry.player_name} ${entry.score}`);
  }
} else if (top.error.retryable) {
  // Network, timeout, 5xx or rate limit: try again later
  console.log('Retry in', top.error.retryAfter, 's');
} else {
  console.warn(`${top.error.code}: ${top.error.message} (${top.error.requestId})`);
}

JSON

// Success
{ "ok": true, "entries": [ … ], "total": 42 }

// Error (HTTP 4xx/5xx)
{
  "ok": false,
  "error": {
    "code": "rate_limited",
    "message": "Project rate limit reached. Try again in a minute.",
    "request_id": "6f1c2a9e-…",
    "details": { "limit": 120, "window": "minute" }
  }
}

Nouvelles tentatives et limites de débit#

Les SDK relancent les requêtes sûres en cas d'erreur réseau ou de réponse 5xx, avec un délai exponentiel, et patientent après une réponse 429 grâce à Retry-After.

Chaque projet peut envoyer jusqu'à 120 requêtes par minute ; au-delà, l'API répond rate_limited.
Chaque compte dispose d'un quota quotidien de requêtes qui dépend de l'offre (voir Limites) ; au-delà, l'API répond quota_exceeded jusqu'à 00:00 UTC.
Les réponses contiennent X-RateLimit-Limit, X-RateLimit-Remaining et, à l'approche du quota, X-RateLimit-Daily-Remaining.

ID de requête et journaux#

Chaque réponse comporte un en-tête X-Request-ID, et chaque erreur inclut request_id. Recherchez-le sur la page Journaux de votre projet pour voir l'endpoint, le statut, la latence et le joueur.