OneLink™ deep linking guide

URI schemes are URLs that lead users directly into activities of mobile apps. In Android, URI schemes can also be used to deep link users into specific activities.

If users of an app enter a URI scheme in a browser address bar box, the app launches and the users are deep linked. The same thing happens when users click on links with URI schemes behind them.

AppsFlyer supports URI scheme deep linking functionality via OneLink URLs, using the af_dp parameter.

Setting URI schemes

Configuring OneLink for URI Scheme should be done in collaboration between the marketer and developer.

URI scheme setup takes place in two places:

1. OneLink template page
2. The app

The URI scheme in the instructions below is greatapp://.

Marketer's part

Setup the OneLink template for your apps, if it's not already set.

Developer's part

<activity android:name="com.appsflyer.sample.Activity">    
      <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="greatapp" />
      </intent-filter>
</activity>

AppsFlyerLib.getInstance().sendDeepLinkData(this); 

@Override
protected void onNewIntent(Intent intent) {
     super.onNewIntent(intent);
     setIntent(intent);
}

Testing URI schemes

To test the URI scheme, create a custom attribution link.

1. Generate a custom attribution link from the OneLink you created
2. Install the app on your device
3. Send the attribution link to the device
4. Click on the link

If the link doesn't open the app, add the parameter af_force_deeplink=true to the custom attribution link. For example:

https://demo.onelink.me/1aBC/123ab45c?af_force_deeplink=true 

Limitations

Neither Apple or Google enforce unique naming for app schemes. Choose a scheme name unique to your brand to avoid conflicting schemes across different applications. A good scheme name could be your app bundle ID i.e. com.company.app.

When a OneLink that has af_force_deeplink=true is opened in iOS 12.3.1, the following logic applies:

• A dialog is shown asking the user if the app installed:
  • If the user chooses OK (app is installed), AppsFlyer attempts to open the app using URI scheme
  • If the user chooses Cancel (app is not installed), AppsFlyer redirects the user to the app store
  • If the user chooses OK but the app is not installed, an error message is shown:
    

    

To enable OneLink to serve both iOS and Android, it is important that the same scheme is defined for both platforms. Here are instructions for iOS and Android.

Deep linking via URI-schemes is currently not supported on Amazon devices.

The Universal Links method links between an iOS mobile app and an associated website/domain. This guide shows how to create and use Universal Links with OneLink.

Setting Universal Links with OneLink is a two-part process:

1. Configuring OneLink
2. Configuring mobile apps to register approved domains

Configuring OneLink

Configuring OneLink for Universal Links should be done in collaboration between the marketer and developer.

Developer's part

 func onConversionDataSuccess(_ installData: [AnyHashable: Any]) {
  //Handle Conversion Data (Deferred Deep Link)
  }
  
  func onConversionDataFail(_ error: Error?) {
    //    print("\(error)")
  }
  
  func onAppOpenAttribution(_ attributionData: [AnyHashable: Any]) {
    //Handle Deep Link Data
    
  }
  
  func onAppOpenAttributionFailure(_ error: Error?) {
  }
// Reports app open from a Universal Link for iOS 9 or later
  func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([Any]?) -> Void) -> Bool {
    AppsFlyerTracker.shared().continue(userActivity, restorationHandler: restorationHandler)
    return true
  }

  // Reports app open from deep link from apps which do not support Universal Links (Twitter) and for iOS8 and below
  func application(_ application: UIApplication, open url: URL, sourceApplication: String?, annotation: Any) -> Bool {
    AppsFlyerTracker.shared().handleOpen(url, sourceApplication: sourceApplication, withAnnotation: annotation)
    return true
  }

  // Reports app open from deep link for iOS 10 or later
  func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey : Any] = [:]) -> Bool {
    AppsFlyerTracker.shared().handleOpen(url, options: options)
    return true
  }
  

func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
	AppsFlyerTracker.shared().continue(userActivity, restorationHandler: nil)
	return true
}

-(void)onConversionDataSuccess:(NSDictionary*) installData {
  //Handle Conversion Data (Deferred Deep Link)
  
}

-(void)onConversionDataFail:(NSError *) error {
  
  NSLog(@"%@",error);
}


- (void) onAppOpenAttribution:(NSDictionary*) attributionData {
  
  //Handle Deep Link
}

- (void) onAppOpenAttributionFailure:(NSError *)error {
  NSLog(@"%@",error);
}

