Android 端快速接入
按本指南依次完成 SUDGI SDK 和广告能力接入、SDK 初始化及用户鉴权后,即可通过 gameId 启动游戏。
一、引入 SDK 与工程配置
1. 通过 Gradle 引入
在项目根目录的 build.gradle 中配置 Maven 仓库,并在应用层级 build.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.0 | Google 版本说明 |
Carty:io.carty.bidad:carty-sdk | 固定为 1.11.0 | Carty 更新日志 |
TopOn: com.anythink.sdk:core-tpn | 固定为 6.6.22.3 | TopOn Android 接入说明 |
MAX:com.applovin:applovin-sdk | 固定为 13.5.1 | MAX Android 接入说明 |
Taku:com.anythink.sdk:core-taku | 固定为 6.6.40 | Taku Android 接入说明 |
二、广告能力接入
完成依赖引入后,按所选广告源配置宿主应用,并在 SDK 初始化前处理适用的用户同意流程。
宿主配置
AdMob App ID
适用条件:使用 AdMob。修改位置:宿主 AndroidManifest.xml 的 <application> 内。
<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> 内。
<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 时:
- 每次启动更新同意信息,展示所需表单。
- 按要求提供隐私选项入口,供用户修改选择。
- 请求广告前检查
ConsentInformation.canRequestAds()。
将宿主已确认的各项隐私状态传入下一节初始化参数;canRequestAds() 不能直接映射为四项状态全部同意。
三、SDK 初始化
完成上方广告依赖、宿主配置和适用的用户同意流程后,在 App 启动阶段执行一次 SDK 初始化,并传入宿主已确认的隐私状态。
3.1、接口定义
/**
* 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 和隐私状态;以下值仅演示写法,不是默认授权。
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);
}
}
);参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
context | Context | Android 上下文,建议传入 ApplicationContext |
appId | String | SUD 平台分配的 AppID |
appKey | String | SUD 平台分配的 AppKey |
privacyConfig | SUDOPPrivacyConfig | 宿主已确认的广告隐私状态 |
listener | SUDOPInitSDKListener | 初始化结果回调 |
初始化接口完整定义见 initSDK。
四、用户鉴权 auth
在启动游戏前,需要完成用户鉴权。业务后端生成 userSignature 后,客户端调用 SUDOP.auth 同步用户登录态。
首次鉴权前注册认证失效监听。收到通知后,向业务服务端获取当前账号的新签名,再调用 SUDOP.auth。
4.1、接口定义
/**
* Authenticate user login status
*
* @param userSignature userSignature
*/
public static void auth(
String userSignature,
SUDOPAuthListener listener
)4.2、调用示例
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、参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
userSignature | String | 业务后端生成并下发的用户签名 |
listener | SUDOPAuthListener | 鉴权结果回调 |
五、启动游戏
完成 SDK 初始化和用户鉴权后,可以通过 gameId 启动游戏。
调用方式
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 表示游戏推荐方向。
示例:
@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 回调中注册:
@Override
public void onCreated(SUDRTGameHandle handle, SUDOPGameInfo gameInfo) {
SUDOP.registerWrappedClient(handle, sudOPWrappedClient);
}其中 sudOPWrappedClient 为业务侧实现的代理对象。
九、销毁与资源释放
当用户退出游戏页面时,例如 Activity.finish(),需要释放游戏相关资源,避免内存、音频、渲染资源泄漏。
示例:
@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 为准。 如果业务中保存了游戏任务对象、游戏句柄或注册了监听器,页面销毁时应一并清理。
十、完整接入流程
引入 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 的实际采集和共享行为一致。
