Menu

Deep Links

To setup deep links in your app, you'll need to do three things:

  1. Complete Android/iOS specific configuration
  2. Handle starting the application from a deep link
  3. Listen to the receivedDeepLink event and do something with the link

These are outlined in more detail below.

Configuration

iOS

iOS provides support for deep linking using two methods: universal links and custom url schemes. Universal links were introduced in iOS 9 and allow standard web links (http or https) to be treated as deep links into your app. This is now the preferred method over custom url schemes.

Universal Links

Enable universal links in your Xcode project with the following steps:

  1. Enable 'Associated Domains' in the Capabilities page of your Xcode project.
    • Add an entry for each domain that you want to support. Each entry should be formatted as: applinks:www.example.com.
  2. Navigate to https://developer.apple.com and enable Associated Domains in the app's provisioning profile (note that you cannot use a wildcard provisioning profile once you begin supporting universal links).

Server configuration

Universal Links also require server support. The server must host a file named apple-app-site-association (exactly that name, without any extension) over SSL at the root of the hostname (for example, if we want to provide deep links to matalan.co.uk there must be an app site association file at https://matalan.co.uk/apple-app-site-association). This request must not redirect and the server must negotiate the SSL connection providing a valid, trusted SSL certificate. See the link at the beginning of this section for more details.

The format of the apple-app-site-association file is as follows:

{
    "applinks": {
        "apps": [],
        "details": [
            {
                "appID": "KS9S3B73SG.com.mobify.builds.matalan",
                "paths": [
                    "/",
                    "*"
                ]
            }
        ]
    }
}

Note that the details array can contain any number of apps, which is useful if there are multiple versions of the app being distributed for different teams for testing (eg. Mobify devices and Matalan devices).

The appID is the full application identifier of the app (eg. KS9S3B73SG.com.mobify.builds.matalan). The paths array can contain any number of entries that match paths that should trigger universal linking to the app (paths that do not match will result in Safari being opened instead of the app).

Note: If you want a "pathless" url to open the app you must include an entry like this: "/" in addition to other paths.

Custom URL scheme

To setup deep links in iOS using Astro, you'll need to make a couple changes to your app info in Xcode:

  1. Open the settings panel for your app (where you define the bundle, version, icon, etc.).
  2. Click the "Info" tab.
  3. Scroll down to the "URL Types" section and enter the following:
    • Identifier: The bundle identifier for your app (ex. com.mobify.astro.)
    • URL Schemes: pick a unique url scheme for your app. For example if you enter "testurlscheme" in this box, your user will be given the option to launch your app for URLs starting with "testurlscheme://".

Testing

The easiest way to test deep links on iOS is to add them to a Contact in the iOS Contacts app. Once added you can tap on them in the contact and your app should open.

Android

In android, you need to use intent filters to handle external intents. Intent filters are added to your android manifest file inside of an activity that you wish to launch.

<activity
    android:name="MyActivity"

    <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="http"
              android:host="www.mobify.com" />
        <data android:scheme="https"
              android:host="www.mobify.com" />
    </intent-filter>
</activity>

After adding this intent filter, when a user clicks on a link to www.mobify.com (http or https), they will be prompted by an application chooser and have the option to open the link in your app.

Testing

You can test Android deep links by issuing the following command in Terminal:

adb shell am start \
    -W -a android.intent.action.VIEW \
    -d URL Package

Starting app from deep link

When a user chooses to open a deep link in your app, the Application will store the deep link uri on for later access. In app.js you can get the start uri using the getStartUri method:

Application.getStartUri(err, uri) {
    webView.navigate(uri || "http://www.default-url.com");
}

receivedDeepLink event

A user of your app may also activate a deep link while your app is already running. This case is differs because the ApplicationPlugin will not store the deep link uri on itself. Instead it will notify your app that it received a deep link by triggering the receivedDeepLink event. The uri will be attached to the params object:

Application.on('receivedDeepLink', function(err, params) {
   webView.navigate(params.uri);
});