# Capacitor and Ionic deep linking

> How deep links reach a Capacitor or Ionic app, the Strait Capacitor plugin that handles them, and how to resolve short links and deferred deep links with the REST API if you'd rather not add a plugin.

Source: https://straitlink.in/guides/capacitor-deep-linking/
Markdown: https://straitlink.in/guides/capacitor-deep-linking.md

- [Guides](https://straitlink.in/guides/)
- Capacitor and Ionic

# Deep links for Capacitor and Ionic apps

A Capacitor app is a web app in a native shell, so links arrive natively and are routed in JavaScript. The Strait plugin does all of it for you; this guide explains how it works and how to do it by hand with the REST API.

- Guide
- Android
- iPhone
- `@straitlink/capacitor`
- [Faster: one prompt](https://straitlink.in/ai/#prompt-capacitor)

STEPS · 5

- [1The quick way: the plugin](https://straitlink.in/guides/capacitor-deep-linking/#the-quick-way-the-plugin)
- [2How links reach a Capacitor app](https://straitlink.in/guides/capacitor-deep-linking/#how-links-reach-a-capacitor-app)
- [3Two kinds of URL arrive](https://straitlink.in/guides/capacitor-deep-linking/#two-kinds-of-url-arrive)
- [4The screen after an install](https://straitlink.in/guides/capacitor-deep-linking/#the-screen-after-an-install)
- [5What you give up without a plugin](https://straitlink.in/guides/capacitor-deep-linking/#what-you-give-up-without-a-plugin)

**Step 1 of 5**The quick way: the plugin

AT A GLANCE · CAPACITOR AND IONIC

- Builds on : `@straitlink/capacitor`

- Platforms : Android, iPhone

- Start in the docs : [Capacitor / Ionic SDK](https://straitlink.in/docs/sdks/capacitor/)

- Free plan : 25,000 taps a month, no card

## The quick way: the plugin

```
npm  install  @straitlink/capacitor@0.4.7 npx  cap  sync
```

The plugin wraps the Strait Android and iOS SDKs: it reads the launch link, the links that arrive while the app runs, and the Play Install Referrer, and gives your JavaScript one `onLink` callback. Setup takes about 10 minutes: [Capacitor / Ionic docs](https://straitlink.in/docs/sdks/capacitor/). The rest of this guide is the manual route.

## How links reach a Capacitor app

The native side receives the link and the `@capacitor/app` plugin passes it to your JavaScript:

- `App.getLaunchUrl()` returns the URL that launched the app from closed, or nothing.

- `App.addListener('appUrlOpen', (e) => …)` fires for links that arrive while the app is running.

Your router (Angular, React or Vue with Ionic, or none) then shows the page. The native configuration is the same as for any Android or iOS app: an intent filter with `autoVerify` for `hilltop.strait.link` plus one for your custom scheme in `android/app/src/main/AndroidManifest.xml`, and **Associated Domains** with `applinks:hilltop.strait.link` plus a URL type in Xcode. The [Android setup page](https://straitlink.in/docs/sdks/android/#4-add-the-intent-filters) has the exact XML.

## Two kinds of URL arrive

A browser hand-off arrives on your custom scheme with the real destination, for example `yourapp://shop.example.com/products/42?strait_click=…`. Route on its path directly.

A verified link arrives as the short link itself, `https://hilltop.strait.link/summer`. Ask the link server for its destination with your publishable key:

```
import  { App }  from  '@capacitor/app' ; import  { Capacitor }  from  '@capacitor/core' ;  const  API  =  'https://hilltop.strait.link' ; const  KEY  =  'st_pub_live_…' ;   // the publishable key: safe in the app  async  function  destinationOf (url :  string ) :  Promise < string  |  null > {   if  ( new  URL (url).host  !==  new  URL ( API ).host)  return  url;           // custom scheme: already the destination   const  res  =  await  fetch ( ` ${ API } /v1/resolve` ,  {     method :  'POST' ,     headers :  {  'Content-Type' :  'application/json'  } ,     body :  JSON .stringify ({ publishableKey :  KEY ,  url ,  platform :  Capacitor .getPlatform () }) ,   });   const  r  =  await  res .json ();   return  r .matched  ?  r .longUrl  :  null ;                               // reason: not_found, expired… }  export  async  function  startLinks ( open :  (path :  string )  =>  void ) {   const  go  =  async  (url ?:  string )  =>  {     const  dest  =  url  &&  ( await  destinationOf (url));     if  (dest) {  const  u  =  new  URL (dest);  open ( u .pathname  +  u .search); }   };   App .addListener ( 'appUrlOpen' ,  (e)  =>  go ( e .url));   go (( await  App .getLaunchUrl ())?.url); }
```

## The screen after an install

**Android.** Google Play passes the link through the install: the referrer string holds `strait_link=<link id>`. Reading it needs the Play Install Referrer library on the native side, through a small plugin of your own or a community one. Send the link id to `POST /v1/referrer` once, on the first launch, and route to `longUrl` when `matched` is true. This match is exact.

**iPhone (opt-in install matching).** On the first launch, `POST /v1/match` with `platform: 'ios'` and these device fields: `screen.width`, `devicePixelRatio`, `navigator.language` and the IANA time zone from `Intl`. The server answers only when exactly one recent tap fits. Store a flag so the call happens once per install.

## What you give up without a plugin

The native SDKs also report each open, so Analytics can show opens and installs next to taps, and they retry reports made offline. Without them, send `POST /v1/open` yourself after each link open if you want those numbers. Taps are counted either way. The [REST API reference](https://straitlink.in/docs/api/) documents every field. The [Strait Capacitor plugin](https://straitlink.in/docs/sdks/capacitor/) does all of this for you.

[Open the Capacitor and Ionic docs](https://straitlink.in/docs/sdks/capacitor/)

Docs for this setup

## Where to go next for Capacitor and Ionic

- [Capacitor / Ionic SDK The plugin: install, onLink, deferred links, events](https://straitlink.in/docs/sdks/capacitor/)
- [Resolve a short link (API) POST /v1/resolve: the destination of a link that opened the app](https://straitlink.in/docs/api/resolve-link/)
- [Install referrer (API) POST /v1/referrer: the exact Android install match](https://straitlink.in/docs/api/resolve-install-referrer/)
- [Match an install (API) POST /v1/match: the iPhone first-launch check (opt-in)](https://straitlink.in/docs/api/match-install/)
- [Report an open (API) POST /v1/open: opens for Analytics](https://straitlink.in/docs/api/report-open/)

Check your setup

## Free tools for the parts that usually break

- [Will it open my app? Simulate a tap from WhatsApp, Instagram or Chrome](https://straitlink.in/tools/will-it-open/)
- [assetlinks.json checker Is your Android App Links file right?](https://straitlink.in/tools/assetlinks-checker/)
- [AASA validator Is your apple-app-site-association file right?](https://straitlink.in/tools/aasa-validator/)
- [Troubleshooting When a link opens the browser instead of the app](https://straitlink.in/docs/troubleshooting/)

Other guides: [Expo](https://straitlink.in/guides/expo-deep-linking/) · [Next.js](https://straitlink.in/guides/nextjs-deep-linking/) · [FlutterFlow](https://straitlink.in/guides/flutterflow-deep-linking/) · [Jetpack Compose (Kotlin)](https://straitlink.in/guides/jetpack-compose-deep-linking/) · [SwiftUI](https://straitlink.in/guides/swiftui-deep-linking/) · [Unity](https://straitlink.in/guides/unity-deep-linking/)

## Ship links that open your Capacitor and Ionic app.

Free for 25,000 taps a month, no card. Every tap gets a trace you can read.

[Start free](https://app.straitlink.in/?signup=1) [Read the quick start](https://straitlink.in/docs/quick-start/)
