Android 快速接入

适用版本：v0.2.1。AAR 与宿主示例 Java 已编译通过，尚未完成真机或模拟器运行验收。SDK 是无第三方运行依赖的原生 Java 库，最低 API 23，提供原生登录、宿主 Activity 内浮球和平台面板。

安装与环境

下载 Android AAR，放入宿主 app/libs/，在模块 Gradle 文件加入：

dependencies {
    implementation files('libs/starlight-sdk-0.2.1.aar')
}

宿主 minSdk 至少 23，检查 Manifest 合并后的 android.permission.INTERNET 和 AAR 的混淆规则。浮球不需要跨应用悬浮权限；它只附着当前游戏 Activity。实际 APK、签名、R8 和主流设备必须另行验证。

本地工作区先启动账号服务；模拟器访问 http://10.0.2.2:18787。USB 真机调试可执行 adb reverse tcp:18787 tcp:18787 后访问 http://127.0.0.1:18787。明文流量配置只放调试构建，正式配置使用 HTTPS。

先运行本地演示闭环

以下 Activity 使用内置演示 App ID 和后端兑换，仅用于本地验证，不含真实充值。将其作为宿主调试入口并注册 Activity；sdk 必须是成员字段，不能在构造时引用尚未赋值的局部变量。

import android.app.Activity;
import android.os.Bundle;
import android.widget.Button;
import android.widget.Toast;
import org.json.JSONObject;
import games.starlight.sdk.StarlightSdk;

public final class SdkDemoActivity extends Activity implements StarlightSdk.Listener {
    private StarlightSdk sdk;

    @Override public void onCreate(Bundle state) {
        super.onCreate(state);
        sdk = new StarlightSdk(new StarlightSdk.Config(
            "starlight-android", "http://10.0.2.2:18787", true), this);
        Button login = new Button(this);
        login.setText("登录本地演示账号");
        login.setOnClickListener(v -> { if (sdk != null) sdk.login(this); });
        setContentView(login);
        sdk.showFloat(this);
    }

    @Override public void onAuthorization(StarlightSdk.Authorization authorization) {
        final StarlightSdk owner = sdk;
        if (owner == null || isFinishing() || isDestroyed()) return;
        owner.exchangeWithDemoBackend(authorization, new StarlightSdk.Callback() {
            @Override public void success(JSONObject result) {
                if (sdk == owner && !isFinishing() && !isDestroyed())
                    owner.completeGameLogin(authorization, result);
            }
            @Override public void failure(String code, String message) {
                if (sdk == owner && !isFinishing() && !isDestroyed()) onError(code, message);
            }
        });
    }
    @Override public void onSessionChanged(JSONObject session) {
        if (sdk != null && !isFinishing() && !isDestroyed()) sdk.openPlatformCenter(this);
    }
    @Override public void onLogout() {
        // 同时清理宿主旧角色、连接、聊天订阅与账号页面状态。
    }
    @Override public void onError(String code, String message) {
        if (!isFinishing() && !isDestroyed())
            Toast.makeText(this, message, Toast.LENGTH_LONG).show();
    }
    @Override protected void onDestroy() {
        if (sdk != null) sdk.destroy();
        sdk = null;
        super.onDestroy();
    }
}

本地演示账号为 13800138000 / Demo12345!。成功预期是 onAuthorization 后完成兑换、触发 onSessionChanged，isLoggedIn() 返回 true，平台中心可读取演示角色。不要根据“登录对话框关闭”判断授权成功。

接入自己的游戏

在 开发者控制台 创建 Android 客户端并等待开通；为自己的游戏使用自己的 App ID。游戏服务器保存一次性密钥，客户端仅持有 App ID 和 API origin。

StarlightSdk.Config config = new StarlightSdk.Config(
    "game_your_id-android", "https://accounts.example.com", false);

App ID 实际值必须符合 [A-Za-z0-9_-]{3,100}；将示例 game_your_id-android 替换为控制台实际值。demo=false 会拒绝明文 HTTP；此配置本身不代表平台已有真实支付/短信供应商。新建应用不能使用 exchangeWithDemoBackend，必须按 可信授权交换 对接游戏后端。

问题	处理
IllegalArgumentException	检查 App ID、HTTPS origin；地址不能有用户信息、业务路径、query 或 fragment
连接失败	模拟器不能把自身 127.0.0.1 当电脑；检查地址、服务与调试明文策略
APP_UNAVAILABLE	审核、扩端复审、应用/开发者停用状态
AUTH_CONTEXT_REQUIRED	改用 completeGameLogin(authorization, result)，禁止单参数完成
DEMO_DISABLED	非演示实例不可调用演示兑换；接自己的游戏服务器

继续阅读 生命周期、API 参考 与 设备验收。

自定义宿主接入

不使用原生登录页时可调用 authorize(JSONObject input)，并处理同样的原 Authorization 事务。启动恢复使用 exportSession()/restoreSession(saved, callback)，宿主必须自行加密保存，SDK 不默认写明文 Preferences。新增订单、权益、密码与客服方法见 API 参考，这些接口不改变真实支付未接通与真机未验收的边界。