Deep Links

By the end of this section, you’ll be able to:

And you'll be able to:

Deep links allow links to be opened in your app instead of being opened in your browser. This ensures users are always being taken to a place where they are more likely to be logged in and to be provided with a better experience (since the app might include more features such as a barcode scanner, in-store features or push message support).

Deep Link

An example of tapping on a Google search navigating to the app.

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.

Deep Links in 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

An image of a unversal link formed long ago

The first universal link formed many years ago 😜

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

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 there must be an app site association file at This request must not redirect and the server must negotiate the SSL connection providing a valid, trusted SSL certificate.

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

    "applinks": {
        "apps": [],
        "details": [
                "appID": "",
                "paths": [

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. Basically, it is your Team ID joined with your bundle identifier (eg. The path’s 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).

Apple Developer Portal

Team ID in the Apple Developer portal.

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:
    1. Identifier: The bundle identifier for your app (ex. com.mobify.astro.)
    2. 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://.


The easiest way to test deep links on iOS is to add the URLs to the Notes app. Once added you can tap on the links and your app should open.

Deep Links in 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.

        <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="" />
        <data android:scheme="https"
              android:host="" />

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


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 Your App from a 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:

const startUri = await Application.getStartUri()
webView.navigate(startUri || '')

Receiving a Deep Link Event in Your App

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', (err, params) => {


One of the things that makes the Internet so successful is the ability to link between documents. This was one of the biggest hurdles in making apps gain traction. Deep linking is the answer to linking between websites and apps. Because Apple and Google are baking deep linking into their respective operating systems, it’s very important you incorporate deep links into your app from the very beginning.

Another benefit of introducing URLs to your app is that URLs can be used to launch your app with a unique state (such as in a debugging mode, or with a promotional message). This makes deep linking very powerful and useful for many people such as users, developers and marketers.

In order for deep linking to work securely, you need to register your app in the Apple App Store and/or the Google Play Store. You’re given a configure/manifest file that you need to include in your app. Apple also requires you to register your URL by uploading a file to your website (to make sure you own the website).

At this point you should have a functioning deep linking system in your app for both iOS and Android. There are quite a few steps but if you've followed this guide everything should be working. If you run into issues, reach out to Mobify Support and we'll help you get unstuck.


For more details on deep linking, please see: