# Capacitor / Ionic deep linking

> After this page, links open your Capacitor app on the right screen, including the first open after an install.

- 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

Source: https://straitlink.in/docs/sdks/capacitor/

`@straitlink/capacitor` is a Capacitor plugin over the Strait [Android](https://straitlink.in/docs/sdks/android/) and [iOS](https://straitlink.in/docs/sdks/ios/) SDKs, with the same API as the [React Native SDK](https://straitlink.in/docs/sdks/react-native/). Links arrive by themselves: you don't wire `appUrlOpen` or `AppDelegate` code.

## 1. Install the plugin

```bash
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:

```ts title="src/main.ts"
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>`:

```xml title="AndroidManifest.xml"
<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

```bash
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()`:

```ts
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

```ts
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):

```bash
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](https://straitlink.in/docs/sdks/web/) 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](https://straitlink.in/docs/sdks/react-native/test/): the same test plan works for Capacitor (direct links, deferred links from Google Play, analytics).
- The plugin's [README and sample app](https://github.com/strait-link/strait-sdk-capacitor) on GitHub.