星途 / DOCS

阅读主题

开发者文档/开发者 / H5 / 游戏服务端v0.3.0已实现

本地游戏联调 ​

本地联调用于让你自己的游戏页面连接平台服务，验证身份、会话、区服角色及客服。使用指定游戏的短期 test_ 专用账号，不使用真人手机号或生产玩家身份，不开放支付、钱包和礼包资产。

H5 SDK v0.4.0 也允许测试人员在统一注册页自行设置用户名和密码。此入口使用 registerAccount()，由来源策略自动创建同游戏作用域内 24 小时测试账号，不自动登录、不绑定真实手机；其可见用户名不要求带 test_ 前缀。下面的后台创建流程仍生成一次性随机 test_ 凭据，两类身份受相同隔离约束。见玩家账号注册。

SDK 安装包仍为 v0.3.0；联调来源和账号管理属于平台服务端能力。游戏自身的 API、角色和存档建议运行在独立测试环境中，不能把平台测试账号当成外部游戏数据已隔离的证明。

1. 确认应用与实际页面来源 ​

使用开发者所有者账号打开开发者控制台，创建逻辑游戏和所需客户端。待审核应用也可以先使用专属测试账号联调，无需先上线；已停用应用无法联调。在该游戏的本地联调设置中登记实际页面 Origin；需要填写协议、主机与明确的非默认端口，不能填写页面完整路径。

页面地址应登记的来源
http://127.0.0.1:8794/#/loginhttp://127.0.0.1:8794
http://localhost:8794/#/loginhttp://localhost:8794
https://localhost:9443/gamehttps://localhost:9443

localhost 和 127.0.0.1 是两个不同来源，需分别登记。最多 6 个，不能重复；不接受尾斜线、路径、查询、片段、凭据、通配符、子域或其他 IP。HTTP 80、HTTPS 443 是浏览器省略的默认端口，不支持作为本地联调来源。

启用至少需要一个来源。此登记只对该游戏的受限 SDK 路径生效，不开放开发者或管理后台跨域；本地来源仅允许所属游戏的联调账号，不允许普通生产玩家登录。若游戏自己还有来源校验，也要在游戏服务器配置相同的实际页面来源。

2. 创建专用账号 ​

启用联调后，为测试人员创建专用账号。昵称可填 1～40 字普通文本；有效期为 1～7 天，默认 1 天。同游戏同时有效的账号最多 10 个，每小时最多创建 30 个。

平台随机生成 test_ 开头的账号与密码。密码只在首次创建成功时显示；请私密交付给对应测试人员，不写进仓库、日志或公开截图。请求结果不确定时使用原 requestId 重试；重试返回 credentials: null，不会再次展示密码。丢失凭据应撤销旧账号后重建，不能从列表找回密码。

联调账号只访问所属逻辑游戏；同游戏各端共享该游戏身份，换端不扩大权限。不要通过绑定真实游戏旧账号的方式测试新账号流程。

3. 显示测试说明并完成 PKCE 登录 ​

登录前向测试人员提供以下两页，由本人阅读和主动确认，不能预勾选或代为确认：

配置示例仅引用上述真实页面，没有包含账号密码或应用密钥：

json
{
  "consentVersion": "2026-09",
  "termsUrl": "https://starai.art/docs/testing/authorization-2026-09",
  "privacyUrl": "https://starai.art/docs/testing/data-2026-09"
}

2026-09 是当前登录接口的授权标识，不是实名核验结果，也不是正式经营协议。上面的字段是给需要这类配置的游戏适配层参考，并非 StarlightSDK 自动渲染协议页面的承诺。游戏自己的创建账号或绑定旧账号说明仍需单独展示。

客户端使用批准的 App ID、baseUrl: "https://api.starai.art" 和专用联调账号进行密码登录。SDK 生成 PKCE 与 state；可信游戏服务器收到 appId、code、codeVerifier 后，用仅在服务端保存的 X-API-Key 调用 /api/server/auth/exchange。不要让本地浏览器直接持有密钥，也不要改走演示快捷会话入口。

