APP LINKS

Publishing App Links

Publishing App Link metadata is as simple as adding a few lines to the <head> tag in the HTML for your content. Apps that link to your content can then use this metadata to deep-link into your app, take users to an app store to download the app, or take them directly to the web to view the content. This allows developers to provide the best possible experience for their users when linking to their content.
App Links are specified using the tags defined in the registry below. Each target platform requires a different set of metadata in order to provide enough context for one app to deep-link into another.
A simple web page that provides App Link metadata might look like this:
File: documentation.html
<html>
<head>
    <meta property="al:ios:url" content="applinks://docs" />
    <meta property="al:ios:app_store_id" content="12345" />
    <meta property="al:ios:app_name" content="App Links" />
    <meta property="al:android:url" content="applinks://docs" />
    <meta property="al:android:app_name" content="App Links" />
    <meta property="al:android:package" content="org.applinks" />
    <meta property="al:web:url"
          content="http://applinks.org/documentation" />
</head>
<body>
Hello, world!
</body>
</html>

Platform Metadata Schema

The following tags can be used to define App Link metadata for your site. Each device type can be specified multiple times to accommodate multiple values, allowing you to provide a fallback list of apps to search for when navigating (e.g. if both a free and paid version of an app is available, or if multiple versions of the app exist that handle different deep-links).
Your app may also define a single fallback URL to be loaded in a web browser if your app is not installed. If your app has no equivalent web content, you may specify al:web:should_fallback as false to indicate that other apps should not attempt to fall back to displaying your content in a web browser.

Device Type: iOS

PropertyExample ContentDescriptionRequired (Y/N)
al:ios:urlapplinks://docsA custom scheme for the iOS appY
al:ios:app_store_id12345The app ID for the App StoreN
al:ios:app_nameApp LinksThe name of the app (suitable for display)N

Device Type: iPhone

PropertyExample ContentDescriptionRequired (Y/N)
al:iphone:urlapplinks://docsA custom scheme for the iPhone appY
al:iphone:app_store_id12345The app ID for the App StoreN
al:iphone:app_nameApp LinksThe name of the app (suitable for display)N

Device Type: iPad

PropertyExample ContentDescriptionRequired (Y/N)
al:ipad:urlapplinks://docsA custom scheme for the iPad appY
al:ipad:app_store_id12345The app ID for the App StoreN
al:ipad:app_nameApp LinksThe name of the app (suitable for display)N

Device Type: Android

PropertyExample ContentDescriptionRequired (Y/N)
al:android:urlapplinks://docsA custom scheme for the Android appN
al:android:packageorg.applinksA fully-qualified package name for intent generationY
al:android:classorg.applinks.DocsActivityA fully-qualified Activityclass name for intent generationN
al:android:app_nameApp LinksThe name of the app (suitable for display)N

Device Type: Windows Phone

PropertyExample ContentDescriptionRequired (Y/N)
al:windows_phone:urlapplinks://docsA custom scheme for the Windows Phone appY
al:windows_phone:app_ida14e93aa-27c7-df11-a844-00237de2db9fThe app ID (a GUID) for app storeN
al:windows_phone:app_nameApp LinksThe name of the app (suitable for display)N

Device Type: Windows

PropertyExample ContentDescriptionRequired (Y/N)
al:windows:urlapplinks://docsA custom scheme for the Windows appY
al:windows:app_ida14e93aa-27c7-df11-a844-00237de2db9fThe app ID (a GUID) for app storeN
al:windows:app_nameApp LinksThe name of the app (suitable for display)N

Device Type: Universal Windows

PropertyExample ContentDescriptionRequired (Y/N)
al:windows_universal:urlapplinks://docsA custom scheme for the Windows Universal appY
al:windows_universal:app_ida14e93aa-27c7-df11-a844-00237de2db9fThe app ID (a GUID) for app storeN
al:windows_universal:app_nameApp LinksThe name of the app (suitable for display)N

Web Fallback

PropertyExample ContentDescriptionRequired (Y/N)
al:web:urlhttp://applinks.org/documentationThe web URL; defaults to the URL for the content that contains this tagN
al:web:should_fallbackfalseIndicates if the web URL should be used as a fallback; defaults to trueN
When crawling URLs for App Link metadata, developers should send a request with al as one of the prefix values for the Prefer-Html-Meta-Tags header. Your server may choose to limit its response to only include HTML containing the tags above, and can use this as a signal to return these tags even when the response type for the given location would otherwise be something other than text/html.
Prefer-Html-Meta-Tags: al

App Link Metadata Examples

