游戏位-安卓SDK接入文档

更新时间：2026-07-25 ｜ SDK 版本：v1.1.0

本文档面向安卓应用接入方，说明 MiniGame 游戏位安卓 SDK 的获取方式、依赖配置、初始化方式、组件接入和测试参数。

0. SDK 获取（开源）

SDK 已开源，源码托管于 GitHub：

开源地址：https://github.com/TeleMiniGame/OpenAPI-AndroidSDK

获取并构建 AAR：

git clone https://github.com/TeleMiniGame/OpenAPI-AndroidSDK.git
cd OpenAPI-AndroidSDK
./gradlew :unite_sdk_lib:assembleRelease
# 产物：unite_sdk_lib/build/outputs/aar/unite-sdk-1.1.0.aar

仓库中的 demo 模块是完整的接入示例工程，包含本文所有组件的用法，可直接参照。
也可以不打 AAR、直接以源码模块方式引入 unite_sdk_lib。

1. 接入要求

minSdk 21（Android 5.0）及以上；
接入凭证（clientId / secretKey）与游戏位 ID（slot_id）由运营分配。

1.1 依赖引入

将构建出的 AAR 放入宿主项目的 libs 目录，并在应用模块中引入以下依赖：

dependencies {
    implementation(files("libs/unite-sdk-1.1.0.aar"))

    // SDK 运行所需依赖（AAR 不传递依赖，需宿主声明）
    implementation("androidx.core:core-ktx:1.17.0")
    implementation("androidx.appcompat:appcompat:1.7.1")
    implementation("com.google.android.material:material:1.13.0")
    implementation("com.squareup.okhttp3:okhttp:4.12.0")
    implementation("com.google.code.gson:gson:2.10.1")
    implementation("androidx.browser:browser:1.8.0")
    implementation("io.coil-kt:coil:2.6.0")
    implementation("io.coil-kt:coil-svg:2.6.0")
    implementation("androidx.media3:media3-exoplayer:1.4.1")
    implementation("androidx.media3:media3-ui:1.4.1")
}

版本以仓库 unite_sdk_lib/build.gradle.kts 与 gradle/libs.versions.toml 为准；
宿主已有同库不同版本时，注意依赖冲突（尤其 Media3）。

1.2 权限配置

在宿主应用的 AndroidManifest.xml 中声明网络权限：

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

2. 初始化

2.1 初始化参数

生产初始化参数通过商户平台或联系 MiniGame 对接人获得。测试环境可使用以下参数联调：

参数	测试值
`client_id`	`233802991579168768`
`api_key`	`5e567421-c0a5-4723-80a6-2f5567517146`

api_key 对应初始化方法中的参数 secretKey；client_id 对应参数 clientId。

参数	类型	说明
`context`	`Context`	`Application Context`
`clientId`	`String`	客户端 ID，由运营分配
`secretKey`	`String`	密钥，由运营分配
`uid`	`String`	宿主 App 内的用户唯一标识
`appId`	`String`	宿主 App 包名（可不填，自动取包名）
`appVersion`	`String`	宿主 App 版本号（可不填，自动取 versionName）
`environment`	`Environment`	`DEV` `PROD` `AUTO`（可不填，默认 AUTO；对接调试期间请显式传 `DEV`）

2.2 初始化

一次调用完成配置，建议放在 Application 或首个承载游戏位的 Activity 中：

import com.unite.sdk.GameSlotSdk

GameSlotSdk.init(
    applicationContext,
    GameSlotSdk.GameSlotConfig(
        clientId = "YOUR_CLIENT_ID",
        secretKey = "YOUR_SECRET_KEY",
        uid = "USER_ID",
        environment = GameSlotSdk.Environment.DEV   // 联调用 DEV；上线改 PROD 或不传
    )
)

2.3 语言与地区（可选）

GameSlotSdk.setLanguage("en")   // 游戏内容语言；不调用则跟随系统语言
GameSlotSdk.setCountry("US")    // ISO 3166 两位码；不调用则按网络/SIM/系统地区自动判定

游戏卡片的标题、描述等内容语言由服务端按请求语言返回，宿主 App 内切换多语言后调用 setLanguage 即可生效（下次加载起）。

3. 游戏位接入

3.0 零代码接入（推荐）

所有游戏位组件都支持在布局 XML 中直接配置 app:slotId，组件展示时自动加载，无需任何代码：

<com.unite.sdk.view.BigCardView
    android:id="@+id/bigCardView"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    app:slotId="YOUR_SLOT_ID" />

前提：SDK 已初始化（见 §2.2）。回调监听（§4）按需另行设置。
也可以不写 app:slotId，用代码 loadSlot(...) 主动加载，两种方式二选一。

3.1 BigCardView（大卡片）

BigCardView 适用于单个大卡片游戏位展示。组件会处理点击行为，并在用户点击卡片或按钮时触发点击上报并打开游戏。

组件	测试 `slot_id`
`BigCardView`	`TSZ3R9W6P2K8`

XML 布局：

<com.unite.sdk.view.BigCardView
    android:id="@+id/bigCardView"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content" />

代码接入：

val bigCardView = findViewById<BigCardView>(R.id.bigCardView)
bigCardView.setSlotListener(listener)
bigCardView.loadSlot("YOUR_SLOT_ID")

3.2 BigVideoView（视频）

BigVideoView 适用于带视频展示能力的游戏位：满足可见与网络条件时自动播放视频预览（静音循环），弱网 / 非 WiFi 环境自动降级为封面图。宿主项目需确保已引入 androidx.media3 相关依赖。

组件	测试 `slot_id`
`BigVideoView`	`TSB4F2H8Y3Q7`

XML 布局：

<com.unite.sdk.view.BigVideoView
    android:id="@+id/bigVideoView"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content" />

代码接入：

val bigVideoView = findViewById<BigVideoView>(R.id.bigVideoView)
bigVideoView.setSlotListener(listener)
bigVideoView.loadSlot("YOUR_SLOT_ID")

3.3 ThreeCardsView（三联卡片）

ThreeCardsView 一次展示三张游戏竖卡（106×188 规范卡型，底部标题蒙版 + PLAY 按钮 + 右下角 M 标），内容多于三条时自动轮播。卡片样式为固定规范卡型，无需也不支持配置。

组件	测试 `slot_id`
`ThreeCardsView`	`TSK9P4X1Q6B2`

XML 布局：

<com.unite.sdk.view.ThreeCardsView
    android:id="@+id/threeCardsView"
    android:layout_width="match_parent"
    android:layout_height="wrap_content" />

代码接入：

val threeCardsView = findViewById<ThreeCardsView>(R.id.threeCardsView)
threeCardsView.setSlotListener(listener)
threeCardsView.loadSlot("YOUR_SLOT_ID")        // 或 loadSlot("YOUR_SLOT_ID", 3)

3.4 GameCenterView（游戏中心入口）

GameCenterView 用于在宿主 App 中放置一个「游戏大厅」入口：加载大厅游戏位后，点击即在内置 WebView 中打开游戏中心页面，曝光 / 点击自动按该游戏位上报。大厅页地址由接口动态下发，宿主不要硬编码任何域名。

组件	测试 `slot_id`
`GameCenterView`	`GCTESTHALL01`

<com.unite.sdk.view.GameCenterView
    android:id="@+id/gameCenterView"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    app:slotId="YOUR_HALL_SLOT_ID" />

val gameCenterView = findViewById<GameCenterView>(R.id.gameCenterView)
gameCenterView.setSlotListener(listener)
gameCenterView.loadSlot("YOUR_HALL_SLOT_ID")
// 入口自身的展示素材（图片 / 标题）由宿主提供：
gameCenterView.setConfig(url = "", imageUrl = "https://...", title = "游戏中心")

大厅位 slot_id 与普通游戏位不同，需单独向运营申请。

4. 回调说明

宿主应用可通过 SlotListener 监听游戏位加载、展示、点击和游戏打开关闭事件。
所有方法均有默认空实现，只需覆写关心的回调：

view.setSlotListener(object : SlotListener {
    override fun onSlotClick(gs: GameSlot, slotId: String) { /* 只关心点击时这样写即可 */ }
})

回调	触发时机
`onSlotLoaded(gs: GameSlot, slotId: String)`	游戏位加载成功
`onSlotFailed(message: String, slotId: String)`	游戏位加载失败
`onSlotShow(gs: GameSlot, slotId: String)`	游戏位展示
`onSlotClick(gs: GameSlot, slotId: String)`	用户点击游戏位
`onGameStart(gs: GameSlot)`	游戏开始打开
`onGameClose(gs: GameSlot)`	游戏关闭

5. 接入注意事项

SDK 初始化应早于组件 loadSlot 调用（XML app:slotId 自动加载同样要求初始化在先）。
测试环境和正式环境的 clientId、secretKey、slot_id 需要隔离配置；本文测试参数仅可用于 DEV 环境联调。
曝光与点击上报由组件内部完成（可见 ≥50% 且 ≥800ms 计一次曝光，含去重与批量延迟上报），宿主应用不要对同一组件重复上报。
游戏卡片右下角的 M 标为合规标识，由 SDK 与服务端自动协同展示，宿主不得遮挡、裁剪或自行叠加。
视频组件依赖 Media3，若宿主项目已有不同版本，需要关注依赖冲突。
正式上线前应验证无网、弱网、接口失败、游戏打开失败和页面销毁等异常路径。

6. 更新日志

版本	日期	更新内容
v1.1.0	2026-07-25	首个对外开放接入版本。① SDK 开源，从 GitHub 获取源码构建 AAR；② 游戏位组件：`BigCardView` 大卡片、`BigVideoView` 视频卡、`ThreeCardsView` 三联卡、`GameCenterView` 游戏中心大厅位（，大厅位对应 API 文档 v4.5.0 的 `gameCenter` 游戏位）；③ 支持 `GameSlotConfig` 一次性初始化与布局 XML `app:slotId` 零代码接入；④ 支持 `setLanguage` `setCountry` 语言与地区设置；⑤ 曝光点击 / 视频播放时长自动上报，M 标合规标识自动展示（对应 API v4.5.0 的 `m_icon_mode`），均无需接入方处理。

大纲