Capacitor and Ionic SDK

Handle cold-start and runtime URLs once in your hybrid application shell.

Choose this SDK when#

Use this adapter when a Capacitor or Ionic application owns navigation and must handle both the launch URL and later appUrlOpen events.

Warning

Version 0.1.3 is source-ready but neither @locusvia/capacitor-sdk nor its Web dependency is published on npm. Use a reviewed checkout for evaluation only.

Choose another SDK when: your product is browser-only, React Native, or fully native. The adapter intentionally delegates HTTP behavior to the Web SDK and does not replace native association setup.

Before you start#

A Capacitor application with @capacitor/app installed and synchronized to iOS and Android.
A LocusVia App Platform ID and SDK key scoped to the target environment.
Valid Apple Universal Link and Android App Link associations for the public domain.

Note

Use an environment-scoped public SDK key. Never embed a server, admin, or privileged credential in an app.

1. Install both source packages#

Install the Web client and Capacitor adapter from the same reviewed checkout, then synchronize native projects.

bash

npm install ../locusvia/sdk ../locusvia/sdk/capacitor @capacitor/app
npx cap sync

2. Start the integration once#

Initialize near application bootstrap, after the router is available. The adapter checks the cold-start URL before subscribing to runtime URLs.

typescript

import { startLocusVia } from "@locusvia/capacitor-sdk";

const integration = await startLocusVia(
  {
    appID: "REPLACE_WITH_APP_ID",
    apiKey: "REPLACE_WITH_SDK_KEY",
    baseUrl: "https://staging.locusvia.com",
  },
  {
    onLink: (link) => {
      if (link.pathname) router.navigateByUrl(link.pathname);
    },
  },
);

3. Keep the listener for the application lifetime#

Do not stop the integration after the first route. Remove it only when the application shell is disposed.

typescript

window.addEventListener("app-shell-dispose", () => {
  void integration.stop();
});

Verify the integration#

Force-stop the app, open a verified public link, and confirm the cold-start route is correct.
With the app already open, tap a second link and confirm appUrlOpen routes without reinitializing the shell.
Repeat on signed iOS and Android builds; simulator browser fallback is not device-link proof.

Warning

A successful build proves source compatibility only. Test a real link on the target browser or signed device before release.

Troubleshoot by symptom#

Browser opens instead of the appFix the Apple or Android association file and native entitlements. The SDK only handles URLs delivered to the app.

Cold start works, later links do notKeep the integration alive and confirm no application code removed the appUrlOpen listener.

Link opens twiceStart the integration once at the shell boundary, not once per page or view.

Route is missingInspect processed and link.pathname before navigation; fail closed when no route was resolved.

Next steps#

Confirm your domain associations, then add conversion and revenue events only after link resolution works end to end.