04/29/2024 11:54:52

接入教程（iOS）

一、工程配置

1.1 文件清单

1.2 配置工程

1. Framework Search Paths 增加 MSDK 相关的 framework 的路径；
2. Enable Bitcode 设置为 No ；
3. 在工程增加以下库：

    libz.tbd
    libsqlite3.0.tbd
    libstdc++.tbd
    libc++.tbd
    Security.framework
    SystemConfiguration.framework
    GameKit.framework
    AppTrackingTransparency.framework  (xcode 12 及以后版本)
   

4. 在工程 Build Settings->Linking->Other Linker Flags 中，新增 -ObjC

1.3 IDFA

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

（1）Xcode - Build Phases - Link Binary With Libraries 新增 AppTrackingTransparency.framework。

Apple 之前要求“App iOS 14 上获取 IDFA 需要通过 AppTrackingTransparency 框架弹出 Apple 许可请求弹窗”。2020 年 9 月 3 日 Apple 发布公告，宣布 IDFA 新政策推迟到 2021 年初实施，并更改了 iOS 系统 IDFA 的默认行为为“默认允许获取 IDFA（和之前的 iOS 13 一样）”。因此在 IDFA 新政策未实施的这段时间，为了能正常的获取 IDFA，不影响未做弹窗适配的游戏。MSDKV5.12 版本开始在 MSDKConfig.ini 中新增 MSDK_APP_TRACKING_ENABLE 配置项，默认值为 0。
MSDK_APP_TRACKING_ENABLE 置 1 时，MSDK 使用 AppTrackingTransparency 框架，获取用户授权结果，如果用户没授权，则用户返回 00000000-0000-0000-0000-000000000000 为 IDFA，不去访问 Apple IDFA API。
MSDK_APP_TRACKING_ENABLE 置 0 时，MSDK 直接访问 Apple IDFA API。
AppTrackingTransparency.framework 的属性需要设置为 optional，若使用 required 属性，在 iOS 13及以下设备上有可能会发生 crash。

（2）Info.plist 中新增 key Privacy - Tracking Usage Description ，value 填写使用 IDFA 原因。

1.3.1 如何不采集 IDFA

适用版本： MSDK V 5.12 及以后版本

由于 Apple 不允许儿童类游戏采集 IDFA，因此 MSDK 采用插件化方式获取 IDFA， 当游戏不被允许采集 IDFA 时，游戏可以删除 MSDKSensitivity.framework

如果在使用 Xcode 12 编译需要在工程中删除 AppTrackingTransparency.framework

Unity 插件位置 ：

• 删除 Plugins/iOS/GCloudSDK/MSDKCore/MSDKSensitivity.framework

UnrealEngine

• 删除 Plugins/OneSDKPlugins/MSDKCore/Source/MSDKCore/lib/iOSMSDKSensitivity.embeddedframework.zip 文件
• 删除 Plugins/OneSDKPlugins/MSDKCore/Source/MSDKCore/MSDKCore.Build.cs 文件中的以下几行

//IOSStart not delete
#if UE_4_22_OR_LATER 
PublicAdditionalFrameworks.Add(new Framework("MSDKSensitivity", "lib/iOS/MSDKCore/MSDKSensitivity.embeddedframework.zip", "MSDKAppSetting.bundle")); 
#else 
    PublicAdditionalFrameworks.Add(new UEBuildFramework("MSDKSensitivity", "lib/iOS/MSDKCore/MSDKSensitivity.embeddedframework.zip", "MSDKAppSetting.bundle")); 
#endif

二、框架运行实例

2.1 初始化

在 AppDelegate.mm 文件中加入 MSDK 的生命周期埋点。

#import <MSDKCore/MSDKCore.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Override point for customization after application launch.
    [[MSDKApplicationDelegate sharedInstance] application:application
                            didFinishLaunchingWithOptions:launchOptions];

    // 登录回调，处理异账号逻辑，所以需要在应用启动时设置回调
    MSDKLogin::SetLoginObserver(new MyLoginObserver());

    return YES;
}

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation {
    return [[MSDKApplicationDelegate sharedInstance] application:application openURL:url sourceApplication:sourceApplication annotation:annotation];
}

