Handling Deep Links on Android

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 Android

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.

Opening your app via App Chooser

Android uses an operating system level feature called the app chooser to send the user to another app based on an “action” it would like to perform (source). When a user clicks on a Yozio SuperLink, we will redirect the user to a domain completely unique to your app; your app will need to recognize this domain as an intent to open your app. You will do this by adding an intent filter to your manifest file. Here is the intent filter you need to add:

1
2
3
4
5
6
<intent-filter>
     <action android:name="android.intent.action.VIEW" />
     <category android:name="android.intent.category.DEFAULT" />
     <category android:name="android.intent.category.BROWSABLE" />
     <data android:scheme="https" android:host="deeplink.yozio.com" android:pathPrefix="/your-app-key" />
</intent-filter>

Notice that the scheme is https; this scheme is shared by all browsers. The Yozio SuperLink will redirect to https://deeplink.yozio.com/your_app_key and since this scheme is shared by browsers, the app chooser will present the user with options to open with your app as well as with their browser apps. The app chooser enables us to detect with certainty whether a user has the app.

A caveat of this method of app detection is that the user will have the option to use their browser to open the link, instead of your app. To address this, add a second intent filter that will open your custom scheme. For information on implementing a custom scheme for your app, click here . Here is the intent filter you need to add to your app:

1
2
3
4
5
6
<intent-filter>
     <action android:name="android.intent.action.VIEW" />
     <category android:name="android.intent.category.DEFAULT" />
     <category android:name="android.intent.category.BROWSABLE" />
     <data android:scheme="your-app-scheme" android:host="yozio" android:path="/" />
</intent-filter>

The host must be “yozio”; this will allow us to open your app when the user chooses to open the Yozio SuperLink with a browser when presented with the app chooser.

There is another caveat affecting users who choose Chrome when presented with the app chooser. Chrome will not automatically open the custom scheme, and instead redirect to the webpage on https://deeplink.yozio.com/your_app_key. On this webpage, we’ve provided a customizable landing page where your users can press a button to open your app.

Once you’ve added your two intent filters, simply go to the redirect settings of your SuperLinks and enable “Deep Link” for Android. Once there, enter your custom scheme. For individual SuperLinks, go to Yozio Console > SuperLinks > Organic Links > Edit (the SuperLink you’d like to modify) > Redirect Settings > Android > 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 > Android > Deep Link User? > Yes* > then enter your custom scheme.

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

We recommend implementing Yozio’s support for Android App Links to ensure your Android 6+ users have the best experience.

With Android 6, Google has released App Links, which allow a more seamless transition between apps that bypasses the app chooser, but still guarantees that the correct app is opened.

Check out this article for information on how to integrate Yozio’s support for App Links for your users on Android 6 and above.

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.

Setup

To implement Deep Link on Android, you must first call Yozio.initialize(Context context) in the main/launcher activity of your application (note that if you have implemented Handling New Installs on Android, this will be an unfamiliar function). Yozio.initialize(Context context) will parse the metadata from the intent (on Android, when another app opens yours, the deep link URL is passed via intent.getData()). Yozio.initialize(Context context) 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 Yozio.initialize(Context context); function call:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    // Basic Yozio initialization
    Yozio.initialize(this);

    // Standard way of getting meta data in the activity whether it's a new install or existing install
    Intent intent = this.getIntent();
    HashMap<String, Object> metaData = Yozio.getMetaData(intent);
}

Note: Yozio.initialize(Context context) will take an Activity context; it will fail when given an Application context.

You’ll notice a function in the previous call Yozio.getMetaData(intent); 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.initialize(Context context) will persist the metadata from the last deep link locally on the device. Access them with the following functions

1
2
Yozio.getLastDeeplinkMetaDataAsHash(Context context);
Yozio.getLastDeeplinkMetaDataAsUrlParameterString(Context context);

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

1
rivendell://

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://?a=1&b=2

You may then parse rivendell://?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
yozio_android_deeplink_url

For example, attached dynamically:

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

The deep link URL you set here will NOT change. We will not append any metadata to this URL; if you have logic that retrieves metadata out of this deep link URL, you must include it in the deep link URL you set here. Any metadata attached to the SuperLink, whether attached statically or dynamically, will not be added to the deep link URL defined by yozio_android_deeplink_url.

In Android, the deep link URL you provide will not actually override the deep link URL sent to the app; this is different from the behavior in iOS, where setting this parameter will cause the deep link URL sent to the app to be replaced with the one provided by this parameter. To access this parameter in Android, simply use the metadata key yozio_android_deeplink_url and retrieve it like any other piece of metadata.

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.initialize 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 this function in the Main/Launcher Activity’s method onCreate.