阅读主题
Android API 参考
适用版本：v0.2.1，包名 games.starlight.sdk，主类 StarlightSdk，常量 StarlightSdk.VERSION 为 0.2.1。前置为 AAR 集成。本页“已实现”指公开源码/编译产物，不意味着设备验证通过。
配置与回调
java
public StarlightSdk(StarlightSdk.Config config, StarlightSdk.Listener listener)
public StarlightSdk.Config(String appId, String apiBaseUrl, boolean demo)
public interface Listener {
void onAuthorization(StarlightSdk.Authorization authorization);
void onSessionChanged(org.json.JSONObject session);
void onLogout();
void onError(String code, String message);
}
public interface Callback {
void success(org.json.JSONObject result);
void failure(String code, String message);
}签名块用于查阅，不作为一个可直接编译的类。Config 的公开 final 字段为 appId、apiBaseUrl、demo。App ID 为 3–100 位字母、数字、_、-；apiBaseUrl 为 HTTPS origin，无 userInfo、业务路径、query、fragment。demo=true 仅允许 localhost、127.0.0.1、10.0.2.2 的 HTTP；末尾 / 会移除。参数非法抛 IllegalArgumentException，不是异步回调。
授权与会话
| 真实签名 | 作用 |
|---|---|
void login(Activity activity) | 打开原生账号登录 |
void completeGameLogin(Authorization authorization, JSONObject result) | 使用原始事务完成游戏后端返回的会话；推荐且必须使用的完成方式 |
void completeGameLogin(JSONObject result) | 已弃用，回报 AUTH_CONTEXT_REQUIRED 并拒绝登录 |
void exchangeWithDemoBackend(Authorization authorization, Callback callback) | 仅本地演示实例和内置演示 App；新应用必须接自己的后端 |
boolean isLoggedIn() | 检查本地 token 是否存在，不是一次服务端有效性确认 |
JSONObject getSessionSnapshot() | 内存会话深拷贝，无会话时 null |
void logout() | 本地立即清除并尝试服务端撤销，调用 onLogout |
Authorization 公开 final String appId, code, codeVerifier 和 JSONObject toJson()。不能公开构造，内部原始对象身份是事务安全的一部分。正确调用见 授权交换。新增 authorize(JSONObject input) 为宿主登录 UI 发起 PKCE 授权，输入为 method/account/consentVersion 及 password 或 challengeId/code；仍通过原 Authorization 完成。cancelLogin() 取消待授权事务；clearLocalSession() 仍为私有实现。
浮球与原生面板
java
void showFloat(Activity activity)
void hideFloat()
void openPlatformCenter(Activity activity)
void openGiftCenter(Activity activity)
void openWallet(Activity activity)
void openOrderCenter(Activity activity)
void openAccountSecurity(Activity activity)
void detachActivity()
void destroy()浮球属于宿主 Activity 内视图，不是系统 overlay。平台中心提供内置导航；openAccountSecurity 打开设备管理。上述方法涉及 UI 时请在主线程调用。反复打开/关闭、软键盘及全屏游戏输入仍需宿主验收。
Android 已新增下述宿主业务方法，可不打开原生中心直接操作；底层 request 仍为私有实现。新增密码/客服接口不等于已补齐对应原生页面，H5 与 Android 的完整页面功能仍有差异。
设备管理接口
java
void listAccountSessions(Callback callback)
void revokeAccountSession(String id, Callback callback)
void revokeOtherSessions(Callback callback)列表返回 {items:[...]}，每项包含 id、appId、gameName、clientDescription、createdAt、lastSeenAt、expiresAt、current。不返回 token/摘要。撤销单设备返回 {ok:true,current:boolean}；撤销本人当前设备会调用内部清会话；撤销其他设备返回 {ok:true,revoked:number}。
java
sdk.listAccountSessions(new StarlightSdk.Callback() {
@Override public void success(org.json.JSONObject result) {
org.json.JSONArray items = result.optJSONArray("items");
// 在仍有效的 Activity 中渲染公开设备列表。
}
@Override public void failure(String code, String message) {
// 显示错误和重试入口；不打印令牌或完整响应。
}
});实际撤销前让玩家确认目标；公开 id 只是操作句柄，服务器仍验证归属。
错误处理与边界
| 错误/情况 | 动作 |
|---|---|
AUTH_CONTEXT_REQUIRED / INVALID_SESSION | 修正完成登录的事务参数/返回对象，不伪造会话 |
AUTH_CANCELLED | 演示交换所用登录事务已取消，重新发起登录 |
DEMO_DISABLED | 接自己的可信服务端 |
APP_UNAVAILABLE / 角色不属于当前游戏 | 检查审批、应用配置，以及 local 演示角色或 external 可信角色绑定 |
| 订单支付结果未知 | 从订单中心查询原单；不根据关闭弹窗或网络超时判定失败后重复建单 |
| 网络/服务器错误 | 展示 Callback.failure/onError 信息与重试，宿主保留自己的请求归属校验 |
演示支付和平台币不等于真实供应商收款或跨厂商结算。平台已有外部游戏服角色绑定、持久化发货与回收协议；external 模式须使用 listRoles 的绑定 id 并由游戏服务端消费、确认，不能仅根据客户端支付回调增加资产。会话撤销不自动撤销外部游戏自身会话。完成集成后必须继续 生命周期验收 和 设备运行验证。
新增宿主业务接口与显式恢复
当前提供以下公开签名，原生 UI 保持兼容。Callback 返回 JSONObject；切号后的旧结果返回 SESSION_CHANGED，销毁后不向已释放宿主投递结果。
java
void authorize(JSONObject input)
void cancelLogin()
JSONObject exportSession()
void restoreSession(JSONObject saved, Callback callback)
void getConfig(Callback callback)
void sendSms(String phone, String purpose, Callback callback)
void resetPassword(JSONObject input, Callback callback)
void changePassword(String currentPassword, String newPassword, Callback callback)
void getCenter(Callback callback)
void listOrders(Callback callback)
void getOrder(String id, Callback callback)
void createOrder(JSONObject input, Callback callback)
void payOrder(String id, String retryId, Callback callback)
void closeOrder(String id, Callback callback)
void refundOrder(String id, String retryId, Callback callback)
void claimGift(String id, String roleId, String retryId, Callback callback)
void claimCoupon(String id, String retryId, Callback callback)
void claimDaily(String retryId, Callback callback)
void readMessage(String id, Callback callback)
void listTickets(int limit, String before, Callback callback)
void getTicket(String id, Callback callback)
void createTicket(JSONObject input, Callback callback)
void replyTicket(String id, String content, String retryId, Callback callback)
void closeTicket(String id, String retryId, Callback callback)createOrder 输入 productId/roleId/paymentMethod、可选 couponId/requestId；createTicket 输入 subject/category/content、可选 orderId/requestId。仅在未传 requestId 时生成；同一动作重试请自行保存并复用请求 ID。pay/refund/权益/工单变更显式传 retryId，使用 UUID 即可。listTickets 的 before 为前页 nextCursor，第一页传 null，limit 为 1–100。resetPassword 输入 phone/challengeId/code/newPassword；短信 purpose 为 login/password_reset/account_deletion。验证码首登自动注册，不存在独立注册路由。
getCenter 返回钱包、商品、礼包、券、会员与消息，不虚构独立 wallet/gifts 列表路由。config.demo=false 拒绝创建 demo 订单，并在付款前拒绝已存在的 demo 订单；wallet 仍属于当前本地验证能力，不代表真实支付已接通。
恢复数据为 {version:1,appId,apiBaseUrl,session}。exportSession 只导出有效内存会话副本，不写磁盘；宿主负责加密保存和访问控制。新实例 restore 时先验证 /api/me，成功前 isLoggedIn 仍为 false。已有活动会话返回 SESSION_ACTIVE；scope 不符返回 SESSION_SCOPE_MISMATCH；候选到期返回 INVALID_SESSION。网络错误保留调用者候选，不修改它；退出时删除宿主保存数据，明确失效时删除候选，网络失败时允许重试。该机制不替代 final Listener 生命周期释放。
HTTP 401 的 SESSION_EXPIRED/SESSION_REVOKED/UNAUTHENTICATED/INVALID_SESSION，以及 HTTP 403 的 ACCOUNT_RESTRICTED/APP_UNAVAILABLE，会清当前认证会话；错误旧密码 INVALID_CREDENTIALS 返回 Callback.failure 并保留登录。失效会话仍完成业务失败回调，宿主不会无限等待。
多区服与账号生命周期接口
getCapabilities、listRealms、listRoles、getDeletionPreview、exportAccount 均通过 Callback 返回实际平台结果；deleteAccount(JSONObject, Callback) 提交本人身份验证与明确注销确认。源码方法签名为准，JSON 字段见账号生命周期。成功注销只清理原会话，不清除在等待期间切换的新账号。