Deep linking with OneLink best practices


OneLink™, AppsFlyer's multi-platform link, enables advertisers to perform device detection and redirection, deep linking and even deferred deep linking, with a single click.

However, due to the fragmented nature of the ecosystem, some advertisers encounter issues with OneLink and deep linking.

This article covers typical pitfalls and solutions for implementing mobile deep linking with OneLink.

Deep links break

links_break.jpgDespite the best intentions, in some cases, your OneLink URLs may not perform the intended deep linking. When this happens, the user, instead of getting deep linked into a specific activity within the app, is redirected to the app store or even to an error page.

This is definitely not the experience that advertisers want for their users, as it creates churn instead of delight.

Why does it happen?

  • Host applications
    Apps, in which your attribution links are shared (e.g., Whatsapp, Gmail, Wechat), use different methods for activating clicked links, such as proprietary internal browsers. Some of these are known to block all attribution links.
  • Browsers
    Different browsers and OS platforms behave differently with links. For example, currently iOS prevents deep linking from the address bar of all browsers.
  • OS updates
    New OS updates may introduce unexpected bugs, that can hamper with the deep linking. This can happen not only in the chaotic multi-vendor Android ecosystem, but also in the closed paradise of iOS, as this issue with iOS 11.2 has demonstrated.
  • Devices
    Users have smartphones, tablets, laptops and other devices running versions of Android, iOS, Windows phone and other operating systems. Their handling of attribution links may vary greatly.
  • Misconfiguration
    Using illegal characters in the deep linking value breaks the link.
    DON'T use these characters: []<>;(){}'`".

Fallback solution

To avoid this bad user experience, we recommend using the fallback solution, which enables sending users to specified web pages, should the deep link fail for any reason.

af_ios_url and af_android_url are destination parameters, which can be used for the deep linking fallback. When deep linking fails in an iOS device (for example, an iPhone or iPad) the user is redirected to the page specified with af_ios_url. af_android_url does the same for Android users. To redirect web users, use the web fallback.


Android/iOS users who click on the OneLink URL above are supposed to get deep linked into the app. Where deep link action fails users are redirected as follows:

  • Android:
  • iOS:


  • Always have af_ios_url and af_android_url on your OneLink URLs, if you're not sure how the serving platform handles it.
  • When redirection takes place through, any parameters on the OneLink will pass through to the destination page that is specified in af_ios_url or af_android_url. To prevent the parameters from being populated on the destination URL, add the parameter af_param_forwarding=false to the OneLink.

Forced deep linking solution

Another solution besides the fallback URLs is forcing deep linking to take place. This solution works well for users who have the app installed. However, iOS users that don't have the app installed and click the link in Safari, are shown an error message and are redirected to the defined URL fallback for iOS users.

To overcome this for iOS users: Add af_force_deeplink=true to the OneLink URL to force deep linking into the activity specified in af_dp.

When a OneLink that has af_force_deeplink=true is opened, 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:


Deep linking from social media

Social media limitations

While OneLink tries to cover redirections and deep linking from paid and non-paid posts in various social media platforms, these platforms can change the way they handle deep links without prior notice.

Check here whether the social app you wish to advertise on supports redirections and deep linking.


Use the URL fallback solution or force deep linking, as explained above, to prevent social apps from breaking the deep linking experience of your users.

Social media previews

When posting OneLink in social media posts, by default the post shows a reduced image of the app's page on Google Play, which may not draw a lot of user attention. You can improve this easily by including the af_web_dp parameter on the OneLink URL.

af_web_dp is mainly used to redirect desktop (Windows or Mac users) users clicking on OneLink. Most social media apps (Facebook, Twitter, Slack, WhatsApp etc.) also use it to render the preview of the links associated with this parameter. Note that the linked page MUST have the relevant open graph meta tags (title, description, image) for the rendering to work.



Use af_web_dp on OneLink URLs in social media posts, to display the reduced image of the web page pointed at by af_web_dp.

Deep linking from Instagram

Deeplinking on Instagram using Android is supported without any special considerations. However, that's not the case with iOS. Instagram doesn't support deep linking into iOS apps.

To overcome this issue, you can take one of two approaches:

  • Recommended - configure an Instagram landing page for custom links. The Clustered Poster and ShowAndTell templates work best.
  • Use force deep linking when using OneLinks on Instagram, keeping in mind the following when using af_force_deeplink=true with OneLink on Instagram:
    User has the app? Click has af_force_deeplink=true? Result
    No Yes Click Doesn't open the app and doesn't open the app store
    No No Click opens the app store
    Yes Yes Click opens the app
    Yes No Click opens the app store

OneLink and desktop users

Desktop users may engage with your OneLink URLs, e.g. via an email campaign. When desktop users click on a deep linking URL, obviously mobile deep linking cannot take place.

So how can you save desktop users and convert them into mobile users?

On the OneLink URL or template, you can set a redirection for desktop users (Windows or Mac) using the af_web_dp parameter, and maintain a unified user experience across platforms.

Another option is to create a dedicated web form that sends a OneLink URL via SMS or email to the mobile device of the desktop user. This is explained as part of the landing page solution for desktop users.


Desktop users have their mobile devices very close by. Use this described technique to attribute these users and measure their comparative quality.

Shortening URLs

Don't wrap your OneLink URLs and don't use external link shorteners.

To activate Universal links, iOS needs to recognize the domain of the URL associated by the app.
A similar situation applies for Android users of App links.

When your OneLink URL is wrapped, the OS is unable to recognize the associated domain and so the deep linking action is broken.

Instead, we recommend to shorten your link using the link management page, where you create your OneLink URLs.

Why is it better?

  • It works, because it uses the OneLink subdomain configured in the OneLink template.
  • It enables you to change parameters on the fly, including any deep linking settings, even after distributing the attribution links to your leads.
  • It counts all the clicks from mobile devices in the AppsFlyer dashboard, so you don't need to check another service.
  • The last part in the short URL can be customized to make it a branded link.


Need to shorten OneLink URLs? Create it in AppsFlyer!
It's simple, free and saves you a lot of trouble.

Using OneLinks in emails

Email Service Providers wrap any link that is placed within emails, to count the performed clicks.

This breaks the deep linking flow for all your users, which click on the URL in the email.

There are three optional solutions:

  1. Disable click recording within the ESP (Email Service Provider)
  2. Force the URI scheme, stated with the af_dp parameter, by adding the flag af_esp=true to the attribution link. This solution is similar to forcing deep linking solution (see above) and has the same problem of bad user experience for leads who don't have the app installed.
  3. Use ESPs that support AppsFlyer's solution for deep linking with Universal Link. in emails. Learn more


The easiest way to stop ESPs from breaking deep linking is by disabling their click recording.

Universal Links and App Links

When to use Universal Links?

If you have iOS users, who you want to engage with retargeting/deep linking campaigns, you MUST use Universal links, which is the deep linking method for over 98% of iOS users.

However, it is still recommended to implement a URI scheme solution for iOS users, to fully cover for all iOS users. In addition, OneLink may also use the URI scheme to perform deep linking if the universal link breaks.

When to use App Links?

Use App Links to smoothly and securely open the app from a clicked link, and deep link users with Android version 6.0 and above. For users with Android versions below 6.0 (for which App Links don't work), you need to use URI schemes.

"Real" deep linking for iOS users

Universal Links is considered as an advanced and secure method for deep linking.

However, the entry point to iOS apps through deep linking is not any specific location in them. To redirect iOS users into specific locations, the URL that invokes the app must contain information about the location. This information should be used programmatically to redirect the user into the location.


In addition to Universal Links and App Links, it is recommended to also implement URI schemes. They are an effective fallback method for when Universal or App Links don't work. Also, it's the only way to open your app from a link on a device with below Android 6 or below iOS 9.

What is deferred deep linking good for?

1. Complete deep linking for new installs

When new or past users install your app following engagements with a OneLink deep linking campaign, the automatic deep linking flow of existing users is broken.

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

However, by accessing the user conversion data in real time at the SDK level you can redirect the user to the correct activity programmatically. This is AppsFlyer's Deferred Deep Linking solution.

2. Serving personalized content

Another use for the conversion data is serving personalized content to the user's preferences.

Add parameters with specific information about the user or the ad to the OneLink URL. When the user installs the app after the click, that information becomes available to use.


Your eCommerce app, SlimeBowl, sells slime in different colors and sizes. You decide to run a campaign where leads installing your app receive a free slime box in the color and size of their choice.

To do this, you create a landing page with a Download button, with a OneLink URL behind it. When the lead selects the color and size of the slime box, the data is added to the URL using the subscriber parameters.

Once the lead clicks and installs the app, using the conversion data, the app displays a message showing the free slime box the user has chosen to receive.

Was this article helpful?