概述

Unity引擎及其生态系统提供了世界一流的跨平台游戏开发平台，使多平台游戏开发更快速，高效，越来越多的开发者使用Unity引擎开发游戏。

MSDK for Unity 借助Unity引擎强大的跨平台能力，对Android、iOS版本MSDK进行一致封装，屏蔽平台差异，对Unity游戏提供一致的接入体验。MSDK for Unity 还提供了一系列辅助接入插件，例如使用MSDK部署插件，您可以在填写简单的游戏信息后一键完成MSDK配置部署工作，并编写少量C#代码即可使用MSDK提供的能力。

MSDK for Unity 除了提供登录，好友关系链，分享，加绑群的能力外，还提供了大量的增值拓展能力，包括公告系统、内置浏览器、腾讯移动推送 TPNS、数据上报、LBS、Crash分析。这些增值模块使游戏开发者能够轻松构建游戏额外能力，更专注于游戏本身的体验，为玩家带来更优质的游戏。

接入向导

1 前置条件

1) 首先您需要确认是否已获取MSDK Unity版本，如果您未获取可点击下面链接进行下载。

MSDK for Unity 下载

2) 需要已安装Java环境，并配置环境变量。

配置系统变量(参考):
JAVA_HOME : D:/Program Files/java/jdk1.6.0_25
Path : C:\Windows\system32;C:\Windows;%JAVA_HOME%\bin;%JAVA_HOME%\jre\bin;
CLASSPATH : .;%JAVA_HOME%\lib\dt.jar;%JAVA_HOME%\lib\tools.jar;
更详细步骤请网上搜索"java 环境变量配置"

3) MSDK for Unity 需要Unity4.6.3及以上版本。

2 导入MSDK

MSDK的Unity版本包中包含示例 Example，及版本内容 Msdk。按以下步骤可快速导入MSDK。

1) 在Unity3D菜单中依次点击 : Assets->Import Package->Custom Package...
2) 选择MSDK的Unity版本包 : MSDK_Unity_<version>.unityPackage

其中version代表版本号，例如：MSDK_Unity_1.0.3u.unityPackage。

3) 64位和gradle的支持说明参考： Assets/Msdk/Editor/Librarys/Android3.2/Gradle 路径下文档说明

3 部署MSDK

导入MSDK后在Unity的菜单栏上可看到 "MSDK" 字样菜单。按下面步骤部署MSDK。

1) 依次点击 MSDK->Deploy Settings，可在 Inspector 面板呈现 MSDK 部署面板

2) 在MSDK部署面板填入游戏信息（包名，手Qappid，微信appid等）
3) 点击部署面板下方按钮 "Deploy MSDK" 即可完成MSDK的部署
4) 在Project面板，右点 Plugins 目录，选择 Refresh，使Unity完成对MSDK文件的加载

其中 MSDK 部署面板的游戏信息都是必填的，可通过您的游戏运营经理在飞鹰系统（dev.ied.com）上获取。

MSDK部署面板条目说明

注意事项

1) 当您的游戏信息发生变化时需要按 2 重新部署MSDK。
2) 您在部署MSDK之前，如果在"Assets/Plugin/Android"目录有"AndroidManifest.xml"、"project.properties"这两个文件，则在部署MSDK时不会替换掉，而是生成副本"Copy_AndroidManifest.xml"、"Copy_project.properties"。您需要参考副本文件手动修改"AndroidManifest.xml"、"project.properties"。
3) Unity 导出的xcode工程，必须连接真机调试。
4)MSDK返回的回调信息中，其字符串编码均为标准UTF8编码。

4 配置游戏信息

依次点击 MSDK->Config Settings，可呼出 MSDK 模块配置面板，包含环境选择，公告开关，推送开关等内容。 各配置项旁有个问号，鼠标悬浮在其上可展现此项配置的详细说明。

MSDK配置面板条目说明

2.16.0及其以上版本注意事项：

从2.16.0之前的版本升级到2.16.0配置文件msdkconfig.ini需要进行如下修改

1.增加了MSDK域名配置（游戏不需要修改直接copy到配置文件里面）

