Skip to content

Android 端快速接入 ​

按本指南依次完成 SUDGI SDK 和广告能力接入、SDK 初始化及用户鉴权后,即可通过 gameId 启动游戏。


一、引入 SDK 与工程配置 ​

1. 通过 Gradle 引入 ​

在项目根目录的 build.gradle 中配置 Maven 仓库,并在应用层级 build.gradle 中添加依赖:

gradle
def sdk_version = '3.0.0'

dependencies {
    implementation "global.sud.gi:SUDGI:${sdk_version}"

    // 可选:为游戏运行时提供 MP3 编码能力
    // implementation "global.sud.gi:SUDGI-shine:${sdk_version}"

    // 按实际业务选择至少一个广告源
    implementation "global.sud.gi:SUDM-adapter-admob:${sdk_version}"
    implementation "global.sud.gi:SUDM-adapter-carty:${sdk_version}"
    implementation "global.sud.gi:SUDM-adapter-topon:${sdk_version}"
    implementation "global.sud.gi:SUDM-adapter-max:${sdk_version}"
    implementation "global.sud.gi:SUDM-adapter-taku:${sdk_version}"

}

SUDGI、公共组件、SUDM Core 及其 Adapter 通过 sdk_version 统一指定版本。升级时修改 sdk_version 并同步更新整套 SDK。

SUDGI-shine 是可选的运行时扩展,用于将音频编码为 MP3,SUDGI 不会自动引入。游戏需要 MP3 编码能力时,取消上方依赖的注释,并与其他 SUD 组件使用相同的 sdk_version;不需要该能力时无需添加。

SUDGI 会自动引入公共组件。仅保留实际接入的广告源,所选 Adapter 会自动引入广告核心。AdMob、Carty、TopOn 和 MAX 的平台 SDK 会自动引入。

使用 Taku 时,在工程现有 Maven 仓库配置中添加 maven { url 'https://jfrog.takuad.com/artifactory/china_sdk' }。

依赖引入完成后,继续下方“广告能力接入”和“SDK 初始化”,完成 App ID、适用的用户同意流程及隐私参数配置。

2. 三方版本要求 ​

以下配套版本作为本接入方案的版本基线,不要降级使用。升级前请查询官网最新版本及兼容要求,并确认与所用 SUD 组件匹配。

三方模块接入基线版本查询
AdMob:com.google.android.gms:play-services-ads固定为 25.4.0Google 版本说明
Carty:io.carty.bidad:carty-sdk固定为 1.11.0Carty 更新日志
TopOn: com.anythink.sdk:core-tpn固定为 6.6.22.3TopOn Android 接入说明
MAX:com.applovin:applovin-sdk固定为 13.5.1MAX Android 接入说明
Taku:com.anythink.sdk:core-taku固定为 6.6.40Taku Android 接入说明

二、广告能力接入 ​

完成依赖引入后,按所选广告源配置宿主应用,并在 SDK 初始化前处理适用的用户同意流程。

宿主配置 ​

AdMob App ID ​

适用条件:使用 AdMob。修改位置:宿主 AndroidManifest.xml 的 <application> 内。

xml
<meta-data
    android:name="com.google.android.gms.ads.APPLICATION_ID"
    android:value="ca-app-pub-XXXXXXXXXXXXXXXX~YYYYYYYYYY" />

替换为 AdMob 控制台对应 Android 应用的 App ID(格式中包含 ~),不要使用广告单元 ID(格式中包含 /)。

AdMob Adapter 已声明网络权限;若宿主有自定义合并规则,请检查最终 Merged Manifest 是否保留所需权限和 App ID。缺少 App ID 会导致初始化失败,参见 AdMob Android 接入说明。

Advertising ID ​

适用条件:面向 Android 13(API 33)及以上且使用 GAID。检查最终 Merged Manifest 是否包含以下权限;仅在缺少时添加到宿主 AndroidManifest.xml 的 <manifest> 内。