依照服务端起步完成兑换，再验证刷新恢复和会话。网络错误应保留重试机会；到期、撤销或配置停用应清理失效的登录状态，不能只靠浏览器缓存显示已登录。

4. 验证角色与客服 ​

  1. 比较游戏服务器确认的 user.gameUserId 与后续 /api/me 身份，同游戏跨端应保持一致，其他游戏必须拒绝。
  2. 用游戏服务端密钥与该联调玩家的有效会话完成可信区服角色绑定，再检查客户端 /api/roles 仅返回本人角色。使用测试角色名称，不导入真实玩家存档。
  3. 通过游戏内客服入口创建明确标注“联调测试”的工单，验证开发者客服接待、回复与关闭。不要提交真实付款凭证、手机号、身份证或密钥。
  4. 验证账号主动退出、管理员撤销、有效期结束和游戏联调关闭后的会话失效行为。

这些账号不获得演示或正式资产，不支持真实支付、平台钱包、礼包领取，也不计入代理推广注册业绩。测试真实支付另需供应商沙箱和正式支付契约，不能通过解除联调账号限制来模拟“已验收收款”。

管理 API ​

以下接口位于开发者域名，使用开发者所有者会话 Bearer；玩家、客服坐席、代理凭据不可代替。:id 为逻辑游戏 ID，而非单端 App ID。所有写入携带 8～100 位字母、数字、_ 或 - 组成的 requestId。

请求输入与响应要点
GET /api/developer/applications/:id/testing返回 {config, players, limits}；配置未建立时 enabled=false、origins=[]、version=0
POST /api/developer/applications/:id/testing{enabled,origins,version,requestId}；返回 {config,replayed}；使用刚读取的版本
POST /api/developer/applications/:id/testing/players{nickname?,expiresInDays?,requestId}；首次 201 返回 {player,credentials:{username,password},replayed:false}；同请求重试 200，credentials=null
POST /api/developer/applications/:id/testing/players/:playerId/revoke{version,requestId}；返回 {player,replayed}；使用该账号的最新版本

账号列表仅展示账号标识、别名、昵称、所属游戏、状态、版本和时间，不返回密码、摘要或令牌。账号状态为 active、expired、revoked，到期状态按有效期判断。

到期、撤销与错误处理 ​

撤销账号会清理其相关玩家会话、授权码及客服会话；关闭配置会撤销该游戏测试会话。游戏停用后仍可关闭配置或撤销账号。到期会阻止继续认证和会话使用，但不代表历史账号、角色、工单和必要审计记录已自动删除。

错误处理
ORIGIN_FORBIDDEN核对实际地址栏 Origin、所属 App ID、配置是否启用及应用是否被停用；待审核不阻止专属测试账号联调，不要登记通配符
LOCAL_TEST_ACCOUNT_REQUIRED本地联调入口只允许专用账号，不能填普通玩家身份
TEST_PLAYER_SCOPE_FORBIDDEN账号属于其他游戏，改用当前游戏的专用账号
SESSION_EXPIRED账号已到期或撤销，清理会话，需新账号再测试
ACCOUNT_RESTRICTED联调关闭或开发者/应用不可用，检查实际状态
TESTING_VERSION_CONFLICT / TEST_PLAYER_VERSION_CONFLICT重新获取最新配置或账号记录，核对后提交，不覆盖他人的管理修改
TEST_PLAYER_ASSETS_DISABLED此账号不支持支付、钱包或礼包资产，改测身份、角色或客服

转为正式接入 ​

测试结束后撤销不再使用的账号，并关闭不用的联调配置。正式上线需另行登记实际生产来源、提供真实有效的游戏经营说明与用户协议、确认玩家开户及合规服务，并配置和验证真实支付、退款、履约与设备能力。

本地来源登记不会自动放行生产域名；专用账号通过登录也不代表完整商业能力已就绪。继续阅读正式环境与演示环境和正式支付接入边界。

为游戏而生，为创造者而来。

© 2026 STARLIGHT 星途 · SDK 接入文档