10/28/2024 17:13:24

MSDK Policy 接入和升级指引

一、 Policy 组件说明

MSDK Policy 组件是 MSDK 团队为业务提供的启动时，弹窗通用解决方案，主要用于解决合规要求中的启动时，用户协议及权限处理相关内容。参考 UI 界面如下

二、 Android 接入指引

2.1 Policy 接入升级指引

2.1.1 基础环境配置

2.1.1.1 引入 SDK 插件包

MSDK V5 默认携带了 MSDK Policy 组件，业务无需处理

2.1.1.2 请求 MSDK 配置服务器地址

在 MSDK 的配置文件中，添加或确认 MSDK_POP_URL 配置。该配置为 MSDK 弹窗服务器地址，用于下发弹窗规则。
配置文件一般在 assets 目录下，文件名：

MSDKConfig.ini

当前 MSDK 有四个环境公有集群环节：

测试域名： https://pop-test.itop.qq.com
业务联调域名： https://pop-hktest.itop.qq.com
国内正式域名：https://pop-release.itop.qq.com
新加坡正式域名：https://pop-sg.itopsdk.com

业务需要跟进安装包类型进行配置，如国内正式环境，配置信息如下：

MSDK_POP_URL = https://pop-release.itop.qq.com

如果有其他独立部署需求，请与我们联系！

2.1.2 配置 Policy 主 Activity

2.1.2.1 版本升级

如果之前有接入过旧版本 MSDKPolicy，升级到新版本 MSDK 时，仅需修改 AndroidManifest.xml 中的 Policy 的 Activity 配置

V1 版本	V2 版本
com.tencent.gcloud.msdk.core.policy.MSDKPolicyActivity	com.tencent.gcloud.msdk.core.policy.MSDKPolicyV2Activity

其他配置保存不变即可

2.1.2.2 新接入

注意：该方案需要修改游戏的主 Activity，项目需要跟进自身情况进行对应的主 Activity 逻辑调整。

对于新接入业务，则需在 AndroidManifest.xml 添加一个 Activity 配置：

<activity android:name="com.tencent.gcloud.msdk.core.policy.MSDKPolicyV2Activity"
    android:configChanges = "keyboard|keyboardHidden|screenLayout|screenSize"
    android:launchMode="singleTask"
    android:theme="@style/MSDKPolicyTheme"
    android:exported="true">
    <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.tencent.msdk.example.StartupActivity" />
    <meta-data android:name="MSDK_POLICY_DEBUG" android:value="true"/>
    <!-- 下面这个 MSDK_RESULT_FILE_NAME 配置从 MSDKCore V5.17 版本, V3-3.3.19 版本开始默认关闭 -->
    <!-- 去掉此配置后，如果用户之前未同意过协议，覆盖安装的情况下都必须弹协议-->
    <!-- <meta-data android:name="MSDK_RESULT_FILE_NAME" android:value="itop_login.txt"/> -->
    <!-- 如需关闭 TDM 上报，需要将下面的 MSDK_POLICY_TDM_REPORT_DISABLE 开关设置为 true-->
    <!-- <meta-data android:name="MSDK_POLICY_TDM_REPORT_DISABLE" android:value="false"/> -->
</activity>

name 固定为 com.tencent.gcloud.msdk.core.policy.MSDKPolicyV2Activity
configChanges 建议保持，如果有其他需求也可以根据业务需求调整
launchMode 一般为 singleTask。更多信息请参考：https://developer.android.com/guide/topics/manifest/activity-element
theme 可以调整为业务自己的主题
intent-filter 示例中的为配置为启动 Activity，业务可根据自身情况进行确认后调整。注意：一个 App 只能有一个主 Activity
MSDK_POLICY_TARGET_ACTIVITY 游戏的原主 Activity，Policy 组件会在完成逻辑后进行跳转
MSDK_RESULT_FILE_NAME 建议保持默认值，如有变更请与我们进行确认
MSDK_POLICY_TDM_REPORT_DISABLE 上报用户开启、关闭日志数据，一般用于监控和排查问题，视情况自行关闭

2.1.3 自定义 Policy 内容

2.1.3.1 调整协议内容

如需替换 Policy 展示的文字内容，则可按下面步骤处理：
1、自行开发一个离线 HTML用于展示 Policy 内容，然后将其放在 assets 目录下
2、调整 MSDK Core 包下的 assets/popup 目录下 MSDKPopupLocal.config 配置文件
文件格式：JSON
调整文件：将 scene = MSDKPolicy 节点为中的 uri 指向需要替换的业务自定义的 HTML 文件路径
调整文件签名：计算自定义的 HTML 文件的 MD5 值，将其填入到 sig 字段中
注意：这里的路径是从 assets 开始，如 HTML 文件放在 assets 目录下，则 uri 为 xxx.html；文件放在assets/popup目录下，则 uri 为 popup/xxx.html
至此，就完成了policy内容的替换，完成后的配置参考如下：

另外，MSDK 支持在管理端上配置并下发（请联系我们开发和确认）

2.1.3.2 【可选】调整权限内容

同上，如果需要使用 MSDK 的权限弹窗，也可以参考上述配置自行进行调整。

三、 iOS 接入指引

3.1 Policy 接入指引

3.1.1 基础环境配置

3.1.1.1 引入 SDK 插件包

MSDK V5 版本已经默认携带了 MSDK Policy 组件，业务无需单独处理

3.1.1.2 请求 MSDK 配置服务器地址

在 MSDK 的配置文件中，添加或确认 MSDK_POP_URL 配置。该配置为 MSDK 弹窗服务器地址，用于下发弹窗规则。
配置文件名如下：

