Cocos Game Android SDK

下载

compileSdk 35minSdk 26targetSdk 34JDK 17arm64-v8a

v0.1.5 问题修复：本人座位身份以后台座位数据为准；修复已入座仍提示「立即加入」、下注提示观战下注，以及入座成功后界面仍显示失败的问题。公共 API 无变更，宿主只需升级依赖版本，imUserId 仍需传正确值。

v0.1.4 兼容更新：「我的记录」接入后台注单查询，支持当前本桌 / 历史场次、筛选、周期切换与滑到底部自动分页；修复小屏下顶部手牌遮挡昵称。公共 API 无变更，宿主只需升级依赖版本。

v0.1.3 不兼容变更：GameSessionConfig 在 liveUserId 后新增必填参数 imUserId（登录响应 userinfo.imUserId），用于识别本人座位；每局结算后自动刷新余额。宿主升级后需补传该参数。

接入前准备

• 宿主客户端完成用户登录并获得 liveUserId、imUserId、liveToken。
• 宿主动态传入 sceneType：1 直播间，2 IM 群。
• 宿主动态传入 sceneId，SDK 不内置固定场景。
• 正式环境必须使用 HTTPS/WSS。

5 分钟快速接入

1. 在 settings.gradle.kts 添加 GitHub Maven 仓库。
2. 在 App 模块添加 game-sdk:0.1.5。
3. 在主进程 Application 初始化 SDK。
4. 客户端登录后创建 GameSessionConfig。
5. 调用 openGame(activity, "niuniu", session)。

maven {
    url = uri("https://raw.githubusercontent.com/eathwinster-jk/cocos-game-android-sdk/main/repository")
}

implementation("com.eath.cocosgamesdk:game-sdk:0.1.5")

CocosGameSDK.getInstance().initialize(applicationContext)

val session = GameSessionConfig(
    websocketUrl, apiBaseUrl, liveUserId, imUserId, liveToken,
    sceneType, sceneId, 0, BuildConfig.VERSION_NAME, "Android"
)
CocosGameSDK.getInstance().openGame(activity, "niuniu", session)

SDK 不提供生产登录。UID、Token、Scene Type、Scene ID 必须由宿主客户端传入。

模式一：本地 AAR 接入

1. 复制文件

app/libs/game-sdk-0.1.5.aar

2. Gradle Groovy

android {
    compileSdkVersion 35
    defaultConfig {
        minSdkVersion 26
        targetSdkVersion 34
        ndk { abiFilters "arm64-v8a" }
    }
    packagingOptions { jniLibs { useLegacyPackaging true } }
}
dependencies {
    implementation files("libs/game-sdk-0.1.5.aar")
}

3. Kotlin DSL

android {
    compileSdk = 35
    defaultConfig {
        minSdk = 26
        targetSdk = 34
        ndk { abiFilters += "arm64-v8a" }
    }
    packaging { jniLibs { useLegacyPackaging = true } }
}
dependencies {
    implementation(files("libs/game-sdk-0.1.5.aar"))
}

模式二：Gradle 远程接入（推荐）

1. Kotlin DSL：settings.gradle.kts

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://raw.githubusercontent.com/eathwinster-jk/cocos-game-android-sdk/main/repository")
        }
    }
}

2. Kotlin DSL：app/build.gradle.kts

dependencies {
    implementation("com.eath.cocosgamesdk:game-sdk:0.1.5")
}

3. Groovy：settings.gradle

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://raw.githubusercontent.com/eathwinster-jk/cocos-game-android-sdk/main/repository")
        }
    }
}

4. Groovy：app/build.gradle

dependencies {
    implementation "com.eath.cocosgamesdk:game-sdk:0.1.5"
}

请固定版本号，不使用 + 或 latest 动态依赖。升级前应完成回归测试。

权限与混淆

AAR 已合并 INTERNET、ACCESS_NETWORK_STATE、VIBRATE 权限和游戏 Activity。

-keep class com.eath.cocosgamesdk.** { *; }
-keep class com.cocos.lib.** { *; }
-dontwarn com.cocos.lib.**

初始化 SDK

在主进程 Application 中只初始化一次，且早于其他 SDK 调用。

Java

public final class App extends Application {
    @Override public void onCreate() {
        super.onCreate();
        CocosGameSDK.getInstance().initialize(this);
    }
}

Kotlin

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        CocosGameSDK.getInstance().initialize(this)
    }
}

创建会话并打开游戏

Java

GameSessionConfig session = new GameSessionConfig(
    websocketUrl,
    apiBaseUrl,
    liveUserId,
    imUserId,
    liveToken,
    sceneType,
    sceneId,
    0,
    BuildConfig.VERSION_NAME,
    "Android"
);
CocosGameSDK.getInstance().openGame(this, "niuniu", session);

Kotlin

val session = GameSessionConfig(
    websocketUrl,
    apiBaseUrl,
    liveUserId,
    imUserId,
    liveToken,
    sceneType,
    sceneId,
    0,
    BuildConfig.VERSION_NAME,
    "Android",
)
CocosGameSDK.getInstance().openGame(this, "niuniu", session)

UID、Token、Scene Type、Scene ID 必须由宿主客户端传入，不能固定写在 SDK 中。

会话失效与公共事件

会话失效

if (requestCode == CocosGameSDK.GAME_REQUEST_CODE
        && resultCode == Activity.RESULT_CANCELED
        && data != null
        && data.hasExtra(CocosGameActivity.EXTRA_SESSION_ERROR)) {
    clearLoginSession();
    openLoginPage();
}

Java 公共事件

