Skip to main content

Deep Link

Deep link and unviersal link are ways to open your app's specific pages on Android and iOS devices respecitvely.

Users can create two types of links in Android apps: deep links and Android app links.

A deep link is a URL that redirects users to specific content in an app. In Android, users can add an intent filter to set deep links based on the data extracted from provided intents. This will direct players to the correct activity.

However, other apps that users install on their devices can process the same intent data, so users may not be able to directly access the app. For example, if a user taps a link in an email from their bank, it may open a dialog box asking whether the user wants to open the link in the web browser or the bank's app.

Android 6.0 (API level 23) and later versions use Android app links to make apps the default means of opening specific link types. Users who do not want apps to open their own links by default can configure the system settings of their devices accordingly.

Android app links offer the following advantages:

  • Secure and specific: Android app links are links to your own website domain or HTTP URL, so other apps cannot use the links. Android weblinks require you to perform website association to verify that you are the owner of the domain.
  • Fluent user experience: Because Android app links use a single HTTP URL to link to the same content in your website or your app, users who have not yet installed your app will directly redirect to your website rather than seeing an error message.
  • Android "no-install" apps support: With Android no-install apps, users can run your Android app without installing it. To add no-install support for your app, set your Android app links and redirect to g.co/InstantApps.
  • Attract users through Google search: When users find and tap links through their mobile browsers, the Google Search app, Android device search, or Google Assistant, they will go directly to the relevant content in your app.

Step 1: Create a deep link to specific content in your app​

In your app manifest, create an intent filter for your website URI and configure your app to use the relevant intent data so that users will reach the correct content in your app.

When a user taps a link or a programmatic request calls the webpage URI intent, the Android system will attempt each operation in the following set order until the request is successful:

  1. If the user sets a preference to open the URI with an app, the system opens the app.
  2. Open the only app that can process this URI.
  3. Allow the user to choose the relevant app from a dialog box.

Step 2: Configure Player Network SDK​

info

Version requirements: Player Network SDK version 1.12.00 or later

Add an intent filter for incoming links: To create links to specific content in your app, add an intent filter with the following elements and properties in the manifest.

<action>

Specify the ACTION_VIEW intent operation so users can access this intent filter from Google Search.

<data>

Add one or more <data> labels, each of which represents a URL format that can be resolved to an Activity. <data> labels must all contain the android:scheme property. Add multiple properties to further refine the URL types accepted by the Activity. For example, when you have multiple Activities and they can accept similar URLs (might be slightly different in path names). In this case, use the android:path property or its pathPattern or pathPrefix variants to distinguish the Activities to be opened by different URL paths.

<category>

Include the BROWSABLE category. Provide this category to access the intent filter. Otherwise, tapping links in the browser will not resolve your app. In addition, include the DEFAULT category to allow your app to respond to implicit intents. Otherwise, an Activity will only be launched when the intent specifies a component name for your app.

The following XML code snippet shows how to specify a deep link intent filter in the app manifest. The URLs “example://gizmos” and “http://www.example.com/gizmos” are both resolved to this Activity.

<activity
    android:name="com.example.android.GizmosActivity"
    android:label="@string/title_gizmos" >
    <intent-filter android:label="@string/filter_view_http_gizmos">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <!-- Accepts URLs that begin with "http://www.example.com/gizmos” -->
        <data android:scheme="http"
              android:host="www.example.com"
              android:pathPrefix="/gizmos" />
        <!-- note that the leading "/" is required for pathPrefix-->
    </intent-filter>
    <intent-filter android:label="@string/filter_view_example_gizmos">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <!-- Accepts URLs that begin with "example://gizmos” -->
        <data android:scheme="example"
              android:host="gizmos" />
    </intent-filter>
</activity>

Note that the <data> elements are the only difference between these two intent filters. Although a single filter can contain multiple <data> elements, it is critical to create separate filters if you want to declare unique URLs (such as specific scheme and host combinations). When a single intent filter contains multiple <data> elements, it will merge them to cover all variants of the merged elements. See the example below:

<intent-filter>
  ...
  <data android:scheme="https" android:host="www.example.com" />
  <data android:scheme="app" android:host="open.my.app" />
</intent-filter>

This example seems to only support https://www.example.com and app://open.my.app, but it also supports variants such as app://www.example.com and https://open.my.app.

