API-Referenz des Combos SDK

SDK 1.1.0 · Geprüft am 2026-10-13. Diese JavaScript-API steht Spielen als window.combos zur Verfügung. Sie umfasst alle 10 globalen Methoden und die 4 Methoden des TikTok-Clients. Zu jeder Methode findest du Eingaben, Rückgabe, Fehlerverhalten und ein Beispiel. Ein vollständiges Spiel beschreibt das TikTok-Tutorial; die UI-Anbindung erklärt Konten und Lokalisierung.

Aufrufe laufen über den Combos-Host. Es sind JavaScript-Methoden, keine REST-Endpunkte: Dein Spiel benötigt weder API-Basis-URL noch API-Schlüssel, HTTP-Statushülle oder selbst konstruierte postMessage-Nachrichten. Der aufgelöste Wert ist das Ergebnis selbst, ohne umschließendes data-Feld.

Laufzeit und TypeScript einrichten

Der unterstützte Combos-Player stellt das SDK bereit. Lade kein zweites Laufzeitskript und überschreibe window.combos nicht. Auf einer eigenständigen Website oder in einer lokalen Vorschau kann das globale Objekt fehlen. Prüfe es im Browser und halte das Grundspiel verfügbar. Greife beim serverseitigen Rendern nicht auf window zu.

Speichere für die Codevervollständigung die öffentliche Deklaration  als combos-host-sdk.d.ts neben deinen Spielquellen und nimm das Verzeichnis in dein TypeScript-Projekt auf. Die Datei liefert nur Typen. Beispiele mit TTLiveClient verwenden import type und erzeugen keine Laufzeitabhängigkeit.

curl --fail --location https://combos.converge.ai/host-sdk.d.ts --output ./combos-host-sdk.d.ts

async function readCapabilities() {
  const sdk = window.combos;
  if (!sdk) return [];
  const { methods } = await sdk.init();
  return methods;
}

Jeder TypeScript-Block ist eine eigenständige Hilfsfunktion. Rufe sie aus deiner UI auf und behandle abgelehnte Promises. Funktionen mit der Endung AfterClick gehören zu einer Spieleraktion. Ihr null steht laut jeweiligem Code für Nichtverfügbarkeit oder Abbruch und ist kein zusätzlicher SDK-Rückgabewert. JSON-Blöcke zeigen direkte Anfragen oder Ergebnisse mit fiktiven Identitäten und Zeiten. Passe Beispieltexte an die Sprache deines Spiels an.

Methodenübersicht

Der erste Host-Aufruf kann zusätzlich bis zu 3 Sekunden für die Fähigkeitsermittlung benötigen. Dies sind Wartegrenzen des SDK, keine Dienstgütegarantien. Öffentliche Methoden akzeptieren weder timeout noch AbortSignal, Erfolgs-Callbacks oder zusätzliche Identitätsparameter.

Unterstützung vor dem Aufruf prüfen

Prüfe init().methods, nicht nur das Vorhandensein einer Funktion. Der aktuelle Web-Host unterstützt checkSession und login. getUserInfo braucht einen vertrauenswürdigen Spielkontext, requestI18n die Übersetzungsunterstützung des Play-Hosts und TikTok eine entsprechende Host-Fähigkeit samt registriertem Startkontext. Ältere Web- und App-Hosts können abweichen.

Der aktuelle Web-Host meldet getSetting, authorize, openSetting und getCloudAbilitySession nicht als verfügbar. Ihr Vertrag gilt für Hosts, die sie ausdrücklich anbieten. Die Veröffentlichung eines Spiels aktiviert Cloud Ability oder TikTok nicht automatisch. Fehlt eine Methode in der Fähigkeitenliste, wird vor ihrer Host-Anfrage mit unsupported abgelehnt.

getTTLiveSession bezeichnet eine interne Fähigkeit. Prüfe sie vor getTTLiveClient(); eine öffentliche Methode combos.getTTLiveSession() existiert nicht. Die globale API bietet auch kein logout, generisches request, Cloud-Speichern, Bezahlen, Ranglisten oder Geschenkregistrierung.

Initialisierung und Konten

combos.init()

