Ionic Deeplinks Plugin
npm install @spoonconsulting/ionic-plugin-deeplinksThis 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.
``bash`
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
* - 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.
#### 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):
`javascript
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):
`javascript
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).
`javascript
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:
`javascript`
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.
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.
applinks:example.org
applinks:example.org
Instead of
applinks only you could use or , 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 )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:
`xml
`$3
#### Set up Android App Links
Your website (i.e. ) 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 )
The fingerprints you can get via $ keytool -list -v -keystore my-release-key.keystore`.