App Links

Support Outbound App Links to Other Apps

Navigating to a target URL that contains App Link metadata follows a common protocol that has two key components:

  1. Platform-specific deep-linking (e.g. a URL on iOS, the Web and Windows Phone, or an intent on Android).
  2. An al_applink_data object that contains context for the navigation.

al_applink_data is meant to be a metadata container that can hold any kind of information that could be held in a JSON object. Top-level properties of al_applink_data are meant to contain routing information relevant to the act of navigating to a URL using this protocol.

iOS and Windows Phone

Deep-linking on iOS and Windows Phone is URL-based, wherein each app can register and define URL schemes (e.g. myapp:// or example:// – note that we strongly recommend that apps choose unique URL schemes to avoid collisions with other apps) that the operating system will route to that app. Performing an App Link navigation on iOS or Windows Phone involves constructing a URL that combines a prefix defined by the app with al_applink_data.

For iOS, the Bolts SDK for iOS available to help you with the discovery and construction of outbound links.

iOS and Windows Phone are covered later in this document.

Android

Deep-linking on Android is Intent-based, wherein each app can register and define Activities and Intent filters that the operating system will route to that app. Performing an App Link navigation on Android involves constructing an Intent that contains al_applink_data in its Intent extras.

The Bolts SDK for Android is available to help you with the discovery and construction of outbound links.

Android is covered later in this document.

al_applink_data Contents

The first step to supporting outbound links is to construct an al_applink_data object that will be used on each platform.

al_applink_data is meant to be a metadata container that can hold any kind of information that could be held in a JSON object. Top-level properties of al_applink_data are meant to contain routing information relevant to the act of navigating to a URL using this protocol.

The following table lists the properties of al_applink_data defined by this protocol, but additional properties may be defined by others to extend the protocol:

PropertyExample ContentDescriptionRequired (Y/N)
target_urlhttps://example.comA string containing the web URL being navigated to. This is an http or https URL representing some content.Y
referer_app_link{ “target_url”: “http://ex.com/docs”, “url”: “example://docs”, “app_name”: “Example App” }An object containing a target url as well as app link metadata (as defined in the metadata registry) that can be used to identify the Referer for this navigation. This enables the receiving app to provide a link back to the navigating app, which is especially important on platforms without a built-in back button.N
campaign_ids ABcDEfghI7GUC4gMdFoX1y An encrypted string and non-user metadata appended to the outbound URL (for example, ad_destination_url) or deep link (for App Aggregated Event Manager) when a user clicked on a link from Facebook.

Graph API definition: Parameter passed via the deep link for Mobile App Engagement campaigns		N
extras{“myapp_token”: “t0kEn”}An object containing information from the navigating app.N
version1.0A string containing the version of the protocol – currently “1.0″; defaults to “1.0″.N
user_agentBolts Android 1.0A string containing an identifier for the library that the navigating code is using to navigate.N

For example, al_applink_data for a navigation to http://example.com/docs might look like:

{
"target_url": "http://example.com/docs",
"extras": {
"myapp_token": "t0kEn"
},
"user_agent": "Bolts iOS 1.1",
"version": "1.0"
}

Deep-linking on iOS is URL-based, wherein each app can register and define URL schemes (e.g. myapp:// or example:// – note that we strongly recommend that apps choose unique URL schemes to avoid collisions with other apps) that the operating system will route to that app. Performing an App Link navigation on iOS involves constructing a URL that combines a prefix defined by the app with al_applink_data as defined above.

To navigate to a target URL on iOS:

  1. Collect the App Link metadata for the target URL
  2. Search for the first App Link target defined in the metadata for your device (i.e. `iphone` on an iPhone or iPod touch, or `ipad` on an iPad) that can open the url in the metadata.
  3. If no target was found, search for the first App Link target defined in the metadata for ios that can open the url in the metadata.
  4. If no target was found that can be opened on this device and al:web:should_fallback is false, the navigation fails. Otherwise, select the value of al:web:url (or the original target URL if none is specified) as your target.
  5. Construct al_applink_data for the navigation, encode it as a JSON string, and URL-encode that string. Add it to the url as a query parameter named al_applink_data.
  6. Open the URL you’ve constructed.

For example, if http://example.com/applinks contained the following markup:

<html>
<head>
<meta property="al:ios:url" content="example://applinks" />
<meta property="al:ios:app_store_id" content="12345" />
<meta property="al:ios:app_name" content="Example App" />
<!-- Other headers -->
</head>
<!-- Other HTML content -->
</html>

An navigating app might open the following URL if the app is installed:

example://applinks?al_applink_data=%7B%22user_agent%22%3A%22Bolts%20iOS%201.0.0%22%2C%22target_url%22%3A%22http%3A%5C%2F%5C%2Fexample.com%5C%2Fapplinks%22%2C%22extras%22%3A%7B%22myapp_token%22%3A%22t0kEn%22%7D%7D

Or to the following URL if the app is not installed:

http://example.com/applinks?al_applink_data=%7B%22user_agent%22%3A%22Bolts%20iOS%201.0.0%22%2C%22target_url%22%3A%22http%3A%5C%2F%5C%2Fexample.com%5C%2Fapplinks%22%2C%22extras%22%3A%7B%22myapp_token%22%3A%22t0kEn%22%7D%7D

Deep-linking on Android is Intent-based, wherein each app can register and define Activities and Intent filters that the operating system will route to that app. Performing an App Link navigation on Android involves constructing an Intent that contains al_applink_data in its Intent extras.

To navigate to a target URL on Android:

  • Collect the App Link metadata for the target URL
  • Search for the first App Link target defined in the metadata for Android that can be opened. To determine this, construct a VIEW Intent with the specified class and package. If a url is specified, set this as the data for the Intent. Otherwise, set the target URL as the data for the intent. Finally, check whether the Intent can be opened by calling PackageManager.resolveActivity() and checking whether any ResolveInfo is returned.
  • If no target was found that can be opened on this device and al:web:should_fallback is false, the navigation fails. Otherwise, use the value of al:web:url (or the original target URL if none is specified) to construct an Intent that will launch the default web browser on the device. To this URL, you should add a query parameter named al_applink_data whose value is al_applink_data encoded as a JSON string and then URL-encoded.
  • If a suitable target and corresponding Intent was found, construct al_applink_data for the navigation as a Bundle (using nested Bundles, Strings, arrays and numbers as values) and add it to the Intent as an extra named al_applink_data.
  • Start an activity for the Intent you've constructed.

For example, if http://example.com/applinks contained the following markup:

<html>
<head>
<meta property="al:android:url" content="example://applinks" />
<meta property="al:android:package" content="com.example" />
<meta property="al:android:app_name" content="Example App" />
<!-- Other headers -->
</head>
<!-- Other HTML content -->
</html>

A navigating app might start the following Intent if the app is installed:

action: android.intent.action.VIEW
data: example://applinks
package: com.example
extras:
al_applink_data:
target_url: "http://example.com/applinks"
user_agent: "Bolts Android 1.0"
version: "1.0"
extras:
myapp_token: "t0kEn"

Or it may start the following Intent if the app is not installed:

action: android.intent.action.VIEW
data: http://example.com/applinks?al_applink_data=%7B%22user_agent%22%3A%22Bolts%20Android%201.0.0%22%2C%22target_url%22%3A%22http%3A%5C%2F%5C%2Fexample.com%5C%2Fapplinks%22%2C%22extras%22%3A%7B%22myapp_token%22%3A%22t0kEn%22%7D%7D

Deep-linking on Windows Phone is URL-based, wherein each app can register and define URL schemes (e.g. myapp:// or example:// – note that we strongly recommend that apps choose unique URL schemes to avoid collisions with other apps) that the operating system will route to that app. Performing an App Link navigation on Windows Phone involves constructing a URL that combines a prefix defined by the app with al_applink_data as defined above.

To navigate to a target URL on Windows Phone:

  • Collect the App Link metadata for the target URL
  • Taking each App Link target defined in the metadata for windows_phone in order, construct a URL from the url and adding a query parameter named al_applink_data containing the al_applink_data for this navigation encoded as a JSON string and then URL-encoded. Until a launch succeeds, attempt to launch the URL.
  • If no launch attempt succeeded on this device and al:web:should_fallback is false, the navigation fails. Otherwise, use the value of al:web:url (or the original target URL if none is specified), adding al_applink_data as above, and attempt to launch this URL.

For example, if http://example.com/applinks contained the following markup:

<html>
<head>
<meta property="al:windows_phone:url" content="example://applinks" />
<meta property="al:windows_phone:app_name" content="Example App" />
<!-- Other headers -->
</head>
<!-- Other HTML content -->
</html>

An navigating app might open the following URL if the app is installed:

example://applinks?al_applink_data=%7B%22user_agent%22%3A%22Bolts%20Windows%20Phone%201.0.0%22%2C%22target_url%22%3A%22http%3A%5C%2F%5C%2Fexample.com%5C%2Fapplinks%22%2C%22extras%22%3A%7B%22myapp_token%22%3A%22t0kEn%22%7D%7D

Or to the following URL if the app is not installed:

http://example.com/applinks?al_applink_data=%7B%22user_agent%22%3A%22Bolts%20Windows%20Phone%201.0.0%22%2C%22target_url%22%3A%22http%3A%5C%2F%5C%2Fexample.com%5C%2Fapplinks%22%2C%22extras%22%3A%7B%22myapp_token%22%3A%22t0kEn%22%7D%7D