;以下配置为msdk内部使用，游戏无需关注
MSDK_ENV_TEST_URL=http://msdktest.qq.com
MSDK_ENV_RELEASE_URL=http://msdk.qq.com

2.增加域名选择配置（游戏根据情况选择正确的环境）

;正式环境与测试环境选择，test为测试环境, release为正式环境
MSDK_ENV=test

3.删除原来的域名配置方案（删除MSDK_URL=xxxxx）

;正式环境与测试环境选择，msdktest.qq.com为测试环境域名，msdk.qq.com为正式环境域名
MSDK_URL=http://msdktest.qq.com (删除)

可以参考MSDKDemo的配置文件

IDFA iOS 14 说明

适用版本： MSDK V3.3.15 及以后版本

在 iOS 14 Apple 进一步收紧用户权限，获取 IDFA 需要弹出用户授权弹窗，并在 info.plist 中新增配置填写获取 IDFA 的用途说明，业务可自行按需适时调用获取 IDFA 接口给用户弹出通知，询问用户是否授权，如果用户不授权，则获取的 IDFA 为一串没有意义的 00000-000000000-000000。IDFA获取模块化，新增MSDKSensitivity.framework，业务可按需接入。

• Xcode - Build Phases - Link Binary With Libraries 新增 AppTrackingTransparency.framework。
• Info.plist 中新增 key Privacy - Tracking Usage Description ，value 填写使用 IDFA 原因。

调用如下API给用户弹授权弹窗：

#import <AppTrackingTransparency/AppTrackingTransparency.h>
if (@available(iOS 14.0, *)) {
    [ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status) {

    }];
}

MSDK 从3.3.16版本开始提供了开关兼容 IDFA 的获取，如下说明：

在开发工程的 info.plist 添加 键 MSDK_APP_TRACKING_ENABLE 和值 YES 或者 NO

• YES ：业务仍需适时自行调用上述 AppTrackingTransparency.framework API 给用户弹授权弹窗，询问用户是否允许获取 IDFA，MSDK 也会调用相关 API 查询用户的授权情况，只有用户授权了才会调用接口获取 IDFA，否则直接返回没意义的00000-000000000-000000。
• NO : MSDK 直接调用 Apple API 获取 IDFA接口。

不添加 MSDK_APP_TRACKING_ENABLE 的默认行为为 NO。

如需删除 MSDK 自身的 IDFA 相关，可按如下操作：

+ 删除 info.plist 中 IDFA 的声明 + 删除 MSDKSensitivity.framework + 删除 AdSupport.framework + 删除 AppTrackingTransparency.framework

CAID 说明

适用版本： MSDK V3.3.17 及以后版本

CAID：是国内广告协同推广的一套 IOS 设备 ID，苹果 IDFA 无法读取后，解决广告归因的问题。Unity 版本脚本自动集成 CAID 所依赖的 tgpasimple.framework，若业务不需要 CAID 能力，可自行去除 TGPA 组件 tgpasimple.framework。

注意事项：

• CAID 的获取和上报仅支持 iOS 9.0 及以上系统，iOS 9.0 以下系统 TGPA 组件无法获取 CAID。
• 因 CAID 的获取需要访问网络，对于首次安装或者卸载重装的场景，可能存在 CAID 获取和上报失败的情况，失败后会重新获取，下次启动登录可见。

5 初始化代码

1) 引入MSDK库

在需要使用MSDK接口的C#脚本中引入MSDK库

using Msdk;

2) 设置PC调试桩环境

PC调试桩环境是MSDK为Unity版本定制的虚拟环境，在PWindows、Mac环境下调试时会返回虚拟的MSDK数据(登录回调，公告数据等)，可以方便游戏在电脑下快速验证MSDK相关逻辑。

a) 在脚本中开启PC调试桩环境。

WGPlatform.SetPCDebug(true);

b) 依次点击MSDK菜单 MSDK -> PC Environment Settings，在Inspector面板设置登录、分享等事件的虚拟回调结果用以验证游戏逻辑。

3) 注册登录回调、平台拉起回调

