Konten und Übersetzung

Lies zuerst SDK-Unterstützung und Fehler. Die Beispiele nutzen das bereitgestellte globale Objekt; das Spiel fordert keine Konto-Zugangsdaten an.

Anmeldung nach einer Spieleraktion

Rufe checkSession() unmittelbar vor einem Vorgang auf, der ein Konto benötigt. Bei false folgt login() nach einer ausdrücklichen Spieleraktion. Der Host verwaltet die Anmeldeoberfläche. cancelled ist eine normale Entscheidung; Transport-, Popup- oder Kontosynchronisationsfehler lehnen das Promise ab.

Setze nach success den aktuellen Vorgang direkt fort. Für denselben Vorgang sind weder Neuladen noch Polling oder eine zweite Sitzungsprüfung nötig. Prüfe bei einer späteren unabhängigen Aktion erneut. Deaktiviere während der Anfrage den auslösenden Button.

<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;
  }
});

Buttons und Meldungen sind Beispieltexte für dein Spiel; passe sie an dessen Sprachen an. Die Hilfsfunktion liefert bei fehlender Unterstützung oder abgebrochener Anmeldung null. Tatsächliche Fehler fängt der Klick-Handler ab.

Spielerinformationen lesen

getUserInfo() hat keine Argumente. Rufe es nach der Sitzungsprüfung oder erfolgreichen Anmeldung auf. Ohne Anmeldung wird die Anfrage mit session_required abgelehnt.

Biete Ersatzwerte für fehlende Anzeigedaten an. Behandle diese Identität innerhalb ihrer App und verwende die Anzeigeantwort nicht als Zugangsdaten oder Berechtigungsnachweis für dein Backend. Sie enthält keine Plattform-Nutzer-ID, E-Mail oder Cloud-Ability-Sitzung.

Bereits sichtbare Spieltexte übersetzen

Zeige zuerst die Quelltexte und fordere dann Übersetzungen an. sourceLocale beschreibt die Quellsprache, nicht die gewünschte Zielsprache. Der Host verwendet seine aktuelle Produktsprache. sourceTexts enthält die exakten Quelltexte oder Vorlagen; dieselben Texte bilden die Ergebnisschlüssel.

<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();

Das Ergebnis ist { needed: false } oder { needed: true, locale, translations }. Behalte bei übersprungener Übersetzung, fehlenden Schlüsseln, nicht unterstützten Hosts oder Fehlern den Quelltext. Ungültige SDK-Ergebnisse werden ebenfalls zu needed: false. Gib Übersetzungen als Text statt als rohes HTML aus. Übersetze feste Vorlagen vor dem Einsetzen dynamischer Werte und aktualisiere sourceLocale, wenn du die englischen Beispieltexte änderst.

Optionale Cloud-Ability-Referenz

Der aktuelle Web-Host meldet diese vier Methoden nicht als unterstützt. Nutze sie nur, wenn init().methods die jeweilige Methode ausdrücklich enthält. Dieser Vertrag schaltet KI nicht allein durch die Veröffentlichung eines Spiels frei.

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 ist eine normale Entscheidung, kein Transportfehler. Schreibe den Nullwert UNSPECIFIED nicht. Zeitwerte sind in Millisekunden. Übermittle keine Nutzer-, Geräte- oder Spiel-IDs. Halte die Sitzung ausschließlich im Arbeitsspeicher, beachte expiresAtMs und verwerfe sie beim Spielende. Sie gehört weder in persistenten Speicher noch in Logs oder URLs.