Capacitor / Ionic deep linking

Add Strait deep links (and deferred deep links) to this Capacitor or Ionic app.

Read https://straitlink.in/docs/sdks/capacitor/ and follow it exactly. If anything here disagrees with that page, the page wins.
My link domain is https://<your-handle>.strait.link and my publishable key is st_pub_live_… (Dashboard → Get started).

Rules:
- Use only the publishable key here. Never put a secret key (st_live_…) in app or website code.
- Use the Strait Capacitor plugin (npm install @straitlink/capacitor, then npx cap sync). Route every link from its onLink callback; do not add an appUrlOpen handler for the link domain.
- iOS needs Swift Package Manager (the Capacitor 8 default); the plugin does not support CocoaPods yet.

Steps:
1. Install the SDK with the command on that page.
2. Let the phone open the app: in android/app/src/main/AndroidManifest.xml the App Links intent filter (autoVerify) for my link domain and one for my custom scheme, and in Xcode the Associated Domain applinks:<your-handle>.strait.link and my scheme under URL Types.
3. Create the client once with publishableKey and endpoint, call start() once at launch, and subscribe to onLink.
4. Map link paths to screens in this codebase.

Finish by telling me exactly how to check it:
- curl https://<your-handle>.strait.link/.well-known/assetlinks.json and /.well-known/apple-app-site-association list my app
- adb shell pm get-app-links <package> says verified after a fresh install
- a tap from WhatsApp on a real phone opens the right screen and onLink fires with matched: true

npm install @straitlink/capacitor@0.3.0

Time

About 10 minutes

You need

A Capacitor 8 app (Ionic, Vue, React, Angular or plain JS) with android/ or ios/ added, a workspace with your app in Dashboard → Apps & stores

Works on

Android, iPhone

@straitlink/capacitor is a Capacitor plugin over the Strait Android and iOS SDKs, with the same API as the React Native SDK. Links arrive by themselves: you don't wire appUrlOpen or AppDelegate code.

#1. Install the plugin

npm install @straitlink/capacitor@0.3.0
npx cap sync

On Android, the plugin adds JitPack to your Gradle repositories for the Strait Android SDK only (a content filter allows nothing else from it). On iOS it needs Swift Package Manager, the default for new Capacitor 8 apps; CocoaPods projects aren't supported yet.

You should see: npx cap sync lists @straitlink/capacitor under "Found … Capacitor plugins" for android and ios.

#2. Start it when your app starts

In main.ts (or wherever your app boots), before your router mounts:

import { createStrait } from '@straitlink/capacitor';

export const strait = createStrait({
  publishableKey: 'st_pub_live_…',           // Dashboard → Get started; never the secret key
  endpoint: 'https://hilltop.strait.link',
});
strait.onLink((e) => {
  console.log('Strait link:', e.kind, e.route, e.matched, e.path);
  if (e.matched && e.path) router.push({ path: e.path, query: e.params });   // your router
});
strait.start();

onLink gets every link, including the one that launched the app and the deferred link on the first open after an install. It also replays links that arrived before you subscribed. createStrait refuses a secret key, so it can't ship inside your app by mistake.

You should see: on the first launch after install, the console prints Strait link: deferred ….

#3. Let the app claim your link domain

Android, in android/app/src/main/AndroidManifest.xml, inside the main <activity>:

<intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="https" android:host="hilltop.strait.link" />
</intent-filter>
<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="yourapp" />
</intent-filter>

The second filter is the custom scheme in Dashboard → Apps & stores; the link page uses it when a browser hands the link to your app.

iOS, in Xcode: App target → Signing & Capabilities → + Associated Domains → applinks:hilltop.strait.link, and your scheme under Info → URL Types.

Then add your Android package and SHA-256 fingerprints, and your Apple Team ID and bundle ID, in Dashboard → Apps & stores. Strait serves assetlinks.json and apple-app-site-association for you.

You should see: adb shell pm get-app-links com.yourcompany.yourapp reports hilltop.strait.link: verified after a reinstall.

#4. Open a link

adb shell am start -a android.intent.action.VIEW -d "https://hilltop.strait.link/summer"
xcrun simctl openurl booted "https://hilltop.strait.link/summer"

You should see: the app opens on the link's screen and the console prints Strait link: direct app_link true /… with the link's path. The open shows up in Dashboard → Analytics within a minute.

#Check your setup

In a debug build, after start():

const report = await strait.doctor();
report.findings.forEach((f) => console.log(f.severity, f.id, f.title, f.fix));

It checks your key and endpoint, and whether hilltop.strait.link lists this app. On Android it also checks this build's signing certificate.

You should see: ok key.ok, ok app.listed and, on Android, ok cert.listed. A debug build often shows error cert.missing with the exact SHA-256 to add in Apps & stores.

#5. Events and revenue

await strait.trackEvent('purchase', { value: 49.99, currency: 'USD' });

The event lands on the tap of the last link that opened the app (7 days), so revenue shows next to the link and channel that brought it. It resolves true when Strait accepted it.

You should see: the purchase in Dashboard → Analytics → Events, on the link that opened the app.

#Test a deferred link on an Android emulator

An app you install with adb never gets a Play Install Referrer. Debug builds accept a stand-in on the first launch after install (release builds ignore it):

adb shell am start -n com.yourcompany.yourapp/.MainActivity \
  --es strait.debugReferrer "'strait_link=lnk_…&strait_click=…'"

Take both values from the referrer= of the Google Play URL your link sends an Android phone to.

You should see: Strait link: deferred install_referrer true /…, and an install on that tap in Dashboard → Analytics.

#Common errors

• Links open the browser, not the app. The intent filter or Associated Domains entry is missing, or the fingerprints and Team ID aren't in Apps & stores yet (step 3).
• Nothing happens on the web. The plugin runs on Android and iOS only; on the web every call resolves a safe default. Use the web SDK for websites.
• iOS build can't find the plugin. The app uses CocoaPods. Capacitor 8 apps created with npx cap add ios use Swift Package Manager; CocoaPods support is coming.

#Next steps

• Test: the same test plan works for Capacitor (direct links, deferred links from Google Play, analytics).
• The plugin's README and sample app on GitHub.