After adding an intent filter containing URLs for Activity content in the app manifest, Android will forward all Intents that contain matching URLs to your app.

Step 3: Verify Android App Links​

Configure your app to require verification for app links. Then, publish a Digital Asset Links JSON file on your website and verify your ownership through the Google Search Console.

An Android App Link is a special type of deep link that allows your website URLs to immediately open the corresponding content in your Android app, without requiring the user to select the app.

To verify that you own both your app and the website URLs, complete the following steps:

  • Request the automatic verification of app links in the manifest. This tells the Android system that it should verify whether your app corresponds to the URL domain used in the intent filter.
  • Declare the relationship between your website and the intent filter by hosting the Digital Asset Links JSON file in the following location:
https://domain.name/.well-known/assetlinks.json

You need to publish the Digital Asset Links JSON file on the website to indicate the Android app associated with the website and verify the app's URL intent. The JSON file uses the following fields to identify the associated app:

  • package_name: The app ID declared in the build.gradle file.
  • sha256_cert_fingerprints: The SHA256 fingerprints of your app's signing certificate. Use the following command to generate the fingerprint via the Java keytool:
$ keytool -list -v -keystore my-release-key.keystore

This field supports multiple fingerprints, which can support different versions of your app, such as debugging and production builds.

The following example assetlinks.json file grants link-opening permissions to a com.example Android app:

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

Step 4: Receive Android Intent Data​

Call the right methods to retrieve data and operations associated with the incoming Intent.

Call the getData() and getAction() methods in the onCreate and onResume of the main Activity to retrieve the data and actions associated with the incoming Intent.

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);

    Intent intent = getIntent();
    String action = intent.getAction();
    Uri data = intent.getData();

    if (data != null) {
        INTLSDK.Deeplink.receive(data.toString());
    }
}

public void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    INTLSDK.onNewIntent(intent);

    Uri appLinkData = intent.getData();
    if (appLinkData != null) {
        INTLSDK.Deeplink.receive(appLinkData.toString());
    }
}

Step 5: Test your configuration​

Install the application and open the link in the Android text editor app.

  1. When users click a link in an Android text editor app (such as Notepad), the log will record [ (intl_deeplink_manager.cpp:37) Receive].

    Image: app_link

  2. The general syntax for using ADB to test the intent filter URL is:

    $ adb shell am start
                -W -a android.intent.action.VIEW
                -d <URL> <PACKAGE>

    For example, the following command attempts to view the target app Activity for a specified URL.

    $ adb shell am start
                -W -a android.intent.action.VIEW
                -d "example://gizmos" com.example.android
note

Due to the limitations of its built-in browser, users cannot redirect to the app by opening a link in WeChat.

Multi-Store package​

Image: Multi-store configuration

For channel packages with different package names, the android:pathPrefix attribute can be used to distinguish them. For example, if android:pathPrefix="/sample" is added to channel A, if both channel A and channel B packages are installed, using the http://sdk-deeplink-confs.intlgame.com/sample link will pull up channel A.

Example of JSON file configuration for multichannel package links:

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.puppies.app",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
  },
  {
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.monkeys.app",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8: 8A:04:96:B2:3F:CF:44:E5"]
  }
}]

Universal Link is a mechanism for redirection between web and app interfaces introduced on Apple devices with iOS 9 and above. With Universal Link, users can open an app link in Safari or WebView to automatically open the relevant app while keeping all parameter data. Universal Link solves several problems with the URL Scheme:

note