因登录回调、平台拉起回调可在游戏未调用相关接口时触发, 所以需要在游戏初始化MSDK前注册。 - 登录回调：登录事件结果的通知，游戏在手Q/微信的登录态以登录回调为准，详细设置参考登录模块回调设置。 - 平台拉起回调：手Q/微信中拉起游戏时会回到此回调，回调中包含拉起的账号，平台透传数据等信息，详细设置参考登录模块异账号处理。

MsdkEvent.Instance.LoginEvent += (LoginRet loginRet) =>
{
    switch (loginRet.flag)
    {
    case eFlag.eFlag_Succ:
    // 登录成功, 可以读取各种票据
    // 游戏TODO：进入游戏
        int platform= loginRet.platform;
        if((int) ePlatform.ePlatform_Weixin == platform) {
            loginState = "微信登录成功";
        } else if((int) ePlatform.ePlatform_QQ == platform) {
            loginState = "QQ登录成功";
        } else if((int) ePlatform.ePlatform_QQHall == platform) {
            loginState = "大厅登录成功";
        } else if((int) ePlatform.ePlatform_Guest == platform) {
            loginState = "游客登录成功";
        }
        break;

    // 游戏TODO：对登录失败情况分别进行处理，一般均为回登录页面引导用户重新授权
    case eFlag.eFlag_QQ_UserCancel:
    // 玩家取消授权
    case eFlag.eFlag_QQ_LoginFail
    // QQ登录失败
    case eFlag.eFlag_QQ_NotInstall
    // 未安装QQ
    case eFlag.eFlag_Local_Invalid:
    // 自动登录失败,包含本地票据过期, 刷新失败登等所有错误
    case eFlag.eFlag_WX_UserCancel:
    // 玩家取消授权
    case eFlag.eFlag_WX_NotInstall:
    // 未安装微信
    case eFlag.eFlag_WX_NotSupportApi:
    // 微信版本不支持
    case eFlag.eFlag_WX_LoginFail:
    //微信登录失败
    default:
        loginState = "登录失败";
        message = loginRet.ToString();
        break;
    }
};

MsdkEvent.Instance.WakeupEvent += (WakeupRet wakeupRet) =>
{
    // TODO GAME 这里增加处理异账号的逻辑
    if (eFlag.eFlag_Succ == wakeupRet.flag || eFlag.eFlag_AccountRefresh == wakeupRet.flag) {
        // 本地账号登录成功可直接进入游戏
        // 游戏TODO：进入游戏逻辑
        if((int) ePlatform.ePlatform_Weixin == wakeupRet.platform) {
            loginState = "微信登录成功";
        } else if ((int) ePlatform.ePlatform_QQ == wakeupRet.platform) {
            loginState = "QQ登录成功";
        } else if((int) ePlatform.ePlatform_QQHall == wakeupRet.platform) {
            loginState = "大厅登录成功";
        }
    } else if (eFlag.eFlag_UrlLogin == wakeupRet.flag) {
        // 本地无账号信息，自动用拉起的账号登录，登录结果在OnLoginNotify()中回调
    } else if (eFlag.eFlag_NeedSelectAccount == wakeupRet.flag) {
        // 游戏TODO：异账号时，游戏需要弹出提示框让用户选择需要登录的账号，并根据用户的选择调用WGSwitchUser接口
        Debug.Log("diff account");
        isShowDiffAcount = true;
        message = "异账号！";
    } else if (eFlag.eFlag_NeedLogin == wakeupRet.flag) {
        // 游戏TODO： 没有有效的票据，登出游戏让用户重新登录
        loginState = "登录失败";
        message = "请重新登录";
    } else {
        loginState = "未登录";
        message = "OnWakeupNotify    flag : " + wakeupRet.flag + "\ndesc : " + wakeupRet.desc;
        WGPlatform.Instance.WGLogout();
    }
};

4) 初始化MSDK的C#层并设置手Q授权项权限

初始化MSDK的C#层并设置手Q授权项权限后即完成Unity版本的初始化操作，之后可根据各个模块说明调用MSDK的接口，并根据6打包游戏包验证真实环境结果。

WGPlatform.Instance.Init();
WGPlatform.Instance.WGSetPermission(ePermission.eOPEN_ALL);

