05/15/2024 15:19:45

Solution

1. What is Universal Link?

Universal Link is a mechanism introduced by Apple from iOS 9 to open up a skip between Web and App. When a link associated with App is opened in Safari or WebView, it will automatically skip to App without losing any parameter content. Universal Link solves some problems of URL Scheme:

(1) When the skip fails, the link will be opened directly in Safari/WebView;

(2) You can use Universal Link to unify the routing of both web and native sides;

(3) No prompt box will pop up in the skip, so the experience is better.

2. Use of Universal Link

To use Universal Link, you need to associate the domain name with App. The association is two-way:

(1) Authentication of App by the domain name: Put a json file named "apple-app-site-association" in the root directory of the web server. The file describes which path will skip to which app.

(2) Authentication of the domain name by App: Set "Associated Domains" in Xcode and add the domain name into it.

{            
    "applinks": {        
        "apps": [],    
        "details": [{    
            "paths": ["/app/*", "/qq_conn/1106977030/*"],
            "appID": "JBS4AWYMFX.com.tencent.itop.example"
        },     
        {    
            "paths": ["/reference2/*", "/qq_conn/1106388413/*"],
            "appID": "JBS4AWYMFX.com.tencent.imsdk2"
        }]    
    }        
}

Precautions:

(1) The domain name must access Universal Link through HTTPS before it takes effect;

(2) apple-app-site-association can only be placed under the domain name's root directory and cannot have any skip;

(3) The system will go to the corresponding domain name to request the "apple-app-site-association" file when App is installed for the first time and upgraded. If Universal Link is unreachable but the configuration is normal, you can try to restart your mobile phone or reinstall App.

3. Universal Link Operation Process

