OneLink™ Deep Linking Guide

Introduction

Deep linking is the act of launching a mobile app while serving personalized content and/or sending the users to specific activities within the app. By doing so you can provide your users with superior user experience, which can greatly enhance their engagement with your apps.

The 2 Deep Linking Types

Since users may or may not have the mobile app installed, there are 2 types of deep linking:

Deep Linking: Directly serving personalized content to existing users, which already have the mobile app installed.
Deferred Deep Linking: Serving personalized content to new or former users, directly after the installation.

AppsFlyer supports both deep linking and deferred deep linking methods using its unique device detecting tracking link - OneLink™.

This guide covers all you need to know about the set up and usage of deep linking for your mobile apps.

Important!

Deep linking relies on the correct setup of OneLink.
Please read the OneLink™ Basic Setup Guide first.

Deep Linking and OneLink

OneLink operates as a ‘bridge’ between the advertisement and the mobile app. It can launch the app and provide the mobile developer with the data required to personalize the user experience. To do so the mobile app MUST be developed with deep linking capabilities and infrastructure.

Deep Linking and Retargeting

Deep linking and OneLink are major tools in advertisers' efforts to re-engage with existing or past users, i.e. retargeting. This subject is covered in the Retargeting Guide, which should be implemented after the deep linking guide.

Deep Linking Methods

There are several methods for deep linking that need implementing to fully cover your user base. The method used depends on the mobile platform (iOS/Android) and OS version of each user.

Method	Description	Required for
URI Scheme	Directly open the app and redirect to the activity path specified in the `af_dp` URL parameter	Android all versions (optionally excluding Android 6 and above) iOS 8 and below iOS 9 and above when using browsers or apps that still do not support Universal Links
Universal Links	Directly open the mobile app at the default activity. Requires mobile developers to build a logic which redirects and/or serves personalized content based on OneLink URL parameters, e.g. `af_dp` or `af_sub1`	iOS 9 and above
App Links		Android 6 and above

Click on any deep linking method box below for its implementation details.

URI Scheme

URI schemes are essentially URLs, that lead users straight into the default activities of mobile apps upon clicking. For example: greatapp://

Tip

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.

Schemes can be used to create longer paths that automatically deep link users into specific activities. For example: greatapp://vintage_items/cars/flying_delorean

If users of an app enter scheme paths in a browser URL box the app launches and the users are deep linked. AppsFlyer supplies the same URI scheme deep linking functionality via OneLink URLs, using the af_dp parameter (its value MUST be encoded). Example:

https://go.onelink.ly/qwerty?af_dp=greatapp%3A%2F%2Fvintage_items%2Fcars%2Fflying_delorean

Important!

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.

Setting URI Schemes

URI scheme setup is handled in the app's code, as shown below. The same URI scheme should also be defined on AppsFlyer's OneLink template page.

Android All Versions

In your app’s manifest add the following intent-filter to your relevant 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="your unique scheme" />
</intent-filter>

Example

<activity android:label="@string/greatapp" ….. >    
      <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>

iOS 8 and below

In Xcode, open app information plist file.
Add a URL types entry
Expand URL type and “item 0” rows and add a new row.
Add a unique identifier for the app for URL identifier as a value. It is best to select a unique identifier which is unlikely to be used by other apps.
Right-click the URL identifier and select Add Row, then select URI Schemes and set the Item 0 value to your unique scheme.

OneLink Template setup:

On AppsFlyer's dashboard, in the OneLink configuration screen, under Deep Linking Custom URI Scheme (iOS8/Android 5 and below) populate the scheme as defined (e.g. "scheme://").

Testing URI Schemes

Install and run the app on your device (or iPhone simulator on iOS).
Open default browser (Safari on iOS) and type in the address bar your URL unique scheme (e.g. "greatapp://").
The mobile app is launched at the default activity.

OneLink Template Configuration

In the OneLink Configuration screen, under Deep Linking Custom URI Scheme (iOS8/Android 5 and below) populate the scheme as defined (e.g. "greatapp://").

Universal Links

From iOS 9 and above, Apple has replaced URI schemes as the primary method for deep linking, with Universal Links. This method has improved security as universal links cannot be claimed by other apps. It also has improved user experience since iOS apps launch directly and users are not firstly redirected to the browser.

Essentially, the Universal Links method links between an iOS mobile app and an associate website/domain, such as AppsFlyer’s OneLink domain (xxx.onelink.me). To do so, it is required to:

Configure OneLink sub-domain and link to mobile app (by hosting the ‘apple-app-site-association’ file - AppsFlyer takes care of this part)
Configure the mobile app to register approved domains.

The associated domains are displayed.

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

Tip

Even with iOS9+, it is still important to implement a URI scheme as some browsers or apps still do not support Universal Links and fall back to the URI scheme method.

Here are the necessary steps to take to utilize deep linking using OneLink and Universal Links:

Configure OneLink sub-domain and link to app

To complete this step, the developer must obtain the app’s ‘Team ID’ (or ‘App Prefix’ in case of multiple Team IDs) from the Apple Developers portal (under ‘View Account >> Account Summary’).
In the app’s AppsFlyer Dashboard/settings go to >>‘Configure OneLink’ in the menu >> under ‘iOS’ check the ‘Enable iOS9 Universal Links for deep linking’ checkbox and populate the Team ID/App Prefix fetched in step 1.

Note

For pending apps, the developer must also provide the iOS App Bundle ID

Choose a OneLink sub-domain and populate it in the Deep Linking (iOS9/Android 6 and above) sub-domain field available under Additional Configuration section.

Note

While the sub-domain can be changed at anytime, it causes all existing OneLink URLs using the original sub-domain to stop working.

Configure mobile app to register approved domains

In the Apple Developers portal under Identifiers >> App IDs, select the app and enable Associate Domains, then generate provisioning files for the app, download them and double-click to install them on Xcode.
In Xcode under the Capabilities section, Enable Associated Domains and populate the OneLink domain as configured on the “OneLink configuration” (AppsFlyer account).

Note

The domain must be prefixed by "applinks:". For example: applinks:mydomain.onelink.me

Warning

Not all apps, including social networks apps, fully support Universal links. For further details, please see this section.

There may also be other limitations with Universal links. Visit the troubleshooting section for more details.

Android App Links

This method, which was introduced with Android 6.0, is Google's version of universal links and has similar benefits.
However, while almost all iOS users have OS version 9 or above, and therefore MUST use universal links, on Android about half of the users still have OS versions lower than 6.0, and therefore MUST use URI schemes for deep linking.
Since URI schemes cover deep linking for all Android users, many app owners elect to implement only this method for Android deep linking.
Advertisers that do want to implement app links, would usually need to implement URI schemes as well.
This article explains how to implement Android app links.

Deep Linking Fallback

Deep linking provides a great user experience, but broken deep links definitely not! You may get broken deep links due to a variety of reasons, from misconfiguration to sudden changes in media source platform behavior.

Therefore, whenever creating a OneLink for deep linking we highly recommend using a fallback!

af_ios_url and af_android_url redirect OneLink users to landing pages, rather than to the app stores. However, when deep linking applies on a OneLink, it takes precedence over the landing page redirection.

This means it's safe to use these parameters with deep linking. If the deep linking works correctly, the user is deep linked as planned. If the deep linking is broken for some reason, the user is taken to the landing page of your choice (e.g., your home page), instead of getting stuck.

More information about redirection parameters here.

Reporting on Deep Linking

Deep linking is a crucial part of retargeting campaigns. In many cases, retargeting campaigns are based on offering returning users some personalized content, such as credits or access to premium content.

To enable AppsFlyer to process and attribute these retargeting/deep linking actions, the app developers MUST report to AppsFlyer's SDK whenever a deep linking occurs.

To implement this, follow these instructions for iOS and Android.

Assigning Apps to Multiple OneLink Templates

Although you can use a single OneLink template to create a limitless numer of OneLink URLs, in some cases you might have to assign an app to more than one OneLink template.

For example, if you have multiple versions of an Android app for out-of-store markets, you may need a separate OneLink template per Android version, yet have the same iOS app assigned to all of them.

For each template to which you add an app (after the first template), you must complete the instructions below, according to the relevant deep linking method.

Android - URI Scheme

No special actions required

iOS - Universal Links

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.

Android - App Links

After creating the new OneLink template, copy the new Onelink ID generated for it.
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.
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.

Note

AppsFlyer accounts are limited to a maximum of 100 defined OneLink templates per account.

Accessing Deep Linking Data

So far this guide has covered the setup of the 3 direct deep linking methods, which enable existing users to launch the mobile app directly after clicking the URL.

