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, read our help article on iOS Universal Links with TUNE instead.

For additional information about implementing Universal Links, you can visit Support Universal Links on 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. Find your subdomain in your Attribution Analytics account:
      1. In the left hand navigation menu, in the Applications section, click on Mobile Apps.
      2. Find and click on the name of the appropriate mobile app.
      3. In the Details box, click Edit.
      4. On the Edit App page, in the Routing section, under the Universal Links section, copy and paste your Domain.
    2. 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>.
      Entitlements
    3. 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:(nullable NSString *)deeplink {
NSLog(@"TUNE.deeplink: %@", deeplink);
// Handle deep link redirect here...
}

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

Then register itself as a listener:

[Tune registerDeeplinkListener:self];

Once your iOS app is set up to handle universal links, you'll need to enable the Universal Link setting in Attribution Analytics. Then follow the standard process for creating a TUNE link in Attribution Analytics.

TUNE links support iOS Universal Link functionality as long as the above setting is enabled and routing is set up properly in your app. When your TUNE link (with Universal Link functionality enabled) is successfully implemented, users who click it are directed to the appropriate destination at the OS level instead of at the app level. No browser app is launched to perform app detection and routing logic, as routing is handled by iOS itself.

Example

For a tangible example of Universal Linking, 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 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.

No Comments

Leave a reply