Handling Deep Links on iOS

In this article, we’ll go over how to set up the Yozio SDK in your app to handle users who already have your app, and who click a Yozio SuperLink.

Overview

The Deep Link of Yozio SuperLinks covers users who already have your app and click on a Yozio SuperLink. There are a number of ways you can handle the users who already have your app, and the deep link case can be divided into three core pieces of functionality to help you achieve your use case:

  • Opening your app
  • Data passing
  • Tracking

Opening your app on iOS

If you’d like to implement more complex user flows for those users who deep link into your app, you must first implement a seamless experience for your users to open your app through a Yozio SuperLink. In order for your app to open when a user clicks on a Yozio SuperLink, your app must first be configured to recognize the SuperLink.

For your users on iOS 9+, we have two options to deep link your users, via custom scheme and via Universal Links. For iOS 9+ users Apple’s Universal Links will provide the superior user experience, but there are various edge cases that make Apple’s Universal Links difficult to implement. We’ve provided a complete solution in our support for Universal Links that will allow you to handle this edge cases and control the user experience.

Custom Scheme

Setup

First, implement a custom scheme for your app. Check out Apple’s documentation for more information on how to implement Custom Scheme.

Then, for individual SuperLinks, go to Yozio Console > SuperLinks > Organic Links > Edit (the SuperLink you’d like to modify) > Redirect Settings > iOS > Do you want to override default settings? > Yes > Deep Link User? > Yes* > then enter your custom scheme.

For all SuperLinks, go to Yozio Console > Settings > Default Redirect Settings > iOS > Deep Link User? > Yes* > then enter your custom scheme

*Make sure to enter your custom scheme in the iOS Custom Scheme field.

You can also add a path to your custom scheme. For example, you can enter

1
rivendell://home

and the SuperLink will redirect to that path in your app.

Notes

If you choose to implement deep linking using custom scheme, there are a few important user experience pieces to be aware about:

Yozio uses a fallback solution to deep link users into the app; this is due to the lack of any way to detect whether or not a user has the app without Universal Link (a design choice that Apple has explicitly made and that Yozio cannot influence). Yozio will first attempt to open the app using the custom scheme you provide. If the user does not have the app, an attempt to open a custom scheme that is not recognized by any app on the phone causes a “cannot open in safari” popup to appear. After this popup, we will redirect the user to the app store. Additionally, users on iOS 9 will see a “open in YOURAPPNAME” popup appear when the user opens your app through a custom scheme.

We recommend implementing Yozio’s support for Universal Links to ensure your iOS 9+ users have the best experience.

Check out this article for information on how to integrate Yozio’s support for Universal Links.

Once inside the app, you’ll want your app to parse the data from the corresponding click event. Since the click event results in the app opening directly, all data appended to the SuperLink URL is preserved and passed into the app; all that is required is that the metadata is parsed into something that the app can easily access. Additionally, this is where the app opening is confirmed to have come from a click on a Yozio SuperLink; clicks on Yozio SuperLinks carry a piece of metadata indicating that the app was opened through a SuperLink, and not through other means. iOS If you are using Yozio’s Universal Link solution, check out this article for information on how to implement Data Passing through Universal Link.

Retrieving metadata from the custom scheme URL

If you are using Custom Scheme, simply call the SDK function [Yozio handleOpenURL] function in the AppDelegate method openURL. [Yozio handleOpenURL] is a convenient “all-in-one” function that will parse the metadata from the query string of the deep link URL, make it available for use later in your app and track that a deep link event on the Yozio Dashboard. Here is some sample code demonstrating how you’d place the handleOpenURL function call:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
- (BOOL)application:(UIApplication *)application
            openURL:(NSURL *)url
  sourceApplication:(NSString *)sourceApplication
         annotation:(id)annotation
{
    if ([Yozio handleOpenURL:url] == YOZIO_OPEN_URL_TYPE_YOZIO_NEW_INSTALL) {
        return YES;
    }

    NSDictionary *metaData = [Yozio getMetaDataFromDeeplink:url];

    NSLog(@"Got meta data from deep link: %@", metaData);

    // Launch main target view controller with meta data
    [Utils launchMainViewControllerWithMetaData:metaData];
    return YES;
}

You’ll notice a function in the previous call [Yozio getMetaDataFromDeeplink:url]; this is a convenient helper function that will parse the metadata from the URL that resulted in the app opening via custom scheme. You can give it any URL, and it will parse the metadata out of the query string into a easy to use dictionary.

You can also access the metadata globally in your app; the function [Yozio handleOpenURL:url] will persist the metadata from the last deep link locally on the device. Access them with the following functions

1
2
[Yozio getLastDeeplinkMetaDataAsHash];
[Yozio getLastDeeplinkMetaDataAsUrlParameterString];

Yozio can also pass additional metadata through custom URL schemes. Say the following iOS deep link URL scheme is configured:

1
rivendell://invite

And the associated metadata (attached via static, dynamic, or Sublink API method(s)) is:

Yozio will then deep link and pass the associated metadata as follows:

1
rivendell://invite?a=1&b=2

You may then parse rivendell://invite?a=1&b=2 as you see fit.

Persevering existing custom scheme format

If you have already implemented your own deep linking URL format, you may want to preserve that format. For example, you may have the following deep linking URL rivendell://item/12345 and already have the code to parse such a URL.

To preserve your own deep linking URL format, you can pass the URL to Yozio using the pre-defined deep link URL override metadata key.

Deep link URL override keys:

1
2
yozio_iphone_deeplink_url
yozio_ipad_deeplink_url

For example, attached dynamically:

1
https://r.rivendell.com/a.b.c?yozio_ipad_deeplink_url=rivendell://item/12345

Note that this will override the deep link URL entirely. Any metadata you attach will not be automatically attached to the deep link URL. If you'd like to do this, add the metadata pieces directly onto the URL you've set as the value of the deep link URL override parameter. For example:

1
https://r.rivendell.com/a.b.c?yozio_ipad_deeplink_url=rivendell://item/12345?hello=world

Once the app has been opened through a Yozio SuperLink, a call to our servers must be made to track the deep link event. In order for a deep link event to be valid, it needs a short URL of the SuperLink that was clicked, and the app key associated with the app. For more segmentation, additional parameters, such as operating system or device type can be added.

Setup

As we mentioned in the Data Passing section, the [Yozio handleOpenURL] function is a convenient “all-in-one” function that will parse the metadata from the query string of the deep link URL, make it available for use later in your app and track a deep link event on the Yozio Dashboard. Simply call the [Yozio handleOpenURL] function in the AppDelegate method openURL.