OneLink troubleshooting and FAQ

At a glance: Quickly find solutions for testing and debugging OneLink custom link redirection/behavior issues.

OneLink troubleshooting guide

OneLink frequently asked questions

OneLink template FAQ

Which method should I use for opening apps—Universal Links, App Links, or URI schemes?

Universal Links: Required for over 98% of iOS users

App Links: For Android users with version 6.0+

 Note

Both Universal Links and App Links require proof that the domain in the clicked URL (in other words, the OneLink custom link domain or branded domain) is owned and associated with the specific app it’s trying to open. This domain association is done via the Apple App Site Association file (AASA) for iOS and Assetlinks file for Android.

These files are either hosted by AppsFlyer or by the advertiser on its website. By default, when you create OneLink templates and set up Universal Links and App Links, these files are generated and hosted by AppsFlyer.

URI schemes: Legacy 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 fail to open the app.

    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.

Which operating systems allow URI schemes to open the app?

OS Do URI schemes work to open the app?
iOS Yes. Use as a fallback for Universal Links failure.

 

Important notes:

  • 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.
Android Yes. Use for Android versions prior to 6.0 and as a fallback for when App Links fail on later Android versions.
Amazon No
Windows Mobile No

Do I need to update the app after iOS Universal Links and Android App Links setup?

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 by OneLink guides 2, 3, and 4 at one time. 

Can I redirect existing users to a web page instead of the app?

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.

Can I assign an app to multiple OneLink templates?

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.

Can I delete a OneLink 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.

Can I change the subdomain in a OneLink template?

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.

Can the domain/subdomain of a OneLink template be applied to the template ID of another template?

No. This would break the functionality of Universal Links and App Links, and pose a security threat.

Can I use the same subdomain for more than one template?

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

OneLink custom link FAQ

Does OneLink work without the AppsFlyer SDK?

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.

Can OneLink custom links open the app from a browser?

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.

How can I redirect desktop users?

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.

 Tip

Try redirecting desktop users to a web URL that contains a dedicated web form that sends a OneLink URL to the mobile device of the desktop user via SMS or email. Learn more about this option as part of the OneLink Smart Script solution.

Why doesn't the OneLink URL open the app or deep link existing users?

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.

different_url.png

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

 Example

Consider, for example, the following OneLink 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

