@straitlink/capacitor 0.3.0 → 0.4.0

package/Package.swift

@@ -10,7 +10,7 @@ let package = Package(
     ],
     dependencies: [
         .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "8.0.0"),
-        .package(url: "https://github.com/strait-link/strait-sdk-swift.git", from: "0.9.4"),
+        .package(url: "https://github.com/strait-link/strait-sdk-swift.git", from: "0.11.0"), // setEnabled + F7 + B6a/B13a/C1 (StraitSDK 0.11.0)
     ],
     targets: [
         .target(

package/README.md

@@ -33,12 +33,23 @@ link-open analytics. It wraps the Strait [Android](https://github.com/strait-lin
 and [iOS](https://github.com/strait-link/strait-sdk-swift) SDKs, and its API matches
 [`@straitlink/react-native`](https://github.com/strait-link/strait-sdk-react-native).
 
+## Guided setup
+
+There's no `strait init` for Capacitor yet: the three steps below are the whole setup. Or let your AI coding tool do it: connect the [Strait MCP server](https://straitlink.in/docs/mcp/) and run its `get_started` prompt with platform `capacitor`; it pastes the exact setup from the docs. Then check that your link domain lists your app:
+
+```sh
+npx @straitlink/cli doctor --host <your-handle>.strait.link --android <your.package> --ios <your.bundle.id>
+```
+
 ## 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**
 
 ```sh
@@ -105,6 +116,11 @@ for (const f of report.findings) console.log(f.severity, f.id, f.title, f.fix);
 `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."
 
+## User consent / opt-out
+
+If your app asks for consent first (for example under India's DPDP Act or a GDPR consent flow in the EU), call `await strait.setEnabled(false)` until the person agrees: Strait then sends no open reports or events, does no install matching, and deletes reports waiting on the device. The choice is kept across launches on the phone; `setEnabled(true)` turns it back on (default: on) and `isEnabled()` reads it. It works before `start()`, so a first-launch consent screen can call it first; `setEnabled(true)` then runs the deferred check.
+Links that carry their own destination still open your screens. A Strait short link is looked up through the engine's `/v1/lookup`, which records nothing (no tap, no open, no tap id), so it still opens the right screen; only if that lookup fails (offline) does it come back `matched: false, reason: 'disabled'`. Whether you need consent, and for what, is a question for your own legal advice.
+
 ## Platform features
 
 | Feature | Status | Notes |
@@ -128,10 +144,11 @@ Debug, release and Play App Signing keys each have their own fingerprint."
 | `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). |
+| `trackEvent(name, { value, currency, linkId, clickId, eventId })` | Conversion or revenue event, placed on the tap of the last attributed open (7 days). `eventId` = your order id, stored once (left out, the SDK makes one). Resolves `true` when accepted; an event that can't be sent (offline, server busy) is kept and sent later with the open reports. Revenue you must trust: send it from your server with the secret key (the publishable key is public). |
+| `pendingOpenReports()` / `flushOpenReports()` | Open reports saved while offline (sent again on start and resume). After a 429/5xx the queue waits (15 s up to 1 h, at least the server's `Retry-After`) before sending again. |
 | `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 }`. |
+| `setEnabled(enabled)` / `isEnabled()` | Opt-out switch for consent flows (see above). Kept on the phone; works before `start()`. |
 | `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. |
 
@@ -145,13 +162,18 @@ The plugin is a thin layer. All link logic (resolving short links, the once-per-
 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
+- **Android:** `strait-sdk-android` **v0.10.0** from JitPack (the version is pinned in `android/build.gradle`). 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
+- **iOS:** `StraitSDK` **0.11.0+** through Swift Package Manager (pinned in `Package.swift`). Links come from Capacitor's
   `capacitorOpenURL` / `capacitorOpenUniversalLink` notifications; state lives in `UserDefaults`.
 
+**Reinstalls (contract B6a):** Android Auto Backup and restored iPhones bring the "deferred check
+done" flag back after a reinstall. The plugin passes the app's install time to the native SDKs
+(Android `firstInstallTime`; iOS a marker file kept out of backups), so a reinstall from a link still
+gets its deferred link and is counted. An app update is never a new install. No app code needed.
+
 What gets recorded, the privacy details and the match methods are the same as the native SDKs:
 see [Android](https://github.com/strait-link/strait-sdk-android#what-strait-records-automatically-no-extra-code)
 and [iOS](https://github.com/strait-link/strait-sdk-swift#what-strait-records-automatically-no-extra-code).
@@ -168,6 +190,17 @@ adb shell am start -n <your.package>/.MainActivity \
 
 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`](examples/capacitor-app): a plain-JS Capacitor app with two screens

package/android/build.gradle

@@ -1,6 +1,6 @@
 // @straitlink/capacitor, Android side: a thin Capacitor plugin over strait-sdk-android (JitPack).
 ext {
-    straitSdkVersion = 'v0.8.3'
+    straitSdkVersion = 'v0.10.0' // setEnabled + B6a/B13a/C1 (strait-sdk-android v0.10.0)
 }
 
 buildscript {
@@ -15,7 +15,7 @@ buildscript {
 
 apply plugin: 'com.android.library'
 
-// strait-sdk-android is built by JitPack from its version tags. Gradle resolves this plugin's
+// strait-sdk-android is built by JitPack from its version tags (or, between releases, a main commit). Gradle resolves this plugin's
 // dependencies with the app's repositories, so add JitPack to every project, limited to the
 // Strait group (nothing else is ever fetched from JitPack).
 rootProject.allprojects {

package/android/src/main/java/dev/strait/capacitor/StraitPlugin.java

@@ -57,10 +57,14 @@ import kotlin.Unit;
  */
 @CapacitorPlugin(name = "Strait")
 public class StraitPlugin extends Plugin {
+    /** strait-sdk-android's opt-out key in the "strait" preferences: "0" = off, absent = on. */
+    private static final String ENABLED_KEY = "strait.enabled";
     private final ExecutorService executor = Executors.newSingleThreadExecutor();
     private StraitClient client;
     /** A link that arrived (onNewIntent) before JS called start(). */
     private String pendingUrl;
+    /** setEnabled() before start(): applied to the client before it starts (which also clears saved reports). */
+    private Boolean pendingEnabled;
 
     @PluginMethod
     public synchronized void start(PluginCall call) {
@@ -81,7 +85,7 @@ public class StraitPlugin extends Plugin {
             if (h != null && !h.isEmpty()) hosts.add(h);
         }
         Context ctx = getContext().getApplicationContext();
-        SharedPreferences prefs = ctx.getSharedPreferences("strait", Context.MODE_PRIVATE);
+        SharedPreferences prefs = prefs(ctx);
         KeyValueStore storage = new KeyValueStore() {
             @Override public String get(String k) { return prefs.getString(k, null); }
             @Override public void set(String k, String v) { prefs.edit().putString(k, v).apply(); }
@@ -99,8 +103,11 @@ public class StraitPlugin extends Plugin {
             new UrlConnectionTransport(10_000, 10_000),
             executor,
             System::currentTimeMillis,
-            deviceClass(ctx)
+            deviceClass(ctx),
+            () -> installTime(ctx) // B6a: Auto Backup restores the flag; a new install time re-runs the check
         ));
+        if (pendingEnabled != null) client.setEnabled(pendingEnabled); // before anything is sent
+        pendingEnabled = null;
         client.onLinkStart(s -> { notifyListeners("linkStart", toJs(s), true); return Unit.INSTANCE; });
         client.onLink(e -> { notifyListeners("link", toJs(e), true); return Unit.INSTANCE; });
         client.onAppState(AppLifecycleState.ACTIVE, System.currentTimeMillis());
@@ -111,6 +118,44 @@ public class StraitPlugin extends Plugin {
         executor.execute(call::resolve); // after start's work on the same single thread
     }
 
+    /** Opt-out switch (consent): the native SDK's setEnabled. Before start() it is saved and applied at start. */
+    @PluginMethod
+    public synchronized void setEnabled(PluginCall call) {
+        Boolean on = call.getBoolean("enabled");
+        if (on == null) {
+            call.reject("Strait: setEnabled needs enabled (true or false)");
+            return;
+        }
+        if (client != null) {
+            client.setEnabled(on);
+            executor.execute(call::resolve); // after the SDK's clearing / re-run on the same single thread
+            return;
+        }
+        pendingEnabled = on;
+        prefs(getContext()).edit().putString(ENABLED_KEY, on ? "1" : "0").apply();
+        call.resolve();
+    }
+
+    @PluginMethod
+    public synchronized void isEnabled(PluginCall call) {
+        JSObject r = new JSObject();
+        r.put("enabled", client != null ? client.isEnabled() : !"0".equals(prefs(getContext()).getString(ENABLED_KEY, null)));
+        call.resolve(r);
+    }
+
+    private static SharedPreferences prefs(Context ctx) {
+        return ctx.getApplicationContext().getSharedPreferences("strait", Context.MODE_PRIVATE);
+    }
+
+    /** This install's time (PackageInfo.firstInstallTime, epoch ms), or null; contract B6a. */
+    private static Long installTime(Context ctx) {
+        try {
+            return ctx.getPackageManager().getPackageInfo(ctx.getPackageName(), 0).firstInstallTime;
+        } catch (Exception e) {
+            return null;
+        }
+    }
+
     @PluginMethod
     public void checkDeferred(PluginCall call) {
         StraitClient c = ready(call);
@@ -131,9 +176,10 @@ public class StraitPlugin extends Plugin {
         String currency = call.getString("currency");
         String linkId = call.getString("linkId");
         String clickId = call.getString("clickId");
+        String eventId = call.getString("eventId");
         executor.execute(() -> {
             JSObject r = new JSObject();
-            r.put("accepted", c.trackEvent(name, value, currency, linkId, clickId));
+            r.put("accepted", c.trackEvent(name, value, currency, linkId, clickId, eventId));
             call.resolve(r);
         });
     }

package/dist/strait.d.ts

@@ -86,6 +86,8 @@ export interface TrackEventExtra {
     currency?: string;
     linkId?: string;
     clickId?: string;
+    /** Your id for this conversion, e.g. the order id (1-64 of A-Z a-z 0-9 _ . : -). Stored once (B13a). */
+    eventId?: string;
 }
 /** The native side (Android: StraitPlugin.java over strait-sdk-android; iOS: StraitPlugin.swift over StraitSDK). */
 export interface StraitNativePlugin {
@@ -111,6 +113,12 @@ export interface StraitNativePlugin {
     openStoreSheet(options: {
         url: string;
     } & StoreSheetOptions): Promise<StoreSheetResult>;
+    setEnabled(options: {
+        enabled: boolean;
+    }): Promise<void>;
+    isEnabled(): Promise<{
+        enabled: boolean;
+    }>;
     addListener(event: 'link', cb: (e: LinkEvent) => void): Promise<PluginListenerHandle>;
     addListener(event: 'linkStart', cb: (s: LinkStart) => void): Promise<PluginListenerHandle>;
 }
@@ -142,6 +150,17 @@ export interface Strait {
      * want people to install), keeping the deep link through the install. Never throws.
      */
     openStoreSheet(url: string, options?: StoreSheetOptions): Promise<StoreSheetResult>;
+    /**
+     * Opt-out switch for consent flows (default on, kept on the phone across launches by the native SDK).
+     * Off: no open reports, no events, no deferred or clipboard matching, nothing remembered; reports saved
+     * earlier and the remembered tap are deleted. A link that carries its own destination still reaches
+     * onLink; a short link is looked up through /v1/lookup, which records nothing (no tap, no open, no tap
+     * id), so it still routes (`reason: 'disabled'` only if that lookup fails). Back on: sending resumes, and
+     * a first-launch check skipped while off runs now. Works before start(): call it first on a consent screen.
+     */
+    setEnabled(enabled: boolean): Promise<void>;
+    /** The opt-out switch's current value (see setEnabled). True when it can't be read (the default). */
+    isEnabled(): Promise<boolean>;
     /** Stop delivering events to this object. */
     stop(): void;
 }

package/dist/strait.js

@@ -55,12 +55,18 @@ export function createStrait(config, native) {
             id: '', kind: 'deferred', route: 'fingerprint', appState: 'foreground',
             matched: false, reason: 'unavailable', ms: 0, at: Date.now(),
         }),
-        trackEvent: (name, extra = {}) => safe(async () => (await native.trackEvent({ name, ...extra })).accepted === true, false),
+        trackEvent: (name, extra = {}) => safe(async () => {
+            // Native getString() reads a number as missing: send a plain-JS number order id as its string (B13a).
+            const eventId = extra.eventId != null && extra.eventId !== '' ? { eventId: String(extra.eventId) } : {};
+            return (await native.trackEvent({ name, ...extra, ...eventId })).accepted === true;
+        }, false),
         pendingOpenReports: () => safe(async () => (await native.pendingOpenReports()).count ?? 0, 0),
         flushOpenReports: () => safe(() => native.flushOpenReports(), undefined),
         deviceClass: () => safe(async () => (await native.deviceClass()).deviceClass, undefined),
         doctor: () => safe(() => native.doctor(), { ok: false, findings: [] }),
         openStoreSheet: (url, options = {}) => safe(() => native.openStoreSheet({ url, ...options }), { opened: false, method: 'none', reason: 'unavailable' }),
+        setEnabled: (enabled) => safe(() => native.setEnabled({ enabled: enabled === true }), undefined),
+        isEnabled: () => safe(async () => (await native.isEnabled()).enabled !== false, true),
         stop() {
             linkCbs.clear();
             startCbs.clear();

package/ios/Sources/StraitPlugin/StraitPlugin.swift

@@ -19,12 +19,16 @@ public class StraitPlugin: CAPPlugin, CAPBridgedPlugin {
         CAPPluginMethod(name: "deviceClass", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "doctor", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "openStoreSheet", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "setEnabled", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "isEnabled", returnType: CAPPluginReturnPromise),
     ]
 
     private var links: StraitLinks?
     private var subscriptions: [StraitSubscription] = []
     /// A link that arrived before JS called start().
     private var pendingURL: URL?
+    /// setEnabled() before start(): applied to StraitLinks before it starts (which also clears saved reports).
+    private var pendingEnabled: Bool?
 
     override public func load() {
         for name in [Notification.Name.capacitorOpenURL, .capacitorOpenUniversalLink] {
@@ -51,6 +55,8 @@ public class StraitPlugin: CAPPlugin, CAPBridgedPlugin {
             let hosts = (call.getArray("linkHosts") as? [String]) ?? []
             let l = StraitLinks(StraitLinksConfig(publishableKey: key, endpoint: endpoint, linkHosts: hosts))
             links = l
+            if let on = pendingEnabled { l.setEnabled(on) } // before anything is sent
+            pendingEnabled = nil
             subscriptions = [
                 l.onLinkStart { [weak self] s in self?.notifyListeners("linkStart", data: Self.js(s), retainUntilConsumed: true) },
                 l.onLink { [weak self] e in self?.notifyListeners("link", data: Self.js(e), retainUntilConsumed: true) },
@@ -62,6 +68,27 @@ public class StraitPlugin: CAPPlugin, CAPBridgedPlugin {
         }
     }
 
+    /// Opt-out switch (consent): StraitSDK's setEnabled. Before start() it is saved (StraitLinks' default
+    /// storage, UserDefaults) and applied at start.
+    @objc func setEnabled(_ call: CAPPluginCall) {
+        guard let on = call.getBool("enabled") else {
+            call.reject("Strait: setEnabled needs enabled (true or false)")
+            return
+        }
+        DispatchQueue.main.async { [self] in
+            if let l = links { l.setEnabled(on) { call.resolve() }; return }
+            pendingEnabled = on
+            UserDefaultsStorage().setItem(StraitLinks.enabledKey, on ? "1" : "0")
+            call.resolve()
+        }
+    }
+
+    @objc func isEnabled(_ call: CAPPluginCall) {
+        DispatchQueue.main.async { [self] in
+            call.resolve(["enabled": links?.isEnabled ?? (UserDefaultsStorage().getItem(StraitLinks.enabledKey) != "0")])
+        }
+    }
+
     @objc func checkDeferred(_ call: CAPPluginCall) {
         guard let l = ready(call) else { return }
         l.checkDeferred { e in call.resolve(Self.js(e)) }
@@ -78,7 +105,8 @@ public class StraitPlugin: CAPPlugin, CAPBridgedPlugin {
             value: call.getDouble("value"),
             currency: call.getString("currency"),
             linkId: call.getString("linkId"),
-            clickId: call.getString("clickId")
+            clickId: call.getString("clickId"),
+            eventId: call.getString("eventId")
         ) { ok in call.resolve(["accepted": ok]) }
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@straitlink/capacitor",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Deep linking for Capacitor and Ionic apps: direct links (App Links, Universal Links, custom schemes), deferred links that survive the install and link-open analytics. Wraps the Strait Android and iOS SDKs.",
   "keywords": [
     "capacitor",