xml
<uses-permission android:name="com.google.android.gms.permission.AD_ID" />

Google Mobile Ads SDK 20.4.0 及以上已声明此权限,正常合并后无需重复添加,也无需运行时申请。

接入广告无需游戏 JS 手动采集或传入 GAID。限制追踪、标识被删除或服务不可用时,不应把空值或全零 ID 当作有效标识。 参见 Android 13 广告 ID 变更。

用户同意与授权 ​

用户同意 ​

SDK 接收宿主确认的状态,不判断法规是否适用,也不展示同意弹窗。权限声明和隐私参数不能替代用户同意流程。

适用条件:需要为广告收集用户同意。接入位置:SDK 初始化之前。

复用宿主 CMP 或隐私流程;使用 Google UMP Android 时:

  1. 每次启动更新同意信息,展示所需表单。
  2. 按要求提供隐私选项入口,供用户修改选择。
  3. 请求广告前检查 ConsentInformation.canRequestAds()。

将宿主已确认的各项隐私状态传入下一节初始化参数;canRequestAds() 不能直接映射为四项状态全部同意。


三、SDK 初始化 ​

完成上方广告依赖、宿主配置和适用的用户同意流程后,在 App 启动阶段执行一次 SDK 初始化,并传入宿主已确认的隐私状态。

3.1、接口定义 ​

java
/**
 * Initialize the SDK
 *
 * @param context  context
 * @param appId    appId
 * @param appKey   appKey
 * @param privacyConfig Host-confirmed advertising privacy states
 * @param listener Callback listener
 */
public static void initSDK(
        Context context,
        String appId,
        String appKey,
        SUDOPPrivacyConfig privacyConfig,
        SUDOPInitSDKListener listener
)

3.2、调用示例 ​

配置字段和枚举含义见 SUDOPPrivacyConfig。替换示例中的 App ID、App Key 和隐私状态;以下值仅演示写法,不是默认授权。

java
SUDOPPrivacyConfig privacyConfig = SUDOPPrivacyConfig.builder()
        .setGdprConsentStatus(SUDOPPrivacyConfig.GdprConsentStatus.NOT_APPLICABLE)
        .setDoNotSellStatus(SUDOPPrivacyConfig.DoNotSellStatus.NOT_APPLICABLE)
        .setLgpdConsentStatus(SUDOPPrivacyConfig.LgpdConsentStatus.NOT_APPLICABLE)
        .setAgeRestrictedTreatment(SUDOPPrivacyConfig.AgeRestrictedTreatment.UNSPECIFIED)
        .build();

SUDOP.initSDK(
        getApplicationContext(),
        "您的 AppID",
        "您的 AppKey",
        privacyConfig,
        new SUDOPInitSDKListener() {
            @Override
            public void onSuccess() {
                Log.d("SUDOP", "SDK 初始化成功");
            }

            @Override
            public void onFailure(int retCode, String retMsg) {
                Log.e("SUDOP", "SDK 初始化失败: " + retMsg);
            }
        }
);

参数说明 ​

参数类型说明
contextContextAndroid 上下文,建议传入 ApplicationContext
appIdStringSUD 平台分配的 AppID
appKeyStringSUD 平台分配的 AppKey
privacyConfigSUDOPPrivacyConfig宿主已确认的广告隐私状态
listenerSUDOPInitSDKListener初始化结果回调

初始化接口完整定义见 initSDK。


四、用户鉴权 auth ​

在启动游戏前,需要完成用户鉴权。业务后端生成 userSignature 后,客户端调用 SUDOP.auth 同步用户登录态。

首次鉴权前注册认证失效监听。收到通知后,向业务服务端获取当前账号的新签名,再调用 SUDOP.auth。

4.1、接口定义 ​

java
/**
 * Authenticate user login status
 *
 * @param userSignature userSignature
 */
public static void auth(
        String userSignature,
        SUDOPAuthListener listener
)

4.2、调用示例 ​