MSDK V5 版本：MSDKConfig.ini (在MSDKAppSetting.bundle中)

当前 MSDK 有四个环境公有集群环节：

测试域名： https://pop-test.itop.qq.com
业务联调域名： https://pop-hktest.itop.qq.com
国内正式域名：https://pop-release.itop.qq.com
新加坡正式域名：https://pop-sg.itopsdk.com

业务需要跟进安装包类型进行配置，如国内正式环境，配置信息如下：

MSDK_POP_URL = https://pop-release.itop.qq.com

如果有其他独立部署需求，请与我们联系！

3.1.2 MSDKV5 接入 policy

3.1.2.1 unity 接入 policy

MSDKPolicy对相关联应用启动的各个生命周期方法进行了拦截，优先执行MSDKPolicy的弹窗逻辑，等到点击弹窗“同意”按钮后，恢复执行原有的生命周期函数，保障用户同意隐私协议前应用不进行初始化。
接入步骤：

将MSDKPolicyDelegate.h 及 MSDKPolicyDelegate.mm放入Assets/Plugins/iOS目录下（注：MSDKPolicyDelegate文件见附录示例）；
在GCloudSDK/Editor/XUPorter/XCodePostProcess.cs文件中，将代码“EditorCode4StopLaunching(pathToBuiltProject);”注释放开。
在Info.plist中配置游戏对应的MSDK_POP_URL、MSDK_GAME_ID 以及 MSDK_SDK_KEY。

3.1.2.2 ue 接入 Policy：

接入步骤：

在Info.plist中配置游戏对应的MSDK_POP_URL、MSDK_GAME_ID 以及 MSDK_SDK_KEY。
在IOSAppDelegate的分类中，仿照IOSAppDelegate+MSDK.mm的逻辑进行相关生命周期的拦截与处理：
hook以下关键生命周期方法：
application:didFinishLaunchingWithOptions:
application:openURL:options:
application:openURL:sourceApplication:annotation:
application:continueUserActivity:restorationHandler:

调用showPolicyPopup方法，并在用户完成授权的回调中，通过反射回调主类 IOSAppDelegate 的对应生命周期方法，例如：

- (BOOL)application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary*)launchOptions
{
    showPolicyPopup(^(id param){
        dispatch_async(dispatch_get_main_queue(), ^() {
        //这里反射调用主类的对应方法，注意传参中的函数名要与当前所在函数名一致
            invokeOriginalMethod([IOSAppDelegate class], @"application:didFinishLaunchingWithOptions:", ^(IMP imp, SEL sel){
                ((BOOL(*)(id, SEL, id, id))imp)(self, sel, application, launchOptions);
            });
            if (!isPolicyProcessed) {
                invokeOriginalMethod([IOSAppDelegate class], @"applicationDidBecomeActive:", ^(IMP imp, SEL sel){
                    ((void(*)(id, SEL, id))imp)(self, sel, application);
                });
                isPolicyProcessed = true;
            }
        });
    });
     return YES;
}

2.反射的方式可仿照以下函数实现

static void invokeOriginalMethod(Class clazz, NSString* methodName, void(^callback)(IMP imp, SEL sel)) {
    if (clazz) {
        unsigned int methodCount;
        Method *methodList = class_copyMethodList(clazz, &methodCount);
        IMP currentImp = NULL;
        SEL currentSel = NULL;
        int index = 0;
        for (NSInteger i = 0; i < methodCount; i++) {
            Method method = methodList[i];
            NSString *currentMethodName = [NSString stringWithCString:sel_getName(method_getName(method))
                                            encoding:NSUTF8StringEncoding];
            if ([methodName isEqualToString:currentMethodName]) {
                currentImp = method_getImplementation(method);
                if (currentImp != NULL && index != 0) {
                    currentSel = method_getName(method);
                    callback(currentImp, currentSel);
                    break;
                }
                index++;
            }
        }
        free(methodList);
    }
}

3.在下列生命周期方法中拦截业务的处理逻辑：
applicationDidBecomeActive
applicationWillResignActive
applicationDidEnterBackground
applicationWillEnterForeground
applicationWillTerminate

例如：

- (void)applicationWillResignActive:(UIApplication*)application
{
    if (isPolicyProcessed) {
        invokeOriginalMethod([IOSAppDelegate class], @"applicationWillResignActive:", ^(IMP imp, SEL sel){
            ((void(*)(id, SEL, id))imp)(self, sel, application);
        });
    }
}

注意：需要配置编译规则，保证处理后的分类在IOSAppDelegate所有分类中最后一个参与编译。如果只有当前这一个分类，则无需保证其编译的先后顺序。
如下图中，在 xcode 中将 IOSAppDelegate+MSDK.mm 放在列表最后

3.1.3 自定义 Policy 内容

3.1.3.1 调整协议内容

如需替换 Policy 展示的文字内容，则可按下面步骤处理：

1、自行开发一个离线 HTML用于展示 Policy 内容，然后将其放在 assets 目录下
2、调整 MSDK Core 包下的 ThirdSDK/MSDKPopupResource.bundle 目录下 MSDKPopupLocal.config 配置文件
文件格式：JSON
调整文件：将 scene = MSDKPolicy 节点为中的 uri 指向需要替换的业务自定义的 HTML 文件路径
调整文件签名：计算自定义的 HTML 文件的 MD5 值，将其填入到 sig 字段中
注意：这里的路径是从 MSDKPopupResource.bundle 的根目录开始，如 HTML 文件放在根目录下，则 uri 为 xxx.html
至此，就完成了policy内容的替换，完成后的配置参考如下：