- (BOOL)application:(UIApplication *)application openURL:(nonnull NSURL *)url options:(nonnull NSDictionary*)options {
    return [[MSDKApplicationDelegate sharedInstance] application:application
                                                         openURL:url
                                                         options:options];
}

- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    [[MSDKApplicationDelegate sharedInstance] application:application didRegisterForRemoteNotificationsWithDeviceToken:deviceToken];
}

- (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error {
    [[MSDKApplicationDelegate sharedInstance] application:application didFailToRegisterForRemoteNotificationsWithError:error];
}

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo {
    [[MSDKApplicationDelegate sharedInstance] application:application didReceiveRemoteNotification:userInfo];
}

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
    [[MSDKApplicationDelegate sharedInstance] application:application didReceiveRemoteNotification:userInfo fetchCompletionHandler:completionHandler];
}

- (void)application:(UIApplication *)application didReceiveLocalNotification:(UILocalNotification *)notification {
    [[MSDKApplicationDelegate sharedInstance] application:application didReceiveLocalNotification:notification];
}

- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray * _Nullable))restorationHandler {
    return [[MSDKApplicationDelegate sharedInstance] application:application continueUserActivity:userActivity restorationHandler:restorationHandler];
}
#pragma mark - Orientation

- (UIInterfaceOrientationMask)application:(UIApplication *)application supportedInterfaceOrientationsForWindow:(UIWindow *)window{
    return [[MSDKApplicationDelegate sharedInstance] application:application supportedInterfaceOrientationsForWindow:window];
}

2.2 接口调用方式

1）创建回调监听

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

class MyLoginObserver : public MSDKLoginObserver {
    // 登录回调，包括 login、bind、autologin、switchuser 等
    void OnLoginRetNotify(const MSDKLoginRet &loginRet) {
        if (loginRet.retCode == MSDKError::NEED_REALNAME) {
            return;
        }
        handleCallback(loginRet, loginRet.methodNameID);
    };

    // 登出回调、应用唤醒回调
    void OnBaseRetNotify(const MSDKBaseRet &baseRet) {
        if (baseRet.methodNameID == kMethodNameWakeUp) {
            handleDiffAccount(baseRet);
            return;
        }

        if (baseRet.retCode == MSDKError::NEED_REALNAME) {
            return;
        }
        handleCallback(baseRet, baseRet.methodNameID);
    };
};

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

2）设置回调监听

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

MSDKLogin::SetLoginObserver(new MyLoginObserver());

3）调用API接口

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

//根据渠道设置登录渠道
permissionList = @"snsapi_userinfo,snsapi_friend,snsapi_message";
//登录mSelectedChannel渠道
MSDKLogin::Login(self.currentChannel.UTF8String, permissionList.UTF8String, self.currentSubChannel.UTF8String);

注：

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

2.3 调用特殊信息控制接口

从 MSDK5.21 版本开始，特殊信息开关相关能力由业务自行控制，开关开启之前 MSDK 自身以及灯塔、手Q OpenSDK 和 Bugly 组件将不会获取特殊信息；业务侧需在用户勾选同意腾讯游戏用户协议相关条款后主动调用 MSDK 特殊信息控制接口打开允许获取开关。

2.3.1 特殊信息开关

1）接口声明

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

2）示例代码

    MSDKSensitive::SetCouldCollectSensitiveInfo(true);

3）注意事项

• 用户勾选同意协议相关条款后务必主动调用该接口。
• 【重点】手Q OpenSDK 3.5.7版本开始更新了权限相关功能，接入方未调用 SetCouldCollectSensitiveInfo 授权前无法使用手Q OpenSDK的各项功能。日志中会报错“用户未授权，暂时无法使用QQ登录及分享等功能”。
• 未使用到 MSDK-QQ 相关功能时，MSDK 不会进行手Q OpenSDK 权限设置。