combos.init(): Promise<ICombosHostInitResult>

Parameter: keine. Anmeldung erforderlich: nein. Rückgabe: Promise mit methods, einem Array unterstützter Fähigkeitsnamen. Die Methode meldet niemanden an, öffnet keine UI und startet keine TikTok-Verbindung.

Gleichzeitige Aufrufe teilen die Ermittlung; das Ergebnis wird für das aktuelle Spieldokument gespeichert. Andere Host-Methoden ermitteln Fähigkeiten automatisch. Unbekannte und doppelte Namen einer gültigen Liste werden entfernt. Schlägt die Ermittlung fehl, ist die Antwort ungültig oder bleibt der Host 3 Sekunden stumm, wird ['checkSession', 'login'] zurückgegeben. Eine gültige leere Liste bleibt leer. Dieser Kompatibilitätsrückfall beweist keinen funktionierenden Host auf einer eigenständigen Seite; spätere Aufrufe können weiterhin ein Timeout erreichen. Es gibt keine öffentliche Option zum erzwungenen Aktualisieren.

Die folgende Antwort ist beispielhaft. Setze diese Methoden nicht als überall verfügbar voraus.

interface ICombosHostInitResult {
  methods: Array<
    | 'checkSession' | 'login' | 'getUserInfo' | 'requestI18n'
    | 'getSetting' | 'authorize' | 'openSetting'
    | 'getCloudAbilitySession' | 'getTTLiveSession'
  >;
}

{
  "methods": ["checkSession", "login", "getUserInfo", "requestI18n", "getTTLiveSession"]
}

combos.checkSession()

combos.checkSession(): Promise<boolean>

Parameter: keine. Anmeldung erforderlich: nein. Rückgabe: true, wenn der Host eine angemeldete Sitzung meldet, sonst false. Der Status wird ohne Anmeldeoberfläche gelesen. Nur der exakte boolesche Wert true zählt; wahrheitsähnliche Strings oder Objekte werden nicht akzeptiert.

Prüfe unmittelbar vor jeder unabhängigen Kontoaktion. Speichere das Ergebnis nicht als dauerhafte Anmeldegarantie, da sich die Sitzung danach ändern kann. Transportfehler und Timeouts lehnen ab; sie sind weder normales false noch ein Beweis für Abmeldung. Bei false entscheidet der Spieler, ob er sich anmeldet. Nach erfolgreichem login() für dieselbe Aktion kannst du ohne erneute Prüfung fortfahren.

async function readSession() {
  const sdk = window.combos;
  if (!sdk) return null;
  const { methods } = await sdk.init();
  if (!methods.includes('checkSession')) return null;
  return sdk.checkSession();
}

combos.login()

combos.login(): Promise<ICombosHostLoginResult>

Parameter: keine; übergib niemals Konto-ID, Passwort oder Token. Anmeldung erforderlich: nein. Wirkung: öffnet bei Bedarf den Anmeldeablauf des Hosts. Starte ihn durch eine Spieleraktion und deaktiviere das auslösende Element während der Wartezeit.

Ein Abbruch löst das Promise normal auf. Blockierte Popups, Transportfehler, Fehler beim Sitzungsabgleich und Timeouts führen zur Ablehnung. Ungültige Antworten oder unbekannte Statuswerte erzeugen request_failed. Bereits angemeldete Spieler erhalten im aktuellen Web-Host success ohne neue Anmeldung. Die Rückgabe enthält weder Zugangsdaten noch Profil; frage das Profil separat ab.

interface ICombosHostLoginResult {
  status: 'success' | 'cancelled';
}

async function loginAfterClick() {
  const sdk = window.combos;
  if (!sdk) return null;
  const { methods } = await sdk.init();
  if (!methods.includes('checkSession') || !methods.includes('login')) return null;
  if (await sdk.checkSession()) return { status: 'success' as const };
  return sdk.login();
}

{ "status": "success" }

combos.getUserInfo()

combos.getUserInfo(): Promise<ICombosHostUserInfo>