(1) App is started for the first time, or it is started for the first time after updating the version (the actual result is not reflected in Apple's official documentation);

(2) App initiates a Get request to the domain name configured in the project to draw the apple-app-site-association Json file;

(3) App registers apple-app-site-association to the system;

(4) Any WebView initiates a skip to URL;

(5) If Universal Link registered by apple-app-site-association is hit by the skip, WebView will open App and trigger Universal Link delegate;

(6) Otherwise, WebView will continue to skip to url.

After apple-app-site-association and app Xcode project are configured, the entire Universal Link operation process is completely controlled by the system.

4. Access to MSDK Universal Link Authorized Login

• SDK Version
  
  MSDKV5.7, which encapsulates QQ OpenSDK 3.3.7 and WeChat OpenSDK 1.8.6v ersion
  
• QQ Platform
  
  QQ Appversion: 8.1.3 and higher versions
  
  iOS system version: iOS13 and higher versions
  
• WeChat platform
  
  WeChat App version: 7.0.7 and higher versions
  
  iOS system version: iOS12 and higher versions
  

Precautions:

(1) Added weixinULAPI scheme whitelist

Add a whitelist of weixinULAPI jump scheme in info.plist, otherwise it will cause problems such as unable to authorize login, share, etc. See the figure below for details:

(2) Enable AppleID Associated Domains capability

According to Apple's Official Documentation, contact the certificate management personnel to apply for enabling AppleID Associated Domains capability, as shown in the following diagram:

After AppleID has enabled Associated Domains capability, please regenerate the signature description file.

Precautions:

(3) Configure Universal Link-related information on the Feiying system

Configure the Universal Link parameters in Feiying System. The configuration path is Feiying Homepage ->Game Management ->My Game ->SDK Parameters -> Edit iOS Information, as shown in the following diagram:

Universal Link is not mandatorily required to be deployed under the official website's domain name, as long as the deployment location is highly available.

Wherein, the Universal Link column is filled in with a subdirectory under the game's official website and needs to be an https link, for example: https://xxx.com/app/, please note that the end must have/; the URL Scheme column is filled in with the game's QQ skip scheme, and the format is tencent+qqappid, for example: tencent100703379. After filling in these columns, click the Update the Game's iOS Information button to save the information.

Precautions:

1. If there are QQ-related error prompts, please do the next step first: (3) Configure apple-app-site-association
   
2. If any error appears here, please contact MSDK Assistant via corporate WeChat to handle it
   

(4) Configure apple-app-site-association

A configuration example is shown as follows:

{            
    "applinks": {            
        "apps": [],            
        "details": [{            
            "appID": "JBS4AWYMFX.com.tencent.newmsdk2",            
            "paths": ["/app/*", "/qq_conn/100703379/*"]            
            },            
            {            
            "appID": "JBS4AWYMFX.com.tencent.itop.example",            
              "paths": ["/app/*", "/qq_conn/1106977030/*"]
              }]
    }            
}

Precautions:

1. The appID parameter needs to be modified to the game's own signature certificate team id + bundle id;
   
2. The /app character in the paths parameter needs to be replaced with the part after .com in the official website address set in Universal Link on the Feiying system. For example, if the address configured on Feiying is https:// xxx.com/client/, then /app/* needs to be replaced with /client/*;
   
   In addition, the QQ interconnection requires that the 'paths' parameter must be configured in the format like /qq_conn/QQ AppID/, where qq_conn is a fixed field and QQ AppID is filled with the QQ AppID of the game itself, such as: /qq_conn/1106977030/; otherwise, the verification will fail when Feiying synchronizes the information to QQ. If you want to configure multiple appID and paths, please refer to the above example. After the changes, save the text as a file named apple-app-site-association (note that the name cannot be added with any suffix), and place the file in the root directory of the official website address set in Universal Link on Feiying. Users need to access https:// xxx.com/apple-app-site-association address to download this file normally.

(5) Configure Xcode Capabilities

Under the Capabilities tag in the Xcode project, enable Associated Domains and configure Domains. Domains is written as applinks:+official website domain name in a fixed way. Note that it is not needed to add https://before it. The example is as follows:

5. WeChat client configuration

(1) Configure MSDKConfig.ini

Add the WeChat_UNIVERSAL_LINK_IOS configuration item inMSDKAppSetting.bundle/MSDKConfig.ini, whose value is filled with Universal Link configured by Feiying system

6. Implement iOS entry function

(1) Unity

Because GCloudCore is not effective to this entry method "hook" now, it is needed to add the lifecycle entry function of iOS to UnityAppController class in the "UnityAppController.mm" file of Unity. Before adding it, please check if the entry function already exists. If not, add it manually (no additional code is needed to be added into the function):
Note: The lifecycle entry function should not be added in a subclass of UnityAppController. Make sure the entry function is in the same class as the system's lifecycle functions such as application:openURL:options:

- (BOOL)application:(UIApplication *)application continueUserActivity:            
(NSUserActivity *)userActivity restorationHandler:(void(^)            
(NSArray<id<UIUserActivityRestoring>> *            
__nullablerestorableObjects))restorationHandler {            
    return YES;        
}

(2) UnrealEngine

Implement a category of iOSAppDelegate in iOS and place it in the MSDKCore/Source/MSDKCore/Private/iOS plugin. This solution is implemented using iOS category, and there is a risk of being replaced by other SDKs. The game must verify whether the UL is valid.

Create a new IOSAppDelegate+MSDK.mm file with the following content:

# define WITH_MSDK 1

# if WITH_MSDK
# ifdef __APPLE__

# import <Foundation/Foundation.h>
# import "IOSAppDelegate.h"//UnrealEngine

# include "CoreDelegates.h"//UnrealEngine
# include "MSDKApplicationDelegate.h"

@interface IOSAppDelegate(MSDK)

@end

@implementation IOSAppDelegate(MSDK)
- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray * _Nullable))restorationHandler
{
    NSLog(@"IOSAppDelegate(MSDK) continueUserActivity ");
    [[MSDKApplicationDelegate sharedInstance] application:application continueUserActivity:userActivity restorationHandler:restorationHandler];
    return YES;
}
@end

# endif
# endif

7. Acceptance Check Standard of Access to Universal Link

(1) WeChat platform

It is needed that WeChat authorized login is launched successfully and MSDK log contains call [WXApi handleOpenUniversalLink:delegate. A sample log is shown in the following diagram:

(2) QQ platform

It is needed that QQ authorized login is launched successfully and MSDK log contains universal link continueUserActivity called. A sample log is shown in the following diagram:

Precautions:

8. References

(1) Universal Links for Developers

(2) Enabling Universal Links

(3) Apple's Official UL Testing Tools

(4) WeChat

(5) QQ