A very common requirement is getting the URL data into the newly launched app, to programmatically redirect users or for serving other personalized content.

For NEW users this data is called Conversion Data (explained here), and for EXISTING users it is called Re-Engagement Data (explained here).

Example

Wendy, the mobile marketer of the com.burgers mobile app, runs a retargeting campaign on xnetwork media source. The campaign offers a free bonus (Fries, Burrito or Soda) for any user, new or existing, ordering a burger using the app.
To do so, Wendy adds the af_sub1 parameter to the retargeting tracking link, which has the bonus selected by the user, e.g. "&af_sub1=fries". The link also contains the af_dp parameter for deep linking into the default activity.
With every app launch the app needs to check if there was a recent link click, extract the value of af_sub1, and display the correct bonus to the user.
When an existing user clicks on the retargeting link, the app launches, and the re-engagement data from the retargeting link becomes parsed and available via the onAppOpenAttribution SDK function.
When a new user, whether returning or brand new, launches the app, the link's information is available via the conversion data API.
Using these methods, com.burgers is always able to give the lead or existing user, the exact bonus they have selected.

Accessing Conversion Data for Deferred Deep Linking

When active users click on OneLink, they can be deep linked and redirected to any content within your app.

How can you give your leads the same experience?

When leads click on OneLink, they are redirected to the app store matching their device type, where they install the app from. On first launch, the app opens at the default activity regardless of the ad they clicked on.

To enable a unified deep linking experience to all users, existing or new, AppsFlyer provides the deferred deep linking solution.

As shown above, when new users launch the app for the first time AppsFlyer provides the app with their attribution details, including any deep linking data, if exists. Using this data the app developer can send the new user to any content within the app, exactly like an existing user being directly deep linked.

To implement deferred deep linking please follow the instructions on this guide.

Tip

If you are able to target only existing mobile users with your deep linking campaigns, you don't have to implement deferred deep linking. However, if a substantial portion of your targeted audience may not have your app installed (e.g. users that have uninstalled recently), then implementing deferred deep linking is important for their good user experience and retention.

Accessing Re-Engagement Data for Direct Deep Linking

Accessing the re-engagement data of existing users, who directly deep link, is also crucial in these cases:

iOS 9.2 and above - for these users the deep linking act (Universal Links) only launches the mobile apps at the default activity regardless of any parameters on OneLink
Android 6.0 and above - the same applies to these users, when App Links is configured
All Android - all Android users can still use URI Schemes for deep linking, and get redirected to specific location. However, to also serve personalized content beyond redirection (e.g. send users to a bonus activity and specify the bonus type on the link), the re-engagement data is needed.

The onAppOpenAttribution SDK function (described below) enables accessing the full re-engagement data for all user types.

The capture below shows the flow for getting either the attribution or re-engagement data:

The conversion data has the is_first_launch parameter, which is "true" only on first launches, and "false" otherwise.

The `onAppOpenAttribution` method

The onAppOpenAttribution method parses the data and returns it via an NSDictionary <key, value> (Hash Map) object on iOS or Map <key, value> object on Android. This is true when using app specific tracking links, URL schemes or shortened OneLinks.
However, when users deep link directly using universal or app links, the onAppOpenAttribution method returns the full link unparsed since the app opens directly without going through AppsFlyer first.

Parse the values in the URL data and programmatically serve content or redirect within app accordingly.

The onAppOpenAttributionmethod should be called from the same class/delegate that the onConversionDataReceived (iOS) or onInstallConversionDataLoaded (Android) method is called.

Tip

We recommend using the af_dp parameter values here as well, to create a unified logic across all deep linking scenarios.

For both methods (onAppOpenAttribution and onConversionDataReceived / onInstallConversionDataLoaded), the user must set the tracker delegate for AppsFlyer's SDK as shown in the code below:

Note

Deep linking flow for iOS is slightly different than Android. See the flowchart below for illustration.

The flow chart above demonstrates the following:

User clicks on a deep link
continuteUserActivity or openURL method tell the AppsFlyer SDK that the app is opened using deep linking
AppsFlyer SDK tracks the app launch
The onAppOpenAttribution method is then called
The onAppOpenAttribution method contains deep linking data
Deep linking data is then used to redirect users to the relevant activity and serve the relevant content

Note

The code below lists two methods: onInstallConversionDataLoaded and onAppOpenAttribution