A few examples of common cases when specifying App Link metadata follows.
An app that is only available on iOS and on the web:
<html>
<head>
<meta property="al:ios:url" content="applinks://docs" />
<meta property="al:ios:app_store_id" content="12345" />
<meta property="al:ios:app_name" content="App Links" />
<!-- Other headers -->
</head>
<!-- Other HTML content -->
</html>
An app that has multiple versions on iOS, where apps following a link should attempt to use the latest version available on the device:
<html>
<head>
<meta property="al:ios" />
<meta property="al:ios:url" content="applinks_v2://docs" />
<meta property="al:ios:app_store_id" content="12345" />
<meta property="al:ios:app_name" content="App Links" />
<meta property="al:ios" />
<meta property="al:ios:url" content="applinks_v1://browse" />
<meta property="al:ios:app_name" content="App Links" />
<!-- Other headers -->
</head>
<!-- Other HTML content -->
</html>
An app with an iPad and iPhone version:
<html>
<head>
<meta property="al:iphone:url" content="applinks://docs" />
<meta property="al:iphone:app_store_id" content="12345" />
<meta property="al:iphone:app_name" content="App Links" />
<meta property="al:ipad:url" content="applinks://docs" />
<meta property="al:ipad:app_store_id" content="67890" />
<meta property="al:ipad:app_name" content="App Links" />
<!-- Other headers -->
</head>
<!-- Other HTML content -->
</html>
An app that has no web content, but has apps on iOS and Android:
<html>
<head>
<meta property="al:android:package" content="org.applinks" />
<meta property="al:android:url" content="applinks://docs" />
<meta property="al:android:app_name" content="App Links" />
<meta property="al:ios:url" content="applinks://docs" />
<meta property="al:ios:app_store_id" content="12345" />
<meta property="al:ios:app_name" content="App Links" />
<meta property="al:web:should_fallback" content="false" />
<!-- Other headers -->
</head>
<!-- Other HTML content -->
</html>
A shared link for an app whose web content may be found at another URL:
<html>
<head>
<meta property="al:android:package" content="org.applinks" />
<meta property="al:android:url" content="applinks://docs" />
<meta property="al:android:app_name" content="App Links" />
<meta property="al:ios:url" content="applinks://docs" />
<meta property="al:ios:app_store_id" content="12345" />
<meta property="al:ios:app_name" content="App Links" />
<meta property="al:web:url"
content="http://www.example.com/applinks_docs" />
<!-- Other headers -->
</head>
<!-- Other HTML content -->
</html>

App Link Navigation Protocol

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, Windows Phone, or the Web, or an intent on Android), described in detail in each platform-specific section below.
  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.
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_urlhttp://applinks.org/documentationA 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://example.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
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"
}

Navigating on iOS

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 openthe 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

Navigating on Android

Deep-linking on Android is Intent-based, wherein each app can register and define Activities and Intent filtersthat 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:
  1. Collect the App Link metadata for the target URL
  2. 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 anyResolveInfo is returned.
  3. 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.
  4. 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.
  5. 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>
An 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

Navigating on Windows Phone

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 withal_applink_data as defined above.
To navigate to a target URL on Windows Phone:
  1. Collect the App Link metadata for the target URL
  2. 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.
  3. 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), addingal_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

UX Guidelines/Recommendations

App Links enable you to provide your users an experienced optimized for their device when viewing content. You should optimize the display of links that have App Link metadata for your app. You may choose to take a user to the native app store when the app is not installed or display the name of the app based upon the App Link metadata for a given link.
As is common when navigating to links on the web, it’s useful to give users the ability to return to apps that they came from after navigating.  On some platforms, such as Android and Windows Phone, there is a built-in notion of a back button that fulfills this function.
Some platforms such as iOS, however, lack a back button.  As specified in the “Navigating on iOS” section, when one app navigates to another, it may provide a referer_app_link with enough information to allow the receiving app to provide a back button for its users. We recommend that the receiver of an App Link navigation display the standard “Touch to return” UI shown in the image below when an incoming navigation contains thereferer_app_link metadata.
Back Button UX
Bolts for iOS provides a reference implementation of this UI, which can be found in theBFAppLinkReturnToRefererController class. This implementation will handle showing and hiding the “Touch to return” UI at the appropriate times and will take care of performing the navigation back to the previous app to handle touches.

Implementations

Developers may choose to implement the App Links protocol for each platform themselves based upon the description above. Alternatively, developers may choose to use a library that helps them properly execute an App Link navigation, handle incoming navigations, and publish App Link metadata.
You may use the following implementations for navigating to and handling incoming App Link navigations:
  • Bolts for iOS - Open-source reference implementation for iOS apps
  • Bolts for Android - Open-source reference implementation for Android apps
  • Rivets for C# – Rivets is a Xamarin component that lets you handle incoming and outgoing App Link navigation.  It will work with the Xamarin runtime on iOS, Android or Windows Phone.
  • .NET SDK from the OuterCurve foundation – The .NET SDK has functionality to add App Links support to your Windows and Windows Phone apps.
The following tools may helpful for publishers of content with App Link metadata:
Some providers may also provide access to a high-performance index of App Link metadata that you may choose to use in your own apps rather than scraping and parsing HTML yourself:

Comments

Post a Comment

Popular Posts