Handle deeplinks into your Ionic/Cordova apps from Universal Links, App Links, and Custom URL schemes. For those using Ionic 2, there are some nice goodies that make life easier.
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.
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.
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://blahDEEPLINK_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.
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.
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);
});
});
}])
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) {
});
})
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.
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.
Your website (i.e. example.org) must provide this both files.
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 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" />
Your website (i.e. example.org) must provide this file.
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.