onInstallConversionDataLoaded is for deferred deep linking.

onAppOpenAttribution is for direct deep linking.

AppsFlyerLib.getInstance().registerConversionListener(this, new AppsFlyerConversionListener() {
	/* for deferred deep linking */
    @Override
	public void onInstallConversionDataLoaded(Map<String, String> conversionData) {
		for (String attrName : conversionData.keySet()) {
			Log.d(AppsFlyerLib.LOG_TAG, "conversion_attribute: " + attrName + " = " +
					conversionData.get(attrName));
		}
	}

	@Override
	public void onInstallConversionFailure(String errorMessage) {
		Log.d(AppsFlyerLib.LOG_TAG, "error onAttributionFailure : " + errorMessage);
	}

    /* for direct deep linking */
	@Override
	public void onAppOpenAttribution(Map<String, String> conversionData) {
		for (String attrName : conversionData.keySet()) {
			Log.d(AppsFlyerLib.LOG_TAG, "onAppOpen_attribute: " + attrName + " = " +
					conversionData.get(attrName));
		}
	}

	@Override
	public void onAttributionFailure(String errorMessage) {
		Log.d(AppsFlyerLib.LOG_TAG, "error onAttributionFailure : " + errorMessage);
	}
});

The tracker delegate should be passed on the delegates header file, as follows:

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate, AppsFlyerTrackerDelegate{

// ...

  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    // Override point for customization after application launch.
    AppsFlyerTracker.shared().appsFlyerDevKey = "repLaceWithYourDevKeY"
    AppsFlyerTracker.shared().appleAppID = "123456789"
// ...
    AppsFlyerTracker.shared().delegate = self
}

func onConversionDataReceived(_ installData: [AnyHashable: Any]) {
  //Handle Conversion Data (Deferred Deep Link)
  }
  
  func onConversionDataRequestFailure(_ 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
  }

In AppDelegate.h:

@interface AppDelegate : UIResponder <UIApplicationDelegate, AppsFlyerTrackerDelegate>

In AppDelegate.m:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  // Override point for customization after application launch.
  
  [AppsFlyerTracker sharedTracker].appsFlyerDevKey = @"repLaceWithYourDevKeY";
  [AppsFlyerTracker sharedTracker].appleAppID = @"123546789";

  [AppsFlyerTracker sharedTracker].delegate = self;
}

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

-(void)onConversionDataRequestFailure:(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;
  }

In the AF GameObject inside the Start method:

#if UNITY_IOS

  /* Mandatory - set your iOS app ID */
  AppsFlyer.setAppID("123456789");
  
  /* Call getConversionData() to get the conversion data in iOS*/
  AppsFlyer.getConversionData();

  AppsFlyer.trackAppLaunch();

#elif UNITY_ANDROID

  /* Mandatory - set your Android package name */

  AppsFlyer.setAppID ("com.company.app");

  /* For getting the conversion data in Android, you need to add the "AppsFlyerTrackerCallbacks" listener.*/

  AppsFlyer.init ("AF_DEY_KEY","AppsFlyerTrackerCallbacks");

#endif

Implement your logic in the didReceiveConversionData method inside the AppsFlyerTrackerCallbacks class:

public class AppsFlyerTrackerCallbacks : MonoBehaviour {

	public Text callbacks;

	// Use this for initialization
	void Start () {
		print ("AppsFlyerTrackerCallbacks on Start");
		
	}
	
	public void didReceiveConversionData(string conversionData) {
		print("AppsFlyerTrackerCallbacks:: got conversion data = " + conversionData);
	}
	
	public void didReceiveConversionDataWithError(string error) {
		print ("AppsFlyerTrackerCallbacks:: got conversion data error = " + error);
	}
	
	public void didFinishValidateReceipt(string validateResult) {
		print ("AppsFlyerTrackerCallbacks:: got didFinishValidateReceipt = " + validateResult);
		
	}
	
	public void didFinishValidateReceiptWithError (string error) {
		print ("AppsFlyerTrackerCallbacks:: got idFinishValidateReceiptWithError error = " + error);
		
	}
	
	public void onAppOpenAttribution(string validateResult) {
		print ("AppsFlyerTrackerCallbacks:: got onAppOpenAttribution = " + validateResult);
		
	}
	
	public void onAppOpenAttributionFailure (string error) {
		print ("AppsFlyerTrackerCallbacks:: got onAppOpenAttributionFailure error = " + error);
		
	}
	
