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
The quick way: the plugin
npm install @straitlink/capacitor@0.4.7
npx cap syncThe 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. 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 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 documents every field. The Strait Capacitor plugin does all of this for you.
Docs for this setup
Where to go next for Capacitor and Ionic
Check your setup
Free tools for the parts that usually break
Other guides: Expo · Next.js · FlutterFlow · Jetpack Compose (Kotlin) · SwiftUI · Unity
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.