// Reports app open from a Universal Link for iOS 9 or above
- (BOOL) application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> *restorableObjects))restorationHandler {
    [[AppsFlyerTracker sharedTracker] continueUserActivity:userActivity restorationHandler:restorationHandler];
    return YES;
  }

  // Reports app open from deep link from apps which do not support Universal Links (Twitter) and for iOS8 and below
  - (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString*)sourceApplication annotation:(id)annotation {
    [[AppsFlyerTracker sharedTracker] handleOpenURL:url sourceApplication:sourceApplication withAnnotation:annotation];
    return YES;
  }
  // Reports app open from deep link for iOS 10
  - (BOOL)application:(UIApplication *)application openURL:(NSURL *)url
  options:(NSDictionary *) options {
    [[AppsFlyerTracker sharedTracker] handleOpenUrl:url options:options];
    return YES;
  }

Marketer's part

Once the steps above are complete, each time users click on an authorized domain URL (when the app is already installed on the device), iOS launches the associated app as its default activity.

Keeping URI scheme in iOS

Even with iOS9+, it is still important to implement a URI scheme. Some browsers or apps don't support Universal Links and fall back to the URI scheme method. See our guide on setting URI scheme for deep linking.

Universal links limitations

Universal Links have some limitations that you should take into account.

This method, which was introduced with Android 6.0, is Google's version of universal links and has similar benefits. To learn more, see our article on App Links.

Setting up Android app links

Setting up OneLink for Android App Links should be done in collaboration between the marketer and developer.

Developer's part

AppsFlyerLib.getInstance().sendDeepLinkData(this); 

@Override
protected void onNewIntent(Intent intent) {
     super.onNewIntent(intent);
     setIntent(intent);
}

Marketer's part

Complete the instructions for Android setup and subdomain setup in your OneLink template.

Deep linking into specific activities

Using conversion data

Another approach is to deep link users according to conversion data. For example, if the user engages with an ad that promotes the shoes category in your app, you can deep link the user into that category and apply discounts or customize content.

1. Designate an activity that the user sees before your code decides where to deep link them. You can can use an empty activity or the main activity for this purpose. This activity acts as an activity that routes users to other activities based on conversion data.
2. Follow the steps in setting up Android for deep linking.
3. In step 2 you are asked to add a snippet to an activity in Android manifest. In Android manifest, in the activity tag of the designated activity, add this snippet.
4. In the routing activity add the API:

   AppsFlyerLib.getInstance().sendDeepLinkData(this); 

5. When this activity opens with deep linking, it makes sure that onAppOpenAttribution get the conversion data.
6. You apply the logic for onAppOpenAttribution to decide where to deep link the user.

Using intent-filter in Android Manifest

Android App Links allow you to deep link users into specific activities.

<activity android:name="com.king.candycrushsaga.DeepLink">
    <intent-filter>
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
    <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:scheme="https"
            android:host="demo.onelink.me"
            android:pathPrefix="/ST6c/c0aae4f" />
    </intent-filter>
</activity>

<activity android:name="com.appsflyersmaple.guide.DeepLink2">
    <intent-filter>
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
    <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:scheme="https"
            android:host="demo.onelink.me"
            android:pathPrefix="/ST6c/6f0b5993" />
    </intent-filter>
</activity>

<activity android:name="com.king.candycrushsaga.DeepLink3">
    <intent-filter>
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
    <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:scheme="https"
            android:host="demo.onelink.me"
            android:pathPrefix="/ST6c/b40bder4" />
    </intent-filter>
</activity>
      

AppsFlyerLib.getInstance().sendDeepLinkData(this); 

Keeping URI scheme in Android

It is still important to implement a URI scheme as Android devices still do not support App Links and fall back to the URI scheme method. See our guide on setting URI scheme for deep linking.

App links limitations

App Links have some limitations that you should take into account.

No special actions required

For the new OneLink to work, the app's AASA file must be updated. After creating the new OneLink template, submit a new version to the store. Only iOS users who updated to the new version can activate a OneLink URL built on the new template.

1. After creating the new OneLink template, copy the new Onelink ID generated for it.
2. Copy the XML snippet at the bottom of the App Link section and add it to your AndroidManifest.xml file inside the intent you want to deep link into, in addition to the previous intent/s.
3. Release the new version to the store. Only Android users who updated to the new version can activate a OneLink URL built on the new template.

1. Install and launch the app on your device (or iPhone simulator on iOS).
   [If app was just installed bring the app to the background and then back to the foreground twice or more.]
2. Prepare a OneLink URL for the app, which has the af_dp parameter with a valid scheme path (e.g. "greatapp://cars").
3. On the tested device paste the link into email, notes, SMS, QR code generator etc.
4. Click the link.

Expected result: The app should open at the requested activity pointed to by af_dp.

