{"id":15097958,"url":"https://github.com/ionic-team/ionic-plugin-deeplinks","last_synced_at":"2025-10-08T03:30:56.150Z","repository":{"id":38985172,"uuid":"60306543","full_name":"ionic-team/ionic-plugin-deeplinks","owner":"ionic-team","description":"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.","archived":true,"fork":false,"pushed_at":"2023-05-26T13:56:57.000Z","size":135,"stargazers_count":332,"open_issues_count":145,"forks_count":220,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-01-17T19:09:07.664Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Objective-C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ionic-team.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-06-03T00:35:59.000Z","updated_at":"2024-11-10T14:14:55.000Z","dependencies_parsed_at":"2024-06-18T13:36:17.529Z","dependency_job_id":"0b442005-b6a9-496c-b092-8d97a38d1d13","html_url":"https://github.com/ionic-team/ionic-plugin-deeplinks","commit_stats":{"total_commits":135,"total_committers":24,"mean_commits":5.625,"dds":0.4296296296296296,"last_synced_commit":"bbbbf108c046141321b51c4a6ce223f682f8a346"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ionic-team%2Fionic-plugin-deeplinks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ionic-team%2Fionic-plugin-deeplinks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ionic-team%2Fionic-plugin-deeplinks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ionic-team%2Fionic-plugin-deeplinks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ionic-team","download_url":"https://codeload.github.com/ionic-team/ionic-plugin-deeplinks/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235678929,"owners_count":19028301,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-09-25T16:41:37.575Z","updated_at":"2025-10-08T03:30:50.859Z","avatar_url":"https://github.com/ionic-team.png","language":"Objective-C","readme":"# Community Maintained\n\nThis plugin is being maintained by the Ionic community. Interested in helping? Message `max` on ionic worldwide slack.\n\nAnother great solution for deep links for Ionic is the Branch Metrics plugin: [https://github.com/BranchMetrics/cordova-ionic-phonegap-branch-deep-linking](https://github.com/BranchMetrics/cordova-ionic-phonegap-branch-deep-linking)\n\nIf 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](https://github.com/EddyVerbruggen/Custom-URL-scheme) to facilitate custom URL schemes.\n\nIonic Deeplinks Plugin\n======\n\nThis plugin makes it easy to respond to deeplinks through custom URL schemes\nand Universal/App Links on iOS and Android.\n\nFor example, you can have your app open through a link to https://yoursite.com/product/cool-beans and then navigate\nto display the Cool Beans in your app (cool beans!).\n\nAdditionally, on Android iOS, your app can be opened through a custom URL scheme, like `coolbeans://product/cool-beans`.\n\nSince 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](#ios-configuration) as it's clear custom URL schemes are on the way out.\n\n*Note: this plugin may clash with existing Custom URL Scheme and Universal Links Plugins. Please let\nus know if you encounter compatibility issues. Also, try removing them and using this one on its own.*\n\nThank you to the [Cordova Universal Links Plugin](https://github.com/nordnet/cordova-universal-links-plugin) and the [Custom URL Scheme](https://github.com/EddyVerbruggen/Custom-URL-scheme) plugin that this plugin is inspired and borrows from.\n\n## Installation\n\n```bash\ncordova plugin add ionic-plugin-deeplinks\n--variable URL_SCHEME=myapp --variable DEEPLINK_SCHEME=https --variable DEEPLINK_HOST=example.com\n--variable ANDROID_PATH_PREFIX=/\n```\n\nFill in the appropriate values as shown below:\n\n * `URL_SCHEME` - the custom URL scheme you'd like to use for your app. This lets your app respond to links like `myapp://blah`\n * `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.\n * `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.\n * `ANDROID_PATH_PREFIX` - (optional): specify which path prefix our Android app should open from [more info](https://developer.android.com/guide/topics/manifest/data-element.html)\n\n(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.\n\n## Handling Deeplinks in JavaScript\n\n#### Ionic/Angular 2\n\n*note: make sure to call IonicDeeplink from a platform.ready or `deviceready` event*\n\nUsing [Ionic Native](https://github.com/ionic-team/ionic-native) (available in 1.2.4 or greater):\n\n```javascript\nimport { Platform, NavController } from 'ionic-angular';\nimport { Deeplinks } from '@ionic-native/deeplinks/ngx';\n\nexport class MyApp {\n  constructor(\n    protected platform: Platform\n    , protected navController: NavController\n    , protected deeplinks: Deeplinks\n    ) {\n    this.platform.ready().then(() =\u003e {\n      this.deeplinks.route({\n        '/about-us': HomePage,\n        '/products/:productId': HelpPage\n      }).subscribe((match) =\u003e {\n        // match.$route - the route we matched, which is the matched entry from the arguments to route()\n        // match.$args - the args passed in the link\n        // match.$link - the full link data\n        console.log('Successfully matched route', match);\n      },\n      (nomatch) =\u003e {\n        // nomatch.$link - the full link data\n        console.error('Got a deeplink that didn\\'t match', nomatch);\n      });\n    });\n  }\n}\n\n// Note: routeWithNavController returns an observable from Ionic Native so it *must* be subscribed to first in order to trigger.\n```\n\nIf you're using Ionic 2, there is a convenience method to route automatically (see the simple [Ionic 2 Deeplinks](https://github.com/ionic-team/ionic2-deeplinks-demo/blob/master/app/app.ts) demo for an example):\n\n```javascript\nimport { Platform, NavController } from 'ionic-angular';\nimport { Deeplinks } from '@ionic-native/deeplinks/ngx';\n\nexport class MyApp {\n  constructor(\n    protected platform: Platform\n    , protected navController: NavController\n    , protected deeplinks: Deeplinks\n    ) {\n    this.platform.ready().then(() =\u003e {\n      this.deeplinks.routeWithNavController(this.navController, {\n        '/about-us': HomePage,\n        '/products/:productId': HelpPage\n      }).subscribe((match) =\u003e {\n        // match.$route - the route we matched, which is the matched entry from the arguments to route()\n        // match.$args - the args passed in the link\n        // match.$link - the full link data\n        console.log('Successfully matched route', match);\n      },\n      (nomatch) =\u003e {\n        // nomatch.$link - the full link data\n        console.error('Got a deeplink that didn\\'t match', nomatch);\n      });\n    });\n  }\n}\n\n// Note: routeWithNavController returns an observable from Ionic Native so it *must* be subscribed to first in order to trigger.\n```\n\n#### Ionic/Angular 1\n\nFor Ionic 1 and Angular 1 apps using Ionic Native, there are many ways we can handle deeplinks. However,\nwe need to make sure we set up a history stack for the user, we can't navigate directly to our page\nbecause Ionic 1's navigation system won't properly build the navigation stack (to show a back button, for example).\n\nThis is all fine because deeplinks should provide the user with a designed experience for what the back button\nshould do, as we are putting them deep into the app and need to provide a natural way back to the main flow:\n\n(See a simple [demo](https://github.com/ionic-team/ionic1-deeplinks-demo) of v1 deeplinking).\n\n```javascript\nangular.module('myApp', ['ionic', 'ionic.native'])\n\n.run(['$ionicPlatform', '$cordovaDeeplinks', '$state', '$timeout', function($ionicPlatform, $cordovaDeeplinks, $state, $timeout) {\n  $ionicPlatform.ready(function() {\n    // Note: route's first argument can take any kind of object as its data,\n    // and will send along the matching object if the route matches the deeplink\n    $cordovaDeeplinks.route({\n      '/product/:productId': {\n        target: 'product',\n        parent: 'products'\n      }\n    }).subscribe(function(match) {\n      // One of our routes matched, we will quickly navigate to our parent\n      // view to give the user a natural back button flow\n      $timeout(function() {\n        $state.go(match.$route.parent, match.$args);\n\n        // Finally, we will navigate to the deeplink page. Now the user has\n        // the 'product' view visibile, and the back button goes back to the\n        // 'products' view.\n        $timeout(function() {\n          $state.go(match.$route.target, match.$args);\n        }, 800);\n      }, 100); // Timeouts can be tweaked to customize the feel of the deeplink\n    }, function(nomatch) {\n      console.warn('No match', nomatch);\n    });\n  });\n}])\n```\n\n#### Non-Ionic/angular\n\nIonic Native works with non-Ionic/Angular projects and can be accessed at `window.IonicNative` if imported.\n\nIf you don't want to use Ionic Native, the plugin is available on `window.IonicDeeplink` with a similar API minus the observable callback:\n\n```javascript\nwindow.addEventListener('deviceready', function() {\n  IonicDeeplink.route({\n    '/product/:productId': {\n      target: 'product',\n      parent: 'products'\n    }\n  }, function(match) {\n  }, function(nomatch) {\n  });\n})\n```\n\n## iOS Configuration\n\nAs of iOS 9.2, Universal Links *must* be enabled in order to deep link to your app. Custom URL schemes are no longer supported.\n\nFollow the official [Universal Links](https://developer.apple.com/library/ios/documentation/General/Conceptual/AppSearch/UniversalLinks.html) guide on the Apple Developer docs\nto set up your domain to allow Universal Links.\n\n### How to set up top-level domains (TLD's)\n#### Set up Associated Domains\nFirst you must enable the `Associated Domains` capability in your [provisioning profile](https://developer.apple.com/account/resources/profiles/list).\nAfter that you must enable it in the Xcode project, too.\nFor automated builds you can do it easily by adding this to your `config.xml`.\n\n    \u003cconfig-file target=\"*-Debug.plist\" parent=\"com.apple.developer.associated-domains\"\u003e\n        \u003carray\u003e\n            \u003cstring\u003eapplinks:example.org\u003c/string\u003e\n        \u003c/array\u003e\n    \u003c/config-file\u003e\n\n    \u003cconfig-file target=\"*-Release.plist\" parent=\"com.apple.developer.associated-domains\"\u003e\n        \u003carray\u003e\n            \u003cstring\u003eapplinks:example.org\u003c/string\u003e\n        \u003c/array\u003e\n    \u003c/config-file\u003e\n\nInstead of `applinks` only you could use `\u003cstring\u003ewebcredentials:example.org\u003c/string\u003e` or `\u003cstring\u003eactivitycontinuation:example.org\u003c/string\u003e`, too.\n\n#### Set up Apple App Site Association (AASA)\nYour website (i.e. `example.org`) must provide this both files.\n\n* /apple-app-site-association\n* /.well-known/apple-app-site-association\n\nThe content should contain your app.\n\n    {\n      \"applinks\": {\n        \"apps\": [],\n        \"details\": [\n          {\n            \"appID\": \"1A234BCD56.org.example\",\n            \"paths\": [\n              \"NOT \\/api\\/*\",\n              \"NOT \\/\",\n              \"*\"\n            ]\n          }\n        ]\n      }\n    }\n\nThis means that all your requests - except /api and / - will be redirected to your app.\nPlease replace `1A234BCD56` with your TEAM ID and `org.example` with your Bundle-ID. (the `id=\"\"` of your `\u003cwidget /\u003e`)\n\n## Android Configuration\n\nAndroid supports Custom URL Scheme links, and as of Android 6.0 supports a similar feature to iOS' Universal Links called App Links.\n\nFollow the App Links documentation on [Declaring Website Associations](https://developer.android.com/training/app-links/index.html#web-assoc) to enable your domain to\ndeeplink to your Android app.\n\nTo prevent Android from creating multiple app instances when opening deeplinks, you can add the following preference in Cordova config.xml file:\n\n```xml\n \u003cpreference name=\"AndroidLaunchMode\" value=\"singleTask\" /\u003e\n```\n\n### How to set up top-level domains (TLD's)\n#### Set up [Android App Links](https://developer.android.com/training/app-links)\nYour website (i.e. `example.org`) must provide this file.\n\n* /.well-known/assetlinks.json\n\nThe content should contain your app.\n\n    [\n      {\n        \"relation\": [\n          \"delegate_permission\\/common.handle_all_urls\"\n        ],\n        \"target\": {\n          \"namespace\": \"android_app\",\n          \"package_name\": \"org.example\",\n          \"sha256_cert_fingerprints\": [\n            \"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\"\n          ]\n        }\n      }\n    ]\n\nReplace `org.example` with your app package. (the `id=\"\"` of your `\u003cwidget /\u003e`)\nThe fingerprints you can get via `$ keytool -list -v -keystore my-release-key.keystore`.\nYou can test it via https://developers.google.com/digital-asset-links/tools/generator.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fionic-team%2Fionic-plugin-deeplinks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fionic-team%2Fionic-plugin-deeplinks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fionic-team%2Fionic-plugin-deeplinks/lists"}