SDK 接入检查与帮助

游戏启动、初始化 SDK 时，SDK会对接入是否正确进行检查。若检查有错，会在 ADB 日志提示；
若游戏还没有发布线上前，也会弹窗提示开发者。

本文档是所有检查错误的详细、全面的说明，主要面向 jar+res 接入方式的开发。
注意：若游戏是二次封装了 SDK 的java 接口，需要在最初封装的环节查看修复这些问题

调试开关

“SDK 调试开关未关闭”，没有关闭 SDK 的调试开关，即下面setDebugEnabled()接口参数没有设置false

perateConfig config = new OperateConfig.Builder(MainActivity.this)
    // 设置调试模式，可选，默认false, 发布前应设置为false或删除调用
    .setDebugEnabled(false)
    .build();

若不关闭，则可能会泄漏敏感信息，对游戏运行性能又一定影响

FileProvider文件访问配置

“OpeFileProvider 设置错误”，游戏 APK AndroidManifest.xml 中 cn.m4399.operate.OpeFileProvider
未注册或属性设置有错。游戏外部接口需要访问 SDK 内部资源，本设置就是注册资源的访问权限。

<!--
    4399 运营SDK：以下是FileProvider配置，以兼容7.0+文件访问权限变更
    注意其中的： android:authorities="游戏包名.operate.FileProvider"
    以及，android:resource="@xml/m4399_ope_file_paths" 是固定格式写法
 -->
<provider
    android:name="cn.m4399.operate.OpeFileProvider"
    android:authorities="${applicationId}.operate.FileProvider"
    android:exported="false"
    android:grantUriPermissions="true">
    <meta-data
        android:name="android.support.FILE_PROVIDER_PATHS"
        android:resource="@xml/m4399_ope_file_paths" />
</provider>

此项有错将影响游戏更新、分享等功能；特别是更新异常，将严重影响用户体验，导致用户流失。
其中的 android:authorities 极易出错，请仔细核对。

游戏Activity配置

"Activity 模式设置有误"，游戏 Activity 设置有错，主要是 android:resizeableActivity 和 android:configChanges

android:resizeableActivity，多窗口相关属性，详细说明参考 多窗口模式配置。 对于 SDK，最好禁用禁用多窗口模式，如果必须使用，则要设置 android:configChanges

<!-- 游戏 Activity：
     若覆盖了 android:resizeableActivity="false"，则必须如下设置 android:configChanges
     android:configChanges="orientation|screenSize|keyboardHidden|screenLayout|navigation|smallestScreenSize|fontScale"
     
     不应该使用 android:launchMode="singleTask" 启动模式，可以考虑 singleTop
 -->
<activity
    android:name="cn.m4399.operate.samples.OnlineGameActivity"
    android:configChanges="orientation|screenSize|keyboardHidden|screenLayout|navigationsmallestScreenSize|fontScale"
    android:exported="true"
    android:theme="@style/AppTheme">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />

        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
 </activity>

游戏 Activity

• Android 应用启动打开的第一个 Activity 称为“入口 Activity”
• 游戏画面一般只在一个 Activity 中展示，称为“主 Activity”
• 游戏一般在入口 Activity 或主 Activity 初始化 SDK、登录账号
• 大多数游戏入口 Activity 即是主 Activity，但并非总数如此

游戏一般在主 Activity或入口 Activity中初始化 SDK，而多窗口模式中的特定操作会使初始化异常。

未正确设置android:resizeableActivity 和 android:configChanges，有可能使游戏跳过重要的初始化弹窗。
另外 android:configChanges 设置不正确，会引起其他问题，如授权登录过程异常，授权后无法正确获取用户信息。

多 Activity 的情况

若游戏有多个 Activity，则游戏需要在入口 Activity 和主 Activity 设置上述属性

必要的Activity

“必须的 Activity 不全”，SDK 必须的 Activity 组件不全，这些组件对应了不同的页面

当前 SDK v3.14.x中需要的 Activity 有

// SDK
cn.m4399.operate.component.OperateActivity,
cn.m4399.operate.recharge.RechargeActivity,
// 支付宝 H5
com.alipay.sdk.app.H5PayActivity,
// 一键登录
cn.com.chinatelecom.account.sdk.ui.AuthActivity,
cn.com.chinatelecom.account.sdk.ui.PrivacyWebviewActivity,
cn.m4399.operate.account.onekey.cu.CuLoginActivity,
cn.m4399.operate.account.onekey.cu.CuPrivacyContentActivity,
com.cmic.gen.sdk.view.GenLoginAuthActivity,
// 人脸识别
com.tencent.cloud.huiyansdkface.facelight.ui.FaceVerifyActivity,
com.tencent.cloud.huiyansdkface.facelight.ui.FaceGuideActivity,
com.tencent.cloud.huiyansdkface.facelight.ui.FaceProtocalActivity

