Android 构建与设备验收

适用版本：v0.2.1。当前 AAR 和宿主示例 Java 已编译通过，真机/模拟器运行尚未验收。本页列出的检查是接入方需要执行的工作，不是已全部通过的结果。

编译证据覆盖什么

仓库提供 android/build-aar.ps1，从固定 Maven Central 工具依赖取得 Android API 编译 jar并验证摘要，以 JDK 17 编译 Java 8 字节码、打包 AAR，并编译示例 Java。

# 在源码工作区根目录执行
powershell -NoProfile -ExecutionPolicy Bypass -File .\android\build-aar.ps1

输出为 android/dist/starlight-sdk-0.2.1.aar。这一步不执行 App，不生成已经过设备测试的 APK。AAR 可从 文档下载 获取；第三方游戏必须验证实际下载产物的版本、校验值与宿主构建。

完整示例构建需要 Android Studio、API 35 及 Gradle 8.9 兼容工具链，打开 android 工程执行 :demo:assembleDebug。仓库没有附带 Gradle wrapper，不应声称 ./gradlew 开箱可用。

开始前记录

记录 SDK/AAR 版本与 SHA-256、宿主 APK 与签名构建类型、App ID/逻辑游戏映射、测试 API 环境、Android/API/ROM、屏幕和引擎版本。服务端密钥仅保存在游戏服务器，验收文档不记录明文。

先完成 快速接入 和 可信授权。本地模拟器用 10.0.2.2:18787；真机通过 adb reverse tcp:18787 tcp:18787 使用 127.0.0.1:18787；随后在受控 HTTPS 环境验证证书和网络策略。

设备场景与成功标准

场景	执行方式	成功标准
安装与冷启动	Debug/Release、Manifest 合并、R8、实际签名安装	无缺类/权限异常，浮球无需系统悬浮授权
原生账号登录	密码和本地验证码路径；外部后端交换	一次授权对应一次成功会话；错误密码不进入游戏
取消/迟到响应	登录中返回、旋转、Activity销毁后返回交换结果	旧身份不复活，不弹旧窗口
切号	连续登录两个账号，并让旧请求延迟返回	只显示最新角色/钱包/订单；旧连接已清理
生命周期	前后台、旋转、多窗口、低内存重建	无旧 Activity 泄漏；内存会话丢失按未登录处理
输入与安全区	软键盘、刘海/挖孔、手势返回、横竖屏	控件可见可点；游戏画布不误收平台点击
浮球/中心	重复展示、拖动、关闭、切换原生页面	单浮球、无 Window 泄漏、宿主恢复输入
弱网	断网、切网络、请求超时、重新连接	明确错误/重试；不把未知订单当成未付款
设备撤销	本设备、另一设备、全部其他设备、跨账号伪造ID	按归属拒绝越权；本设备清状态，其他设备下次平台访问失效
游戏隔离	两账号、同游戏H5/Android、另一逻辑游戏	同游戏gameUserId一致、不同游戏数据隔离；不推断存档互通

遇到异常保留脱敏操作步骤、设备和构建信息、错误码及服务端对应记录；不要把 token、授权码/verifier、密码或完整响应写进公开日志。

订单和平台币：本地与外部验证分开

本地可验证未付取消释放占券、支付前查原单、重复提交不重复扣款、退款按付费/赠送来源回收、切号后不展示旧订单。默认 local 模式使用内置角色与本地钱包。external 模式已有独立区服/角色绑定与发货协议：先由可信游戏服务器绑定角色，再将 listRoles 返回的绑定 id 用作 roleId；直接提交未绑定的外部角色号会被拒绝。

真实发行还必须接供应商支付/回调验签/主动查单/退款，并让实际游戏服接入平台已有的外部角色绑定、发货与资产回收协议。外部礼包返回 ok=true 和 deliveryStatus=pending 时只代表领取已接受，需按 orderId 查到 fulfilled 才是游戏服确认；还要验证游戏服离线、重复消费、失败重试与退款先后顺序。供应商回跳、渠道要求、三方对账和失败补偿必须在实际环境执行。Android 中看到“支付成功”或 Java 编译成功均不替代这些验收。

交付判定

验收记录至少包含安装运行、原授权事务完成、退出/切号/设备撤销、旋转及迟到响应、软键盘、弱网、订单重试的证据。对未通过项标记是否阻止该游戏交付。当前也未交付已验收的 Unity/Cocos 插件；AAR 可以作为桥接基础，但不能直接宣传所有引擎即插即用。

具体方法查 API 参考，Activity 持有关系与释放规则查 生命周期。

JVM 协议回归的适用范围

本轮新增 android/test-protocol.ps1，编译真实 SDK 源码并运行真实 HttpURLConnection/JSON 请求，覆盖候选恢复、scope、错误密码不退出、失效回调、PKCE、到期与迟到结果。测试仅为 Handler/Looper/Base64 提供 JVM shim，不执行 Android UI，也不证明主线程调度、ROM 或设备生命周期已通过。设备验收新增：加密候选恢复中断网/撤销/切号、密码错误保留登录、headless 业务操作重试及其与原生 UI 混合使用。