Parameter: keine. Voraussetzungen: angebotene Fähigkeit getUserInfo, vertrauenswürdiger Spielkontext und bestehende Sitzung. Ohne Anmeldung wird mit session_required abgelehnt. Trotz erfolgreicher vorheriger Sitzungsprüfung musst du späteren Sitzungsablauf behandeln.

Es werden weder E-Mail, Telefonnummer, Plattformnutzer-ID, Anmeldetoken noch Cloud-Ability-Sitzung geliefert. Leite aus openId keine anwendungsübergreifende Identität ab und nutze diese Browserantwort nicht als Authentifizierungsnachweis für deinen Server. Behandle Anzeigewerte als Text statt HTML. Fehlende Identitäten, nicht textuelle Anzeigefelder und andere ungültige Ergebnisse führen zu request_failed; Host und Backend können weitere Codes liefern.

interface ICombosHostUserInfo {
  appId: string;
  openId: string;
  nickName: string;
  avatarUrl: string;
  locale: string;
}

async function readPlayerAfterClick() {
  const sdk = window.combos;
  if (!sdk) return null;
  const { methods } = await sdk.init();
  if (!methods.includes('checkSession') || !methods.includes('login') || !methods.includes('getUserInfo')) return null;
  if (!(await sdk.checkSession())) {
    const login = await sdk.login();
    if (login.status === 'cancelled') return null;
  }
  return sdk.getUserInfo();
}

{
  "appId": "app_example",
  "openId": "player_example",
  "nickName": "Alex",
  "avatarUrl": "",
  "locale": "en"
}

Lokalisierung des Spiels

combos.requestI18n(params)

combos.requestI18n(params: ICombosHostRequestI18nParams): Promise<ICombosHostI18nResult>

Anmeldung erforderlich: die aktuelle Web-Übersetzungsbrücke verlangt keine Anmeldung. Der Host muss requestI18n anbieten. Zeige zuerst Ausgangstexte; Übersetzung ist eine optionale asynchrone Ergänzung und darf das Laden nicht blockieren.

Es gibt kein targetLocale. Der Host verwendet seine aktuelle Produktsprache. Die Web-Verarbeitung entfernt äußere Leerzeichen beim Locale, überspringt leere/nicht textuelle Einträge, dedupliziert Texte und übersetzt in Paketen von 50. Diese Paketgröße ist keine öffentliche Eingabegrenze des SDK. Verwende kleine Gruppen stabiler UI-Texte, die innerhalb von 30 Sekunden fertig werden können; übersetze nicht in jedem Animationsbild.

interface ICombosHostRequestI18nParams {
  sourceLocale: string;
  sourceTexts: string[];
}
 
type ICombosHostI18nResult =
  | { needed: false }
  | { needed: true; locale: string; translations: Record<string, string> };

{
  "sourceLocale": "en",
  "sourceTexts": ["Play", "Score: {score}"]
}

{
  "needed": true,
  "locale": "zh-CN",
  "translations": { "Play": "开始", "Score: {score}": "得分：{score}" }
}

Gleichwertige Sprachen, keine nutzbaren Texte, nicht verfügbare Übersetzung und aktuelle Fehler des Web-Übersetzungsbackends können { needed: false } liefern. Das SDK wandelt auch ungültige Übersetzungsantworten in diesen Fall um. Fehlende Unterstützung und Transport-Timeouts können trotzdem ablehnen. Behalte bei fehlender oder leerer Übersetzung den jeweiligen Originaltext. Setze Inhalte mit textContent, niemals innerHTML.

Übersetze Vorlagen wie Score: {score} vor dem Einsetzen von Werten; das SDK ersetzt keine Platzhalter. Prüfe vor der Verwendung, ob notwendige Platzhalter erhalten blieben. Bewahre Ausgangstexte zwischen Aufrufen auf, statt bereits übersetzte Texte mit veraltetem sourceLocale erneut zu übersetzen.

async function translateVisibleLabels(nodes: HTMLElement[]) {
  const sourceTexts = nodes.map(node => node.textContent ?? '');
  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) => {
      node.textContent = result.translations[sourceTexts[index]] || sourceTexts[index];
    });
  } catch {
    // Source text stays visible.
  }
}

Optionale Cloud-Ability-APIs

