Implementing iOS Universal Links

This page provides instructions for configuring your app and web server to support Universal Links. For conceptual information about Universal Links, please visit iOS Universal Links with TUNE.

For additional information about implementing Universal Links, please visit Support Universal Links at the Apple Developer web site.

On the Apple Developer Tools Site

Visit https://developer.apple.com and register your app to establish an App ID. Then enable Associated Domains so that your Xcode project can support Universal Links.

  1. Register your app to establish an App ID:
    1. On the Apple Developer Member Center home page, click Certificates, Identifiers & Profiles.
    2. On the Certificates, Identifiers & Profiles page, under the iOS Apps column, click Identifiers.
    3. On the iOS App IDs page, click Register your App ID.
    4. On the Registering an App ID page, enter an App ID Description/Name, enter your app’s Bundle ID, and then click Continue.
    5. On the Confirm your App ID page, click Submit.
    6. On the Registration complete page, click Done.
  2. Enable Associated Domains for your App ID:
    1. On the iOS App IDs page, select your App ID, and then click Edit.
    2. On the iOS App ID Settings page, check the box for Associated Domains.
    3. In the confirmation dialog box, click OK.
    4. On the iOS App ID Settings page, click Done.

The result of completing these steps is that your app/Xcode project now supports Universal Links. In the next section, you’ll associate your Xcode project with a TUNE web domain.

In Your Xcode Project

Add a “com.apple.developer.associated-domains” entitlement to register your app with Apple as being capable of handling Universal Links; the entitlement lists all the domains that your app can handle as Universal Links.

  1. Enable Associated Domains:
    1. Load your app project in Xcode.
    2. In the left pane treeview, click the project.
    3. In the right pane, click the Capabilities tab.
    4. On the Capabilities tab, enable Associated Domains by clicking the toggle to On (blue color).
  2. Add a Domain Entitlement:
    1. In the Domains box, add all the domains that your app wants to handle as Universal Links. Prefix each domain with "applinks:<your tlnk.io here>. In order to find your subdomain, create a measurement link by selecting your app and partner, and note the generated measurement url's domain (e.g. "applinks: <subdomain>.tlnk.io/").Entitlements
    2. Include the entitlement file in your build: in the project browser, select the entitlement file for membership to the appropriate targets.

The result of completing these steps is that your domain now supports Universal Links. In the next section, you’ll configure your web server to support Universal Links.

In Your AppDelegate

Include logic for handling Universal Links: this code only runs if users have your app installed (else they get the mobile web version). So provide a mapping that correlates Universal Links with specific app screens.

For example, the sample code below handles receiving a Universal Link:

// Capturing Universal Links
- (BOOL)application:(UIApplication *)application continueUserActivity:(nonnull NSUserActivity *)userActivity restorationHandler:(nonnull void (^)(NSArray * _Nullable))restorationHandler {
    // Check if Tune will handle the Universal Link. If so, the deeplink will be handled in your tuneDidReceiveDeeplink: or tuneDidFailDeeplinkWithError: callback
    BOOL handledByTune = [Tune handleContinueUserActivity:userActivity restorationHandler:restorationHandler];
    
    // If handledByTune is false, handle the routing yourself
    if (!handledByTune) {
        ...
    }
    return YES;
}

After setting up the Universal Link call, implement registerDeeplinkListener: with a TuneDelegate implementation after your TUNE SDK init call. The implementation must implement the methods tuneDidReceiveDeeplink: and tuneDidFailDeeplinkWithError:

For example, you can have your app delegate implement the following TuneDelegate callbacks:

- (void)tuneDidReceiveDeeplink:(NSString *)deeplink {
NSLog(@"TUNE.deeplink: %@", deeplink);
// Handle deep link redirect here...
}

- (void)tuneDidFailDeeplinkWithError:(NSError *)error {
NSLog(@"TUNE.deeplink failed: %@", [error localizedDescription]);
}

Then register itself as a listener:

[Tune registerDeeplinkListener:self];

In Your Attribution Analytics Account

Once your iOS app is setup to handle universal links, you'll need to enable the Universal Link setting in your Attribution Analytics account.

Appending Campaign Parameters

Embed your ad with a Universal Link instead of a standard measurement URL or app-specific deep link. Then append your campaign parameters to the Universal Link (in the same way you append parameters to a standard measurement URL).

For example, here’s an Attribution Analytics measurement URL with campaign parameters appended (including an “invoke_id”/deep link destination).

https://112233.tlnk.io/serve?action=click&publisher_id=12345&invoke_id=1234&sub_campaign=Atomic%20Dodge%20Ball%20Lite%201&sub_adgroup=US%2018%2B&sub_ad=Challenge%20Friends%20Blue&sub_placement=Mobile%20News%20Feed

The issue with measurement URLs is that they typically require an extra browser-redirection step to detect if the app is installed (then either open the app or open the App Store). It is this extra redirection that causes many users to abandon the process, leading to poor conversion rates.

Now here’s an app-specific deep link (for the Atomic Dodge Ball Lite app) with campaign parameters appended.

adblite://up?publisher_id=12345&sub_campaign=Atomic%20Dodge%20Ball%20Lite%201&sub_adgroup=US%2018%2B&sub_ad=Challenge%20Friends%20Blue&sub_placement=Mobile%20News%20Feed

While deep links can minimize user drop-off by opening the app directly (without any redirection), the issue with app-specific deep links is that they simply don’t work when the app is not installed, leading to a poor user experience.

So the ideal implementation involves appending parameters to a Universal Link so that users are directed to the appropriate destination (by the OS level instead of at the app level): there is no launching a browser app to perform the app detection and routing logic, it is handled by iOS itself.

https://alpha.tlnk.io/atomic/upgrade.php?publisher_id=12345&sub_campaign=Atomic%20Dodge%20Ball%20Lite%201&sub_adgroup=US%2018%2B&sub_ad=Challenge%20Friends%20Blue&sub_placement=Mobile%20News%20Feed

Note: The deep link parameter in the callbacks deliver the deep link defined in the measurement URL, or the invoke_url parameter on the measurement URL.

Example

For a tangible example of Universal Linking, please visit our sample site at http://alpha.tlnk.io/atomic. This site is a mobile version of the Atomic Dodge Ball Lite app, and the site is configured to handle Universal Links.

To test Universal Links with our sample site:

  1. Use an iOS device that is running iOS 9+ and do NOT install the Atomic Dodge Ball Lite app yet (if installed, please remove it for this test and then re-install it afterwards).
  2. Email yourself the following deep links:
  3. Open the email on your iOS device and click the deep links:
    • If you installed the app, then the deep links open the app directly to the relevant screen.
    • Without the app installed, the deep links fail.
  4. Now email yourself the following Universal Links:
  5. Open the email on your iOS device and click the Universal Links:
    • If you installed the app, then the Universal Links open the app directly to the relevant screen.
    • Without the app installed, iOS directs you to the relevant page of the mobile web version.

Implications of the test:

  • Without Universal Links, new users get a poor experience when deep links fail to do anything.
  • With Universal Links, new users can fail gracefully to a mobile web version.
  • Embed your ads with Universal Links and append your campaign parameters.
  • On ad click, iOS detects if the app is installed:
    • If not, then handle the Universal Link as a standard hyperlink (open the web page).
    • If so, then open the corresponding deep link specified in AppDelegate.
Have a Question? Please contact support@tune.com for technical support.