Web SDK

Resolve links and record attributed outcomes in browser applications.

Choose this SDK when#

Use the Web SDK for browser-rendered applications, including SPAs, when you control the page that receives the LocusVia URL and the conversion action.

Warning

Version 0.1.3 is source-ready but is not published on npm. Evaluate it from a reviewed repository checkout; do not add @locusvia/web-sdk as a registry dependency yet.

Choose another SDK when: you are building a native or hybrid mobile shell. Use the native, React Native, or Capacitor guide so cold starts and operating-system link events are handled correctly.

Before you start#

A LocusVia App Platform ID and SDK key for the same tenant and environment.
The LocusVia API origin for that environment.
A browser route that can receive the public link and preserve its click context.

Note

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

1. Install the reviewed source package#

From an application beside a reviewed LocusVia checkout, install the Web package by local path. Replace the path with your checkout location.

bash

npm install ../locusvia/sdk

2. Create one client#

Create the client once at application bootstrap. The storage adapter keeps queued analytics across reloads; it does not store privileged credentials.

typescript

import { createLocalStorageAdapter, createLocusViaClient } from "@locusvia/web-sdk";

export const locusVia = createLocusViaClient({
  appID: "REPLACE_WITH_APP_ID",
  apiKey: "REPLACE_WITH_SDK_KEY",
  baseUrl: "https://staging.locusvia.com",
  storage: createLocalStorageAdapter(),
});

3. Resolve the received URL#

Resolve the full public URL before routing. Treat processed=false or a missing link as a safe no-match, not as a destination.

typescript

const result = await locusVia.resolveShortLink(window.location.href);

if (result.processed && result.link?.pathname) {
  router.navigate(result.link.pathname);
}

4. Record the business outcome#

Generate a stable event ID at the action boundary. Pass the click ID when one was carried into your page so retries remain idempotent and attributable.

typescript

await locusVia.trackRegistration({
  eventId: crypto.randomUUID(),
  ...(clickId && { clickId }),
});

Verify the integration#

Open a real LocusVia URL in a clean browser session and confirm the intended route renders.
Trigger the conversion once, reload, and confirm a retry does not create a second event for the same event ID.
Test without a click ID and confirm the event is accepted without being falsely attributed.

Warning

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

Troubleshoot by symptom#

401 or generic authorization responseConfirm appID, SDK key, API origin, tenant, and environment all belong together.

processed is falseConfirm the full URL is passed to resolveShortLink and that its domain and slug exist in the same environment.

Conversion is not attributedPreserve the click ID through browser routing and send it with the canonical conversion event.

Events disappear after reloadConfigure createLocalStorageAdapter and call flush after connectivity returns.

Next steps#

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