H5 快速接入

适用版本：v0.2.1。SDK 提供账号、订单及玩家运营 API，不注入登录框、悬浮球或平台中心。本文完成客户端安装与登录；你的游戏服务端兑换接口是必需前置。

接入前准备

1. 在 开发者控制台 创建应用并选择 H5，等待平台审批开通，记录该客户端 App ID。
2. 将创建时的一次性服务端密钥保存在游戏服务器。遗失时在控制台轮换；旧密钥会立即失效。密钥不得出现在页面、构建环境注入的前端变量或公开配置中。
3. 游戏服务器提供 POST /game-server/session：接收 { appId, code, codeVerifier }，携带仅存于服务端的 X-API-Key 调用账号服务 POST /api/server/auth/exchange，返回其 SessionResponse。这条游戏服务器路径是本文宿主示例约定，不是 SDK 自动提供的接口。
4. 使用支持 ES2022、Fetch、Web Crypto、structuredClone 的浏览器，页面运行于 HTTPS 或 localhost 安全上下文。平台应允许真实接入页面的 Origin。

服务端还需用兑换结果中的可信 user.gameUserId 建立游戏自己的业务会话。平台 token 不自动授权你的游戏接口；退出平台也不会自动通知外部游戏撤销会话。

安装

下载 H5 安装包，将文件放入项目根目录后执行：

npm install ./starlight-sdk-0.2.1.tgz

包名为 @starlight/sdk，包含 ESM、CommonJS、自包含 TypeScript 声明和浏览器全局脚本。以下使用 ESM。

创建实例

import { StarlightSDK } from '@starlight/sdk';

export const sdk = new StarlightSDK({
  appId: 'game_your_id-h5', // 替换为已开通的 H5 App ID
  baseUrl: 'http://127.0.0.1:18787', // 本地平台；外部环境使用实际 HTTPS origin
  timeoutMs: 15_000,
  storage: sessionStorage,
  exchange: async (authorization) => {
    const response = await fetch('/game-server/session', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(authorization),
      signal: AbortSignal.timeout(15_000),
    });
    if (!response.ok) throw new Error(`游戏服务端兑换失败：${response.status}`);
    return response.json();
  },
});

baseUrl 传 origin，不加 /api 或末尾斜线。SDK 请求超时不覆盖你自定义的 exchange 回调，所以回调应自行限制超时、处理失败。不要在浏览器中直接携带服务端密钥兑换。

初始化、恢复与玩家登录

下面代码在宿主已显示协议并取得玩家同意后，由登录按钮触发。手机号和密码来自宿主表单；代码中的演示账号仅适用于本地演示库。

import { ApiError } from '@starlight/sdk';
import { sdk } from './sdk'; // 上一段保存为 sdk.ts

export async function boot() {
  const config = await sdk.init();
  const restored = await sdk.restoreSession();
  return { config, session: restored }; // 服务端验证成功后才显示已登录身份
}

export async function submitLogin(account: string, password: string) {
  try {
    const session = await sdk.login({
      method: 'password', account, password,
      consentVersion: '2026-09',
    });
    return { gameUserId: session.user.gameUserId, role: session.role };
  } catch (error) {
    if (error instanceof ApiError) throw new Error(`${error.code}：${error.message}`);
    throw error; // exchange 自身也可能抛出宿主定义的错误
  }
}

init() 只获取平台配置，不自动恢复或登录。SDK 在 login() 中生成 PKCE/state、校验 state，再调用 exchange；不得跳过登录直接相信客户端传来的身份。启动断网时，宿主应显示“连接失败，重试”，不要伪装已登录。

成功预期与排错

成功后 sdk.getSession() 返回快照，触发 session 事件，sdk.center() 可获取当前账号/游戏的数据。H5 与同逻辑游戏的 Android 可获得相同 gameUserId，这不等于存档自动互通。

现象或错误	检查与处理
APP_UNAVAILABLE	应用是否审核通过、是否因扩端重新待审、开发者或应用是否停用
INVALID_CREDENTIALS	玩家账号/密码；此错误不是会话过期
INVALID_AUTH_CODE	服务端是否拿到原 appId/verifier、是否重复或超时兑换；重新开始登录
STATE_MISMATCH / LOGIN_CANCELLED	不建立游戏会话；玩家重新发起登录
NETWORK_ERROR / TIMEOUT	检查服务地址、CORS、HTTPS及游戏后端；恢复失败保留候选，不显示已验证身份
登录成功却没有弹窗	正常：本包没有 UI，需宿主订阅事件并渲染

默认 local 模式使用每个账号/逻辑游戏一个内置演示角色。平台同时提供区服、可信角色绑定与持久化外部发货队列；切换 external 模式后，游戏服务端需绑定角色并消费、确认发货与回收，客户端通过 realms() / roles() 选择绑定目标。真实短信与供应商收款尚需接入，已提供外部履约协议不表示你的游戏服已经完成联调。见角色绑定与外部履约。接下来阅读 会话管理、接入宿主 UI 和 API 参考。

验证码登录首次验证新手机号时，服务端自动创建账号，没有独立注册 API。密码登录不会自动注册。客服可使用 tickets({limit,before})/ticket(id)，列表返回 nextCursor；支付与权益变更支持显式复用 requestId，详见 API 参考。