Both iOS and Android users who click on this link should be deep linked into the app. However, when deep linking fails, users are redirected as follows:

  • iOS: www.yoursite.com/ios-bonus
  • Android: www.yoursite.com/android-bonus

 Note

  • If you include a hash symbol (#) as part of a parameter value in the URL, you need to encode it.

  • When redirection occurs, OneLink URL parameters pass through to the destination page specified by af_ios_url or af_android_url. To prevent this behavior, add the parameter af_param_forwarding=false to the OneLink.

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.

Why does my OneLink URL open a blank page in Chrome?

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.

Do OneLink custom links take longer to load than other links?

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.

How can I record the cost per install when using OneLink?

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.

 Example

An SMS campaign costs $20 per 1000 messages (CPM). Experience has shown that your campaigns achieve a 5% conversion rate, meaning the derived CPI is $0.40. Setting the cost per install to 0.40 USD allows you to measure the eventual ROI of the SMS campaign.

Learn more about measuring cost and ROI.

How can I prevent parameter forwarding on redirections?

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

Are single-platform custom links still available?

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.

Can I change the short URL ID after saving a link?

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

Can I wrap and shorten OneLink custom links?

No, 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 wrapping, shortening, or redirect 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 automatically generated by AppsFlyer when you create OneLink custom links (instead of external shorteners like bit.ly).
    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.

Can I use OneLink custom links in emails?

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.

How do users get redirected to their regional app store?

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

OneLink parameter FAQ

What parameters are mandatory for OneLink custom links?

Only the media source (pid) parameter is mandatory.

Can parameters be appended to the short URL?

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.

 Example

  • You create a OneLink custom link with the following output:
    • Long URL: https://onelink-sim.onelink.me/Il2C?pid=training&c=peaches
    • Short URL: https://onelink-sim.onelink.me/Il2C/70e6d165
  • You append the following parameters to the short URL: https://onelink-sim.onelink.me/Il2C/70e6d165?c=bananas&af_adset=fruits
  • The af_adset=fruits parameter appended to the short URL is effective for attribution. However, the c=bananas parameter is not effective since there is already a c parameter in the long URL.

What custom media source names can I use?

Integrated partner-reserved pid values (those ending with _int), cannot be used as media source values in OneLink custom links. Use integrated partners setup to create partner-related attribution links. For more details, click here.

Do not use facebook, facebook ads, googleadwords, twitter, or organic as custom media source names. This could affect attribution data integrity, causing installs from your owned media to be attributed to integrated partners.

What attribution parameters can be added to a OneLink?

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

Attribution parameter Description Parameter link name
Campaign Set campaign names to compare different campaigns within the owned media source c
Adset Set ad set names to compare different ad sets within specific campaigns of the owned media source af_adset
Ad Name

Set ad names to compare different creatives within specific ad sets/campaigns of the owned media source

af_ad
Channel

Set channel names if you want to compare more than one distribution channel for your owned media.

Example: If you split SMS messages between two SMS service providers, specify the provider using the channel parameter. Later, you can compare the conversion rates of the two providers.

af_channel
Subscriber Parameters

Use any of the 5 available subscriber parameters to insert values that are useful for your analysis.

Note: These parameters are parsed and appear in raw data reports, which makes them useful for performing data aggregation or filtering.

af_sub1, af_sub2, af_sub3, af_sub4, af_sub5

Custom Parameters

Similar to subscriber parameters, you can specify fields with any parameter names and values. and any names.

Unlike subscriber parameters, custom parameters are not parsed in raw data; they appear in raw data reports only in the original url column.

Custom
(as you specify)

See more information about AppsFlyer attribution link structure and parameters.

Are custom parameters added to OneLink custom links available in raw data?

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. 

Are parameter names case sensitive?

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.

Integrated partner FAQ

Can I use OneLink in social apps (unpaid)?

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:

Social app Android users without app installed Android deep linking iOS users without app installed iOS deep linking
Facebook (including boosted posts) ✓* ✓* 
Facebook Messenger ✓*  ✓* 
Snapchat ✓*  ✓* 
Instagram ✓* 
LinkedIn ✓** ✓*
Reddit - - - -
Slack ✓*  ✓* 
Twitter ✓*  ✓* 
WeChat †  †  ✓* ✓*† 
WhatsApp

* If URI scheme, or a Social app landing page set up. Learn more

** Must have URI scheme.

User may be prompted to open the link in an external browser.

Can I use OneLink with ad networks (paid)?

Yes, but note that OneLink is mainly used with owned media, not with ad networks.

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.

 Important!

When you use OneLink with ad networks, you must use the OneLink long URL.

To setup OneLink for partner ad networks:

  1. Go to Integrated Partners on your Android app's dashboard and select the relevant ad network.
  2. Copy the app's attribution link from the setup window, and save it to an external document.
  3. Repeat steps 1 and 2 for your iOS app.
  4. Build the attribution link:
    1. Make sure OneLink is properly set up.
      In the Attribution section, use "test" as the media source name.
    2. Click Generate Link.
      The short and long URLs appear.
    3. Copy the long URL.
    4. In the long link, replace the "test" media source with the exact PID of the integrated partner to the link. For example: https://greatapp.onelink.me/U8ru?pid=network_int&c=MyCampaign
    5. Add ALL parameters from BOTH attribution links.
      If the attribution link of the iOS and Android apps are identical, simply copy the parameters from either one of the links. Otherwise, make sure you have all the parameters from both links.

Once all the parameters 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.

 Example

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

The network uses either the IDFA or GAID parameters according to the client's device platform and disregards the other parameter.

What methods are available for creating OneLink custom links?

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

Link creation method Uses Short/long URL Premium feature Visible in UI? Attribution TTL (Time to Live) max and default
AppsFlyer UI Create OneLink template and custom links Both -- No TTL
OneLink API Create thousands of OneLinks quickly Short -- 31 days
SDK User invite (referral) campaigns Short -- -- 180 days
OneLink Smart Script Mobile web-to-app campaigns Long -- -- No TTL
Spreadsheet Create thousands of OneLink custom links by applying your own formulas Long -- -- No TTL

How can I solve the iOS app-launching issue from social media apps?

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.

Can I use OneLink on Instagram?

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

Can I use OneLink for Android redirection on WeChat?

WeChat overrides Android 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.

WeChat_a.jpg

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

WeChat_b.jpg

Testing FAQ

How can I A/B test the Social app landing page?

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

How can I bypass the app selection dialog?

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.

Deep linking FAQ

What deep linking methods should be implemented?

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.

Can a URI scheme (af_dp parameter) be used for deep linking?

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.

iOS 14 FAQ

Does OneLink deep linking work for iOS 14?

There is no user experience impact to iOS 14 users who are deep linked from campaigns on ad networks and owned media.

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.

Does OneLink deferred deep linking work for iOS 14?

There is no user experience impact to iOS 14 users who are deferred deep linked from campaigns on ad networks and owned media.

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.

iOS 14 may affect deferred deep linking from ad network campaigns that rely on IDFA. 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 the overall impact, and benefit from faster response times.

Was this article helpful?