11/25/2024 10:18:48

接入教程（Android）

[info]版本须知
minSdkVersion : 15
targetSdkVersion : 28+

一、配置工程

1.1 文件清单

1.2 AndroidManifest 配置

<!--TDM begin-->
<!-- 网络通信-->
<uses-permission android:name="android.permission.INTERNET" />
<!-- 获取网络状态 -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<!--TDM end-->

<application>
    <!-- TDataMaster 配置 -->
    <meta-data android:name="GCloud.TDM.AppId" android:value="@string/tdm_AppId" />
    <meta-data android:name="GCloud.TDM.AppChannel" android:value="@string/tdm_AppChannel" />
    <meta-data android:name="GCloud.TDM.Protocol" android:value="@string/tdm_Protocol" />
    <meta-data android:name="GCloud.TDM.Test" android:value="true"/>
</application>

接入 TDM 组件需关注，TDataMaster 配置说明可参考 TDM 渠道文档 。

修改游戏主Activity的启动方式launchmode为singleTask 示例配置如下：

<activity
    android:name=".StartupActivity"
    android:configChanges="orientation|screenSize|keyboardHidden"
    android:launchMode="singleTask"
    android:taskAffinity="com.tencent.itop.example">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
        <category android:name="android.intent.category.LEANBACK_LAUNCHER" />
    </intent-filter>
</activity>

二、框架运行实例

2.1 初始化

需要在 UI 线程调用

MSDKPlatform.initialize(this);

2.2 生命周期埋点

需要对 onActivityResult、onNewIntent 以及 onRequestPermissionsResult 进行埋点
Activity 的其他周期函数已经主动 hook，业务无需处理

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
   super.onActivityResult(requestCode, resultCode, data);
   MSDKPlatform.onActivityResult(requestCode, resultCode, data);
 }

@Override
protected void onNewIntent(Intent intent) {
   super.onNewIntent(intent);
   MSDKPlatform.onNewIntent(intent);
 }

@Override
public void onRequestPermissionsResult(int requestCode, String[] permissions, int[] grantResults) {
   super.onRequestPermissionsResult(requestCode, permissions, grantResults);
   MSDKPlatform.onRequestPermissionsResult(requestCode, permissions, grantResults);
 }

2.3 C++ 接入（可选）

将头文件放入工程 /app/src/main/cpp 文件夹：

在 CMakeLists.txt 中编入 .so 文件，例如：

ADD_LIBRARY(libMSDKCore.so SHARE IMPORTED)
SET_TARGET_PROPERTIES(
    libMSDKCore.so
    PROPERTIES IMPORTED_LOCATION
    ${CMAKE_CURRENT_SOURCE_DIR}/libs/${ANDROID_ABI}/libMSDKCore.so
)

[warning] 如果第三方库 libThird.so 调用了 libMSDKCore.so 的接口，那么需要先调用 MSDK 初始化

否则会报 undefined linked 错误，正确做法应该是：

MSDKPlatform.initialize(this);
System.loadLibrary("Third");

2.4 初始化

在启动activity中调用MSDKPlatform.initialize()进行MSDK SDK初始化

  @Override
  protected void onCreate(@Nullable Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);
      ...
      // 所有的初始化入口放在此处
      MSDKPlatform.initialize(this);
      ...
    }

2.5 创建回调监听

以登录为例，实现MSDKLoginObserver接口，创建监听实例，如下：

private class LoginObserver implements MSDKLoginObserver{

        @Override
        public void onBaseRetNotify(MSDKRet baseRet) {
            MSDKLog.d("onBaseRetNotify, result = " + formatString(baseRet));
            handleLoginResult(baseRet);
        }

        @Override
        public void onLoginRetNotify(MSDKLoginRet loginRet) {
            MSDKLog.d("onLoginRetNotify, result = " + formatString(loginRet));
            handleLoginResult(loginRet);
        }
        private void handleLoginResult(MSDKRet baseRet){
            switch (baseRet.retCode) {
                case MSDKErrorCode.SUCCESS:
                    showResult("登录成功", formatString(baseRet));
                    break;
                case MSDKErrorCode.LOGIN_ACCOUNT_REFRESH:
                    showResult("异账号：通过URL将票据刷新", formatString(baseRet));
                    break;
                case MSDKErrorCode.LOGIN_URL_USER_LOGIN:
                    showResult("异账号：使用URL登陆成功", formatString(baseRet));
                    break;
                case MSDKErrorCode.LOGIN_NEED_SELECT_ACCOUNT:
                    showDiffLogin();
                    break;
                case MSDKErrorCode.LOGIN_NEED_LOGIN:
                    showResult("异账号：需要进入登陆页", formatString(baseRet));
                    break;
                case MSDKErrorCode.NEED_NAME_AUTH:
                    // 实名认证
                    break;
                default:
                    showResult("登录通知（未知消息）", formatString(baseRet));
                    break;
            }
        }
    }

登录成功返回SUCCESS，失败返回对应的错误码，你可以根据自己的需求处理。

2.6 设置回调监听

通过MSDKLogin类的setLoginObserver设置监听，示例如下：

//init observer
MSDKLogin.setLoginObserver(new LoginObserver());

2.7 调用特殊信息控制接口

从 MSDK5.20 版本开始，特殊信息开关以及特殊信息设置相关能力由业务自行控制，开关开启之前 MSDK 自身以及灯塔、手Q OpenSDK 和 Bugly 组件将不会获取特殊信息；业务侧需在用户勾选同意腾讯游戏用户协议相关条款后主动打开 MSDK 特殊信息开关以及主动设置相关特殊信息至 MSDK，否则将会影响 MSDK 的数据获取以及灯塔组件的数据获取和数据统计。

2.7.1 特殊信息开关

1）接口声明

// 设置是否允许收集特殊信息
MSDK_EXPORT_UE static void SetCouldCollectSensitiveInfo(bool couldCollect);

2）示例代码

MSDKSensitive::SetCouldCollectSensitiveInfo(true);

3）注意事项

• 用户勾选同意腾讯游戏用户协议相关条款后务必主动调用该接口，否则将会影响 MSDK 和灯塔组件的相关信息获取。另外，手Q OpenSDK3.5.7（对应 MSDK5.20.001）更新了权限相关功能，接入方未调用 SetCouldCollectSensitiveInfo 授权前无法使用 手Q OpenSDK 的各项功能，日志中会报错“用户未授权，暂时无法使用QQ登录及分享等功能”。
• 游戏引擎未起来之前或 MSDK 初始化之前，Android 端可在 Java 层提前调用 Java 接口MSDKSensitive.setCouldCollectSensitiveInfo(true); 打开开关。
• MSDK 初始化之后仅可通过 C++ 接口来控制开关，请勿再使用 Java 接口。
• 多进程场景未明确支持，建议对组件的特殊信息开关接口调用都放主进程，或者子进程自行调用组件特殊信息开关接口。

2.7.2 特殊信息设置

1）接口声明

// 以 json 形式设置特殊信息字段至各个组件 SDK，目前支持 {"AndroidID":"xxx","WiFiMacAddress":"xxx","Model":"xxx","Oaid":"xxx","Imsi":"xxx","Cid":"xxx"}
MSDK_EXPORT_UE static void SetSensitiveInfo(const String &jsonInfo);

2）示例代码

char *jsonInfo = "{\"AndroidID\":\"xxx\", \"WiFiMacAddress\":\"xxx\", \"Model\":\"xxx\", \"Oaid\":\"xxx\", \"Imsi\":\"xxx\", \"Cid\":\"xxx\"}";
MSDKSensitive::SetSensitiveInfo(jsonInfo);

3）注意事项

• 用户勾选同意腾讯游戏用户协议相关条款后务必主动调用该接口设置 `AndroidID` 字段（`AndroidID` 需业务自行获取），否则将会影响灯塔组件的数据统计。
• MSDK5.28.001（GCloud2.2.10.1）版本开始必须传递手机 Model 给 OpenSDK，否则将无法授权。若业务未配置，则 MSDK 内部获取并处理；若上述都失败，将无法使用手Q互联 OpenSDK 相关功能。另外，不传入 Model 值还会影响灯塔中台算法效果。
• 游戏引擎未起来之前或 MSDK 初始化之前，Android 端可在 Java 层提前调用 Java 接口 MSDKSensitive.setSensitiveInfo(jsonInfo); 设置相关特殊信息。
• MSDK 初始化之后仅可通过 C++ 接口来设置相关特殊信息，请勿再使用 Java 接口。

2.8 AndroidID & Apn 采集配置

从 MSDK5.23.001 版本开始，新增针对单个字段 AndroidID & Apn 采集的代码开关和配置开关，业务可按需自行配置这些字段是否允许采集。

前置条件：V5.20 及以上版本，且 SetCouldCollectSensitiveInfo 设置为 true。

采集开关优先级说明：

• 代码及配置均有值：代码开关为准；
  
• 代码及配置均为空：默认采集；
  
• 代码及配置其中一个有值：以获取的该值为准。
  

2.8.1 代码开关接口声明

// 以json形式设置特别信息单字段开关，目前支持设置AndroidID、Apn，参数示例{"AndroidID":true,"Apn":true}
// 参数中的value即对应字段的代码开关情况，为true时可以采集
MSDK_EXPORT_UE static void SetCollectSensitiveInfo(const String &jsonInfo);

2.8.2 代码开关示例代码

char *jsonInfo = "{\"AndroidID\":true,\"Apn\":true}";
MSDKSensitive::SetCollectSensitiveInfo(jsonInfo);

2.8.3 配置开关

配置开关位于 MSDKConfig.ini 中，对应配置项为 MSDK_DENIED_COLLECT_LIST，该配置项为不允许采集的特别字段列表，目前针对字段为AndroidID、Apn。配置示例如下：

//配置项位于MSDKConfig.ini，默认不允许采集的特别字段列表为空，多个字段使用英文逗号连接
MSDK_DENIED_COLLECT_LIST =

2.8.4 注意事项

• 游戏引擎未起来之前或 MSDK 初始化之前，Android 端可在 Java 层提前调用 Java 接口 MSDKSensitive.setCollectSensitiveInfo(jsonInfo);提前设置针对单个字段采集的代码开关；
  
• MSDK 初始化之后仅可通过 C++ 接口来控制代码开关，请勿再使用 Java 接口；
  
• 多进程场景未明确支持，建议将代码开关的设置接口调用都放在主进程，或者子进程自行调用。
  

2.9 调用API接口

MSDK接口按照不同模块进行划分，调用之前，请找到对应模块，例如登录、好友、WebView等。以登录为例，调用示例如下：

//根据渠道设置登录渠道
permissions = getChannelTestPermissions(mSelectedChannel);
//登录mSelectedChannel渠道
MSDKPlatform.Login.login(permissions, mSelectedChannel, mSelectedSubChannel, "");

注：

• 不同模块有各自的Observer，返回码不相同，调用相似
• 一个模块只有一个Observer，多次设置后之后最后一个生效
• 兼顾异账号情况，登录模块设置Observer需要在入口Activity的onCreate和onResume生命周期之间

三、MSDKPolicy接入

3.1 概述

MSDKPolicy 是一套通用的 Android 数据权限策略流程实现方案，整合了用户协议和权限授权流程，通过配置的形式供业务快速接入。用户协议更新参考文档：https://docs.qq.com/doc/DSnlkYU5SZWhPYmNR

MSDKPolicy 的流程如下：

3.2 接入步骤

3.2.1 涉及文件

• msdk_policy_content.html
  用于配置协议内容，已提供一套经法务审阅的文案

• msdk_permission_content.html
  用于配置 App 所需的权限列表和用途的说明，当前内容为 Demo 展示所用，业务需要根据自己 App 的实际情况做修改，必要权限需要靠前，并给出（必要） 高亮提示

• values.xml - msdk_permission_list
  用于配置必要权限，以供权限申请流程轮询，在轮询过程中会向用户申请必要权限

3.2.2 配置指引

（1）引入MSDKPolicy

重要：通过在 AndroidManifest.xml 中添加如下配置，引入 MSDKPolicy

<activity 
    android:name="com.tencent.gcloud.msdk.core.policy.MSDKPolicyActivity"
    android:configChanges ="keyboard|keyboardHidden|screenLayout|screenSize"
    android:launchMode="singleTask"
    android:theme="@style/MSDKPolicyTheme">
    <!-- 将 MSDKPolicy 设置为主 activity，使其启动就展示 -->
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
        <category android:name="android.intent.category.LEANBACK_LAUNCHER" />
    </intent-filter>
    <!-- MSDK_POLICY_TARGET_ACTIVITY 用于指定要跳转到的（应用或者游戏的首个 activity）-->
    <meta-data android:name="MSDK_POLICY_TARGET_ACTIVITY" android:value="{your_main_acitivity}" />
    <!-- 开启 MSDKPolicy 的 Debug，用户调试输出⽇志 -->
    <meta-data android:name="MSDK_POLICY_DEBUG" android:value="true"/>

    <!-- 为了符合最新的流程要求，MSDK_RESULT_FILE_NAME 配置从 MSDKCoreV5.17 版本开始默认关闭；-->
    <!-- 去掉此配置后，如果用户之前未同意过协议，覆盖安装的情况下也会弹协议，无论用户覆盖安装前是否登录过；-->
    <!-- 如果您是新接入MSDKPolicy的业务，也建议注释掉下面的 MSDK_RESULT_FILE_NAME 配置以满足最新要求。-->
    <!-- <meta-data android:name="MSDK_RESULT_FILE_NAME" android:value="itop_login.txt"/> -->
    <!-- 用于标记协议版本，如果协议有更新，则往上累加，请填写整数值 -->
    <meta-data android:name="MSDK_POLICY_VERSION" android:value="1" />

</activity>

注意事项：

• MSDK_POLICY_TARGET_ACTIVITY 用于指定在流程结束时，需要跳转的应用或者游戏的首个 Activity，MSDK_POLICY_TARGET_ACTIVITY 参数 value 值需要调整为游戏的启动 Activity。
  
• 其余参数请保持与示例一致。
  
• 请通过 android:screenOrientation 将 MSDKPolicyActivity 的屏幕方向配置为与您的游戏或者应用同向，以获得更好的体验。
  

重要：添加完如上配置后，需要将自己游戏中的 mainactivity 的 LAUNCHER 和 MAIN 标记删除

<activity
    android:name=".StartupActivity"
    android:configChanges="orientation|screenSize|keyboardHidden"
    android:launchMode="singleTask"
    android:taskAffinity="com.tencent.itop.example">
    <!-- 注释掉了 intent-filter 中的 MAIN 和 LAUNCHER，因为已不再是启动的第一个 activity -->
    <!-- <intent-filter>-->
    <!-- <action android:name="android.intent.action.MAIN" />-->
    <!-- <category android:name="android.intent.category.LAUNCHER"/>-->
    <!-- <category android:name="android.intent.category.LEANBACK_LAUNCHER" />-->
    <!-- </intent-filter>-->
</activity>

（2）MSDKPolicy分为两部分

用户协议：

在用户点击 App 图标启动游戏的时候，会拉起用户协议（如上图）。图中的协议内容部分可以配置，当前为业务提供了一套默认协议，如有修改麻烦联系法务确认风险评估。协议内容可以在资源文件 msdk_policy_content.html 中配置，仅支持基础的 html 标签。如果是棋牌类游戏接入，烦请自行联系法务确认棋牌类游戏的协议和链接地址，并做相应调整。

<!doctype html>
<head>
    <meta charset='UTF-8'>
    <meta name='viewport' content='width=device-width initial-scale=1'>
    <title></title>
