Combos SDK API リファレンス
SDK 1.1.0 · 確認日:2026-10-13。ゲームから window.combos を通じて利用する JavaScript API の詳細です。グローバル API の 10 メソッドと TikTok クライアントの 4 メソッドについて、入力、結果、失敗時の動作、実装例を掲載しています。ゲーム全体の作成は TikTok チュートリアル、ボタンへの組み込みはアカウントと多言語対応を参照してください。
呼び出しは Combos ホストが処理します。REST エンドポイントではないため、ゲームで API ベース URL、API キー、HTTP エンベロープ、手動の postMessage を用意する必要はありません。Promise の解決値は結果そのもので、外側の data はありません。
実行環境と TypeScript の準備
対応する Combos プレイヤーが SDK を注入します。別のランタイムを読み込んだり、window.combos を上書きしたりしないでください。単独ページやローカルプレビューには存在しない場合があります。ブラウザー側で存在を確認し、基本のゲームは遊べる状態に保ちます。サーバーレンダリング中は window にアクセスしません。
公開型定義 をゲームのソースと同じ場所に combos-host-sdk.d.ts として保存し、そのディレクトリを TypeScript プロジェクトに含めると補完が利用できます。このファイルは型のみで、SDK をインストールしません。以下の import type も実行時の依存を追加しません。
curl --fail --location https://combos.converge.ai/host-sdk.d.ts --output ./combos-host-sdk.d.tsasync function readCapabilities() {
const sdk = window.combos;
if (!sdk) return [];
const { methods } = await sdk.init();
return methods;
}各 TypeScript ブロックは独立したヘルパーです。自分の UI から呼び出し、Promise の拒否を処理してください。AfterClick はプレイヤーの操作に結び付けます。ヘルパーの null はコードに示す未対応やキャンセルを表し、SDK 固有の戻り値ではありません。JSON は生のリクエスト/結果の例で、ID と時刻は架空です。UI の例文はゲームの言語に合わせてください。
メソッド一覧
| メソッド | 用途 | ホスト要求のタイムアウト |
|---|---|---|
init() | 対応機能を取得 | 3 秒後に互換フォールバック |
checkSession() | ログイン状態を確認 | 10 秒 |
login() | ホストのログインを開く | 5 分 |
getUserInfo() | ゲーム内のプレイヤー情報 | 10 秒 |
requestI18n(params) | 表示済みテキストを翻訳 | 30 秒 |
getSetting() | Cloud Ability の許可を取得 | 10 秒 |
authorize(params) | 1 つの権限を要求 | 5 分 |
openSetting() | 権限設定を開く | 5 分 |
getCloudAbilitySession() | 短期セッションを取得 | 10 秒 |
getTTLiveClient() | このページのクライアントを取得 | 同期、通信なし |
client.connect(options) | インタラクションに接続 | 独自のライフサイクル、全体の期限なし |
client.getLiveStatus() | インタラクション状態を照会 | セッション取得後、HTTP は最大 5 秒 |
client.onStatusChange(listener) | 状態を購読 | 同期 |
client.disconnect() | クライアントを停止 | 同期 |
初回は機能検出に最大 3 秒追加される場合があります。これは SDK の待機期限で、サービス水準の保証ではありません。公開メソッドに独自の timeout、AbortSignal、成功コールバック、追加の ID を渡すことはできません。
呼び出す前に対応状況を確認
関数の存在だけでなく init().methods を確認します。現在の Web ホストは checkSession と login を提供します。getUserInfo には信頼されたゲームコンテキスト、requestI18n には Play ホストの翻訳対応、TikTok には対応機能と登録済み起動コンテキストが必要です。旧版 Web や App では異なる場合があります。
現在の Web ホストは getSetting、authorize、openSetting、getCloudAbilitySession を公開していません。以下の契約は明示的に対応するホスト向けです。ゲーム公開だけで Cloud Ability や TikTok は有効になりません。一覧にないメソッドは、その要求をホストへ送る前に unsupported で拒否されます。
getTTLiveSession は内部の機能名です。getTTLiveClient() の前に確認しますが、公開の combos.getTTLiveSession() はありません。logout、汎用 request、クラウドセーブ、決済、ランキング、ギフト登録もグローバル API にはありません。
初期化とアカウント
combos.init()
combos.init(): Promise<ICombosHostInitResult>
引数:なし。ログイン:不要。戻り値:機能名の配列 methods を持つ Promise。ログインや UI 表示、TikTok 接続は行いません。
同時呼び出しは検出を共有し、結果をこのゲームドキュメント内でキャッシュします。他のホストメソッドも自動初期化します。有効な配列中の未知の名前と重複は除かれます。検出失敗、不正なペイロード、3 秒間無応答の場合は ['checkSession', 'login'] で解決します。有効な空配列は空のままです。この互換動作は、単独ページに動作するホストがある証明ではなく、後続呼び出しはタイムアウトし得ます。強制再取得オプションはありません。
以下の結果は例です。すべてのホストがこの一覧に対応すると仮定しないでください。
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>
引数:なし。ログイン:不要。戻り値:ホストがログイン済みと報告すると true、それ以外は false。ログイン UI は開きません。SDK は厳密にブール値 true のみを受け入れ、文字列などの truthy な値は受け入れません。
独立したアカウント操作の直前に確認し、永続的なログイン保証としてキャッシュしないでください。確認後にも状態は変わります。通信エラーとタイムアウトは拒否され、正常な false やログアウトの証拠ではありません。false ならプレイヤーにログインを選んでもらいます。同じ操作で login() に成功した後は再確認せず続行します。
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>
引数:なし。アカウント ID、パスワード、token は渡しません。ログイン:不要。副作用:必要に応じホストのログイン UI を開きます。プレイヤー操作から開始し、処理中はボタンを無効にします。
status | 意味と次の操作 |
|---|---|
success | 現在の操作を続行。リロード、ポーリング、再確認は不要 |
cancelled | キャンセルとしてゲームに戻る。自動で再表示しない |
キャンセルは正常終了です。ポップアップブロック、通信、ログイン同期の失敗やタイムアウトは拒否されます。不正な結果/未知の状態は request_failed になります。現在の Web ホストではログイン済みなら直接 success を返します。認証情報やプロフィールは返さず、プロフィールは別途取得します。
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>
引数:なし。前提:getUserInfo 対応、信頼されたゲームコンテキスト、ログイン済みセッション。未ログインは session_required。直前の確認に成功しても、取得時の失効を処理してください。
| フィールド | 型/必須性 | 意味 |
|---|---|---|
appId | 必須、空でない string | ゲームのアプリ ID。Post URL やゲームが指定したプロジェクト ID ではない |
openId | 必須、空でない string | アプリ内のプレイヤー ID。appId と組み合わせる |
nickName | 必須 string、空文字可 | 表示名。代替表示を用意する |
avatarUrl | 必須 string、空文字可 | アバター。未設定/読込失敗時は代替を表示 |
locale | 必須、空でない string | プレイヤーが保存した公開言語。例: en、zh-CN。未保存なら現在の製品言語 |
メール、電話、プラットフォームのユーザー ID、ログイン token、Cloud Ability セッションは含まれません。openId で異なるアプリのユーザーを同一視したり、ブラウザーの結果をサーバー認証の証明にしたりしないでください。表示値は HTML ではなくテキストとして扱います。ID の欠落や表示値の型違いなどは request_failed。追加のホスト/バックエンドエラーもあり得ます。
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"
}ゲームの多言語対応
combos.requestI18n(params)
combos.requestI18n(params: ICombosHostRequestI18nParams): Promise<ICombosHostI18nResult>
ログイン条件:現在の Web 翻訳ブリッジでは不要ですが、requestI18n 対応が必要です。原文を先に表示し、翻訳を非同期の追加機能として扱います。
| 引数 | 型 | 必須 | 意味 |
|---|---|---|---|
sourceLocale | string | はい | 原文の言語。例:en、zh-CN。翻訳先ではない |
sourceTexts | string[] | はい | すでに表示している正確な原文や固定テンプレート |
targetLocale はありません。ホストの現在の製品言語が翻訳先です。Web 実装は言語タグの前後空白を除き、空/非文字列項目を除外し、同じ原文を重複排除して 50 件ずつ翻訳します。50 件は内部バッチサイズであり SDK の入力上限ではありません。30 秒で完了しやすい小さなまとまりを使い、アニメーションの各フレームでは呼び出さないでください。
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}" }
}| 戻り値 | 意味 |
|---|---|
needed: false | 原文を維持。locale と translations は存在しない |
needed: true | 翻訳あり。ただし一部のキーが欠ける場合がある |
locale | ホストが選んだ言語。needed: true のときのみ存在 |
translations | 原文文字列 → 翻訳文字列。アプリ独自 ID ではなく正確な原文がキー |
同等の言語、利用できる原文なし、翻訳不可、現在の Web 翻訳バックエンドの失敗は { needed: false } になり得ます。不正な翻訳結果も SDK が同じ分岐へ変換します。一方、未対応や通信タイムアウトは拒否され得ます。欠落/空の翻訳は原文で補い、innerHTML ではなく textContent を使います。
Score: {score} のようなテンプレートを先に翻訳し、値を後から挿入します。SDK は補間をしません。必要なプレースホルダーが残っているか検証し、再呼び出しでは最初の原文を維持してください。翻訳済みの文を古い sourceLocale で再送しないでください。
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.
}
}オプションの Cloud Ability API
現在の Web ホストは以下の 4 メソッドを公開していません。各メソッドの対応を個別に確認します。例は対応ホスト用で、有効化の手段ではありません。ユーザーの許可成功も、ゲーム所有者が能力を有効にした証明にはなりません。
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 }| フィールド/値 | 契約 |
|---|---|
scope | 現在は 'ai_model' のみ。authorize で必須 |
decision | 実行時は AUTHORIZATION_DECISION_GRANTED または AUTHORIZATION_DECISION_DENIED を受け入れる |
AUTHORIZATION_DECISION_UNSPECIFIED | 型のゼロ値。SDK が受け入れる有効な決定ではない |
decidedAtMs | 必須の有限数、Unix ミリ秒。秒や有効期限ではない |
ai_model の欠落 | このゲームの権限をまだ尋ねていない。拒否とは異なる |
session | 必須の空でない短期認証情報。機密としてメモリー内だけで保持 |
expiresAtMs | 必須の有限数、Unix ミリ秒の失効時刻。固定 TTL の保証なし |
ユーザー、デバイス、プロジェクト、Post、プレイインスタンスの ID は渡しません。信頼されたコンテキスト、ログインと権限 UI はホストの責任です。保護された操作はそのホストのログイン条件を満たし、拒否後に繰り返し要求しないでください。
combos.getSetting()
combos.getSetting(): Promise<ICombosHostAuthSetting>
引数:なし。タイムアウト:10 秒。現在のゲームに対する現在のプレイヤーの決定を読み取り、設定 UI は開きません。戻り値は ICombosHostAuthSetting。未設定なら {} も有効です。
SDK は既知の ai_model のみを返します。キーがある場合は許可/拒否と有限数の decidedAtMs が必須で、不正なレコードは request_failed です。欠落を拒否と同一視せず、設定変更後は古い決定を使い続けないでください。
{
"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>
引数:scope: 'ai_model' を持つ必須オブジェクト。デフォルト、ワイルドカード、スコープ配列、呼び出し側の決定指定はありません。タイムアウト:5 分。プレイヤー操作からホストの権限 UI を要求します。
設定全体ではなく 1 件の許可レコードを返します。AUTHORIZATION_DECISION_DENIED は正常な結果です。GRANTED の後だけ対象操作へ進み、拒否後に自動で再要求しません。cancelled の契約はなく、UI を閉じた場合も実際のレコード/拒否で処理します。ログインの状態を流用しないでください。未対応、不正な結果、通信失敗、タイムアウトは拒否されます。
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>
引数:なし。タイムアウト:5 分。プレイヤー操作でホストの権限設定を開き、その後の ICombosHostAuthSetting を返します。無言で権限を付与する設定オブジェクトは受け取りません。
欠落や拒否も含め、戻り値で UI を更新します。ブール値、単一レコード、ログイン状態ではありません。検証は getSetting() と同じです。未対応、不正な結果、ホスト/通信失敗は拒否され、独立したキャンセル状態は定義されていません。
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>
引数:なし。タイムアウト:10 秒。対応ホストで現在のプレイの { session, expiresAtMs } を取得します。許可ダイアログを開く操作ではなく、全 AI モデルへのアクセス保証でもありません。セッション、権限、能力の利用可否のエラーを処理します。
認証情報はメモリーにのみ保持し、そのホストが説明する Cloud Ability 連携でだけ使用します。ログ、スクリーンショット、URL、ストレージ、ソースに含めないでください。使用前に期限を確認し、必要なら再取得し、アカウント/プレイの変更時に破棄します。refreshToken、TTL 引数、汎用バックエンド認証の保証はありません。不正な結果は 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 クライアント
実際の TikTok 連携は現在、有効化できる手続きがありません。以下の契約は新規公開ゲームで実際のギフトを受信できるという意味ではありません。ゲーム制作、シミュレーター、Combos への公開は可能ですが、実際の連携はプラットフォームの有効化手続きを待つ必要があります。
管理対象はこのゲームの TikTok インタラクションセッションであり、配信全体の状態ではありません。通信、ハートビート、更新、再接続はクライアントが担当し、指令、効果、永続的な重複排除と結果はゲームが担当します。ギフト対応、公開、準備資料、完全なプロジェクトはチュートリアルにあります。
combos.getTTLiveClient()
combos.getTTLiveClient(): TTLiveClient
引数:なし。戻り値:同期的に TTLiveClient を返し、この時点では通信しません。同じ SDK/ゲームページでは同一インスタンスを返します。複数コンポーネントで競合する接続管理をしないでください。
先に getTTLiveSession の対応を確認します。オブジェクト取得は対応、ログイン、起動登録、接続成功の証明ではありません。実接続前にアカウント処理を完了させます。プロバイダーキー、CAS、launchData、WebSocket URL は内部管理で、指定用の引数はありません。
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>
引数:必須 options。必須の onCommand は boolean または Promise<boolean> を返す関数です。ルーム ID、配信者 ID、token、再接続、タイムアウトのオプションはありません。
ready フレームで Promise<void> が解決しますが、効果の実行や継続接続の証明ではありません。別途状態を購読します。回復中は無期限に pending となり得るため、待つ前に停止操作を用意します。接続意図がある間の再呼び出しは既存の pending を共有するか直ちに解決し、ハンドラーは置き換えません。変更前に切断します。
onCommand がない場合は通常の Error で拒否。ready 前の切断や終了状態も pending を拒否します。一時的な通信/セッション障害は通常、即時拒否せず回復に入ります。別 ID の非同期ハンドラーは並行実行され得るため、共有状態は直列化またはトランザクションで更新します。
interface TTLiveConnectOptions {
onCommand: (command: TTLiveCommand) => boolean | Promise<boolean>;
}
interface TTLiveCommand {
messageId: string;
instruction: string;
count: string;
timestamp: string;
}| フィールド | 型/検証 | ゲームの責任 |
|---|---|---|
messageId | 空でない string。SDK 1.1.0 は最大 256 文字 | 不透明な冪等キー。効果と結果と一緒に保存 |
instruction | string | 宣言した指令に照合。SDK はギフト一覧を検証しない |
count | 大整数の精度を保つ十進数字列 | 業務上の範囲を検証後に変換。無条件の Number は避ける。SDK はゼロ/先頭ゼロ自体を拒否しない |
timestamp | string | 元の時刻表現。型は単位/形式を保証しない。ID や順序保証に使わない |
以下は指令例で、ギフト登録 API ではありません。視聴者 ID、表示名、価格、実際のギフト ID は含まれません。count はマッピング後の指令数量で、ギフト数やコイン額とは限りません。
{
"messageId": "example-command-001",
"instruction": "gift_flash",
"count": "3",
"timestamp": "1791800000"
}| ハンドラーの結果 | SDK の動作 |
|---|---|
true/true で解決 | 成功を報告。効果とレシートのコミット後に返す |
false/false で解決 | 効果のない未知の指令など、確定した拒否/失敗を報告 |
| throw/Promise 拒否/非ブール値 | 不明のまま未確認。再接続し再配信され得る |
メモリーの重複排除は限定的で、明示的な切断やページ更新で消えます。永続的な exactly-once ではありません。messageId、効果、結果を原子的に保存し、重複時は保存済み結果を返します。効果が部分的に起きて不明なら false にしません。Gift Arenaにトランザクションの例があります。
以下のヘルパーはすぐに停止操作を返し、拒否を処理します。実際の指令ハンドラーと例外を投げない UI コールバックを渡してください。connected は await でき、stop は pending/接続済み双方で使えます。
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>
引数:なし。現在の状態を照会し、リスナーへ通知して TTLiveStatus を返します。指令ストリームは開始しません。ホストセッション取得に 10 秒(初回は検出も追加)、その後の HTTP に 5 秒の期限があります。
ネットワーク、HTTP、セッション解析、不正な状態は通常 unknown などの結果となり、ended の証明ではありません。ホストの tt_not_launched は ended / relaunch_game になります。終了状態は実行中のクライアントも停止します。プレイ中は頻繁なポーリングより購読を使います。
interface TTLiveStatus {
state: 'connecting' | 'connected' | 'recovering' | 'ended' | 'unknown';
reason: string;
action: 'none' | 'wait' | 'relaunch_game';
confirmedAtMs: number;
}| フィールド/値 | 意味と対応 |
|---|---|
state: connecting | 初期接続中 |
state: connected | このゲームのセッションが確認済み |
state: recovering | SDK が通信を回復中。再試行を待つ |
state: unknown | 確認できない。配信終了とは判断しない |
state: ended | このインタラクションが終了。action を確認 |
reason | 空や追加値もある診断文字列。閉じた enum ではない |
action: none | 回復操作なし |
action: wait | 回復を待ち、キャンセルを提供 |
action: relaunch_game | LIVE Studio からゲームを開き直す。配信の再起動ではない |
confirmedAtMs | 最新の起動/ハートビート確認の Unix ミリ秒。0 は不明、有効期限ではない |
既知の理由は platform_unconfirmed、transport_unavailable、client_disconnected、tt_not_launched、session_required などです。回復は state と action で制御し、理由の完全な列挙を仮定しないでください。生の値はそのままプレイヤー向け表示にしません。
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
引数:TTLiveStatus を受け取る必須の同期リスナー。戻り値:購読解除関数。登録時に直ちに現在値が通知され、その後はフィールド変更時に通知されます。state が同じでも確認時刻の更新で呼ばれ得ます。
UI を取り除く際に解除します。解除は切断ではなく、切断もリスナーを削除しません。リスナーは例外を投げないでください。最初の同期呼び出しでは例外が外へ伝わる場合があります。例は診断値の表示であり、本番 UI は翻訳した文言を使います。
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
引数:なし。戻り値:undefined(void)。タイマー、再試行、ソケットを停止し、メモリー上の実行/結果を消去します。pending の接続を拒否し、unknown / client_disconnected / wait、confirmedAtMs: 0 を通知します。
TikTok 配信を同期的に終了する API や、サーバーの終了 ACK の証明ではありません。ゲームの保存レシートは削除せず、実行中のハンドラーもロールバックできません。UI は別途解除し、遅延処理を管理して、永続レシートは保持します。同じクライアントで再接続でき、後片付けの切断を繰り返しても安全です。
import type { TTLiveClient } from './combos-host-sdk';
function stopTikTok(client: TTLiveClient, unsubscribe: () => void) {
unsubscribe();
client.disconnect();
}エラーと回復
ホストメソッドの失敗は文字列 code と message を持つ Error で拒否されます。メッセージではなくコードで分岐します。以下は網羅的ではなく、ホスト/バックエンドのコードも通過します。TikTok の例外は code のない通常の Error もあり、getLiveStatus は多くの失敗を状態として返します。
checkSession() === false、ログインの cancelled、権限の DENIED、翻訳の needed: false は正常な結果です。以下はこの区別を維持し、特定クラスを仮定せず、認証情報をログに出さない例です。
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) };
}
}| コード | 意味 | 回復 |
|---|---|---|
unsupported | ホストが非対応 | 任意機能を無効化、基本ゲームを維持 |
timeout | SDK の待機期限 | ローディングを終了し手動再試行を提供。ホスト処理の取消とは限らない |
transport_failed | 送信失敗 | 対応プレイヤー環境を確認し代替 UI を維持 |
request_failed | ホスト失敗/不正な結果 | 対象操作を確認、安全な場合のみ再試行 |
disposed | ドキュメント/SDK 終了 | 処理を止め、ループで再試行しない |
session_required | セッションなし | ログイン成功後に元の操作を再試行 |
model_not_supported | モデルが拒否された | 対応する Cloud Ability モデルを使う |
100250001 | 権限要求の検証失敗 | scope と信頼されたゲームコンテキストを確認 |
100260001 / 100260002 | セッション作成/コンテキスト/セッションが無効 | 正規のプレイセッションを再確立。ID や認証情報を捏造しない |
100260004 | AI モデルの許可なし | 決定を尊重し、対応ホストで許可を要求 |
100260005 | ゲーム能力が無効 | 所有者に確認。再ログインでは有効にならない |
数字コードは既知のホスト/バックエンドの値で、Web が Cloud Ability を公開する証明ではありません。先に対応を確認します。未知のコードは回復可能な UI で扱い、非機密の診断だけ記録します。
TikTok の reason と action は状態フィールドです。指令ハンドラーの拒否が自動的に失敗 ACK になるわけではありません。効果が起きたかもしれない処理を catch(() => false) で包まないでください。ホストのタイムアウトは SDK の待機だけを止め、ログイン、権限、翻訳には公開キャンセル API がありません。UI の再表示や不確かな処理の重複を起こす自動再試行は避けます。
ライフサイクルと連携範囲
- ドキュメントの機能を取得し、新しいアカウント操作の直前にログイン状態を確認します。
- ログイン/権限はプレイヤー操作から開始し、取消や拒否後に自動再表示しません。
- 原文を表示し翻訳は任意にします。シーン削除後の古い非同期 UI 結果は破棄します。
- TikTok クライアントの管理者を 1 つにし、購読、永続的な指令処理、接続、待機中の取消を管理します。
- 終了時は購読解除と切断を行います。レシートを残し、プレイ/アカウント終了時に機密セッションを破棄します。
window.combos に全体の dispose()、アカウント変更イベント、ログイン取消ハンドル、共通タイムアウト設定はありません。内部クラスや非公開 HTTP を代わりに使わないでください。サンプルのヘルパーや保存件数制限はゲームの設計で、追加の SDK API ではありません。
バージョン、型、完全な例
公開 TypeScript 定義 がエディター向けの正式な型です。本ページは SDK 1.1.0 の実行時検証、タイムアウト、Web 機能選択、翻訳、TikTok ライフサイクルも確認しています。型の存在と実行時の利用可否は異なり、将来の版で変更される場合があります。
- アカウントと多言語対応:ボタン、ログイン後の継続、安全なテキスト更新。
- TikTok ゲーム作成:ギフト、プロジェクト、ローカルテスト、公開、準備、開通後の LIVE 検証。
- Gift Arena をダウンロード:トランザクション処理を含む全ソース。
例は公開型で検証しますが、型検証やシミュレーターは実アカウントのログイン、Cloud Ability、実際の有料ギフトの成功を証明しません。対応ホスト、資格のあるアカウント、登録済みゲームで別途検証してください。