注意:

若未调用 WGSetPermission，可能会导致拉取手Q好友时出现 100030 错误，详细参考登录模块概述部分的授权页说明。

6 导出游戏包

完成MSDK的部署和配置后可直接导出游戏Android的安装包或iOS的Xcode工程。

Android

对于Android打包，这里提供三种方式供参考。第一种可直接在Unity中打出Apk包最为方便；如果需要修改原生代码建议用第三种方法导出游戏自己的Jar包再到Unity中导出Apk，这样兼容性更好且便于游戏更新版本和SDK。

1) 导出Android安装包

如游戏不需要修改Android原生代码，可直接在Unity中导出Apk安装包，步骤如下：
a) 修改游戏appid等信息，点击“Deploy MSDK”，对比Copy_AndroidManfest.xml文件修改AndroidManifest.xml文件的信息
b) 点击 File->Build Settings... 呼出Unity编译设置面板
c) 在 Platform 条目选择 Android 平台，点击 Play Settings... 配置Android打包信息
d) 在 Other Settings 条目配置游戏包名(Bundle Identifier)、版本号(Bundle Version，Bundle Version Code)
e) 在 Publishing Settings 配置游戏的 Keystore证书（MSDKSample的证书位于Assets/Example/debug.keystore，密码为android，别名为androiddebugkey，别名密码为android）
f) 最后在 Build Settings 面板点击 Build 即可导出Android安装包

2) 导出Android工程

如果游戏需要接入其他Android原生组件或修改java代码可以按以下方法导出Android工程并修改：
a) 修改游戏appid等信息，点击“Deploy MSDK”，对比Copy_AndroidManfest.xml文件修改AndroidManifest.xml文件的信息
b) 点击 File->Build Settings... 呼出Unity编译设置面板
c) 在 Platform 条目选择 Android 平台, 勾选“Google Android Project”，点击 Export 导出Android工程
d) 用Eclipse打开刚导出的Android工程，新建一个Activity并继承com.tencent.msdk.adapter.MsdkActivity
e) 在AndroidManifest.xml中调整启动Activity为刚才新建的Activity，然后就可以自由集成其他组件、修改java代码了

注意：

1) 新建的Activity不要忘记在AndroidManifest.xml中声明 2) Override Activity生命周期时，请调用父类的生命周期，例如：

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    ……
}

3) 游戏自定义原生代码打出Jar包，再集成到Unity中打出Apk

a) 首先游戏需要有一个Android工程(新建或已有)
b) 在Unity IDE的MSDK部署面板，配置好游戏信息，点击”Deploy MSDK”, 对比Copy_AndroidManfest.xml文件修改AndroidManifest.xml文件的信息
c) 为了1步骤的Android工程能够调用Unity和MSDK的原生接口，需要添加Unity和MSDK的Jar包到 /libs 目录下

Unity原生Jar包：Assets/Msdk/Editor/Librarys/Android2.14/UnityClasses.jar (或使用Unity安装目录中的Jar包)
MSDK原生Jar包: Assets/Plugins/Android/MSDKLibrary/libs/MSDK_Android_<版本信息>.jar (例如MSDK_Android_2.14.4a_svn69363.jar)
MSDK Unity适配Jar包: Assets/Plugins/Android/libs/msdk_unity_adapter_<版本号>.jar (例如msdk_unity_adapter_1.0.4u.jar)

d) 在步骤1的Android工程中新建MainActivity类，继承com.tencent.msdk.adapter.MsdkActivity类。启动入口Activity设置为MainActivity。在此Android工程中实现并调用各种原生方法与接口。
e) 在Android工程完成原生方法的调用后，将游戏实现的原生代码导出为Jar包，并放入Assets/Plugins/Android/libs中，即可集成到游戏Apk。

iOS

关于iOS打包，首先必须在MacOS中用Unity导出Xcode工程，再到Xcode中编译出ipa游戏安装包。

导出Xcode工程

在Unity中导出Xcode工程后，使用Xcode打开并修改签名证书即可编译运行或导出安装包。

