OneLink troubleshooting and FAQ

Universal Links: Required for over 98% of iOS users

URI schemes: The primary method for opening apps on Samsung devices. Otherwise, it is a legacy and fallback method for opening apps. Can be used:

• For Android users with versions prior to 6.0 (less than 15% of Android users)
• As a fallback for when Universal Links and App Links don't open the app, either because they don't work, or aren't set up.

  Note: Using URI schemes as a fallback for Universal Links is subject to iOS-based limitations. Learn more.

Deep linking

Universal Links, App Links, and URI schemes are secure methods for opening an app. To deep link and redirect users into specific activities or pages in the app, follow the OneLink deep linking instructions.

Yes. Whenever Universal Links or App Links are implemented to open the app for existing users, iOS Associated Domains or AndroidManifest.xml is updated. This means that you must upload a new version of the app to the relevant app store. Tip: To minimize the need for app updates, make all the dev-related changes required to open the app and deep link at one time. 

Yes. However, configuring your template to do so affects all users (new and existing), and sends everyone to the landing page/web URL. Meaning, new users are not sent to the app store.

To send users to a web page:

1. In your template, do not set up Universal Links, App Links, or URI scheme.
2. Set up the redirections for when the app isn't installed to the landing page/web URL.
   • The landing page/web URLs are added as the values for the af_android_url and af_ios_url parameters.
   • The redirections are then automatically applied for when the app is installed (for existing users), as well. 

Note: If you want to redirect existing users to a mobile web page only after app launch, your app developer must configure that behavior.

You can set specific redirections for:

• Windows phones
• iPads
• Amazon Kindle Fire.

Other tablets are not currently supported for separate redirection.

Yes. While you can use a single OneLink template to create a limitless number of OneLink URLs, in some cases, it might be necessary 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 for each Android version with the same iOS app assigned to all of them.

Important:

For templates using iOS Universal Links and Android App Links to open the app, if your templates have different subdomains, you need to configure and update your iOS and Android apps for each one: 

• iOS Universal Links: After creating the new OneLink template, and updating the associated domain in the app, submit a new version to the App Store. Only iOS users who have updated to the new version can activate a OneLink URL built on the new template.
• Android App Links:
  1. After creating the new OneLink template, copy the XML snippet at the bottom of the App Link section and add it to the AndroidManifest.xml file inside the intent you want to deep link into, in addition to any previous intents.
  2. Release the new version to the store. Only Android users who have updated to the new version can activate a OneLink URL built on the new template.

Yes, but only by contacting your CSM or by sending an email to our Customer Engagement team at hello@appsflyer.com.

Note: If you have existing OneLink URLs based on the deleted template, they won’t work even to get users to the app store. For this reason, it’s particularly important that you don’t delete a template without first making sure that there are no OneLink URLs using it. Alternatively, consider if it's possible to achieve the results you need by changing the existing template's configuration instead of deleting it.

Yes, as long as there are no existing custom links in AppsFlyer based on the template.

If there are already custom links in AppsFlyer based on the OneLink template, then the subdomain can't be changed. This limitation is designed to prevent breaking the redirection/deep linking behavior of live links.

If you do need to change the subdomain in a template with existing custom links, you can either: 

• Create a new OneLink template with the new subdomain, and create links based on it.
• Delete all existing custom links based on the template for which the subdomain needs to be changed. Once all links based on the template have been deleted, the subdomain becomes editable.

No. Taking the subdomain/domain configured to a specific template and template ID and manually concatenating it to a different template ID breaks the functionality of Universal Links and App Links, and poses a security threat.

Example:

• Template 1ABC is configured with subdomain bank.onelink.me.
• Template D123 is configured with subdomain game.onelink.me.
• The link bank.onelink.me/1ABC/shorturl is created based on template 1ABC and works.
• The link game.onelink.me/D123/exampleurl is created based on template D123 and works.
• The link game.onelink.me/1ABC/shorturl doesn't work
• The link bank.onelink.me/D123/exampleurl doesn't work

