# Android SDK 集成

> 来源：https://help.gravity-engine.com/docs/gravity-dock/integration/android-sdk
> 在 Android Application 中引入并初始化 GravityDock SDK，配置 GravityDock.config，接通隐私同意、生命周期与浮标流程。
> 文档修改日期：2026-11-06




## 1. 获取 SDK [#1-获取-sdk]

您可以通过以下两种方式将 GravityDock SDK 引入 Android 工程。

### 1.1 Maven 引入（推荐） [#11-maven-引入推荐]

* 在 `Project` 级别的 `build.gradle` 文件中添加如下仓库配置：

```groovy
maven {
    url "https://nexus.gravity-engine.com/repository/maven-releases/"
}
maven {
    url "https://nexus.gravity-engine.com/repository/maven-snapshots/"
}
```

* 在 `Module`（app）工程目录下的 `build.gradle` 文件中添加依赖项：

```groovy
implementation "cn.gravity.dock:GravityDockSDK:1.0.0"
```

> **注意**
> 请使用与 SDK 交付包配套的最新版本号，以获得及时的更新支持。版本信息可咨询引力运营支持团队获取。

### 1.2 AAR 手动引入 [#12-aar-手动引入]

* 在 [GravityDock-Android-Demo Releases](https://github.com/GravityInfinite/GravityDock-Android-Demo/releases) 页面下载最新版本的 SDK aar 包。
* 将 `GravityDockSDK.aar` 复制到项目的 `libs` 文件夹中。
* 在 `Module`（app）工程目录下的 `build.gradle` 文件中添加如下配置引入依赖：

```groovy
dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar'])
}
```

## 2. 配置 GravityDock.config [#2-配置-gravitydockconfig]

在 `app/src/main/assets/` 目录下创建 `GravityDock.config` 文件，SDK 启动时读取该配置确定游戏身份与渠道组件：
测试调试阶段，使用类似下卖的developer渠道配置，其他渠道在打包时会自动替换这个配置文件

```json
{
    "GravityDockConfig": {
        "token": "引力后台游戏token",
        "channel_pk": "引力后台对应游戏developer渠道的id",
        "channel_template_id": "developer"
    },
    "sdks": [
        {
            "sdkId": "developer",
            "className": "com.gravitydock.develop.GravityDockSDKDevelopAdapter",
            "config": {}
        }
    ]
}
```

参数说明：

| 参数          | 说明                                      |
| ----------- | --------------------------------------- |
| token       | 游戏 Token，在管理台游戏详情中获取。                   |
| channel\_pk | 渠道实例 ID，标识当前包归属的渠道实例。 接入开发期间填写对应开发渠道的ID |

> **注意**
> `token`、`channel_pk` 为示例值，请替换为您实际交付环境的参数。配置错误会导致 SDK 初始化或运行时配置请求失败。

## 3. 初始化 SDK [#3-初始化-sdk]

在游戏的 `Application.onCreate()` 中初始化 SDK。若使用自定义 Application，在合并后的 Manifest 核对 `android:name`。

```java
import android.app.Application;
import android.util.Log;
import com.gravitydock.sdk.GravityDockSDK;
import com.gravitydock.sdk.GravityDockSDKListener;

public class GameApplication extends Application {

    private static final String TAG = "GravityDockDemo";

    @Override
    public void onCreate() {
        super.onCreate();
        // 开发联调阶段打开 SDK 日志，便于观察各模块调用与事件分发；正式版本可关闭
        GravityDockSDK.setLogEnabled(true);
        GravityDockSDK.initSDK(this, new GravityDockSDKListener() {
            @Override
            public void onInitSuccess() {
                Log.i(TAG, "SDK 初始化成功");
            }

            @Override
            public void onInitFail(String error) {
                Log.e(TAG, "SDK 初始化失败: " + error);
            }

            @Override
            public void onAppExit() {
                // 渠道触发退出时回调，在这里接入游戏自己的退出流程。
            }
        });
    }
}
```

## 4. 隐私协议 [#4-隐私协议]

用户完成游戏内隐私授权后，在 Activity 上调用 `GravityDockSDK.onUserAgree(activity)`，SDK 才会启动涉及设备标识的采集与渠道组件。

```java
//单次冷起动必须且只能调用一次
GravityDockSDK.onUserAgree(activity);
```

## 5. 游戏生命周期与浮标 [#5-游戏生命周期与浮标]

按目标渠道的审核要求接入以下接口，并在最终渠道包上验证。不支持的渠道会自动忽略对应调用：

| 方法                                         | 说明                               |
| ------------------------------------------ | -------------------------------- |
| `GravityDockSDK.appStart(activity)`        | 游戏页启动时调用，部分渠道需要上报启动行为。           |
| `GravityDockSDK.gameBegin(activity)`       | 进入对局/关卡等游戏开始节点时调用。               |
| `GravityDockSDK.gameEnd(activity)`         | 游戏结束节点时调用。                       |
| `GravityDockSDK.showFloatWindow(activity)` | 展示渠道悬浮窗（如防沉迷、用户中心入口）。            |
| `GravityDockSDK.hideFloatWindow(activity)` | 隐藏渠道悬浮窗，如进入全屏播放、过场动画时。           |
| `GravityDockSDK.exitApp(activity)`         | 请求渠道退出流程，渠道确认后触发 `onAppExit` 回调。 |

```java
// 典型接入示例
GravityDockSDK.appStart(mainActivity);      // 主界面启动
GravityDockSDK.showFloatWindow(mainActivity); // 进入主界面后展示浮标
GravityDockSDK.gameBegin(mainActivity);     // 开始对局
// ... 游戏进行中 ...
GravityDockSDK.gameEnd(mainActivity);       // 结束对局
GravityDockSDK.exitApp(mainActivity);       // 玩家点击退出按钮
// 渠道确认退出后，Application 中注册的 onAppExit 回调被触发
```

正式版本可调用 `setLogEnabled(false)` 关闭 SDK 日志。

## 6. 验证母包与渠道包 [#6-验证母包与渠道包]

构建 Android 母包，在[批量打包](/docs/gravity-dock/product-manual/apk-builds)生成目标渠道 APK。安装产物并检查 SDK 初始化、首次隐私同意和渠道登录。若初始化或配置请求失败，核对渠道包对应的游戏、渠道实例、渠道组件和 `server_url`，同时检查设备能否访问该环境的数据面。