Deep linking with OneLink best practices

At a glance: This article provides solutions to common issues encountered when implementing deep linking with OneLink.


OneLink™, an AppsFlyer 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. Below are some of the most common issues and their solutions.

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

Fallback URLs lets you send users to specified web pages if opening the app or deep linking fails for any reason. Note! This will send users without your app installed to the fallback URL instead of to the correct app store. Therefore, you should only use this if you're retargeting users with your app already installed.

In the OneLink template or custom link settings, set the link behavior for when the app isn't installed to redirect to a different URL.

This addsaf_ios_url and af_android_url as destination parameters for the fallback. In an iOS device (for example, an iPhone or iPad), users are redirected to the page specified with af_ios_urlaf_android_url does the same for Android users.


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, 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, by using the URI scheme to open the app as a fallback. Add af_force_deeplink=true to the OneLink URL to force deep linking into the activity specified in af_dp.

This solution works well for most users who have the app installed. However, for iOS, using URI scheme to open the app, has limitations. Learn more about URI scheme fallback for iOS.

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

Deep linking 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 a Social media landing page for custom links. The Clustered Poster and ShowAndTell templates work best. In addition to the social landing page, we recommend setting a URI scheme in your OneLink template.
  • 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 opens 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, for example, 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.

Note: If your link contains af_web_dp, AppsFlyer does not register a click when the click is from a desktop.


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. Use the short URLs automatically generated by AppsFlyer when you create a OneLink custom link.

To activate Universal links, iOS needs to recognize the domain of the URL associated with the app. A similar situation applies to 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 you use the short URL generated by AppsFlyer in 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.

Use one of the following three optional solutions:

  • Disable click recording within the ESP (Email Service Provider)
  • 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 the deep linking solution (see above) and has the same problem of bad user experience for leads who don't have the app installed.
  • Use ESPs that support the AppsFlyer 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 all iOS users. In addition, OneLink may also use the URI scheme to perform deep linking if the Universal Links breaks. Learn more.

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 an advanced and secure method for opening the app.

However, the entry point to iOS apps is not to any specific location in them. To deep link and 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 Android when App Links don't work.  And for iOS, they have limited fallback capabilities for when Universal Links don't work. Learn more.

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 the first launch, the app opens at the default activity regardless of the ad they clicked on.

However, by accessing the user conversion data in realtime at the SDK level you can redirect the user to the correct activity programmatically. This is the AppsFlyer 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?