1. Logout of app.
2. Delete the app.
3. Prepare a OneLink URL for the app, which has the af_dp parameter (or another) with a valid scheme path (e.g. "greatapp://cars").
4. On the tested device paste the link into email, notes, SMS, QR code generator etc.
5. Click the link.
6. Install and launch the app on your device (or iPhone simulator on iOS).

Expected result: The link (conversion data) is fetched by the app on first launch. The af_dp parameter is extracted and the user is redirected within the app according to the af_dp value.

1. Install and launch the app on your device (or iPhone simulator on iOS).
   [If app was just installed bring the app to the background and then back to the foreground twice or more.]
2. Prepare a OneLink URL for the app, which has the af_dp parameter (or another) with a valid scheme path (e.g. "greatapp://cars").
3. iOS - Paste the link in Notes, iMessage or in an email using the Apple Mail Client.
   Android - Paste the link into email, SMS, QR code generator etc. Do not use Slack, Facebook or any other social app to click the link!
4. Click the link.

Expected result: The app opens immediately, without a redirect through the browser. The af_dp parameter is extracted and the user is redirected within the app according to the af_dp value.

Note for testing deep linking with Universal Links - if you make changes to Universal Links setting in OneLink templates (like OneLink subdomain or App ID prefix), make sure to delete and reinstall the app after every change.

Yes, but only partly. Although OneLink is an integral tool for deep linking, regular app-specific URLs can also deep link users, who use the URI scheme. Effectively this means that you can use deep linking on Android apps by simply adding the af_dp parameter to a regular AppsFlyer attribution link.
Universal links, which is the available deep linking method for over 98% of iOS users, can only be activated by OneLink and not by single-platform regular attribution links.

Unfortunately, yes.
Social apps treat deep linking from viral posts in different ways, which often break the user's experience. The workaround AppsFlyer recommends for device diagnostics and redirection by OneLink, is by using landing pages as explained in the OneLink Redirections guide.

For deep linking purposes there is another workaround, which can be used in cases where the universal link or app link are broken due to the host application, e.g. Instagram stories with OneLink. The solution is forcing usage of a URI scheme for deep linking.

1. Add the af_dp parameter to OneLink, specifying the path to the deep linked activity (more details)

2. Add &af_force_deeplink=true to the attribution link to force usage of af_dp

This workaround works well for active users, i.e. users that have the app installed on their devices. However, in iOS, Safari users that don't have the app installed are shown a system error message and are then redirected to the defined fallback.

No, you can't paste URLs in Android Chrome browser, nor in iOS Safari.
In the past, it used to be supported by the browsers, but is now deprecated due to browser security reasons.
Test by clicking on URLs, not by pasting them in the browser URL box.

Yes, it's possible to delete a OneLink template. Note that if there are OneLink URLs using the deleted template out there, clicking users would not be even redirected to the app store. Therefore, make sure there are no OneLink URLs using the template before deletion. Alternately, see if you can just change the template configuration.

Yes, but changing the OneLink subdomain can cause deep linking and custom links to stop working. It is always better to create a new OneLink template and custom links, and slowly phase out the old OneLink and the custom links that depend on it.

Changing the OneLink subdomain

1. Change the OneLink subdomain - you can do that in the One Link template configuration.
2. Update the custom links that depend on the OneLink template:
   1. Go to Custom Link Management.
   2. Click on the link you want to update.
   3. Don't make any changes - simply click Update Link at the bottom of the page.
3. Update your Android configuration - refer to setting up Android App Links, specifically the section about adding intent filter to activities in AndroidManifest.xml.
4. Update your iOS configuration - refer to setting up Universal Links, specifically the section about configuring approved domains in XCode.
5. Publish both apps in the app stores.

Deep linking doesn't work for users with older versions of the app, before changes to the OneLink subdomain. This is why you need to publish the apps to the app stores after changing the OneLink subdomain.

