01/10/2025 10:53:00

iOS

I. Project Configuration

1.1 File List

1.2 Project Configuration

1. Framework Search Paths adds the path of MSDK's related framework
2. Enable Bitcode is set as No
3. Add the following libraries in the project:

    libz.tbd
    libsqlite3.0.tbd
    libstdc++.tbd
    libc++.tbd
    Security.framework
    SystemConfiguration.framework
    GameKit.framework
    AppTrackingTransparency.framework  (xcode 12 and later versions)
   

4. In the project's "Build Settings-> Linking-> Other Linker Flags", add -ObjC

1.3 IDFA

In iOS 14, Apple has further tightened user privacy permissions. When you collect IDFA, you are required to add a new configuration in info.plist and to fill in the purpose of collecting IDFA. When the IDFA acquisition interface is called, a notification featuring "Ask the user whether to authorize this" will pop up. If the user does not authorize this, the collected IDFA will be a string of meaningless 00000-000000000-000000. IDFA acquisition is modularized. By adding MSDKSensitivity.framework, developers can access this function on demand.
(1) 'Xcode-Build Phases-Link Binary With Libraries' adds 'AppTrackingTransparency.framework'.
Apple previously required that "getting IDFA on App iOS 14 requires an Apple permission request pop-up window to pop up through the AppTrackingTransparency framework". On September 3, 2020, Apple issued a notice, announcing that the implementation of the new IDFA policy was postponed to early 2021, and the default behavior of IDFA in the iOS system was changed to "Acquisition of IDFA is allowed by default (the same as the previous iOS 13)". Therefore, during the period when the new IDFA policy is not implemented, in order to obtain IDFA normally and not to affect games that have not been adapted to the pop-up window, MSDKV5.12 version starts to add the MSDK_APP_TRACKING_ENABLE configuration item in MSDKConfig.ini, whose default value is 0.
When MSDK_APP_TRACKING_ENABLE is set to 1, MSDK uses the AppTrackingTransparency framework to obtain the user's authorization result. If the user does not authorize this, MSDK returns "00000000-0000-0000-0000-000000000000" and does not access Apple IDFA API.
When MSDK_APP_TRACKING_ENABLE is set to 0, MSDK directly accesses Apple IDFA API.
The property of AppTrackingTransparency.framework needs to be set to optional. If the 'required' property is used, a crash may occur on devices installed with iOS 13 and earlier versions.
(2) Add key Privacy-Tracking Usage Description in info.plist, and fill the reason for using IDFA into 'value'.

1.3.1 How to not collect IDFA

Applicable version: MSDK V 5.12 and later versions

Since Apple does not allow children's games to collect IDFA, MSDK adopts a plug-in method to obtain IDFA. When the game is not allowed to collect IDFA, the game can delete MSDKSensitivity.framework

If you use Xcode 12 to compile your project, you need to delete AppTrackingTransparency.framework in the project

• Delete Plugins/iOS/GCloudSDK/MSDKCore/MSDKSensitivity.framework

UnrealEngine

• Delete Plugins/OneSDKPlugins/MSDKCore/Source/MSDKCore/lib/iOSMSDKSensitivity.embeddedframework.zip file
• Delete the following lines in Plugins/OneSDKPlugins/MSDKCore/Source/MSDKCore/MSDKCore.Build.cs file

//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

II. Frame Operation Example

2.1 Initialization

In AppDelegate.mm file, add MSDK's key points of the lifecycle

#import <MSDKCore/MSDKCore.h>

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

    // Login callback, which is the logic to handle account inconsistency; so it is needed to set the callback when the app starts
    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 Interface Calling Method

1) Create a callback listener

Take Login as an example. Implement MSDKLoginObserver interface to create a listener instance, as follows:

class MyLoginObserver: public MSDKLoginObserver {
    // Login callback, including login, bind, autologin, switchuser, etc.
    void OnLoginRetNotify (const MSDKLoginRet &loginRet)  {
        if (loginRet.retCode == MSDKError::NEED_REALNAME) {
            return;
        }
        handleCallback(loginRet, loginRet.methodNameID);
    };

    // Logout callback; application wakeup callback
    void OnBaseRetNotify (const MSDKBaseRet &baseRet)  {
        if (baseRet.methodNameID == kMethodNameWakeUp) {
            handleDiffAccount(baseRet);
            return;
        }

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

If login succeeds, the system will return SUCCESS; if login fails, the system will return the corresponding error code, and you can process the error according as your need.

2) Set callback listener

Set the listener through SetLoginObserver of MSDKLogin class, as shown as follows:

MSDKLogin:: SetLoginObserver (new MyLoginObserver ());

3) Call API

The MSDK interfaces are designed by different modules. Before calling them, please find the corresponding module, such as Login, Friend, WebView, etc. Taking Login as an example, the call example is as follows:

// Login the channel according to the channel settings
permissionList = @"snsapi_userinfo,snsapi_friend,snsapi_message";
//Login mSelectedChannel channel
MSDKLogin:: Login (self.currentChannel.UTF8String, permissionList.UTF8String, self.currentSubChannel.UTF8String);

Note:

• Different modules have their own Observer, their return codes are not the same, but their call methods are similar
• One module has only one Observer. The last one takes effect after multiple settings
• In case of account inconsistency, the login module sets Observer, and it is also needed to set a callback in the entry didFinishLaunchingWithOptions lifecycle.
  

2.3 Invoke the special information control interface

Starting from MSDK5.21, the special information switch is controlled by the game itself. Before the switch is turned on, MSDK itself as well as Beacon, QQ OpenSDK and Bugly components cannot obtain special information; the game needs to automatically invoke MSDK's special information control interface to enable the switch for allowing to get the information after the user checks to agree to the relevant clauses of Tencent Games User Agreement.

2.3.1 Special information switch

1) Interface declaration

    // Set whether to allow the collection of special information
    MSDK_EXPORT_UE static void SetCouldCollectSensitiveInfo(bool couldCollect);

2）Demo code

    MSDKSensitive::SetCouldCollectSensitiveInfo(true);

3) Warning

• The game must actively invoke the interface after a user checks to agree to the relevant clauses of the agreement.
  
• [Important] QQ OpenSDK 3.5.7 has updated the permission-related functions. The access party cannot use the functions of QQ OpenSDK without invoking the authorization of SetCouldCollectSensitiveInfo. The log will report an error like "The user is not authorized and is temporarily unable to use QQ's login, sharing and other functions".
  
• When MSDK-QQ related functions are not used, MSDK will not set QQ OpenSDK permissions.