Yes. However, make sure you create separate templates with the subdomain; don't just manually add the subdomain to a template ID. 

Desktop users can engage with your OneLink custom links, for example, via an email campaign. However, when desktop users click on these links, they cannot be redirected to a mobile site, app store, or app.

So how can I give desktop users a good user experience and convert them into mobile users?

In the OneLink URL or template, you can redirect desktop users (Windows or Mac) to a different URL. This web URL is added to the link in the af_web_dp parameter. Note: If your link contains af_web_dp, AppsFlyer does not register a click when it comes from a desktop.

Apps on Chromebooks are considered to be Android apps.

For Chromebook, to redirect new users without your app installed to a different web URL:

1. In the OneLink template settings, under Set link behavior > When app isn't installed > Android, click Change to a different URL.
   OR
   In the OneLink link settings, under Deep linking & redirection > Redirect > When app isn't installed > Android, select Web URL.
2. Enter the URL.
   When added via the link settings, the URL is added to your link in the af_android_url parameter.

Yes, but only in part.

If you need to convert mobile web visitors into mobile users fast and can't integrate the AppsFlyer SDK, it is possible to do so.

Basic user redirection and app launching work even if AppsFlyer SDK isn't yet integrated into the app. Smart Banners don't require the SDK either and also work fine without it.

However, the absence of the SDK means that:

• Clicking users can't be deep linked beyond the initial app launch.
• Attribution data isn't recorded.
• In-app events aren't recorded.

The following table compares the different methods available for creating OneLink custom links.

Yes, but be aware that Universal Links and App Links only work when clicked on (for example, when clicking a link on a web page or email). Pasting the link in the browser address bar doesn't launch the app. Test your links by clicking on URLs; not by pasting them in the browser URL box.

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

There are several possible reasons for this: 

• Host applications: Apps in which your attribution links are shared (for example, WhatsApp, Gmail, WeChat) use different methods to activate clicked links, such as proprietary internal browsers. Some of these are known to block all attribution links.
• Browsers: Certain browsers and OS platforms behave differently with links. In certain browsers, for example, pasting a link does not work. The link must actually be clicked. 
• OS updates: New OS updates (both iOS and Android) may introduce unexpected bugs that hamper deep linking.
• Devices: Different smartphones, tablets, laptops, and other devices running different versions of iOS, Android, Windows Mobile, and other operating systems can vary greatly in their handling of attribution links.
• Misconfiguration: The use of special characters in the deep linking value breaks the link.

Two solutions for improving the user experience are Fallback URLs and forced deep linking.

Fallback URLs

Fallback URLs send users to specified web pages if opening the app or deep linking fails for any reason. Caution! They also send users without your app installed to the fallback URL instead of to the correct app store. So, be sure to only use this option if you're retargeting users with your app already installed.

To implement a fallback URL, 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.

Using this setting adds af_ios_url and af_android_url as destination parameters for the fallback, which will cause iOS users to be redirected to the page specified by af_ios_url and Android users to be redirected to the page specified by af_android_url. 

https://go.onelink.ly/qwerty?pid=source&af_dp=greatapp%3A%2F%2F&af_ios_url=www.yoursite.com/ios-bonus
&af_android_url=www.yoursite.com/android-bonus

Forced deep linking

Forced deep linking allows you to use a URI scheme as a fallback to open the app and deep link users.

This solution works well for most users who have the app installed. However, for iOS, using a URI scheme to open the app has limitations, and you may need to add af_force_deeplink=true to the OneLink URL to force deep linking into the activity specified in the URI scheme (the af_dp parameter). Learn more about URI scheme fallback for iOS.

Make sure you are not using an HTML <a> tag that includes the target attribute. If the OneLink URL is placed inside an <a> tag with the target="_blank" attribute, it opens a blank page in Chrome (on both iOS and Android), and the user is not redirected to the App Store or to Google Play.