Yes. And no.
af_dp can contain a URI value, and any parameters can be transferred as part of the path of the URI, e.g. af_dp=greatapp%3A%2F%2Fparam1%2Fparam2 (greatapp://param1/param2).

Even easier, you can add any parameters to the attribution link after its '?' character.

However, concatenating parameters to the value of af_dp after '?' is NOT recommended. The parameters may be discarded and not be available via conversion data or via other APIs.
Bad example: af_dp=greatapp%3A%2F%2F%3Fparam1%3Da%26param2%3Db (greatapp://?param1=a&param2=b).

If OneLink URL is placed inside an html a tag with target="_blank" attribute, it opens a blank page in Chrome on Android. This affects OneLink functionality. Make sure that the a tag doesn't include the target attribute.

This means that the SDK integration for deep linking was not fully completed. The continueUserActivity method on the AppDelegate is missing and should be called.

This usually happens as a result of code in the app that performs a redirection to a browser when an https link launches the app.

On iOS 9 & 10 (removed from iOS 11) there is an option to ignore deep linking. When an app is opened by Universal Links, iOS shows a deep link bypass link in the top right corner which sets that link to be opened without deep linking.

This is a per-app setting that is saved on each unique device. The setting is preserved even if you delete the app and reinstall it. The only way to reverse this is by re-enabling Universal Link behavior for that app on your device. There are a couple of ways to do this:

To reset this setting paste the OneLink into Notes or iMessage (or some other app that supports Universal Links) and long-press on it. You'll see an 'Open in [App]' option. Select it, and after that all Universal Links for that app will work again.

Select Open in your app (e.g. open in LoginBox).
Deep linking is now restored.

I performed a long tap, but I don't see the "Open in your app" option!

• iOS apps are built with a provisioning file (similar to a license). This file is generated on Apple's developer console, and should be enabled for Universal Links.
• On Xcode - make sure Associate Domains is enabled on the Capabilities tab and includes the OneLink domain for the app.
  
• Make sure the team ID of the app matches the one entered on the OneLink templates page.

Delete the app, reinstall and run it again. If the problem persists, try to add another row on the Associate Domains (so it is changed). Then, delete the app and repeat the process. Also make sure your OneLink has the same domain as set on the app.

Hey, we hear ya. If all of the above did not resolve the issue, try to generate your provisioning files again for your app. Download them one more time and double-click to install them on Xcode.
You can also try to delete the app and re-install it with an advanced app version.

iOS 11.2, and all its subsequent patches, have a bug that sometimes prevents deep linking through Universal links.

Apparently, the apple-app-site-association file, that is used to open apps with Universal links and is automatically downloaded with any iOS app install, sometimes fails to download with app installs of devices running iOS 11.2 and above. Without this file on the iOS device Universal links fail to directly open apps.

If you witness this problem while testing deep linking uninstall the app, restart your (white listed) iOS device and reinstall the app. Didn't help? Try again.

It is still unclear how widespread this sporadic problem really is, although it has been reproduced on multiple iPhone devices running iOS 11.2. Hopefully Apple would soon solve this bug, that may affect deep linking for more than 2/3 of its iOS users.

Note - You can click the Follow button at the top of the screen to get updated when this issue is solved, or whenever this article is updated.

iOS 13 has a bug that sometimes prevents deep linking through Universal links.

Apparently, a process that runs in iOS 13 to verify installations sometimes fails. This failure prevents iOS from verifying associated domains. As a result, deep linking in iOS 13 might not work. This doesn't always happen but the rate at which it does is unknown at the moment. See here for more information.

As a workaround you can use URI-scheme deeplinking mechanism. By default, when Universal Links fail for any reason, OneLink redirects the user to the store. You can add af_force_deeplink=true parameter to the link. Doing so causes OneLink to try and do deep linking using the scheme specified in the af_dp parameter.

You can read more about force deep linking here.

Note - You can click the Follow button at the top of the screen to get updated when this issue is solved, or whenever this article is updated.

Opting out users affect the correct attribution and data collection. Here is why they prevent the correct work of the deep linking mechanism, and how this can be fixed.

With App links or Universal links there is a difference in the response from onAppOpenAttribution depending on the type of OneLink that is used.

For both iOS and Android, when using the short version of OneLink, the conversion data is a structured map of all the parameters in the link:

Example:

{
  af_dp: "superapp://Deeplink",
  pid: "media_source_name"
  c: "campaign_name",
  link: "https://abcd.onelink.me/12ab/12ab34c"
  is_retargeting: true
}

The long version of OneLink, on the other hand, produces a map with a single key-value pair that contains the entire OneLink

{
  "link": "https://abcd.onelink.me/12ab?pid=media_source&c=campaign_name&is_retargeting=true&af_dp=superapp%3A%2F%2FDeepLink"
}

The response for the short OneLink is well-structured and easier to parse. We therefore recommend using the short version of OneLink.

Chrome has released a new browser version (V.79) that interrupts the deep link functionality for some users. 

Impacted users are Android users who click on a link that contains the af_dp parameter, and either -

• Don’t have the app installed
• Don’t have Chrome running in the background (even if the app is installed)

To make sure that such users reach the correct content inside the app, we have created a landing page to which they are taken upon clicking the link with af_dp.

These users are redirected to the Chrome browser, where they see an automatic AppsFlyer-generated landing page with the app name, icon, and Go to the app button.

The following table shows the options when an impacted user clicks on a OneLink URL with af_dp: