@spoonconsulting/ionic-plugin-deeplinks

Community Maintained

This plugin is being maintained by the Ionic community. Interested in helping? Message max on ionic worldwide slack.

Another great solution for deep links for Ionic is the Branch Metrics plugin: https://github.com/BranchMetrics/cordova-ionic-phonegap-branch-deep-linking

If you used to handle URI schemes with the help of this plugin and have migrated to Branch Metrics, you can make use of a plugin such as https://github.com/EddyVerbruggen/Custom-URL-scheme to facilitate custom URL schemes.

Ionic Deeplinks Plugin

This plugin makes it easy to respond to deeplinks through custom URL schemes and Universal/App Links on iOS and Android.

For example, you can have your app open through a link to https://yoursite.com/product/cool-beans and then navigate to display the Cool Beans in your app (cool beans!).

Additionally, on Android iOS, your app can be opened through a custom URL scheme, like coolbeans://product/cool-beans.

Since Custom URL scheme behavior has changed quite a bit in iOS 9.2 for the case where the app isn't installed, you'll want to start using Universal Links as it's clear custom URL schemes are on the way out.

Note: this plugin may clash with existing Custom URL Scheme and Universal Links Plugins. Please let us know if you encounter compatibility issues. Also, try removing them and using this one on its own.

Thank you to the Cordova Universal Links Plugin and the Custom URL Scheme plugin that this plugin is inspired and borrows from.

Installation

cordova plugin add ionic-plugin-deeplinks
--variable URL_SCHEME=myapp --variable DEEPLINK_SCHEME=https --variable DEEPLINK_HOST=example.com
--variable ANDROID_PATH_PREFIX=/

Fill in the appropriate values as shown below:

• URL_SCHEME - the custom URL scheme you'd like to use for your app. This lets your app respond to links like myapp://blah
• DEEPLINK_SCHEME - the scheme to use for universal/app links. Defaults to 'https' in 1.0.13. 99% of the time you'll use https here as iOS and Android require SSL for app links domains.
• DEEPLINK_HOST - the host that will respond to deeplinks. For example, if we want example.com/product/cool-beans to open in our app, we'd use example.com here.
• ANDROID_PATH_PREFIX - (optional): specify which path prefix our Android app should open from more info

(New in 1.0.13): If you'd like to support multiple hosts for Android, you can also set the variables DEEPLINK_2_SCHEME, DEEPLINK_2_HOST, ANDROID_2_PATH_PREFIX and optionally substitue 2 with 3, 4, and 5 to set more.

Handling Deeplinks in JavaScript

Ionic/Angular 2

note: make sure to call IonicDeeplink from a platform.ready or deviceready event

Using Ionic Native (available in 1.2.4 or greater):

import { Platform, NavController } from 'ionic-angular';
import { Deeplinks } from '@ionic-native/deeplinks/ngx';

export class MyApp {
  constructor(
    protected platform: Platform
    , protected navController: NavController
    , protected deeplinks: Deeplinks
    ) {
    this.platform.ready().then(() => {
      this.deeplinks.route({
        '/about-us': HomePage,
        '/products/:productId': HelpPage
      }).subscribe((match) => {
        // match.$route - the route we matched, which is the matched entry from the arguments to route()
        // match.$args - the args passed in the link
        // match.$link - the full link data
        console.log('Successfully matched route', match);
      },
      (nomatch) => {
        // nomatch.$link - the full link data
        console.error('Got a deeplink that didn\'t match', nomatch);
      });
    });
  }
}

// Note: routeWithNavController returns an observable from Ionic Native so it *must* be subscribed to first in order to trigger.

If you're using Ionic 2, there is a convenience method to route automatically (see the simple Ionic 2 Deeplinks demo for an example):

import { Platform, NavController } from 'ionic-angular';
import { Deeplinks } from '@ionic-native/deeplinks/ngx';

export class MyApp {
  constructor(
    protected platform: Platform
    , protected navController: NavController
    , protected deeplinks: Deeplinks
    ) {
    this.platform.ready().then(() => {
      this.deeplinks.routeWithNavController(this.navController, {
        '/about-us': HomePage,
        '/products/:productId': HelpPage
      }).subscribe((match) => {
        // match.$route - the route we matched, which is the matched entry from the arguments to route()
        // match.$args - the args passed in the link
        // match.$link - the full link data
        console.log('Successfully matched route', match);
      },
      (nomatch) => {
        // nomatch.$link - the full link data
        console.error('Got a deeplink that didn\'t match', nomatch);
      });
    });
  }
}

// Note: routeWithNavController returns an observable from Ionic Native so it *must* be subscribed to first in order to trigger.