a) 在 Build Settings 面板 Platform 条目选择 iOS 平台，点击 Play Settings... 配置iOS打包信息
b) 在 Other Settings 条目配置游戏包名(Bundle Identifier)、版本号(Bundle Version)，Scripting Backend 选择 IL2CPP，Target iOS Version 选择 6.0 及以上

c) 在 Build Settings 面板点击 Build 即可导出Xcode工程
d) 在Xcode的工程配置中，依次选择 Build Settings->Code Signing，在 Code Signing Identity 中配置游戏自己的iOS证书即可编译运行游戏

Android MSDKPolicy

1 MSDKPolicy插件

3.3.15a版本开始新增 MSDKPolicy 插件。MSDKPolicy 是一套通用的 Android 权限流程实现方案，整合了用户协议和权限授权流程，通过配置的形式供业务快速接入。业务可根据自身情况按需合入该插件。用户协议更新参考文档：https://docs.qq.com/doc/DSnlkYU5SZWhPYmNR

重要：如果项目中有接入 TDM 组件，则需要将 TDM 升级到版本：V1.9.000 或以上版本。

MSDKPolicy 的流程如下：

1.1 导入插件

MSDK 部署面板中勾选 ENABLE MSDKPolicy,MSDK部署完成后，需要将启动Activity调整为MSDKPolicyActivity，示例如下：

    <!-- MSDKPolicy 插件配置 -->
    <activity android:name="com.tencent.gcloud.msdk.core.policy.MSDKPolicyActivity"
        android:configChanges = "keyboard|keyboardHidden|screenLayout|screenSize"
        android:launchMode="singleTask"
        android:theme="@style/MSDKPolicyTheme">
        <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="com.example.wegame.MainActivity" />
        <meta-data android:name="MSDK_POLICY_DEBUG" android:value="true"/>
        <!-- 为了符合最新的流程要求，MSDK_RESULT_FILE_NAME 配置从 3.3.19 版本开始默认关闭 -->
        <!-- 去掉此配置后，如果用户之前未同意过协议，覆盖安装的情况下也会弹协议，无论用户覆盖安装前是否登录过 -->
        <!-- 如果您是新接入MSDKPolicy的业务，也建议注释掉下面的 MSDK_RESULT_FILE_NAME 配置以满足最新要求 -->
        <!--<meta-data android:name="MSDK_RESULT_FILE_NAME" android:value="WEGAMEDB2"/> -->
        <meta-data android:name="IS_MSDK_V5" android:value="false"/>
        <!-- 如果业务不想升级到 TDM 的合规版本，需要将下面的 MSDK_POLICY_TDM_REPORT_DISABLE 开关设置为 true，注意，打开后，MSDKPolicy 流程不会做 TDM 上报，流程无法被追踪-->
        <meta-data android:name="MSDK_POLICY_TDM_REPORT_DISABLE" android:value="false" />
        <!-- 用于标记协议版本，如果协议有更新，则往上累加，请填写整数值 -->
        <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 的屏幕方向配置为与您的游戏或者应用同向，以获得更好的体验。
• 为了符合最新的流程要求，MSDK_RESULT_FILE_NAME 配置从 3.3.19 版本开始默认关闭；去掉此配置后，如果用户之前未同意过协议，覆盖安装的情况下也会弹协议，无论用户覆盖安装前是否登录过。如果您是新接入 MSDKPolicy 的业务，也建议注释掉 MSDK_RESULT_FILE_NAME 配置以满足最新要求。

1.2 涉及文件

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

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

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

1.3 MSDKPolicy分为两部分

用户协议：

在用户点击 App 图标启动游戏的时候，会拉起用户协议（如上图）。图中的协议内容部分可以配置，当前为业务提供了一套默认协议，如有修改麻烦联系法务确认风险评估。协议内容可以在资源文件 \Assets\Msdk\Editor\Librarys\Android3.2\MSDKPolicy\assets\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 的所有权限，将其罗列到配置中，其中必要权限需要如上图内容标注清楚。配置文件为 \Assets\Msdk\Editor\Librarys\Android3.2\MSDKPolicy\assets\msdk_permission_content.html，仅支持基本的 html 标签。 以下仅为示例，业务需要梳理好自己 App 的所有权限。

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