	public void onInAppBillingSuccess () {
		print ("AppsFlyerTrackerCallbacks:: got onInAppBillingSuccess succcess");
		
	}
	public void onInAppBillingFailure (string error) {
		print ("AppsFlyerTrackerCallbacks:: got onInAppBillingFailure error = " + error);
		
	}

	void printCallback(string str) {
		callbacks.text += str + "\n";
	}
}

Deep linking with SRNs

SRNs (Self Reporting Networks, e.g. Facebook and Twitter) have their own proprietary methods for deep linking, which don't involve tracking URLs of external attribution services.
So how can you deep link your users and get the relevant data from SRNs?

Direct deep linking with SRNs

SRNs use their own methods to perform deep linking.
Unfortunately, this means that the onAppOpenAttribution method is NOT called when a user's device performs deep linking from an SRN.
Therefore, if there's a need for the direct deep linking data within the app, the app owner needs to use the SRN's methods to get it upon app launch.

Deferred deep linking with SRNs

In contrast, deferred deep linking with SRNs is possible.
AppsFlyer always receives the conversion data and makes it available to the app on first launch.
New users that install after clicking on a deep linking/retargeting campaign on an SRN can be redirected within the app upon launch, by using the conversion data.

However, with SRNs, the regular AppsFlyer deep linking parameters, such as af_dp, are not present as part of the deep link data.
To use this data within the app, the developer needs to employ further logic based on available parameters, such as campaign, ad set or single ad names.

Example

Jill, the mobile marketer of greatapp, decides to run a deep linking campaign on Facebook, targeted for general audiences.
The campaign redirects any clicking users to a "bonus" activity.
Jack, the mobile developer, adds this logic after getting the conversion data:
1. Is it Facebook originated ("is_fb=true")?
2. If true - get the value of the adgroup parameter.
3. If the value contains the word "bonus" send the user to the "bonus" activity.
Using Facebook's methods existing users clicking the ad are redirected to the activity directly, while new users get the same experience using AppsFlyer's conversion data.

Building OneLink URLs

You can build and use an unlimited number of custom OneLink URLs based on each configured OneLink template:

Go to the relevant app's dashboard (i.e. one of the apps that are configured at the relevant OneLink's template).
Click on Link Management
Select Multiple Platforms link for OneLink URL
Name your new link in the general settings section
Populate the attribution parameters, such as Media Source, Campaign, ad set or subscriber parameters.
To enable retargeting attribution, set the Retargeting Campaign toggle button to ON
If required, add deep linking or redirection parameters
If required, use the advanced settings section to customize the click-through lookback window
If required, set fixed install cost on the tracking link
We highly recommend using the shortened links
Save the link, copy and use it with your owned media or any other relevant media source

Using OneLink with Integrated Partners

In some rare cases, you may wish to use OneLink's diagnostic and redirection abilities with integrated partners, rather than use their own tracking links.

Visit here for instructions.

Testing OneLink URLs

To test deep linking quickly and easily you can use:

For Android - AppsFlyer's SDK integration test app
For iOS - Dashboard's SDK Integrations Tests page

Alternately or additionally, you can also manually test deep linking into your app. Tests for all 3 deep linking methods are described below.

Note

AppsFlyer supports testing app versions that are not live yet (e.g. pending approval or in development).
To do this, follow the instructions below fully with one distinction: whenever you are instructed to install the app, install locally and not from the market.

Testing Direct Deep Linking for Scheme URIs

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.]
Prepare a OneLink URL for the app, which has the af_dp parameter with a valid scheme path (e.g. "greatapp://cars").
On the tested device paste the link into email, notes, SMS, QR code generator etc.
Click the link.

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

Testing Deferred Deep Linking for Scheme URIs

Logout of app.
Delete the app.
Prepare a OneLink URL for the app, which has the af_dp parameter (or another) with a valid scheme path (e.g. "greatapp://cars").
On the tested device paste the link into email, notes, SMS, QR code generator etc.
Click the link.
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.

Testing Universal Links or Android App Links

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.]
Prepare a OneLink URL for the app, which has the af_dp parameter (or another) with a valid scheme path (e.g. "greatapp://cars").
iOS - Paste the link in Notes, iMessage or in an email using the Apple Mail Client.
Android - Paste the link into email, Chrome, SMS, QR code generator etc. Do not use Slack, Facebook or any other social app to click the link!
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.