</head>

<body>
<p>在您使用我们（腾讯）服务前，请您务必审慎阅读、充分理解 
    <a href='http://game.qq.com/contract.shtml'>腾讯游戏许可及服务协议</a>、
    <a href='http://game.qq.com/privacy_guide.shtml'>腾讯游戏隐私保护指引</a>、
    <a href='https://game.qq.com/privacy_guide_children.shtml'>腾讯游戏儿童隐私保护指引</a>和
    <a href="https://game.qq.com/zlkdatasys/privacy_SDK.html">第三方信息共享清单</a>的各条款。<strong>同时，您应特别注意前述协议中免除或者限制我们责任的条款、对您权利进行限制的条款、约定争议解决方式和司法管辖的条款。</strong>如您已详细阅读并同意 
    <a href='http://game.qq.com/contract.shtml'>腾讯游戏许可及服务协议</a>、
    <a href='http://game.qq.com/privacy_guide.shtml'>腾讯游戏隐私保护指引</a>、
    <a href='https://game.qq.com/privacy_guide_children.shtml'>腾讯游戏儿童隐私保护指引</a>和
    <a href="https://game.qq.com/zlkdatasys/privacy_SDK.html">第三方信息共享清单</a> ，请点击 “同意” 开始使用我们的服务。</p>
</body>

</html>

必要权限申请流程：

当用户点击同意后，进入权限说明页面，开始必要权限申请流程，如下图。

权限说明页面中的内容可以配置，业务需要梳理好自己 App 的所有权限，将其罗列到配置中，其中必要权限需要如上图内容标注清楚。配置文件为 msdk_permission_content.html，仅支持基本的 html 标签。

<p>为确保您的游戏体验，我们将在您使用我们的服务过程中申请以下权限，届时您可以选择同意或者拒绝开启相关权限，若是拒绝则会影响部分功能：</p>
<br/>
<p><strong>存储权限</strong></p>
<p>缓存图片/视频，降低流量消耗</p>
<br/>
<p><strong>⼿机/电话权限</strong></p>
<p>校验 IMEI&IMSI 码，防止账号被盗</p>
<br/>
<p><strong>位置权限</strong></p>
<p>获取您的位置信息，可以和附近的玩家一起游戏</p>
<br/>
</ul>

当用户点击权限说明页面中的确定按钮，开始申请 必要权限 。

此过程中，会轮询询问用户，以获取 必要权限。业务需要将自己 App 中所需要的必要权限配置到 values/values.xml 的 msdk_permission_list 中，例如。

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <array name="msdk_permission_list">
        <item>android.permission.ACCESS_FINE_LOCATION</item>
    </array>
</resources>

此配置中配置 必要权限。则，在上图中会弹框来申请配置的 必要权限（如未授权）。
上面配置的 位置权限 仅为示例，业务根据自身需求配置。需注意：当有多个权限时，建议将array置空，按需向用户申请权限。

从 MSDK5.23.001 版本开始，MSDKPolicy 插件权限说明页面支持配置化。
msdk_permission_content.html “置空” 或者 “被删除”，则不弹权限说明页面。用户在协议页面点击同意后，会直接进入游戏。

3.3 注意事项

1. 用户在协议页面点击同意后，会开启 TDM 上报打点数据和设备信息；
   
2. values.xml 的 msdk_permission_list 中的必要权限需要和 msdk_permission_content.html 中带高亮（必要）的权限一致；
   
3. 接入完成后，一定要做好关键路径测试，登录&关系链&分享&游戏中心启动&异账号，必须覆盖这些路径；
   

四、常见问题

1、关于 Android 端混淆配置文件 proguard-rules.pro 的注意事项

PIX 版本，大部分 java 类都是通过 JNI 反射调用的，当业务开启代码混淆后，可能会导致部分反射找不到类或方法。当业务在 gradle 打包插件时，业务需注意 MSDK proguard-rules.pro 文件新增的内容。