Diese vier Methoden werden vom aktuellen Web-Host nicht angeboten. Prüfe jede einzeln. Die Beispiele sind bedingter Integrationscode für unterstützende Hosts, keine Freischaltung. Eine erteilte Autorisierung beweist außerdem nicht, dass der Spielinhaber die zugrunde liegende Fähigkeit aktiviert hat.

type CombosHostPermissionScope = 'ai_model';
type CombosHostAuthorizationDecision =
  | 'AUTHORIZATION_DECISION_UNSPECIFIED'
  | 'AUTHORIZATION_DECISION_GRANTED'
  | 'AUTHORIZATION_DECISION_DENIED';
 
interface ICombosHostPlayableAuthorization {
  decision: CombosHostAuthorizationDecision;
  decidedAtMs: number;
}
type ICombosHostAuthSetting = Readonly<
  Partial<Record<CombosHostPermissionScope, ICombosHostPlayableAuthorization>>
>;
interface ICombosHostAuthorizeParams { scope: CombosHostPermissionScope }
interface ICombosHostCloudAbilitySession { session: string; expiresAtMs: number }

Diese APIs akzeptieren keine Nutzer-, Geräte-, Projekt-, Post- oder Spielinstanz-IDs. Der Host liefert den vertrauenswürdigen Kontext und steuert Anmeldung und Berechtigungsoberfläche. Erfülle seine Sitzungsvoraussetzungen vor geschützten Aktionen. Wiederhole Berechtigungsdialoge nach Ablehnung nicht automatisch.

combos.getSetting()

combos.getSetting(): Promise<ICombosHostAuthSetting>

Parameter: keine. Zeitlimit: 10 Sekunden. Liest die Entscheidungen des aktuellen Spielers für das aktuelle Spiel ohne Einstellungsdialog. Liefert ICombosHostAuthSetting; {} ist gültig, wenn die Entscheidung für ai_model fehlt.

Das SDK übernimmt nur den bekannten Scope ai_model. Falls er vorhanden ist, sind Erteilung/Ablehnung und ein endliches decidedAtMs erforderlich; ungültige Datensätze erzeugen request_failed. Interpretiere fehlende Scopes nicht als Ablehnung und verwende nach einer Einstellungsänderung keine veraltete Entscheidung.

{
  "ai_model": {
    "decision": "AUTHORIZATION_DECISION_GRANTED",
    "decidedAtMs": 1791800000000
  }
}

async function readPermissionSettings() {
  const sdk = window.combos;
  if (!sdk) return null;
  const { methods } = await sdk.init();
  if (!methods.includes('getSetting')) return null;
  return sdk.getSetting();
}

combos.authorize(params)

combos.authorize(params: ICombosHostAuthorizeParams): Promise<ICombosHostPlayableAuthorization>

Parameter: erforderliches Objekt mit scope: 'ai_model'; kein Standardwert, Platzhalter, Scope-Array oder vom Aufrufer gesetzte Entscheidung. Zeitlimit: 5 Minuten. Diese interaktive Berechtigungsanfrage steuert der Host; starte sie durch eine Spieleraktion.

Liefert einen Autorisierungsdatensatz, nicht sämtliche Einstellungen. AUTHORIZATION_DECISION_DENIED ist eine normale Rückgabe. Fahre mit einer geschützten Aktion nur nach GRANTED fort; Ablehnung rechtfertigt keine automatischen Wiederholungen. Ein Ergebnis cancelled ist nicht definiert. Interpretiere das Schließen der Oberfläche anhand der tatsächlichen Rückgabe oder Ablehnung, nicht anhand der Login-Statuswerte. Nicht unterstützende Hosts, ungültige Ergebnisse, Transportfehler und Timeouts lehnen ab.

async function requestAiPermissionAfterClick() {
  const sdk = window.combos;
  if (!sdk) return null;
  const { methods } = await sdk.init();
  if (!methods.includes('authorize')) return null;
  return sdk.authorize({ scope: 'ai_model' });
}

{ "decision": "AUTHORIZATION_DECISION_DENIED", "decidedAtMs": 1791800000000 }

combos.openSetting()

combos.openSetting(): Promise<ICombosHostAuthSetting>

Parameter: keine. Zeitlimit: 5 Minuten. Öffnet nach einer Spieleraktion die Host-Berechtigungseinstellungen und liefert das resultierende ICombosHostAuthSetting. Es gibt kein Eingabeobjekt zum stillen Erteilen von Rechten.

Aktualisiere die Oberfläche mit den zurückgegebenen Einstellungen, auch bei fehlendem oder abgelehntem Scope. Die Rückgabe ist weder boolesch noch ein einzelner Autorisierungsdatensatz oder Login-Status. Es gilt dieselbe Prüfung wie bei getSetting(). Nicht unterstützte Methoden, ungültige Ergebnisse und Host-/Transportfehler lehnen ab. Ein separater Abbruchstatus ist nicht definiert.

async function openPermissionsAfterClick() {
  const sdk = window.combos;
  if (!sdk) return null;
  const { methods } = await sdk.init();
  if (!methods.includes('openSetting')) return null;
  return sdk.openSetting();
}

combos.getCloudAbilitySession()

combos.getCloudAbilitySession(): Promise<ICombosHostCloudAbilitySession>

Parameter: keine. Zeitlimit: 10 Sekunden. Liefert auf einem unterstützenden Host { session, expiresAtMs } für die aktuelle Partie. Der Aufruf öffnet keinen Berechtigungsdialog und beweist keinen Zugriff auf jedes KI-Modell. Behandle Host-Fehler zu Sitzung, Berechtigung und Verfügbarkeit.

Halte die Zugangsdaten im Arbeitsspeicher und verwende sie ausschließlich mit der vom Host dokumentierten Cloud-Ability-Integration. Sie gehören niemals in Logs, Screenshots, URLs, lokalen Speicher oder Quellcode. Prüfe den Ablauf, beschaffe bei Bedarf eine neue Sitzung und verwirf die alte bei Spieler-/Partiewechsel. Es gibt weder refreshToken noch TTL-Parameter oder eine allgemeine Backend-Authentifizierungsgarantie. Ungültige Ergebnisse erzeugen request_failed.

async function obtainCloudSession() {
  const sdk = window.combos;
  if (!sdk) return null;
  const { methods } = await sdk.init();
  if (!methods.includes('getCloudAbilitySession')) return null;
  const value = await sdk.getCloudAbilitySession();
  if (value.expiresAtMs <= Date.now()) throw new Error('Session already expired');
  return value; // Keep in memory only; never log or persist this value.
}

TikTok-Client-Referenz

Für die echte TikTok-Integration gibt es derzeit keinen verfügbaren Freischaltungsprozess. Der folgende API-Vertrag bedeutet nicht, dass ein neu veröffentlichtes Spiel echte Geschenke empfangen kann. Du kannst das Spiel erstellen, den Simulator ausführen und es auf Combos veröffentlichen. Die echte Integration muss warten, bis die Plattform einen Freischaltungsprozess bereitstellt.

Der Client verwaltet die TikTok-Interaktionssitzung dieses Spiels, nicht den gesamten LIVE-Status des Streamers. Er übernimmt Transport, Heartbeats, Sitzungserneuerung und Wiederverbindung. Das Spiel verantwortet Anweisungen, Effekte, dauerhafte Deduplizierung und korrekte Ergebnisse. Das vollständige Tutorial enthält Geschenkzuordnung, Veröffentlichung, Vorbereitung und das ausführbare Projekt.

combos.getTTLiveClient()

combos.getTTLiveClient(): TTLiveClient

Parameter: keine. Rückgabe: synchroner TTLiveClient; beim Abruf erfolgt keine Netzwerkanfrage. Wiederholte Aufrufe liefern dieselbe Instanz für dieses SDK-/Spieldokument. Vermeide konkurrierende Steuerungen in verschiedenen Komponenten.

Prüfe die Fähigkeit getTTLiveSession wie unten gezeigt. Das Clientobjekt beweist weder Host-Unterstützung, Anmeldung, registrierten Start noch erfolgreiche Verbindung. Schließe vor einer echten Verbindung den Kontoablauf ab. Anbieterschlüssel, CAS-Zugangsdaten, launchData und WebSocket-URLs werden intern verwaltet; öffentliche Eingabeparameter dafür gibt es nicht.