Player Network SDK for iOS platform only handles the Deep Links in Universal Link. For the OpenUrl method where AppDelegate is opened through a custom scheme, Player Network SDK will not handle the method nor return the Deep Link callback, the game will have to handle this on their own.

  1. When redirect fails, links are opened in Safari or WebView.
  2. Universal Link provides unified web and native routing.
  3. Redirects do not open popup prompts, improving the user experience. {#universal-link}

Step 1: Configure the Web Server​

Configure JSON file apple-app-site-association and add it in the root directory of your web server. Universal Link does not require deployment in the official website domain. Just ensure the deployment location is in a high-level directory that can be accessed. If deploying it on the official website, refer to the configuration example below or the official Apple Docs.

The required configuration for deploying Universal Link on the official website:

{
    "applinks": {
        "apps": [],
        "details": [
            {
                "appID": "9JA89QQLNQ.com.apple.wwdc",
                "paths": [ "/wwdc/news/", "/videos/wwdc/2015/*"]
            },
            {
                "appID": "ABCD1234.com.apple.wwdc",
                "paths": [ "*" ]
            }
        ]
    }
}
  1. apps key must be an empty array
  2. details key corresponds to a dictionary. Website supports one dictionary per app, The order of the dictionaries in the array determines the order the system follows when looking for a match. Therefore, it is able to designate an app to handle specific parts of the website.
  3. Each dictionary contains one appID key and one paths key:
    • appID is the team ID or app ID prefix followed by the bundle ID.
    • paths is a string array to specify the website paths supported by the app and the website paths not associated with the app. When specifying the section not to be associated with the Universal Link, add "NOT" (including the space)to the start of the path string, for example, "paths": [ "/wwdc/news/", "NOT/videos/wwdc/2010/*", "/videos/wwdc/201?/*"]. As the system paths evaluates each path in the array in the specified order, and stops evaluating when a positive or negative match is found, specify high-priority paths before low-priority paths.
info

For re-signed apps, the appID and paths keys of the re-signed certificate must also be configured here.

To specify website paths（paths）in apple-app-site-association:

  • Use * to indicate the entire site.
  • Use a specified URL to indicate a specified link, such as /wwdc/news/.
  • Use * to indicate any string, and add * to specified URL to indicate a section of the website, such as /videos/wwdc/2015/*.
  • Use ? to match any character, and combine both wildcard characters (* and ?) in one URL, such as /foo/*/bar/201?/mypage.
info

Strings specifying website paths in the paths array must be case-sensitive.

Step 2: Configure the Associated Domains​

  1. To enable AppleID Associated Domains capability: to apply for AppleID Associated Domains capability from the relevant credential management director, see Apple Docs.

    Image: Associated Domains

    After enabling the Associated Domains capability for your AppleID, generate a new signature description file.

  2. Configure Xcode Capabilities. In the Xcode project's Signing & Capabilities interface, enable Associated Domains and set Domains to applinks: + official website domain.

note

The Domains configuration does not require https://.

Image: Associated_Domains_Xcode

Games can also automatically add and enable Associated Domains via code and configuration.

Users can add the following code in PostProcess:

#if UNITY_2019_3_OR_NEWER
    var capManager = new UnityEditor.iOS.Xcode.ProjectCapabilityManager(projPath, entitlementsFilePath, targetGuid: targetProjectName);
#else   
    var capManager = new UnityEditor.iOS.Xcode.ProjectCapabilityManager(projPath, entitlementsFilePath, targetProjectName);
#endif

capManager.AddAssociatedDomains(new string[] { "your_link1", "your_link2", "your_link3" });

Step 3: Configure Player Network SDK​

info

Version requirements: Player Network SDK version 1.12.00 or later

As the INTLCore is not currently effective for the hook of this entry method, add the iOS lifecycle entry function in the UnityAppController class of Unity's UnityAppController.mm file.

The XCodePostProcess.cs code has automatically added the application:continueUserActivity:restorationHandler method in the compiled process flow (users do not need to add additional code in the function).

note

Do not add the lifecycle entry function in a UnityAppController sub-class and ensure that the function is in the same class as application:openURL:options: and other system lifecycle functions.

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

Step 4: Test your Universal Link​

Type the URL associated with your app in iOS Notes app and click on it. A redirect to your app should be triggered and the following log will be recorded INTLApplicationDelegate:continueUserActivity:restorationHandler. For example:

Image: INTL_Universal_Link_Log

note
  1. Due to the limitations of its built-in browser, users cannot redirect to the app by opening a link in WeChat.
  2. When an app is installed for the first time or updated, the system will request the apple-app-site-association file from the corresponding domain. If Universal Link is not accessible but the configuration is correct, try to restart the mobile phone or reinstall the app.

Workflow​

After apple-app-site-association and the Xcode configuration of the application, the entire Universal Link operation process is completely controlled by the system. According to deduction, the first time the app is opened for installation or update, the following scenarios will occur:

  1. App initiates a GET request to get the apple-app-site-association file from the domain configured in the project.
  2. App registers apple-app-site-association with the system.
  3. When an URL is opened in WebView, it will be checked against the registered apple-app-site-association URLs.
  4. If there is a match, system opens the app and triggers Universal Link delegate.
  5. If there is no match, system continues to open the URL in WebView.

AppsFlyer supports the following deep linking functions provided by AppsFlyer SDK:

  • Deep linking: Deep linking happens when the target app is already installed. The configured deep link sends users to specific in-app locations or to complete specific in-app activities.

  • Deferred deep linking: Deferred deep linking happens when the target app is not installed. The configured deep link sends users to the download page of the target app in a specific app store. When the user installs and opens the app, deferred deep linking sends the user to the target in-app location or completes target in-app activities.

A feature unique to AppsFlyer, AppsFlyer OneLink refers to attribution links that function across platforms, supports forwarding a user to the target app from various source platforms (such as email, social media, web, QR code, etc.), in the process also relaying the ID of the user. The operations team is required to confirm if the ID returned is the OpenID or the device ID，then use the resulting user IDs in a final data analysis to attribute the relevant channels to the invited users.

Step 1: Create an app on the AppsFlyer console​

Create your app according to the AppsFlyer documentation Add App.

Step 2: Configure OneLink​

note

If you are new to OneLink Management, follow the user guide for new users to create a OneLink template. For more information, see OneLink templates

  1. Go to AppsFlyer OneLink Management.

  2. On the top-right corner, click the menu icon then select New OneLink Template, and record the template ID.

    Image: OneLink Configuration

  3. On the OneLink setup page, enter the template name, subdomain, and select the app that was created previously.
    Record the subdomain you entered.

    Image: OneLink Configuration 2

  4. For Android apps, in the When app is installed section, click Use App Links to launch the app to add SHA-256 into keystore. For more information, see Android initial setup.

    Image: OneLink Configuration 3

  5. Record down the intent-filter code generated by the AppsFlyer console.

    Image: OneLink Configuration 4

  6. Save the OneLink template.

Step 3: Configure Player Network SDK​

iOS

  1. Add the following code to INTLConfig.ini under the [AppsFlyer] node and replace {OneLink_Template_ID} with the template ID recorded in Step 2.

    APPSFLYER_APP_INVITE_ONELINK_ID_IOS = {OneLink_Template_ID}

  2. In Assets\INTLSDK\Editor\XUPorter\XCodePostProcess.cs, add the subdomain (for example appslinks:subdomain.onelink.me) obtained from Step 2 to the below line.

    capManager.AddAssociatedDomains(new string[] { "appslinks:subdomain.onelink.me"});
Android

  1. Add the following code to INTLConfig.ini under the [AppsFlyer] node and replace {OneLink_Template_ID} with the template ID recorded in Step 2.

    APPSFLYER_APP_INVITE_ONELINK_ID_ANDROID = {OneLink_Template_ID}

  2. If [Android LifeCycle] in INTLConfig.ini does not contain AppsFlyer, add AppsFlyer.

    LIFECYCLE =　WeChat,QQ,Twitter,Adjust,Facebook,Google,Line,VK,Garena,Discord,Dmm,Update,Firebase,KaKao,WhatsApp,Permission,GooglePGS,AppsFlyer

  3. In AndroidManifest.xml, add the Android intent-filter code recorded from Step 2 under the MainActivity node of the game.
    This code will be used to launch the game, replace {Subdomain} and {OneLink_Template_ID} accordingly.

<activity
            android:name="com.intlgame.unity.MainActivity"
            android:configChanges="fontScale|keyboard|keyboardHidden|locale|mcc|mnc|navigation|orientation|screenLayout|screenSize|smallestScreenSize|touchscreen|uiMode"
            android:exported="true"
            android:label="@string/app_name"
            android:launchMode="singleTask">
            <intent-filter android:autoVerify="true">
                <action android:name="android.intent.action.VIEW" />
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.BROWSABLE" />
                <data
                    android:host="{Subdomain}.onelink.me"
                    android:pathPrefix="/{OneLink_Template_ID}"
                    android:scheme="https" />
            </intent-filter>
</activity>

For more information, see OneLink links and experiences.

Step 4: Calling OneLink interface​

  1. Set the callback for generating OneLink.
INTLAPI.AddExtendResultObserver(OnExtendEvent);// Setting callbacks
INTLExtend.Invoke("AppsFlyer", "generateInviteLinkUrl", paramsJsonString);// paramsJsonString is the information to be relayed to OneLink
    public void OnExtendEvent(INTLExtendResult extendResult)
    {
        if ("generateInviteLinkUrl".Equals(extendResult.ExtendMethodName))// Methods to generate OneLink
        {
            if (extendResult.RetCode == 0)// OneLink generation success
            {
                string inviteUrl = extendResult.RetMsg;// The generated OneLink, which can be shared with other players
                //TODO:share link to other players
            }
            else// Failed to generate OneLink
            {
                //TODO: handle OneLink Failed result
            }
        }
    }

  1. Set the result callback after the invited user clicks on the generated OneLink.

Generating OneLink and clicking OneLink events share a single callback, distinguished by the parameter INTLExtendResult in the callback.

  INTLAPI.AddExtendResultObserver(OnExtendEvent);// Setting callbacks
    public void OnExtendEvent(INTLExtendResult extendResult)
    {
        if ("OnOneLinkResult".Equals(extendResult.ExtendMethodName))// OneLink click callback
        {
            if (extendResult.RetCode == 0)// OneLink click callback success
            {
                string jsonParameter = extendResult.ExtraJson;// Parameters returned by AF after clicking on OneLink
                //TODO:Handle OneLink Parameter
            }
            else// OneLink Click callback failed
            {
                //TODO: handle OneLink Failed result
            }
        }
    }

  1. Refer to the following code to generate OneLink, and replace the parameters within the code accordingly.
 StringBuilder sb = new StringBuilder();
        sb.Append("{");
        sb.Append("\"deep_link_value\":\"abc\"").Append(","); //<TARGET_VIEW>
        
        sb.Append("\"deep_link_sub1\":\"1234\"").Append(",");//<PROMO_CODE>
        sb.Append("\"deep_link_sub2\":\"1234\"").Append(",");//<REFERRER_ID(openid)>
        sb.Append("\"channel\":\"mobile_share\"").Append(",");//Channel
        sb.Append("\"campaign\":\"summer_sale\"");//Campaign
        // Other parameters, optional
        sb.Append("\"deep_link_sub3\":\"1234\"").Append(",");
        sb.Append("\"deep_link_sub4\":\"1234\"").Append(",");
        sb.Append("\"deep_link_sub5\":\"1234\"").Append(",");
        sb.Append("\"deep_link_sub6\":\"1234\"").Append(",");
        sb.Append("\"deep_link_sub7\":\"1234\"").Append(",");
        sb.Append("\"deep_link_sub8\":\"1234\"").Append(",");
        
        sb.Append("\"af_sub4\":\"12324\"").Append(",");
        sb.Append("\"af_sub5\":\"dfasdf\"").Append(",");
        
        sb.Append("}");
        String paramsJsonString = sb.ToString();
        INTLExtend.Invoke("AppsFlyer", "generateInviteLinkUrl", paramsJsonString);

Integration Tests​

  1. Go to AppsFlyer console.

  2. On the left sidebar, click SDK Integration Tests.

  3. Select the app to test and click Run test.

    Image: Integration Tests 1

  4. On the Run non-organic install test page, select the test device and select Other.

  5. Scan the QR code and install the app.

    Image: Integration Tests 2

note

To test activation again, delete the app and restart the test.

Reference Docs​

AppsFlyer Deep Linking and OneLink: Deep linking

iOSAndroid
iOS initial setupAndroid initial setup
iOS Unified Deep LinkingAndroid Unified Deep Linking
iOS Legacy APIsAndroid Legacy APIs
iOS Extended Deferred Deep LinkingAndroid Extended Deferred Deep Linking
iOS organic search attributionAndroid Organic Search Attribution

Client API​

Deep Link Observer​

Deep Link Observer handles the callback functions related to deep link data. For more information, see:

APIFunction
SetDeepLinkObserverSets the deep link callback, which notifies the game when data reaches the engine layer. When this callback is received, call the Fetch function to obtain the data.
RemoveDeepLinkObserverRemoves the deep link callback

Fetch​

Fetch method returns the deep link data in the SDK cache. For more information, see:

APIFunction
FetchObtains the deep link data in the SDK cache.
Last updated on