Ionic/Angular 1

For Ionic 1 and Angular 1 apps using Ionic Native, there are many ways we can handle deeplinks. However, we need to make sure we set up a history stack for the user, we can't navigate directly to our page because Ionic 1's navigation system won't properly build the navigation stack (to show a back button, for example).

This is all fine because deeplinks should provide the user with a designed experience for what the back button should do, as we are putting them deep into the app and need to provide a natural way back to the main flow:

(See a simple demo of v1 deeplinking).

angular.module('myApp', ['ionic', 'ionic.native'])

.run(['$ionicPlatform', '$cordovaDeeplinks', '$state', '$timeout', function($ionicPlatform, $cordovaDeeplinks, $state, $timeout) {
  $ionicPlatform.ready(function() {
    // Note: route's first argument can take any kind of object as its data,
    // and will send along the matching object if the route matches the deeplink
    $cordovaDeeplinks.route({
      '/product/:productId': {
        target: 'product',
        parent: 'products'
      }
    }).subscribe(function(match) {
      // One of our routes matched, we will quickly navigate to our parent
      // view to give the user a natural back button flow
      $timeout(function() {
        $state.go(match.$route.parent, match.$args);

        // Finally, we will navigate to the deeplink page. Now the user has
        // the 'product' view visibile, and the back button goes back to the
        // 'products' view.
        $timeout(function() {
          $state.go(match.$route.target, match.$args);
        }, 800);
      }, 100); // Timeouts can be tweaked to customize the feel of the deeplink
    }, function(nomatch) {
      console.warn('No match', nomatch);
    });
  });
}])

Non-Ionic/angular

Ionic Native works with non-Ionic/Angular projects and can be accessed at window.IonicNative if imported.

If you don't want to use Ionic Native, the plugin is available on window.IonicDeeplink with a similar API minus the observable callback:

window.addEventListener('deviceready', function() {
  IonicDeeplink.route({
    '/product/:productId': {
      target: 'product',
      parent: 'products'
    }
  }, function(match) {
  }, function(nomatch) {
  });
})

iOS Configuration

As of iOS 9.2, Universal Links must be enabled in order to deep link to your app. Custom URL schemes are no longer supported.

Follow the official Universal Links guide on the Apple Developer docs to set up your domain to allow Universal Links.

How to set up top-level domains (TLD's)

Set up Associated Domains

First you must enable the Associated Domains capability in your provisioning profile. After that you must enable it in the Xcode project, too. For automated builds you can do it easily by adding this to your config.xml.

<config-file target="*-Debug.plist" parent="com.apple.developer.associated-domains">
    <array>
        <string>applinks:example.org</string>
    </array>
</config-file>

<config-file target="*-Release.plist" parent="com.apple.developer.associated-domains">
    <array>
        <string>applinks:example.org</string>
    </array>
</config-file>

Instead of applinks only you could use <string>webcredentials:example.org</string> or <string>activitycontinuation:example.org</string>, too.

Set up Apple App Site Association (AASA)

Your website (i.e. example.org) must provide this both files.

• /apple-app-site-association
• /.well-known/apple-app-site-association

The content should contain your app.

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "1A234BCD56.org.example",
        "paths": [
          "NOT \/api\/*",
          "NOT \/",
          "*"
        ]
      }
    ]
  }
}

This means that all your requests - except /api and / - will be redirected to your app. Please replace 1A234BCD56 with your TEAM ID and org.example with your Bundle-ID. (the id="" of your <widget />)

Android Configuration

Android supports Custom URL Scheme links, and as of Android 6.0 supports a similar feature to iOS' Universal Links called App Links.

Follow the App Links documentation on Declaring Website Associations to enable your domain to deeplink to your Android app.

To prevent Android from creating multiple app instances when opening deeplinks, you can add the following preference in Cordova config.xml file:

 <preference name="AndroidLaunchMode" value="singleTask" />

How to set up top-level domains (TLD's)

Set up Android App Links

Your website (i.e. example.org) must provide this file.

• /.well-known/assetlinks.json

The content should contain your app.

[
  {
    "relation": [
      "delegate_permission\/common.handle_all_urls"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "org.example",
      "sha256_cert_fingerprints": [
        "12:A3:BC:D4:56:E7:89:F0:12:34:5A:B6:78:90:C1:23:45:DE:67:FA:89:01:2B:C3:45:67:8D:9E:0F:1A:2B:C3"
      ]
    }
  }
]

Replace org.example with your app package. (the id="" of your <widget />) The fingerprints you can get via $ keytool -list -v -keystore my-release-key.keystore. You can test it via https://developers.google.com/digital-asset-links/tools/generator.