async function getTikTokClient() {
  const sdk = window.combos;
  if (!sdk || typeof sdk.getTTLiveClient !== 'function') return null;
  const { methods } = await sdk.init();
  if (!methods.includes('getTTLiveSession')) return null;
  return sdk.getTTLiveClient();
}

client.connect(options)

client.connect(options: TTLiveConnectOptions): Promise<void>

Parameter: erforderliches options-Objekt mit einer Funktion onCommand, die boolean oder Promise<boolean> liefert. Die öffentliche Signatur enthält keine Raum-, Streamer-, Token-, Wiederverbindungs- oder Timeout-Optionen.

Liefert Promise<void> nach dem Bereitschafts-Frame des Datenstroms. Das bestätigt weder einen Geschenkeffekt noch dauerhafte Verbindung; beobachte den Status separat. Wiederherstellung kann das Promise unbegrenzt offenhalten. Biete eine Stoppaktion an, bevor du darauf wartest. Erneutes connect bei bereits gewünschter Verbindung verwendet das wartende Promise wieder oder löst sofort auf; der ursprüngliche Handler wird nicht ersetzt. Trenne die Verbindung vor einem Handlerwechsel.

Fehlendes onCommand führt zu einem normalen Error. Explizites Trennen oder ein Endzustand vor Bereitschaft lehnt ebenfalls das offene Promise ab. Vorübergehende Transport-/Sitzungsfehler starten meist die Wiederherstellung, statt sofort abzulehnen. Verschiedene Befehls-IDs können asynchrone Handler gleichzeitig auslösen; serialisiere gemeinsame Zustandsänderungen oder nutze Transaktionen.

interface TTLiveConnectOptions {
  onCommand: (command: TTLiveCommand) => boolean | Promise<boolean>;
}
interface TTLiveCommand {
  messageId: string;
  instruction: string;
  count: string;
  timestamp: string;
}

Das Beispiel zeigt einen Befehl, keine Geschenkregistrierungs-API. Der Callback enthält keine Zuschauer-IDs, Anzeigenamen, Geschenkpreise oder echten Geschenk-IDs. count ist die zugeordnete Anweisungsmenge, nicht zwingend die Geschenkanzahl oder der Münzwert.

{
  "messageId": "example-command-001",
  "instruction": "gift_flash",
  "count": "3",
  "timestamp": "1791800000"
}

Die Deduplizierung im Arbeitsspeicher ist begrenzt und wird bei explizitem Trennen oder Neuladen gelöscht. Sie garantiert keine dauerhafte Genau-einmal-Ausführung. Speichere messageId, Effekt und Ergebnis atomar; liefere bei Duplikaten das gespeicherte Ergebnis. Gib nach einem teilweise ausgeführten Effekt mit unsicherem Ausgang nicht false zurück. Das Gift-Arena-Beispiel nutzt eine Transaktion.

Diese Hilfsfunktion bietet sofortigen Abbruch und behandelt Ablehnungen. Übergib deinen echten Befehlshandler und UI-Callbacks, die keine Fehler werfen; connected kann weiterhin abgewartet werden. Bewahre stop für wartende und bestehende Verbindungen auf.

import type { TTLiveClient, TTLiveConnectOptions, TTLiveStatus } from './combos-host-sdk';
 
function attachTikTok(
  client: TTLiveClient,
  onCommand: TTLiveConnectOptions['onCommand'],
  onStatus: (status: TTLiveStatus) => void,
  onConnectionError: (error: unknown) => void,
) {
  const unsubscribe = client.onStatusChange(onStatus);
  const connected = client.connect({ onCommand });
  void connected.catch(onConnectionError);
  return {
    connected,
    stop() {
      unsubscribe();
      client.disconnect();
    },
  };
}

client.getLiveStatus()

client.getLiveStatus(): Promise<TTLiveStatus>

Parameter: keine. Fragt den aktuellen Status ab, veröffentlicht ihn an Listener und liefert TTLiveStatus. Startet keinen Befehlsstrom. Intern wird zuerst die Host-Sitzung bezogen (10 Sekunden Host-Wartezeit plus gegebenenfalls initiale Fähigkeitsermittlung), danach gilt für die HTTP-Statusanfrage ein Limit von 5 Sekunden.

Netzwerk-, HTTP-, Sitzungsformat- und ungültige Statusantwortfehler werden als Statuswerte, meist unknown, abgebildet. Sie beweisen nicht ended. tt_not_launched vom Host wird zu ended mit relaunch_game. Ein terminaler Status stoppt auch einen aktiven Client. Verwende im Spiel bevorzugt Abonnements statt wiederholter Abfragen.

interface TTLiveStatus {
  state: 'connecting' | 'connected' | 'recovering' | 'ended' | 'unknown';
  reason: string;
  action: 'none' | 'wait' | 'relaunch_game';
  confirmedAtMs: number;
}

Bekannte Gründe sind platform_unconfirmed, transport_unavailable, client_disconnected, tt_not_launched und session_required. Steuere Wiederherstellung über state und action; die Liste ist nicht vollständig und rohe Gründe sind keine fertigen Spielertexte.

import type { TTLiveClient } from './combos-host-sdk';
 
async function checkTikTokStatus(client: TTLiveClient) {
  const status = await client.getLiveStatus();
  return status;
}

{ "state": "unknown", "reason": "transport_unavailable", "action": "wait", "confirmedAtMs": 0 }

client.onStatusChange(listener)

client.onStatusChange(listener: (status: TTLiveStatus) => void): () => void

Parameter: erforderlicher synchroner Listener für TTLiveStatus. Rückgabe: Funktion zum Abmelden. Der Listener läuft sofort mit dem aktuellen Status und anschließend bei Feldänderungen. Neue Heartbeat-Bestätigungszeiten können Updates auslösen, auch wenn state gleich bleibt.

Melde den Listener beim Entfernen seiner UI ab. Abmelden trennt keine Verbindung; Trennen entfernt keine Listener. Wirf im Listener keine Fehler, da der sofortige Aufruf einen Fehler des aufrufenden Codes weitergeben kann. Das Beispiel zeigt Protokollwerte zum Debuggen; lokalisiere produktive Statusmeldungen.

import type { TTLiveClient } from './combos-host-sdk';
 
function showTikTokStatus(client: TTLiveClient, output: HTMLElement) {
  const unsubscribe = client.onStatusChange(status => {
    output.textContent = `${status.state} · ${status.action}`;
  });
  return unsubscribe; // Call when the UI is removed.
}

client.disconnect()

client.disconnect(): void

Parameter: keine. Rückgabe: undefined (void). Stoppt Timer, wartende Wiederholungen und Socket, löscht den Ausführungs-/Ergebnis-Cache im Speicher und lehnt ein noch offenes Verbindungs-Promise ab. Veröffentlicht unknown / client_disconnected / wait mit confirmedAtMs: 0.

Dies ist weder eine synchrone TikTok-Stream-Ende-API noch der Beweis eines serverseitigen End-ACK. Gespeicherte Ausführungsbelege werden nicht gelöscht und laufende Handler nicht rückgängig gemacht. Melde UI-Listener separat ab, sichere spätere Spieloperationen ab und behalte dauerhafte Belege. Derselbe Client kann erneut verbinden; wiederholtes Trennen ist für Aufräumarbeiten unbedenklich.

import type { TTLiveClient } from './combos-host-sdk';
 
function stopTikTok(client: TTLiveClient, unsubscribe: () => void) {
  unsubscribe();
  client.disconnect();
}

Fehler und Wiederherstellung

Host-Methoden lehnen mit einem Error mit den Strings code und message ab. Vergleiche code, nicht den lesbaren Meldungstext. Die Liste ist nicht vollständig; Host-/Backend-Codes können weitergegeben werden. TikTok-Lebenszyklusfehler können normale Error-Objekte ohne code sein. getLiveStatus stellt viele Fehler bewusst als Statuswerte dar.

Unterscheide normale Entscheidungen von Fehlern: checkSession() === false, Login cancelled, Berechtigung DENIED und Übersetzung needed: false sind aufgelöste Ergebnisse. Die folgende Hilfsfunktion bewahrt diese Unterscheidung, ohne eine Fehlerklasse vorauszusetzen oder Zugangsdaten zu protokollieren.

