Conceptos básicos

Proyectos, claves, sesiones de jugador y cómo comunican los SDK los resultados y los errores.

Los comentarios del código y los nombres de la API se mantienen en inglés para que coincidan con los SDK.

En esta página

Proyectos y claves
Jugadores y sesiones
Resultados en lugar de excepciones
Reintentos y límites de frecuencia
ID de solicitud y registros

Proyectos y claves#

Cada juego es un proyecto. Sus claves identifican el proyecto, no a un jugador.

Credencial	Dónde se usa
Base URL	La dirección de esta instalación. La API está bajo `/v1`.
Project ID	En cada solicitud, como `X-Project-ID`. Público.
Clave de cliente `pk_live_…`	En las builds del juego y las páginas web, como `X-Client-Key`. Pública: solo puede actuar en nombre de jugadores con sesión iniciada.
Clave secreta `sk_live_…`	Solo en tus propios servidores, como `X-Secret-Key`. Se muestra una vez y se almacena como hash; da acceso a los endpoints exclusivos de servidor.

Nunca pongas la clave secreta (sk_live_…) en una build del juego ni en una página web. Todo lo que se entrega a los jugadores se puede leer.

Jugadores y sesiones#

Las llamadas de jugador necesitan un token de acceso. Al iniciar sesión se obtiene uno (válido durante una hora) junto con un token de actualización (válido durante 30 días).

Los SDK guardan la sesión en el dispositivo y la renuevan antes de que caduque, así que los jugadores mantienen la sesión iniciada entre ejecuciones.
Los tokens de actualización rotan con cada uso. Reutilizar uno antiguo cierra esa sesión en todas partes (detección de robo).
Todos los jugadores empiezan como invitados y más tarde pueden vincular una cuenta de correo o de Google; el progreso del invitado se conserva. Consulta Jugadores.

Resultados en lugar de excepciones#

Las llamadas del SDK nunca lanzan excepciones por errores de red o del servidor. Devuelven un resultado con ok, un valor y un error con un código estable, un mensaje y el ID de solicitud.

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" }
  }
}

Reintentos y límites de frecuencia#

Los SDK reintentan las solicitudes seguras ante errores de red y respuestas 5xx con espera exponencial, y ante una respuesta 429 esperan el tiempo que indica Retry-After.

Cada proyecto puede enviar hasta 120 solicitudes por minuto; por encima de eso, la API responde rate_limited.
Cada cuenta tiene una cuota diaria de solicitudes que depende del plan (consulta Límites); por encima de ella, la API responde quota_exceeded hasta las 00:00 UTC.
Las respuestas incluyen X-RateLimit-Limit, X-RateLimit-Remaining y, cerca de la cuota, X-RateLimit-Daily-Remaining.

ID de solicitud y registros#

Cada respuesta tiene una cabecera X-Request-ID, y cada error incluye request_id. Búscalo en la página Registros de tu proyecto para ver el endpoint, el estado, la latencia y el jugador.