Tip

Getting unexpected behavior on iOS devices?

1. Restart the device (turn off and then on again) - on iOS 11 this can often fix strange entitlement issues.

2. Do not paste the link into Safari - currently iOS prevents deep linking from any browser's address bar.

3. Anything else? Check the FAQs and troubleshooting section.

Wrapping and Shortening OneLink

Deep Linking with iOS Universal Link and Android App Links requires associating your OneLink domain (e.g. myapp.onelink.me) within the app's code. This domain is then recognized by the Operating System as a domain which invokes the app when clicked.

Wrapping a OneLink URL or shortening it through EXTERNAL link shorteners (e.g. bit.ly) breaks deep linking through iOS Universal Links and Android App Links, as it disables the Operating System's ability to identify which app needs to be invoked with the link.

Wrapped or shortened OneLink URLs still redirect to the app stores or to landing pages, but at the expense of an additional redirect impacting the end user experience.

Best Practices

Before embarking on a full-scale deep linking campaign we recommend visiting the Best Practices for Deep Linking article. It covers typical pitfalls and solutions for implementing mobile deep linking tracking with OneLink.

For other frequently asked questions and troubleshooting tips see below.

FAQs

Can I deep link without OneLink?

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 tracking 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 tracking links.

Are there any Deep Linking Limitations on Social Network apps?

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 tracking 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.

885402320830842.XbZXy5YrCSL3FKIBZPjn_height640.png

Can I add parameters to af_dp?

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 tracking 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).

Important!

The following characters are not allowed [<>;(){}`']

Troubleshooting

iOS App Launches but onAppOpenAttribution callback is not called

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.

iOS app Launches but immediately redirects to the App Store

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.

iOS - Tapping the link always redirects to the App Store

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 button on the top right of the device which sets that link to be opened without deep linking.

To reset this setting perform a long tap on the link on your iOS device until the following popup menu appears:

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!

In this case the app was not configured properly for Universal Links. Check the following:

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 configuration page.

iOS Universal links - Safari opens instead of the app

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.

iOS Universal links - I tried it all but still it doesn't work. Help!

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 Universal links - iOS 11.2 Problem

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.

Why Can't My Opted-Out Users Deep link?

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.

App Links and Universal Links - Long OneLink Response in onAppOpenAttribution

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.

Introduction

The 2 Deep Linking Types

Important!

Deep Linking and OneLink

Deep Linking and Retargeting

Deep Linking Methods

URI Scheme

Tip

Important!

Setting URI Schemes

Android All Versions

Example

iOS 8 and below

Testing URI Schemes

OneLink Template Configuration

Universal Links

Tip

Configure OneLink sub-domain and link to app

Note

Note

Configure mobile app to register approved domains

Note

Warning

Android App Links

Deep Linking Fallback

Reporting on Deep Linking

Assigning Apps to Multiple OneLink Templates

Android - URI Scheme

iOS - Universal Links

Android - App Links

Note

Accessing Deep Linking Data

Example

Accessing Conversion Data for Deferred Deep Linking

Tip

Accessing Re-Engagement Data for Direct Deep Linking

The onAppOpenAttribution method

Tip

Note

Note

Deep linking with SRNs

Direct deep linking with SRNs

Deferred deep linking with SRNs

Example

Building OneLink URLs

Using OneLink with Integrated Partners

Testing OneLink URLs

Note

Testing Direct Deep Linking for Scheme URIs

Testing Deferred Deep Linking for Scheme URIs

Testing Universal Links or Android App Links

Tip

Wrapping and Shortening OneLink

Best Practices

FAQs

Can I deep link without OneLink?

Are there any Deep Linking Limitations on Social Network apps?

Can I add parameters to af_dp?

Important!

Troubleshooting

iOS App Launches but onAppOpenAttribution callback is not called

iOS app Launches but immediately redirects to the App Store

iOS - Tapping the link always redirects to the App Store

iOS Universal links - Safari opens instead of the app

iOS Universal links - I tried it all but still it doesn't work. Help!

iOS Universal links - iOS 11.2 Problem

Why Can't My Opted-Out Users Deep link?

App Links and Universal Links - Long OneLink Response in onAppOpenAttribution

Articles in this section

Related articles

Page Contents:

The `onAppOpenAttribution` method