Yes. However, on Android, when a user clicks a OneLink link on a Brave browser, deferred deep linking doesn't work. And on iOS, after the user clicks, they see a blank screen, and deferred deep linking only works if they then do something on the blank screen, for example, scroll, or tap.

No. OneLink custom links do not add any extra processing or load time to function properly and redirect users as required. They're just as fast as any other AppsFlyer links.

Turning on Enable cost per install (under Advanced parameters) allows you to apply a specific CPI value to each install coming from the link.

Select the cost currency and then a numeric ONLY value (with up to 4 digits after the decimal point) representing the CPI. This adds the parameters af_cost_currency and af_cost_value to the link.

af_r, af_ios_url, af_android_url, and af_web_dp carry over parameters from the attribution link or OneLink to the redirected page. To prevent this behavior, add af_param_forwarding=false to the attribution link.

OneLink is now the only supported method for creating custom attribution links for owned media.

In the past, app owners could also use single-platform (app-specific) custom links without using OneLink. This method is deprecated, and new custom links can only be created based on a OneLink template.

However, if you have legacy single-platform custom links, they still work as always. You can also view and edit your legacy links by clicking View legacy single platform links in the top right corner of the OneLink custom links page.

No, the short URL ID can only be set at the time the link is created.

External link shorteners or wrapping your OneLink custom links will break the app-opening functionality of Universal Links and App Links.

In order to activate Universal Links or App Links, the OS needs to recognize the domain of the URL associated with the app, and any type of external wrapping, shortening, or redirecting to the user-facing link makes this impossible. This includes using bit.ly, non-AppsFlyer branded links, or Email Service Providers (ESPs) with click recording enabled.

To wrap or shorten a link in a way that allows the redirection to work properly: 

• Use the short URLs generated by AppsFlyer when you create OneLink custom links (instead of external shorteners like bit.ly).
  Tip! Make the URL even shorter by creating a short branded domain on your link. And if you're creating the links in the AppsFlyer UI, you can edit the URL ID to be as short as possible. Example: https://brand.com/a1b2/a (where brand.com is your branded domain, a1b2 is the template ID which is always 4 characters, and a is the URL ID, which can be edited down to 1 character. 
  Benefits:
  • This method 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 of the short URL can be customized to make it a branded domain.
• Use the URI scheme as a fallback to open the app when Universal Links and App Links fail, and add the following parameter to the link: af_force_deeplink=true.
• See options for working with ESPs.

Yes, but it requires special consideration when you're working with Email Service Providers (ESPs). In order to count performed clicks, ESPs wrap all links placed inside emails. This breaks the app opening/deep linking flow for users who click the URL.

To prevent this, use one of the following optional solutions:

• Disable click recording in your ESP configuration.
  (Tip: This is generally the easiest solution.)
• Force the app open with the URI scheme specified in the af_dp parameter by adding the flag af_esp=true to the attribution link. This solution works well for users who have the app installed.
• Use ESPs that support the AppsFlyer solution for app opening and deep linking with Universal Links. Learn more.

OneLink redirects users to the correct regional app store based on their IP address.

Check whether you have activated Redirect allowlists in AppsFlyer. If you have it activated, the desired web URL domain or subdomain must be listed. Learn more about Redirect allowlists

Only the media source (pid) parameter is mandatory.

Yes, any parameter can be appended to the short URL.

Important! Parameters appended to the short URL do not override the parameters inside the link.

For owned media, custom media source names can be anything. However, it is recommended not to use organic as a custom media source name as this could affect attribution data integrity.

If you're using OneLink for paid media:

• Use the integrated partner-reserved pid values (those ending with _int), as media source values in OneLink custom links. Don't use SRN media sources like facebook, facebook ads, googleadwords, or twitter, as custom media source names. This could affect attribution data integrity.
• Make sure the partner is integrated in AppsFlyer (with Activate partner toggle turned on) for all apps that are set up in the OneLink template.

Best practice: Do not use organic as a custom media source name. This could affect attribution data integrity.

You can add numerous attribution parameters to enable you to perform a thorough drill-down analysis. 

See more information about AppsFlyer attribution link structure and parameters.

Yes. Custom parameters are passed to the original url column in raw data and can be seen there. They do not have their own columns in raw data.

For parsed data, use subscriber parameters af_sub1-5, each of which has a separate column in raw data reports. 

Yes. Make sure you use only lowercase letters for your parameters and values. Uppercase letters or Inconsistent capitalization of parameter names and values could cause errors or data discrepancies, both on the dashboard and in raw data.

You may want to use OneLink in unpaid posts on social apps since potential users who are exposed to such posts cannot be targeted in advance according to their devices.

Unfortunately, iOS Universal Link limitations and restrictions set by some social apps complicate the use of OneLink for basic device recognition, redirection and attribution, and deep linking. In certain cases, it may be necessary to set up a Social app landing page or URI scheme in order to redirect or deep link users.

The following table summarizes when OneLinks can be used in today’s popular social apps:

Yes, but note that OneLink is mainly used with owned media, not with ad networks. This is because ad networks usually advertise in apps (which means they know the user's platform, device ID, and so on), app and platform-specific attribution links suffice, so using OneLink isn't necessary. However, for cases in which ad networks don't know the user platform in advance (for example, when they run email or SMS campaigns themselves), OneLink can be the solution.

To set up OneLink for partner ad networks:

• Follow the ad network attribution link instructions, and select Use OneLink when prompted.

Once all the parameters for Android and iOS are added correctly, when the OneLink custom link is clicked and the user is redirected to the right platform, the required parameters are sent to the network within a postback after the user installs.

https://greatapp.onelink.me/3287867539?pid=network_int&c=email&
idfa{$IDFA}&gaid={$GAID}&clickid=$SITEID&
af_sub1=[pixel_code]&af_sub2=[creative]

Facebook and other social media apps sometimes block iOS Universal Links from opening apps. Social app landing pages are the recommended solution for these app-launching issues.

If you do not want to use Social app landing pages, you can use URI schemes as a fallback method. Note, however:

• Using URI schemes as a fallback is subject to iOS-based limitations.
• For many browsers, including Safari, you must add the af_force_deeplink=true parameter to the URL to use URI schemes as a fallback. Learn more.

Yes, but be aware of the following limitations:

• Due to the way Instagram renders the text of a page post, links are not clickable when entered into a post caption.

• App opening and deep linking into Android apps are supported without any special considerations. However, Instagram doesn't support app opening and deep linking into iOS apps. To overcome this issue, you can take one of two approaches:

  • Recommended: Configure a Social app landing page. 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 a URI scheme and forced deep linking when using OneLinks on Instagram. Be sure to keep the following considerations in mind the following when using af_force_deeplink=true with OneLink on Instagram:
    

    App installed?	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

WeChat overrides Android and iOS deep links and redirects users to a web page. From the web page, the user must click the Options button and choose to open the page in a browser. As a result, users encounter a broken user experience, increasing the chance for them to drop off in the conversion funnel.

To overcome this, OneLink recognizes clicks in WeChat and loads a dedicated landing page instructing the user to click the options button and then to click Open in Browser. This, in turn, opens the redirect URL defined in the OneLink template setup.

If the user’s WeChat language is registered as Chinese, OneLink generates a localized version of the landing page:

Opening the app and deep linking from an ad on Facebook is usually possible. However, if the following conditions apply, Facebook is not able to open the app for existing app users from the OneLink URL. Instead, all users, including those with the app, are sent to the URL defined in the OneLink template, or in the value of either the af_android_url, af_r, or af_custom_android_url parameter:

• User has an Android mobile device.
• Link is clicked on the Facebook app.
• Link leads to an HTML page that opens in Facebook webview (either a site or social app landing page).
• The HTML page contains a link with both an af_dp parameter (with a URI scheme) and a URL redirection setting in either the OneLink template or in a parameter (one of af_android_url, af_r, or af_custom_android_url).

The social app landing page gives users a seamless app-launching experience when using OneLink in social network apps. You may be concerned that adding a step to the funnel decreases conversion rates. But the truth is, that without the landing page, user journeys are generally broken, resulting in very low conversion rates.

If you're not fully convinced, why not test it?

A/B test your custom link in social media apps, with and without the Social app landing page.

To A/B test the Social app landing page:

1. Create a OneLink link (called Link1) to use with social media apps. Don't set the Social app landing page for this link.
2. Add the af_adset attribution parameter.
3. Add the af_ad attribution parameter with the value "no lp". 
4. Test Link1 outside of social media apps, and verify the link works and launches your app correctly.
5. Duplicate Link1 and call it Link2.
6. Change the af_ad attribution parameter value to "using lp". 
7. Create the Social app landing page for Link2 only.
8. Publish 2 different posts in the same social media app, using Link1 and Link2.
   Don't worry about the different number of clicks each link produces. The important KPI is the final conversion rate of each link.
9. Check the A/B test results after enough traffic is created.
   1. Go to the AppsFlyer overview dashboard and scroll down to the Aggregated performance report table.
   2. Link1 and Link2 have the same media source, campaign, and adset name. Drill down to the specific adset.
   3. Compare the conversion rates (and other KPIs) of users that clicked either Link1 or Link2.

If you see an app selection dialog when testing your OneLinks, make sure to sign your app, even if it's a debug app. The certificate you use to sign the app is the same certificate you use to generate the SHA256 fingerprint when configuring OneLink for App Links.

Your developers should implement the unified deep linking (UDL) method for deep linking. See our full instructions for deep linking.

iOS Universal Links and Android App Links are app-launching methods, which don't actually deep link users (sending them to specific content within the app). The URI scheme method can launch the app and deep link users (via the af_dp custom link parameter), but it should only be configured for app-launching. Its main usage is as a fallback method for Universal Links and App Links and for app-launching users with Android OS versions prior to 6.0.

After the app is launched using any of these methods, the AppsFlyer SDK supplies the deep_link_value specified in the custom attribution link. This value should be delivered via the UDL method implemented by your developers.

Yes, but it's not recommended. Ideally, you should use the deep_link_value for deep linking, and the URI scheme as a fallback method to launch the app without deep linking (via the af_dp parameter). However, if you already have the URI scheme set up to deep link, with additional parameters concatenated as part of the URI path (for example, greatapp://param1/param2), there is no need to change your existing configuration or code; the URI scheme will continue to work. 

The best practice for adding custom parameters is via the custom link setup page.

There is no user experience impact to iOS 14 users who are deep linked from campaigns on ad networks and owned media using the UDL method. The legacy method may impede deep linking.

For attribution/reporting purposes, AppsFlyer uses IDFA or IDFV when available. If there is no IDFA or IDFV, probabilistic modeling may be used. Starting with iOS 14.5+, probabilistic modeling is limited to the context of owned media, cross-promotion, and consenting user web-to-app flows.

There is no user experience impact to iOS 14 users who are deferred deep linked from campaigns on ad networks and owned media using the UDL method. The legacy method may impede deferred deep linking.

For attribution/reporting purposes, AppsFlyer uses IDFA or IDFV when available. If there is no IDFA or IDFV, probabilistic modeling may be used. Starting with iOS 14.5+, probabilistic modeling is limited to the context of owned media, cross-promotion, and consenting user web-to-app flows. We advise customers who want to implement deferred deep linking from ad networks and owned media to use AppsFlyer iOS SDK V6.1.0+ to allow for ATT consent (if needed), mitigate any attribution impact, and benefit from faster response times.