XMDT —— Android

原生 SDK，不使用 WebView。用 Kotlin 编写，可从 Java 调用。与 SDK v2 相互独立——不要把 vn.alogame.kycsdk 和 vn.oeg.sdk.v2 的 import 混用，也不要指望它们共享任何状态。

环境

环境	Base URL
Dev	`https://api-xmdt.dev.alogame.vn`
Prod	`https://api-xmdt.alogame.vn`

两者都已上线。你的 gameId 必须先由 Alogame 运营方开通 XMDT，两个环境才能使用——参见服务器集成。

请先阅读这部分

服务器集成介绍了你服务器唯一需要发起的调用，用于生成 sessionToken。你的客户端从不直接调用 Alogame 的身份认证 API，也从不会看到你的 HMAC secret。

1. 添加依赖

settings.gradle.kts
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://jitpack.io") }
    }
}

app/build.gradle.kts
dependencies {
    implementation("com.github.alo-game:alogame-kyc-sdk-android:0.1.1")
}

坐标是 GitHub 仓库地址，不是 vn.alogame:kyc-sdk

请使用 com.github.alo-game:alogame-kyc-sdk-android:<version>——JitPack 只会按照第一次被请求时使用的坐标提供构建，而这个坐标始终是这种 GitHub org/repo 形式。自定义的 vn.alogame:kyc-sdk groupId 无法解析，即便它出现在发布仓库自己的 build.gradle 里；已通过直接 curl jitpack.io 确认（vn/alogame/kyc-sdk/ 下返回 404，com/github/alo-game/alogame-kyc-sdk-android/ 下返回 200）。

可用版本请见 jitpack.io/#alo-game/alogame-kyc-sdk-android。

已发布的构件零第三方运行时依赖——不会与你 App 现有的依赖树产生任何冲突。

2. 初始化

在 App 启动时执行一次：

Kotlin
import vn.alogame.kycsdk.AlogameKycSdk
import vn.alogame.kycsdk.AlogameKycConfig
import vn.alogame.kycsdk.AlogameKycEnv

AlogameKycSdk.init(
    context,
    AlogameKycConfig(env = AlogameKycEnv.DEV)
)

Java
import vn.alogame.kycsdk.AlogameKycSdk;
import vn.alogame.kycsdk.AlogameKycConfig;
import vn.alogame.kycsdk.AlogameKycEnv;

AlogameKycSdk.INSTANCE.init(
    context,
    new AlogameKycConfig(AlogameKycEnv.DEV, null)
);

OEG 品牌游戏

AlogameKycConfig 增加了一个可选的第三个参数 brand——AlogameKycBrand.ALO（默认）或 AlogameKycBrand.OEG。它只改变屏幕头部显示的 logo；env 仍然是选择网络端点的唯一开关。

Kotlin
AlogameKycConfig(env = AlogameKycEnv.DEV, brand = AlogameKycBrand.OEG)

3. 设置游戏角色

在你从服务器拿到 sessionToken 之后（参见服务器集成）：

Kotlin
AlogameKycSdk.setGameRole(
    uid = "player_account_name",   // 必须与你服务器 mint session 时使用的 `username` 一致
    sessionToken = sessionToken,
    serverId = "server_01",        // 可选——不适用时可省略
    roleId = "character_123"       // 可选
)

Java
AlogameKycSdk.INSTANCE.setGameRole("player_account_name", sessionToken, "server_01", "character_123");

uid 和 sessionToken 永远一起从同一个服务器响应中获得——绝不要只传其中一个而不传另一个。切换到不同的 uid 会清除上一个 uid 缓存的已验证状态。

4. 显示界面

Kotlin
import vn.alogame.kycsdk.AlogameKycListener
import vn.alogame.kycsdk.AlogameKycResult

AlogameKycSdk.show(activity, object : AlogameKycListener {
    override fun onResult(result: AlogameKycResult) {
        when (result) {
            is AlogameKycResult.Success -> {
                // 仅是界面信号——在解锁任何内容之前请先看下面的警告
            }
            is AlogameKycResult.Failed -> {
                println("XMDT failed: ${result.reason}${result.message?.let { " ($it)" } ?: ""}")
            }
            is AlogameKycResult.Cancelled -> {
                // 玩家关闭了表单——只有在 xmdtRequired 为 false 时才可能出现
            }
        }
    }
})

Java
AlogameKycSdk.INSTANCE.show(activity, new AlogameKycListener() {
    @Override
    public void onResult(AlogameKycResult result) {
        if (result instanceof AlogameKycResult.Success) {
            // 仅是界面信号——见下面的警告
        } else if (result instanceof AlogameKycResult.Failed) {
            AlogameKycFailReason reason = ((AlogameKycResult.Failed) result).getReason();
            String message = ((AlogameKycResult.Failed) result).getMessage();
        } else if (result instanceof AlogameKycResult.Cancelled) {
            // 玩家关闭了表单
        }
    }

    @Override
    public void onSessionTokenNeeded(String uid) { /* 见下方"刷新过期 token" */ }
});

onResult 是界面信号，不是证明

这里的 Success 仅表示玩家设备报告流程已完成——被修改过的客户端可以在从未真正验证的情况下产生这个回调。在放行任何依赖 XMDT 的内容之前，请从你的服务器再次调用 POST /xmdt/session，并信任该响应中的 xmdtCompleted 字段。参见服务器集成。

SDK 完全自己管理界面——姓名、出生日期、手机号输入、OTP 和同意书都在内部处理，玩家输入的任何内容都不会暴露给你的 App。onResult 在每次 show() 调用中只会触发一次，在主线程上，且是在界面已经关闭之后——可以立即安全地显示你自己的界面。

在一个流程已经打开时再次调用 show() 会被忽略（会记录日志，不会崩溃）。

处理 `Failed`

Kotlin
import vn.alogame.kycsdk.AlogameKycFailReason

when (result.reason) {
    AlogameKycFailReason.notInitialized,
    AlogameKycFailReason.noGameRole -> {
        // 你这边的集成错误——没有先调用 init()/setGameRole()。
        // 绝不要把这个展示给玩家；请修正调用顺序。
    }
    AlogameKycFailReason.sessionUnavailable,
    AlogameKycFailReason.sessionInvalid -> {
        // 未能获取可用的 session token。请重新 mint 一个，
        // 然后从头重试 show()。
    }
    AlogameKycFailReason.otpAttemptsExceeded,
    AlogameKycFailReason.otpUnavailable,
    AlogameKycFailReason.rateLimited -> {
        // 玩家（或其网络）触发了防滥用限制。显示一个通用的
        // "请稍后再试"——不要暴露具体触发了哪个限制。
    }
    AlogameKycFailReason.serviceUnavailable -> {
        // Alogame 的身份认证服务在玩家已经在界面内重试一次之后
        // 仍然不可用。让他们稍后再试一次 show()。
    }
    AlogameKycFailReason.unknownError -> {
        // 面向未来兼容性的兜底情况。绝不会崩溃。
    }
}

可恢复的问题（OTP 输错、校验错误、短暂的网络抖动）都在 SDK 自己的界面内部处理，从不会传到 onResult——上面每一个 Failed 原因都是流程无法继续的情况，而不是玩家只是手误打错的情况。

刷新过期 token

当 setGameRole 传入的 token 在流程中途过期时，有两种方式提供新的 sessionToken——选择其中一种：

基于闭包（如果你的 App 能跨 SDK 边界持有闭包）：

Kotlin
AlogameKycSdk.init(
    context,
    AlogameKycConfig(
        env = AlogameKycEnv.DEV,
        tokenProvider = AlogameKycTokenProvider { uid, callback ->
            // 为这个 uid 再次调用你服务器的 mint 接口，然后：
            callback.onToken(newSessionTokenOrNull)
        }
    )
)

基于回调（适用于无法跨语言边界传递闭包的 bridge/引擎层——不设置 tokenProvider，改为实现下面的方法）：

Kotlin
override fun onSessionTokenNeeded(uid: String) {
    // 为 `uid` 生成一个新 token，然后：
    AlogameKycSdk.provideSessionToken(newToken)
    // 或者，如果无法获取：
    AlogameKycSdk.abortPendingToken()
}

如果你两种方式都没有实现，过期的 token 会以 sessionUnavailable 结束流程，而不会一直挂起。

屏幕方向

界面同时支持竖屏和横屏——你这边不需要做任何配置。

参考

类型	用途
`AlogameKycSdk`	完整的公开 API —— `init`、`setGameRole`、`setPrefill`、`isVerified`、`show`、`provideSessionToken`、`abortPendingToken`
`AlogameKycConfig(env, tokenProvider, brand)`	传给 `init` 一次——`brand` 可选，默认 `AlogameKycBrand.ALO`
`AlogameKycEnv`	`DEV` \| `PROD`
`AlogameKycBrand`	`ALO` \| `OEG`——仅影响外观，不影响 `env`/端点选择
`AlogameKycResult`	`Success` \| `Failed(reason, message)` \| `Cancelled`
`AlogameKycFailReason`	9 个固定取值——见上文
`AlogameKycListener`	`onResult(result)`，可选的 `onSessionTokenNeeded(uid)`

AlogameKycSdk.setPrefill(fullName) 是可选的——如果你的登录环节已经拿到了玩家姓名（例如来自某个社交登录），可以在调用 show() 之前传进来，预填表单字段。它只保存在内存中，在玩家看到并能够编辑之前绝不会被发送到任何地方。

AlogameKycSdk.isVerified() 读取的是最近一次成功流程留下的内存缓存——不是授权依据，与上面 onResult 的提醒相同。只能用于界面状态（例如隐藏一个"立即验证"按钮），绝不能作为真正的门禁判断。

1. 添加依赖​

2. 初始化​

3. 设置游戏角色​

4. 显示界面​

处理 Failed​

刷新过期 token​

屏幕方向​

参考​