游戏位-安卓SDK接入文档

更新时间：2026-05-09

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

附件下载：

MiniGame-GameSolt.android-sdk-1.0.1.zip：包含 AAR 和 Demo APK。

1. 接入要求

1.1 依赖引入

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

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

    // SDK dependencies required by the host app.
    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")
    implementation("androidx.appcompat:appcompat:1.6.1")
    implementation("com.google.android.material:material:1.9.0")
}

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。

参数	类型	说明
`context`	`Context`	`Application Context`
`clientId`	`String`	客户端 ID，由运营分配
`secretKey`	`String`	密钥，由运营分配
`appId`	`String`	应用包名
`uid`	`String`	用户唯一标识
`appVersion`	`String`	应用版本号

2.2 初始化与组件接入示例

建议在首个承载游戏位的 Activity 或应用初始化流程中完成 SDK 初始化。环境可设置为 DEV 或 PROD；不设置时默认使用 PROD。

import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import com.unite.sdk.GameSlotSdk
import com.unite.sdk.slot.SlotListener
import com.unite.sdk.slot.GameSlot
import com.unite.sdk.view.BigCardView
import com.unite.sdk.view.BigVideoView
import com.unite.sdk.view.ThreeCardsView

class MainActivity : AppCompatActivity(), SlotListener {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        // Initialize the SDK.
        GameSlotSdk.setEnvironment(GameSlotSdk.Environment.PROD)
        GameSlotSdk.init(
            applicationContext,
            "YOUR_CLIENT_ID",
            "YOUR_SECRET_KEY",
            "YOUR_APP_ID",
            "USER_ID",
            "1.0.0"
        )

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

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

        // Load ThreeCardsView.
        val threeCardsView = findViewById<ThreeCardsView>(R.id.threeCardsView)
        threeCardsView.setSlotListener(this)
        threeCardsView.loadSlot(
            "YOUR_SLOT_ID",
            3,
            ThreeCardsView.CardStyle.NORMAL_VERTICAL188
        )
    }

    override fun onSlotLoaded(gs: GameSlot, slotId: String) {}

    override fun onSlotFailed(message: String, slotId: String) {}

    override fun onSlotShow(gs: GameSlot, slotId: String) {}

    override fun onSlotClick(gs: GameSlot, slotId: String) {}

    override fun onGameStart(gs: GameSlot) {}

    override fun onGameClose(gs: GameSlot) {}
}

3. 游戏位接入

3.1 BigCardView（大卡片）

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

测试 slot_id：

组件	测试 `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("SLOT_ID")

3.2 BigVideoView（视频）

BigVideoView 适用于带视频展示能力的游戏位。宿主项目需要确保已引入 androidx.media3 相关依赖。

测试 slot_id：

组件	测试 `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 适用于一次展示多个游戏卡片的场景。接入时可以指定展示数量和卡片样式。

测试 slot_id：

组件	测试 `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",
    3,
    ThreeCardsView.CardStyle.NORMAL_VERTICAL188
)

4. 回调说明

宿主应用可通过 SlotListener 监听游戏位加载、展示、点击和游戏打开关闭事件：

回调	触发时机
`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 调用。
测试环境和正式环境的 clientId、secretKey、slot_id 需要隔离配置。
组件已处理基础曝光和点击链路时，宿主应用不要对同一组件重复上报。
视频组件依赖 Media3，若宿主项目已有不同版本，需要关注依赖冲突。
正式上线前应验证无网、弱网、接口失败、游戏打开失败和页面销毁等异常路径。

大纲