CocosGameSDK.getInstance().setHostListener(
    (gameId, event, payloadJson) -> {
        if ("wallet.open".equals(event)) openWalletPage();
    }
);
CocosGameSDK.getInstance().sendGameEvent(
    "wallet.closed",
    "{\"isBalanceChanged\":true}"
);

Kotlin 公共事件

CocosGameSDK.getInstance().setHostListener { gameId, event, payloadJson ->
    if (event == "wallet.open") openWalletPage()
}
CocosGameSDK.getInstance().sendGameEvent(
    "wallet.closed",
    """{"isBalanceChanged":true}""",
)

公共 API

GameSessionConfig 参数

客户端与 SDK 职责

Demo 登录模式

账号密码

Demo 调用测试登录接口，将服务端返回的 UID、Token 注入 GameSessionConfig。账号密码不写入 SDK，也不持久化。

UID Token

直接输入已有 UID、Token。两种模式都需要客户端输入或确认 Scene Type、Scene ID。

账号密码登录仅用于 Demo。正式客户端必须复用自身登录体系。

热更新接入

当前 AAR 内置首装游戏模块。启用远程模块更新时，客户端传入 SDK 发布方提供的目录地址、宿主版本、SDK API 版本、公钥和缓存上限。

GameSDKConfig updateConfig = new GameSDKConfig(
    catalogUrl,
    BuildConfig.VERSION_NAME,
    sdkApiVersion,
    ed25519PublicKey,
    200L * 1024L * 1024L
);
CocosGameSDK.getInstance().initialize(applicationContext, updateConfig);
CocosGameSDK.getInstance().setUpdateListener(updateListener);

不启用远程更新时只调用 initialize(context)。

生命周期、旋转与弹窗

• 进入后台时 SDK 暂停音频和实时连接；回前台重新同步权威桌态。
• 旋转按钮只向客户端发请求，是否旋转由客户端决定。
• 客户端完成布局后回传实际游戏容器宽高，游戏只负责界面适配。
• SDK 内置退出确认和下注卡；钱包、充值等业务页面通过公共事件接入。
• 规则弹窗关闭、大屏切小屏后应继续验证全部按钮可点击。

我的记录接入

「我的记录」由 SDK 内置实现，客户端无需调用任何新 API、无需注册回调，升级到 v0.1.4 及以上即可使用。用户在游戏内点击「规则」按钮，切换到「我的记录」页签即可查看本人注单，页面以原生弹窗展示。

工作方式

• SDK 使用 GameSessionConfig 中的 apiBaseUrl、liveUserId、liveToken 直接请求后台，请求头与入座、下注接口相同（live-user-id、live-user-token）。
• 当前本桌：POST /api/lobby/bet/table/mine，按当前桌号查询，游标分页。
• 历史场次：POST /api/lobby/bet/history，按下注日期区间查询，页码分页。
• 每页 20 条，列表滑到底部自动加载下一页；加载失败显示点击重试，无数据显示空状态。
• 顶部场景标签取自 sceneType、sceneId 和实际进入的桌号。

页面功能

客户端需确认

• apiBaseUrl 指向的大厅网关已开放上述两个接口，且与入座、下注使用同一环境。
• liveToken 在游戏期间保持有效；Token 失效时记录页显示加载失败，点击可重试。
• 记录只展示当前登录用户本人的注单，不涉及其他用户数据。

运行测试 Demo

源码：cocos-game-android-demo

1. 下载上方 Demo APK，安装到 API 26 以上的 ARM64 设备；或克隆源码构建。
2. 输入 Scene Type：1 直播间，2 IM 群。
3. 输入当前 Scene ID。
4. 选择账号密码登录，或输入 Live User ID、IM User ID、Live Token。
5. 点击对应按钮打开游戏。

adb install -r game-sdk-demo-0.1.5.apk

常见问题

Gradle 无法下载

确认可访问 raw.githubusercontent.com，然后执行 ./gradlew --refresh-dependencies。

x86 模拟器不能运行

当前 SDK 仅包含 arm64-v8a，请使用 ARM 模拟器或 ARM64 真机。

提示 sessionConfig 不能为空

SDK 不允许无会话启动。客户端必须先传入 UID、Token、Scene Type、Scene ID。

会话认证失败

确认 UID 与 Token 匹配、未过期，HTTP 与 WebSocket 属于同一环境。

我的记录加载失败或为空

确认大厅网关已开放 /api/lobby/bet/table/mine 与 /api/lobby/bet/history，Token 未过期；当前本桌需先成功进入桌台，历史场次可切换为最近 30 天查看。

找不到桌台

确认 Scene Type、Scene ID 以及后台开桌场景完全一致。

AAR 冲突或找不到 native 库

确认仅保留一个 SDK 版本、启用 arm64-v8a，并检查 APK 中存在 lib/arm64-v8a/libcocos.so。

上线验收清单

• SDK 仅在主进程初始化一次。
• UID、Token、Scene Type、Scene ID 均来自客户端。
• API 26、API 34 和主流设备构建运行通过。
• 账号密码与 UID Token Demo 均能进入游戏。
• 入座、离座、下注和结算正常。
• 结算金额与后端 seatSettlements.netCent 一致。
• 规则弹窗关闭后按钮仍可点击。
• 「我的记录」当前本桌、历史场次均能加载，筛选、周期切换与滑到底部分页正常。
• 大屏、小屏往返后全部按钮仍可点击。
• 进入后台再返回能够恢复桌态。
• Token 失效后能返回客户端登录流程。
• Release 混淆后反射桥正常。
• 未记录 Token、密码或完整敏感响应。