Cuentas y traducción

Empieza por la disponibilidad y los errores del SDK. Los ejemplos usan el objeto global inyectado; el juego nunca solicita las credenciales de la cuenta.

Inicia sesión tras una acción del jugador

Llama a checkSession() justo antes de una acción que requiera cuenta. Si devuelve false, llama a login() desde una acción explícita del jugador. El host controla la interfaz. cancelled es una decisión normal; los fallos de transporte, ventana emergente o sincronización de cuenta rechazan la Promise.

Después de success, continúa la acción directamente. No recargues, hagas sondeos ni vuelvas a comprobar la sesión para esa misma acción. Haz una nueva comprobación para otra acción independiente posterior. Desactiva el botón mientras la solicitud esté pendiente.

<button id="player-button">Show player</button>
<output id="player-info" aria-live="polite"></output>

async function readPlayerAfterClick() {
  const sdk = window.combos;
  if (!sdk) return null;
  const { methods } = await sdk.init();
  if (!methods.includes("getUserInfo")) return null;
  if (!(await sdk.checkSession())) {
    const result = await sdk.login();
    if (result.status !== "success") return null;
  }
  return sdk.getUserInfo();
}
 
const button = document.querySelector<HTMLButtonElement>("#player-button");
const output = document.querySelector<HTMLOutputElement>("#player-info");
button?.addEventListener("click", async () => {
  if (!output) return;
  button.disabled = true;
  try {
    const player = await readPlayerAfterClick();
    output.textContent = player
      ? player.nickName || "Player"
      : "Player information is unavailable.";
  } catch {
    output.textContent = "Unable to read player information. Please try again.";
  } finally {
    button.disabled = false;
  }
});

Los botones y mensajes son textos de ejemplo: adáptalos a los idiomas del juego. La función devuelve null si falta la capacidad o se cancela el acceso; el controlador del clic captura los errores reales.

Consulta la información del jugador

getUserInfo() no acepta argumentos. Úsalo después de comprobar la sesión o iniciar sesión correctamente. Sin sesión, rechaza con session_required.

Ofrece valores alternativos para datos visibles ausentes. Respeta el ámbito de la aplicación para esta identidad; no uses esta respuesta de presentación como credencial o prueba de autorización de tu backend. No incluye ID de usuario de la plataforma, correo ni sesión de Cloud Ability.

Traduce textos ya visibles

Muestra primero el texto fuente y después solicita la traducción. sourceLocale identifica el idioma original, no el destino deseado. El host elige su idioma actual de producto. sourceTexts contiene las cadenas o plantillas originales exactas, que también son las claves del resultado.

<button data-source-text="Play"></button>
<button data-source-text="Pause"></button>

async function localizeLabels() {
  const nodes = [...document.querySelectorAll<HTMLElement>("[data-source-text]")];
  const sourceTexts = nodes.map(node => node.dataset.sourceText ?? "");
  nodes.forEach((node, index) => { node.textContent = sourceTexts[index]; });
 
  const sdk = window.combos;
  if (!sdk) return;
  try {
    const { methods } = await sdk.init();
    if (!methods.includes("requestI18n")) return;
    const result = await sdk.requestI18n({ sourceLocale: "en", sourceTexts });
    if (!result.needed) return;
    nodes.forEach((node, index) => {
      const source = sourceTexts[index];
      node.textContent = result.translations[source] || source;
    });
  } catch {
    // Keep the source copy on screen.
  }
}
 
void localizeLabels();

El resultado es { needed: false } o { needed: true, locale, translations }. Conserva el original si no hace falta traducir, faltan claves, el host no es compatible o hay errores. Los resultados SDK inválidos también se convierten en needed: false. Inserta traducciones como texto, no HTML sin procesar. Traduce plantillas estables antes de completar valores dinámicos y cambia sourceLocale si modificas los originales en inglés del ejemplo.

Referencia opcional de Cloud Ability

El host Web actual no anuncia estos cuatro métodos. Úsalos solo si init().methods incluye expresamente el correspondiente. Este contrato no habilita IA por el simple hecho de publicar un juego.

type Authorization = {
  decision: "AUTHORIZATION_DECISION_GRANTED" | "AUTHORIZATION_DECISION_DENIED";
  decidedAtMs: number;
};
type AuthSetting = Partial<Record<"ai_model", Authorization>>;
type CloudAbilitySession = { session: string; expiresAtMs: number };

AUTHORIZATION_DECISION_DENIED es una decisión normal, no un error de transporte. No escribas el valor cero UNSPECIFIED. Los tiempos están en milisegundos. No envíes IDs de usuario, dispositivo o juego. Mantén la sesión solo en memoria, respeta expiresAtMs, descártala al terminar la partida y nunca la pongas en almacenamiento, registros o URL.