At a glance: This article provides solutions to common issues encountered when implementing deep linking with OneLink.
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. Below are some of the most common issues and their solutions.
Deep links break
Despite 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 desktop users, use the web fallback.
Example
https://go.onelink.ly/qwerty?pid=source&af_dp=greatapp%3A%2F%2F
af_ios_url=www.yoursite.com/ios6&af_android_url=www.yoursite.com/android6
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: www.yoursite.com/android-bonus
- iOS: www.yoursite.com/ios-bonus
Tip
- Always have
af_ios_url
andaf_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
oraf_android_url
. To prevent the parameters from being populated on the destination URL, add the parameteraf_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.
Tip
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.
Tip
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. 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 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.
Tip
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.
Tip
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:
- Disable click recording within the ESP (Email Service Provider)
- Force the URI scheme, stated with the
af_dp
parameter, by adding the flagaf_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. - Use ESPs that support AppsFlyer's solution for deep linking with Universal Link. in emails. Learn more
Tip
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 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.
Tip
In addition to Universal Links and App Links, it is recommended to also implement URI schemes. They are an effective fallback method for Adnroid 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 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.
Example
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.