当用户点击权限请求页面中的确定按钮，开启 必要权限 的申请流程。

此过程中，会轮询询问用户，以获取 必要权限。业务需要将自己 App 中所需要的必要权限配置到 \Assets\Msdk\Editor\Librarys\Android3.2\MSDKPolicy\res\values\values.xml 的 msdk_permission_list 中。以下仅为示例，业务需要梳理好自己 App 中所需要的必要权限，例如：

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

此示例中配置了 地理位置 必要权限。则在上图中会弹框来申请这个权限（如未授权）。

V3.3.25 版本开始，msdk_permission_content.html 支持配置化。

msdk_permission_content.html “置空” 或者 “被删除”，则不弹 “权限说明” 页面。用户在协议页面点击同意后，会直接进入游戏。

1.4 测试验证

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

2 开关配置接口

Android 3.3.21 版本/iOS 3.3.22 版本 新增该接口，在用户同意用户协议条款之后，业务可调用该接口开启MSDK以及MSDK所包含的第三方组件(目前支持该能力的有灯塔和TBS组件)对相关信息的获取；在开关开启之前，MSDK不会获取相关信息。接口说明如下：

java接口：
MSDKSensitive.setCouldCollectSensitiveInfo(true);

c++接口：
/*
 * 设置是否允许获取相关信息
 */
void WGSetCouldCollectSensitiveInfo(bool couldCollect);

注意事项

• 在MSDK初始化之前，可调用java接口提前打开开关，避免个别上报缺失相关信息字段（iOS直接调用c++接口即可）
• 若在MSDK初始化之前，未调用java接口时，则MSDK初始化之后，必须调用c++接口
• 不支持多进程场景，建议对开关配置接口调用都放主进程，或者子进程自行调用组件的相关接口
• 【重点】手Q OpenSDK 3.5.7版本开始更新了权限相关功能，接入方未调用SetCouldCollectSensitiveInfo授权前无法使用手Q OpenSDK的各项功能。日志中会打印 “用户未授权，暂时无法使用QQ登录及分享等功能”。

3 设置信息字段接口

Android 3.3.21 版本/iOS 3.3.28 版本 新增设置信息字段接口，在用户同意用户协议条款之后，业务可自行获取相关信息字段，调用该接口设置到MSDK以及MSDK所包含的第三方组件(目前支持该能力的有灯塔组件)。接口说明如下：

java接口：
MSDKSensitive.setSensitiveInfo("{\"AndroidID\":\"xxx\", \"WiFiMacAddress\":\"xxx\", \"Model\":\"xxx\", \"Oaid\":\"xxx\", \"Imsi\":\"xxx\", \"Cid\":\"xxx\"}");

c++接口：
/*
 * 以json形式设置信息字段至各个组件SDK，目前支持{"AndroidID":"xxx","WiFiMacAddress":"xxx","Model":"xxx","Oaid":"xxx","Imsi":"xxx","Cid":"xxx"}
 */
void WGSetSensitiveInfo(const char *jsonInfo);

注意事项

Android

• 在MSDK初始化之前，可调用java接口提前设置相关信息，避免个别上报缺失相关信息字段
• 若在MSDK初始化之前，未调用java接口时，则MSDK初始化之后，必须调用c++接口
• AndroidID字段请务必设置（AndroidID 需业务自行获取），否则影响灯塔数据统计
• 灯塔、手Q互联OpenSDK、Bugly均需传入Model；Model非空（手Q互联OpenSDK从3.3.281版本开始支持，Bugly从3.3.29版本开始支持）

iOS

• 灯塔iOS目前支持 WiFiMacAddress、WiFiName、Idfa字段。

4 Apn & AndroidID & QImei & QImei36 采集配置接口开关

3.3.25 版本 新增 Apn & AndroidID & QImei & QImei36 采集配置接口开关，业务可按需自行配置这些字段是否允许采集（该接口功能与msdkconfig.ini文件中的MSDK_DENIED_COLLECT_LIST配置项为一个功能，但优先级高于后者）。接口说明如下：

    /**
    * 以json形式设置特别信息单字段开关，优先级小于总开关，目前支持设置AndroidID、Apn、QImei、QImei36
    * 参数示例{"AndroidID":true,"Apn":true,"QImei":true,"QImei36":true}
    *
    */
    void WGSetCollectSensitiveInfo(const char *jsonInfo);

Target API 31 升级指南

1. 背景

Google Play Store 要求 2022 年 8 月之后上线、11 月之后更新的 App 必须升级到 Target API 31。

官方参考资料：

• https://developer.android.com/google/play/requirements/target-sdk

Starting in August 2022, new apps must target API level 31 (Android 12) or above and adjust for behavioral changes. Wear OS apps must target API level 28 or higher.Starting in November 2022, app updates must target API level 31 or above and adjust for behavioral changes in Android 12.

• https://support.google.com/googleplay/android-developer/answer/11926878?hl=en

2. 如何升级到 Target API 31

简单说，将编译的 targetSdkVersion 的值修改为 31 即可

2.1 Android Studio 及 Gradle 编译工程

一般在 App 目录中的 build.gradle 文件中，修改 android -> defaultConfig ->targetSdkVersion 的值为 31 即可，如：

2.2 Unity 项目

在 Unity 菜单 File -> Build Settings ... 弹窗中，Platform 选中 Android，在 Player Settings ...

中打开 Inspector 面板中，找到 Other Settings -> Target API Level 中进行设定

2.3 UnrealEngine 项目

在 UnrealEngine 菜单 File -> Package Project -> Packaging Settings... 中打开弹窗，

并在找到 Platforms -> Android 配置项，修改对应的配置

3. 配置及处理

3.1 安全和隐私设置变更——位置信息

在 Android 12（API 级别 31）或更高版本中，用户可以请求该应用只检索大致位置信息（即仅给予应用ACCESS_COARSE_LOCATION权限），即使该应用请求 ACCESS_FINE_LOCATION 运行时权限也是如此。

关于请求位置权限的官方文档：https://developer.android.com/training/location/permissions#approximate-request

注意：必须在单个运行时请求中同时包含 ACCESS_COARSE_LOCATION 权限及 ACCESS_FINE_LOCATION 权限

3.1.1 权限声明

在 AndroidManifest.xml 文件中声明 ACCESS_COARSE_LOCATION 权限及 ACCESS_FINE_LOCATION 权限。

//权限声明
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

3.1.2 处理定位低精度的情况

当应用的 Target API 为31时，对于 Android12 的用户，若用户仅给予获取大致位置的权限，受 GPS 信号强度影响，可能导致定位的精度过低，甚至可能出现定位超时失败的情况，为提高定位成功率及精确度，业务可适当引导用户开启精确位置信息。

3.1.3 关于相关策略说明

为了提高定位的成功率，采用了两个系统 API 来获取附近的基站信息进行辅助定位，具体方式是：优先使用更高版本的 getAllCellInfo，若失败则使用 getCellLocation。此处需要对相关合规进行说明：若 getAllCellInfo 失败则会增加一次获取基站信息的接口调用。

3.2 组件导出的变更

当应用以 Android 12 或更高版本为目标平台，且包含使用 intent 过滤器的 activity、服务或广播接收器，则必须为上述组件显式地声明 `android:exported` 属性。MSDK 已经对内部各个组件进行了相应的处理，无需应用进行相关配置。

3.3 WebView 中的现代 SameSite Cookie 变更

当应用以 Android 12（API 级别 31）或更高版本为目标平台时，WebView 中会包含关于第三方 Cookie 处理方式的变更，应用需关注在需要时使用适当的值对 Cookie 中的 SameSite 属性进行显式的设置，详细的变更说明可参见下方链接。

关于WebView变更的官方文档：https://developer.android.com/about/versions/12/behavior-changes-12#samesite

3.4 关于包可见性的说明

若应用以 Android 11 或更高版本为目标平台，且有拉起其他应用进行登录、分享等操作的应用场景，则应用需要在自身的 AndroidManifest.xml 中添加‘queries‘元素，并声明相应的应用包名。