function readErrorCode(error: unknown): string | null {
  if (error && typeof error === 'object' && 'code' in error && typeof error.code === 'string') {
    return error.code;
  }
  return null;
}
 
async function checkAccountSafely() {
  const sdk = window.combos;
  if (!sdk) return { kind: 'unavailable' as const };
  try {
    return { kind: 'success' as const, signedIn: await sdk.checkSession() };
  } catch (error) {
    return { kind: 'error' as const, code: readErrorCode(error) };
  }
}

Numerische Codes sind bekannte Host-/Backend-Codes, keine Verfügbarkeitsgarantie für Cloud Ability im Web. Prüfe zuerst die jeweilige Methodenverfügbarkeit. Zeige bei unbekannten Codes einen behebbaren Fehler und erfasse nur nicht vertrauliche Diagnosen.

TikToks reason und action sind Statusfelder, keine Host-Fehlercodes. Ein abgelehnter Handler erzeugt nicht automatisch ein Fehler-ACK. Umschließe möglicherweise bereits ausgeführte Effekte nicht mit catch(() => false). Ein Host-Timeout beendet nur das Warten des SDK; öffentliches Abbrechen von Anmeldung, Autorisierung oder Übersetzung ist nicht vorgesehen. Vermeide automatische Wiederholungen, die Dialoge erneut öffnen oder unsichere Aktionen wiederholen.

Lebenszyklus und Integrationsgrenzen

1. Ermittle Fähigkeiten einmal pro Dokument und prüfe das aktuelle Konto vor jeder neuen Kontoaktion.
2. Binde Anmeldung und Berechtigung an Spieleraktionen. Behandle Abbruch/Ablehnung ohne erneutes Öffnen desselben Dialogs.
3. Halte Übersetzung optional und Ausgangstexte sichtbar. Verwirf veraltete asynchrone UI-Ergebnisse nach Entfernen einer Szene.
4. Weise den TikTok-Client des Dokuments einer verantwortlichen Stelle zu. Abonniere Status, verbinde einen dauerhaft abgesicherten Handler und erlaube Abbruch während der Wartezeit.
5. Melde Listener ab und trenne beim Verlassen der Interaktion. Bewahre Ausführungsbelege auf und verwerfe vertrauliche Sitzungen nach Ende von Partie/Konto.

window.combos bietet kein globales dispose(), Kontowechselereignis, Login-Abbruchobjekt oder global konfigurierbares Anfragezeitlimit. Ergänze diese Lücken nicht durch interne Klassen oder undokumentierte Host-HTTP-Routen. Das herunterladbare Demo und seine Speichergrenzen sind Spielentscheidungen, keine zusätzlichen SDK-APIs.

Version, Typen und vollständige Beispiele

Die öffentliche TypeScript-Deklaration  definiert die editorseitigen Typen. Diese Referenz prüft außerdem Laufzeitvalidierung von SDK 1.1.0, Zeitlimits, Web-Fähigkeiten, Übersetzung und TikTok-Lebenszyklus. Das Vorhandensein eines Typs beweist keine Laufzeitverfügbarkeit; künftige SDK-/Host-Versionen können Verhalten ändern.

• Konten und Lokalisierung: Schaltflächen, Fortsetzung nach Anmeldung und sichere Textaktualisierung.
• Ein TikTok-Spiel erstellen: Geschenkdeklaration, vollständiges Projekt, lokale Tests, Veröffentlichung und Vorbereitung künftiger Integration und LIVE-Abnahme.
• Gift Arena herunterladen: vollständige Quellen mit transaktionaler Befehlsverarbeitung.

Die Beispiele werden gegen öffentliche Typen geprüft. Diese Prüfung und der lokale Simulator bestätigen weder echte Kontoanmeldung noch Cloud-Ability-Zugriff oder bezahlte Geschenkzustellung. Solche Abläufe benötigen einen geeigneten Host, ein passendes Konto und ein registriertes Spiel, sobald ein Freischaltungsprozess verfügbar ist.