请注意：

• 必须的Activity可能随着 SDK 版本的不同有所变化，升级 SDK 时应仔细核对
• Activity 的其他配置也应遵循原有写法，除了方向设置可以与游戏本身一致

必要的服务

“必须的 Service 不全”，SDK 必须的服务组件没有注册

当前 SDK v3.14.x中需要的 Service 有

<!-- 录屏相关 -->
<service
    android:name="cn.m4399.operate.video.record.container.RecordService"
    android:foregroundServiceType="mediaProjection" />

上面服务与录屏功能有关（由后台配置开关），高版本系统要求注册前台服务以完成录屏功能。

注意：

• 必须的Service可能随着 SDK 版本的不同有所变化，升级 SDK 时应仔细核对
• Service 的其他配置也应遵循原有写法

必要的权限

“必须的应用权限不全”，SDK 必须的权限不全，其中大多数是第三方 SDK 需要的

  <!--
     4399 运营SDK：
     以下是必须的，包括第三方SDK需要的，以jar+res 方式接入需要打开以下内容，aar则不需
  -->
  <!-- 一般性权限 -->
  <uses-permission android:name="android.permission.INTERNET" />
  <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  <uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />
  <!-- 兼容低版本系统 -->
  <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
  <!-- 录屏功能 -->
  <uses-permission android:name="android.permission.RECORD_AUDIO" />
  <uses-permission android:name="android.permission.RECORD_VIDEO" />
  <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
  <!-- 一键登录 -->
  <uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
  <uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
  <!--suppress DeprecatedClassUsageInspection -->
  <uses-permission android:name="android.permission.GET_TASKS" />
  <!-- 人脸识别 -->
  <uses-permission android:name="android.permission.CAMERA" />
  <uses-permission android:name="android.permission.WAKE_LOCK" />

  <uses-sdk tools:overrideLibrary="com.tencent.cloud.huiyansdkface.wecamera" />

注意：

• 必须的权限可能随着 SDK 版本的不同有所变化，升级 SDK 时应仔细核对
• 权限配置的附加属性也应遵循原有写法
• 部分权限并非所有版本都需要，而是为了兼容系统版本而添加

缺少必须的权限会引起各种异常，比如网络请求失败、实名时无法打开相册、无法启动录屏、无法启动摄像头等

必要的Assets资源

“必须的 assets 资源不全”，SDK 运行时需要的资源不全，游戏打包后解压的assets目录应包含

// SDK 悬浮窗关闭的教学图片
m4399_ope_fab_hide_animation.gif,
// models目录 是人脸识别的数据资源
models

注意：

• assets 资源可能随着 SDK 版本的不同有所变化，升级 SDK 时应仔细核对，废弃资源可及时移除
• 某些 IDE 的配置，无法在依赖工程中加入这些资源，就需要将这些资源移动到主工程

JNI 库是否完整且对齐

游戏打包的so不全，游戏 APK 应至少同时包含 armeabi-v7a 和 arm64-v8a 两个 jni 目录，且 SDK 必须的 so 应健全
jar+res 接入和解开 aar 手动接入的游戏要注意

当前 SDK v1.19.0 中的 so 有

ibBugly-idasc.so
libCtaApiLib.so
libYTCommonLiveness.so
libYTLiveness.so
libkycgm.so
libsmsdk_mirror.so
libturingmfa.so
libweconvert.so
libweyuv.so

# === 3.19.0
libcpuaffinity.so
libgp.so
libgzstd.so
liblog.so
# === 3.19.0

第三方依赖

当前 SDK v3.19.0 中的外部依赖有

## 实现依赖(implementation)，12 个
CTAccountSdk_HY_v4.5.9_all.jar
alipaySdk-v15.8.37-20250814.jar
quick_login_android_5.9.7.jar
smsdk-2.24.3_mirror.jar
unicom_login_android_v6.1.3CR001B0322.jar
TuringFace_youtu_108158_7WCF54SWX5H87QEV_196_106_pack.jar
WbCloudFaceLiveSdk-v4.5.6.2.1-92b2fb0b.jar
WbCloudFaceLiveSdk_R.jar
WbCloudNormal-v5.1.5-5dfadab.jar
facelight.jar
gmssl-release-1.0.0.jar

# === 3.19.0
libUpgrade-20260417.jar
# === 3.19.0

## 编译依赖(compileOnly)，8 个，注释部分为对应的 aar 形式
android-support-v13-23.2.1.jar # com.android.support:support-v4:28.0.0
volley-v1.2.1.jar              # com.android.volley:volley:1.2.1

# === 3.19.0
okhttp-3.12.8.jar              # com.squareup.okhttp3:okhttp:3.12.8
okio-1.15.0.jar                # com.squareup.okio:okio:1.15.0
logging-interceptor-3.12.8.jar # com.squareup.okhttp3:logging-interceptor:3.12.8
kotlin-stdlib-jdk7-2.2.0.jar   # org.jetbrains.kotlin:kotlin-stdlib-jdk7:2.2.0
kotlin-stdlib-2.2.0.jar        # org.jetbrains.kotlin:kotlin-stdlib:2.2.0
# org.jetbrains.kotlin:kotlin-android-extensions-runtime:2.2.0
kotlin-android-extensions-runtime-2.2.0.jar 
# === 3.19.0

SDK 的主 jar 包一般为 m4399OperateSDK-3.x.y+z.jar，它的依赖分实现依赖与编译依赖两类
其中实现依赖已经打到 SDK 主 jar 包中，其他易冲突的依赖采用编译依赖的方式，由接入方选择兼容版本
对于使用 jar + res形式接入的游戏，尤其要注意下每次 SDK 更新时是否移入了新的编译依赖
游戏打包时，特别是非 gradle 项目方式打包时，可能因为以下原因导致类或方法不能正常找到或初始化：

• 错误混淆，打包时有引入依赖，但是打包后类或方法找不到
• 未引入，导致运行时类找不到
• 重复引入，打包时无意引入多次
• 不当引入，打包时看似引入，但是引入了不兼容的版本

其他

除了上述必须的、SDK 加入检查的配置/资源，还有一些也是需要的，但没有加入检查

res 资源

SDK res下为兼容不同屏幕尺寸、方向，和不同系统的资源不应丢失，否则会出现页面变形，严重的会功能异常

应用信息查询quries

<!-- 4399 运营SDK：Android 11兼容，声明所要进行交互的应用包名，主要用于外部授权登录和支付 -->
<queries>
    <package android:name="com.m4399.gamecenter" />
    <package android:name="com.tencent.mobileqq" />
    <package android:name="com.sina.weibo" />
    <package android:name="com.tencent.mm" />
    <!-- 支付宝 SDK -->
    <package android:name="com.eg.android.AlipayGphone" /> <!-- 支付宝 app -->
    <package android:name="com.eg.android.AlipayGphoneRC" /> <!-- 沙箱支付宝 app -->
    <package android:name="hk.alipay.wallet" /> <!-- 香港版支付宝 app -->
    <!-- 好游快爆 -->
    <package android:name="com.xmcy.hykb" />
</queries>

缺少影响独代游戏的激活、授权登录、微信/支付宝/QQ 钱包的充值

quries 编译错误

若编译时出现类似于以下的错误

Missing 'package' key attribute on element package at [cn.m4399.sdk:operate:x.x.x] AndroidManifest.xml

查看 Android studio 项目根目录下的build.gradle，可能是这样的声明：

buildscript {
    dependencies {
        classpath 'com.android.tools.build:gradle:3.5.3'
    }
}

此为Gradle 插件兼容问题，参考 Android Gradle 插件 4.0.0（2020 年 4 月），解决方式：

• 升级上述插件版本到4.1或更高版本
• 若不方便升级大版本，可以调整为兼容版本，如3.5.3调整为3.5.4

http 请求兼容networkSecurityConfig

<!--
    4399 运营SDK：
    Android 9.0 兼容， 对少量外部 http 请求的兼容，
    参考或修改配置 android:networkSecurityConfig="@xml/m4399_network_policy"
-->
<application
    android:networkSecurityConfig="@xml/m4399_network_policy"
    android:resizeableActivity="false">
</application>

缺少无法在 Android 9+ 上进行 http 请求

注意：

• 此项配置容易在打包中被其他 SDK 的配置覆盖，应以 APK 解压后的配置为准
• 可以将多个配置文件融合为一个文件，只注册这个文件

遗留 apache 网络请求库

<!-- 4399 运营SDK：旧的http请求库的兼容，支付宝等少数外部依赖需要 -->
<uses-library
    android:name="org.apache.http.legacy"
    android:required="false" />

缺少导致无法打开支付宝网页