@straitlink/capacitor gives a Capacitor 8 app (Ionic, Vue, React, Angular or plain JS) direct
links (App Links, Universal Links, custom schemes), deferred links that survive the install, and
link-open analytics. It wraps the Strait Android
and iOS SDKs, and its API matches
@straitlink/react-native.
Quick start (60 seconds)
You need: a Capacitor 8 app with android/ and/or ios/ added, and from
Dashboard → Get started your publishable key (st_pub_live_…) and link domain
(https://<your-handle>.strait.link).
Android builds of a Capacitor 8 app need JDK 21 (Capacitor's own requirement; with JDK 17 the
Gradle build fails). Android Studio's bundled JDK is 21; on the command line check java -version.
1. Install and sync
npm install @straitlink/capacitor
npx cap sync
2. Start it when your app starts (for example in main.ts)
import { createStrait } from '@straitlink/capacitor';
const strait = createStrait({
publishableKey: 'st_pub_live_…', // safe in apps; never the secret key
endpoint: 'https://<your-handle>.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();
3. Let the app claim your link domain
-
Android, 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="<your-handle>.strait.link" />
</intent-filter>
-
iOS, Xcode → App target → Signing & Capabilities → + Associated Domains →
applinks:<your-handle>.strait.link.
-
In Dashboard → Settings → App: your Android package name + signing SHA-256, and your
Apple Team ID + bundle ID. Strait then serves assetlinks.json and the
apple-app-site-association file for you.
You should see: run the app on a phone or emulator, then open one of your links:
adb shell am start -a android.intent.action.VIEW -d "https://<your-handle>.strait.link/<code>"
xcrun simctl openurl booted "https://<your-handle>.strait.link/<code>"
The app opens on the link's screen and the console prints
Strait link: direct app_link true /p/42 (your path). The open shows up in the dashboard's
Analytics within a minute. On a fresh install the first launch prints a deferred event instead.
Check your setup
In a debug build, after start():
const report = await strait.doctor();
for (const f of report.findings) console.log(f.severity, f.id, f.title, f.fix);
You should see ok key.ok, ok app.listed and, on Android, ok cert.listed. Anything marked
error comes with the fix, for example cert.missing: "Add AB:CD:… in Dashboard → Apps & stores.
Debug, release and Play App Signing keys each have their own fingerprint."
Platform features
| Feature | Status | Notes |
|---|
| Android: direct links and deferred links | ● Live | Deferred = exact match through the Play Install Referrer (read for you). |
| iPhone links (Universal Links, custom schemes) | ● Live | Through Capacitor's AppDelegate / SceneDelegate proxy: no extra code. |
| iPhone: install matching (deferred links) | Opt-in | Your choice in Dashboard → Settings → iPhone installs, read at runtime. See the iOS SDK. |
| iOS with CocoaPods | – Not yet | Swift Package Manager only (the Capacitor 8 default for new apps). |
| Web | – | Every call resolves a safe default; use @straitlink/web for websites. |
| Published on npm | ● Live | npm install @straitlink/capacitor |
● Live · Opt-in: off until you switch it on · – Not yet. The same words as the
platform status page.
API
| Call | What it does |
|---|
createStrait({ publishableKey, endpoint, linkHosts? }) | One client per app. Throws only for a missing or secret key. linkHosts adds custom short-link hosts or old <x>.page.link hosts. |
start() | Reads the link that launched the app, listens for new ones, runs the deferred check once per install, sends saved open reports. Call it once, after onLink. |
onLink(cb) | Every link event, including ones from before you subscribed. Returns an unsubscribe. |
onLinkStart(cb) | A link just arrived and is being resolved: show a loading state. |
checkDeferred() | Asks for the deferred link again (settings or debug screens). Doesn't add an install. |
trackEvent(name, { value, currency, linkId, clickId }) | Conversion or revenue event, placed on the tap of the last attributed open (7 days). Resolves true when accepted. |
pendingOpenReports() / flushOpenReports() | Open reports saved while offline (sent again on start and resume). |
deviceClass() | phone or tablet (iPad / 600 dp and up), as sent with open reports. |
openStoreSheet(url, options?) | The app store inside your app for one of your links (another app to install), deep link kept through the install. Options: androidPackage, listing, inline, appStoreId, providerToken, customProductPageId, style. Resolves { opened, method, clickId, linkId, referrer, reason }. |
doctor() | Setup check for debug builds (key, endpoint, this app listed in your link domain's files, Android signing certificate). Resolves { ok, findings }. |
stop() | Stops delivering events to this object. |
LinkEvent: id, kind (direct|deferred), route (app_link|custom_scheme|install_referrer|fingerprint|clipboard), appState (closed|background|foreground), matched, reason, rawUrl, url, path, params, linkId, referralCode, ms, at.
After createStrait, nothing throws: a failure resolves matched: false with a reason, false, 0 or nothing.
How it works
The plugin is a thin layer. All link logic (resolving short links, the once-per-install deferred
check, open reports and their retry queue, app-state labels) runs in the native SDKs, which share
golden test vectors with the Strait engine:
- Android:
strait-sdk-android v0.8.3 from JitPack. The plugin adds JitPack to your Gradle
repositories, limited to the com.github.strait-link group, so nothing else is ever fetched from
it. It reads the Play Install Referrer (com.android.installreferrer:installreferrer:2.2), the launch
intent and onNewIntent, and keeps state in SharedPreferences (strait).
- iOS:
StraitSDK 0.9.4+ through Swift Package Manager. Links come from Capacitor's
capacitorOpenURL / capacitorOpenUniversalLink notifications; state lives in UserDefaults.
What gets recorded, the privacy details and the match methods are the same as the native SDKs:
see Android
and iOS.
Testing a deferred link on an Android emulator
A sideloaded app never gets a Play Install Referrer. Debug builds only accept a stand-in on the
first launch after install (release builds ignore it):
adb shell am start -n <your.package>/.MainActivity \
--es strait.debugReferrer "'strait_link=lnk_…&strait_click=…'"
Take both values from the Play Store URL your link redirects an Android phone to (its referrer=).
Size and speed
Measured 25 Oct 2026 on 0.3.0.
| What | Size or time | How it was measured |
|---|
| npm package | 15.6 KB download, 50 KB unpacked (JS, plus the Android and iOS plugin sources) | npm pack --dry-run |
| In your web bundle | 1.5 KB minified, 0.8 KB gzip (@capacitor/core is yours already) | esbuild 0.25 --bundle --minify |
| Native | the Android SDK (about 35 KB of dex after R8) and the Swift SDK (about 280 KB of arm64 code before App Store compression); see their READMEs | measured in those repos |
| Start-up (JS side) | 3.0 ms to load the module with @capacitor/core + 0.07 ms for createStrait(...) | fresh Node 26 process, median of 25. The native side's start-up is in the Android and Swift READMEs |
Sample app
examples/capacitor-app: a plain-JS Capacitor app with two screens
(Home and Product), a "Check deferred link" button and a "Log a purchase" button. CI builds it for
Android and the iOS Simulator on every pull request.
cd examples/capacitor-app && npm install
STRAIT_PUBLISHABLE_KEY=st_pub_live_… STRAIT_ENDPOINT=https://<your-handle>.strait.link npm run sync
npx cap run android # or: npx cap run ios
Docs and support
