URI scheme fallback for iOS

For:
Marketers Developers
Last update:

At a glance: Understand the flow when a user with an iOS device clicks on a OneLink custom link and Universal Links fails to open the app.

About URI fallback for iOS

  • The best-supported way to open apps on iOS devices is by using Universal Links. Since 2016, there are considerable built-in OS limitations to using URI schemes as a fallback method for when iOS Universal Links don't open the app. These limitations are not AppsFlyer-related, and would also impact any other links with URI schemes you might use to open the app.
  • By default, URI schemes (carried as the value of the af_dp param) are only used as a fallback method for opening the app on iOS on a few specific browsers/platforms.
  • For Safari, you can try to use URI schemes as a fallback to open apps on iOS by setting the following parameters on your OneLink URL: 
    • af_dp (that carries the URI scheme as the value).
    • af_force_deeplink=true (that forces the app to open using the af_dp URI scheme). Without this parameter, the app doesn't open using the URI scheme.
  • For other browsers, URI schemes are unpredictable and therefore, not supported by default. Users clicking the link are likely to be redirected to the App Store (or if set, to the URL set on the af_ios_url param).
  • See the scenarios flowchart and use cases that follow for additional details. 

Scenarios flowchart

Copy_of_Ios_fall_back_-_scenarios_flowchart__2_.png

Use cases

Browsers that can use URI schemes by default

Sometimes, Universal Links fail to open the app, either because the app does not exist, or the link does not have Universal Links configured. In those cases, the following browsers/platforms can use URI schemes as a fallback method to open the app by default:

  • Chrome
  • X (formerly Twitter)
    Note: If the app is not installed, users see an error message, and after dismissing the message, are redirected to the App Store (or as per the af_ios_url parameter).
  • Kakaotalk
  • Naver
  • Naver-Blog
  • Weibo

Flowchart

Copy_of_Ios_fall_back_-_browsers_that_can_use_URI_schemes_by_default__2_.png

Safari

The following describes the flow for users when Universal Links fail to open the app, and the link contains af_dp (that carries the URI scheme as the value).

If the app is not installed:

  1. Safari error message dialog displays.

  2. User clicks OK to dismiss the dialog, briefly sees a landing page load in the background, and then within 1 second, is automatically redirected to the App Store, or as per the af_ios_url param.

If the app is installed: 

  • If the link does not contain af_force_deeplink=true, user is redirected to the App Store, or as per the af_ios_url param.
  • If the link contains af_force_deeplink=true:
    1. Safari dialog displays.

    2. If the user clicks Open, the app opens.
    3. If the user clicks Cancel:
      • If the af_ios_url param is set, the user is redirected accordingly.
      • If the af_ios_url param is not set, the Safari error message dialog displays over a landing page in the background.

    4. User clicks OK and see a landing page with a call to action (CTA).
    5. User clicks the CTA and a dialog displays.

    6. If the user clicks Open, the app opens. 
    7. If the user clicks Cancel, a dialog displays.

    8. If the user clicks OK, they are redirected to the App Store. 
    9. If the user clicks Cancel, they remain on the landing page. 

Flowchart

Copy_of_Ios_fall_back_-_safari.png

Facebook post—unpaid

The following describes the flow for users when Universal Links fail to open the app, and the link contains af_dp (that carries the URI scheme as the value).

If the app is installed: 

  • The app opens.

If the app is not installed: 

  1. If there is no social media app configured, or after the user clicks the CTA on the SALP, a dialog displays over a landing page in the background.

  2. Click Open App. One of the following results can occur:
    • If the af_ios_url param is set, the user is redirected accordingly.
    • If the af_ios_url param is not set and if af_force_deeplink=true is not on the link the user is redirected accordingly.
    • If the af_ios_url param is not set, and If af_force_deeplink=true is on the link, the dialog displays again over the landing page in the background.

  3. If the user clicks Open, they are sent to the App Store.
  4. If the user clicks Close, the landing page in the background displays.

  5. User clicks the App Store badge and is redirected to the App Store.

Flowchart

diagram-X.png