<manifest package="com.example.game">
    <queries>
        <!-- 指定QQ的包名，可拉起QQ相关的应用进行相应的操作 -->
        <package android:name="com.tencent.mobileqq" />
        <package android:name="com.tencent.tim" />
        <package android:name="com.tencent.minihd.qq" />
        <package android:name="com.tencent.qqlite" />
        
        
    	<!-- 指定微信的包名，可拉起微信进行相应的操作 -->
     	<package android:name="com.tencent.mm" />
		
      	...
      
    </queries>
    ...
</manifest>

关于包可见性的官方文档：https://developer.android.com/training/package-visibility/declaring

4. 升级注意事项

4.1 Gradle版本要求

Target API 升级到 30 及以上时，使用‘queries’标签时需要 Gradle 插件版本至少为 3.3.3，Gradle 版本至少为 4.10.1，若不符合条件，则编译时报 xml 文件合并的错误：

> Task :app:processDemoDebugManifest FAILED
> Error: Missing 'package' key attribute on element package at AndroidManifest.xml:...

解决方案：

升级 Android Gradle 插件版本到 3.3.3 或以上，Gradle 版本到 4.10.1 或以上。

MSDK 权限列表

Android

iOS

常见问题

注意事项：

MsdkActivity继承了UnityPlayerActivity,游戏主Activity继承MsdkActivity后无需在生命周期中再调用UnityPlayer的相关函数，例如onPause()、onResume()等，避免与MSDK冲突导致crash。

关于微信 OpenSDK iOS 15 系统的适配说明

Xcode13.0 以及以上版本编译出的 App 在 iOS 15.0 以及以上系统上被限制了 URL Scheme query 的数 量为 50。对于 plist 中 LSApplicationQueriesSchemes 配置的 scheme 数量超过 50 的 App,可能会导致：

1. 微信 OpenSDK 某些接口返回错误结果；
2. 无法使用 Universal Link 拉起微信，引发分享消息到微信后，应用名被添加 "未验证应用" 的问题。

使用 13.0 以及以上版本 Xcode 编译 App 的开发者需要适配以确保微信 OpenSDK 的正常使用。

背景

从 iOS 9 开始，iOS 支持在工程 plist 中配置 LSApplicationQueriesSchemes。

示例：

将其他 App 的 scheme 配置到 LSApplicationQueriesScheme 中后，可以通过以下代码判断是否可 以通过 scheme 跳转对于的 App。

 BOOL ret = [[UIApplication sharedApplication] canOpenURL:[NSURL URLWithString:@"weixin://"]];

在接入微信 OpenSDK 时，接入文档有要求在 LSApplicationQueriesScheme添加 weixin 和 weixinULAPI （如上面截图所示）。

iOS 15系统相关变更

和苹果确认， 在 iOS 15 系统上，使用 Xcode 13 编译出的 App, LSApplicationQueriesSchemes 的数量会限制为50个。

第 50 个之后的 scheme 配置会不生效，以下代码会返回 NO

BOOL ret = [[UIApplication sharedApplication] canOpenURL:[NSURL URLWithString:@"otherAppScheme://"]]; 

微信 OpenSDK 适配建议

如果 LSApplicationQueriesSchemes 配置的 scheme 数量小于 50,或者 "weixin" 和 "weixinULAPI" 这两个 sheme 在前 50,无需适配。

使用 Xcode 12 以及以下版本 Xcode 编译的 App 目前暂不需要适配。

确保 "weixin" 和 "weixinULAPI" 配置在 LSApplicationQueriesSchemes 的前 50。否则以下接口可能会在 iOS 15 系统上返回错误结果或者表现异常：

1. [WXApi isWXAppInstalled]:安装微信的情况下，也返回 NO
2. [WXApi isWXAppSupportApi]:支持的情况下，也返回 NO
3. [WXApi isWXAppSupportStateAPI]:支持的情况下，也返回 NO
4. [WXApi sendAuthReq:viewController:delegatecompletion]:会判断微信未安装，拉起网页授权。
5. 所有的接口都会无法使用 Universal Link 拉起微信，降级使用 scheme 拉起微信，导致未验证应用问题。