java
String userSignature = "业务后端下发的签名字符串";

SUDOP.auth(userSignature, new SUDOPAuthListener() {
    @Override
    public void onSuccess() {
        Log.d("SUDOP", "用户鉴权成功");
    }

    @Override
    public void onFailure(int retCode, String retMsg) {
        Log.e("SUDOP", "用户鉴权失败: " + retMsg);
    }
});

4.3、参数说明 ​

参数类型说明
userSignatureString业务后端生成并下发的用户签名
listenerSUDOPAuthListener鉴权结果回调

五、启动游戏 ​

完成 SDK 初始化和用户鉴权后,可以通过 gameId 启动游戏。

调用方式 ​

java
String language = "zh-CN";
SUDOPGameTask sudOPGameTask = SUDOP.startGame(gameId, language, new SUDOPStartGameListener() {
    @Override
    public void onGameViewCreated(View view) {
        // 游戏 View 创建完成
        // 将 view 添加到自己的游戏容器中
        gameContainer.addView(view);
    }

    @Override
    public void onGamePkgDecrypt(GamePkgDecryptHandle handle, String filePath) {
        // 游戏包解密回调
        // 如果业务没有自定义加密包处理逻辑,通常可以不处理
    }

    @Override
    public void onCreated(SUDRTGameHandle handle, SUDOPGameInfo gameInfo) {
        // 游戏运行环境创建完成
        // 可在此处设置横竖屏、注册业务回调、设置游戏状态等

        // 示例:根据游戏推荐方向设置屏幕方向
        if ("landscape".equals(gameInfo.deviceOrientation)) {
            setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_SENSOR_LANDSCAPE);
        } else if ("portrait".equals(gameInfo.deviceOrientation)) {
            setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_SENSOR_PORTRAIT);
        } else if ("auto".equals(gameInfo.deviceOrientation)) {
            setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_FULL_SENSOR);
        }

        // 示例:注册业务代理
        // SUDOP.registerWrappedClient(handle, sudOPWrappedClient);

        // 保存游戏句柄,后续可用于控制游戏状态或释放资源
        gameHandle = handle;
    }

    @Override
    public void onSuccess(String gameId, SUDRTGameHandle gameHandle) {
        Log.d("SUDOP", "游戏启动成功: " + gameId);
    }

    @Override
    public void onProgress(int progress) {
        Log.d("SUDOP", "游戏加载进度: " + progress + "%");
    }

    @Override
    public void onFailure(int retCode, String retMsg) {
        Log.e("SUDOP", "游戏启动失败: " + retCode + ", " + retMsg);
    }
});

将 language 设置为应用当前选择的 BCP 47 语言标签,可与 getGameInformation 使用相同的值。

原有 SUDOP.startGame(gameId, listener) 重载仍可使用。加载界面在 language 为 null 或空字符串时使用系统语言;名称和图标先匹配语言,再读取各自 map 的 default,图标仍为空时使用原有 game_icon 图标。语言选择与完整回退规则见 startGame。

游戏运行后,由小游戏通过 sud 广告 API 加载和展示广告,参见 游戏开发示例。SDK 初始化成功不表示广告已加载,游戏侧仍需等待广告对象的 onLoad。


六、SUDOPStartGameListener 回调说明 ​

SUDOPStartGameListener 用于接收游戏启动过程中的关键状态。

回调方法说明
onGameViewCreated(View view)游戏 View 创建完成。开发者需要将该 View 添加到自己的页面容器中
onGamePkgDecrypt(GamePkgDecryptHandle handle, String filePath)游戏包解密回调。如果业务侧需要处理自定义加密包,可在此处完成解密逻辑;如果不需要,通常无需处理
onCreated(SUDRTGameHandle handle, SUDOPGameInfo gameInfo)游戏运行环境创建完成。可在此处保存 SUDRTGameHandle、设置屏幕方向、注册业务代理、设置游戏状态等
onSuccess(String gameId, SUDRTGameHandle gameHandle)游戏启动成功
onProgress(int progress)游戏加载进度回调,progress 通常为 0 ~ 100
onFailure(int retCode, String retMsg)游戏启动失败,可根据错误码和错误信息进行提示或重试

七、设置游戏方向 ​

游戏创建完成后,SDK 会通过 SUDOPGameInfo 返回游戏信息,其中 deviceOrientation 表示游戏推荐方向。

示例:

java
@Override
public void onCreated(SUDRTGameHandle handle, SUDOPGameInfo gameInfo) {
    if ("landscape".equals(gameInfo.deviceOrientation)) {
        activity.setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_SENSOR_LANDSCAPE);
    } else if ("portrait".equals(gameInfo.deviceOrientation)) {
        activity.setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_SENSOR_PORTRAIT);
    } else if ("auto".equals(gameInfo.deviceOrientation)) {
        activity.setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_FULL_SENSOR);
    }
}
deviceOrientation说明
landscape横屏
portrait竖屏
auto跟随传感器自动旋转

八、注册业务代理 ​

如果游戏需要向 App 请求用户信息、图片选择、图片预览、保存图片等能力,需要注册业务代理。

建议在 onCreated 回调中注册:

java
@Override
public void onCreated(SUDRTGameHandle handle, SUDOPGameInfo gameInfo) {
    SUDOP.registerWrappedClient(handle, sudOPWrappedClient);
}

其中 sudOPWrappedClient 为业务侧实现的代理对象。


九、销毁与资源释放 ​

当用户退出游戏页面时,例如 Activity.finish(),需要释放游戏相关资源,避免内存、音频、渲染资源泄漏。

示例:

java
@Override
public void finish() {
    if (sudOPGameTask != null) {
        sudOPGameTask.destroy();
        sudOPGameTask = null;
    }
    super.finish();
}
@Override
protected void onDestroy() {
    super.onDestroy();
    if (sudOPGameTask != null) {
        sudOPGameTask.destroy();
        sudOPGameTask = null;
    }
}

具体释放方法请以当前 SDK 版本提供的 API 为准。 如果业务中保存了游戏任务对象、游戏句柄或注册了监听器,页面销毁时应一并清理。


十、完整接入流程 ​

text
引入 SUDGI SDK、SUDM Core 和广告源依赖
        ↓
完成广告宿主配置和适用的用户同意流程
        ↓
SUDOP.initSDK 携带 privacyConfig 初始化 SDK
        ↓
业务后端生成 userSignature
        ↓
SUDOP.auth 完成用户鉴权
        ↓
SUDOP.startGame(gameId, listener) 启动游戏
        ↓
onGameViewCreated 中添加游戏 View
        ↓
onCreated 中设置方向、注册业务代理、保存游戏句柄
        ↓
onProgress 接收加载进度
        ↓
onSuccess 游戏启动成功
        ↓
页面退出时释放游戏资源

十一、注意事项 ​

  • 完成广告配置和适用的用户同意流程后调用 initSDK。
  • 启动游戏前必须先完成 auth 鉴权。
  • userSignature 应由业务后端生成,不建议在客户端拼装敏感签名参数。
  • onGameViewCreated 回调后,需要将游戏 View 添加到业务自己的容器中。
  • onCreated 回调中可以进行屏幕方向设置、业务代理注册、游戏状态设置等操作。
  • onProgress 可用于展示游戏加载进度。
  • onFailure 中建议展示错误提示,并根据业务需要进行重试。
  • 页面销毁时务必释放游戏资源,避免资源泄漏。

十二、发布前检查 ​

  • 最终 Merged Manifest 包含所需的 INTERNET、ACCESS_NETWORK_STATE;使用 AdMob 时包含正确的 App ID。
  • 需要使用 GAID 时,按上方适用条件核对 AD_ID 权限。
  • 隐私政策及商店数据披露与 App、广告 SDK 的实际采集和共享行为一致。