Web SDK

Use the browser SDK when you want web-native attribution, manual route tracking, deep-link handling, and event capture without adding React-specific wrappers.

SDK / Web

This section stays intentionally general. For detailed configuration, project-specific diagnostics, release context, and exact disclosure guidance, open the app workspace for your project.

Package surface

General guide for @attriax/js. Use the app workspace when you need detailed setup steps, release context, and project-specific values.

Open on npmjs

What teams use it for

These are the runtime jobs the product already exposes through the SDK and the matching workspace tools.

Browser-native

Fits websites, web apps, and landing flows that need attribution without a mobile runtime.

Router aware

Lets your app decide how URLs are consumed while still reporting the outcome to Attriax.

Analytics ready

Feeds page views, route context, and events into the same analytics surface used by mobile apps.

Integration notes

Keep the public docs lightweight, then open the app workspace when you need the exact setup steps for your own release flow.

Capabilities

Initialize a browser SDK instance at module scope and keep it alive across SPA navigation.
Record page views manually when your own router owns path and title changes.
Wait for initial deep links, subscribe to runtime deep-link events, and resolve URLs the router already consumed.
Capture web-side events and route context so browser journeys show up beside app attribution data.

Notes

Browser web is a primary Attriax surface, not just a fallback destination.
Use the JS package when you want maximum control over router integration and event timing.
If you are already in React, the React wrapper adds provider and hook ergonomics on top of this runtime.

Install

The JS package is the lowest-level browser entry point and works well when your site or app already owns its own router lifecycle.

Install command

npm install @attriax/js

Example

The snippet below mirrors the app workspace starting point while keeping the guide general instead of project-specific.

src/attriax.ts

Initialize the browser runtime, record page views, wait for the initial deep link, and resolve any URLs your router did not already consume.

1import { Attriax, type AttriaxDeepLinkResolution } from '@attriax/js';
2
3// Keep one SDK instance at module scope.
4const attriax = new Attriax({
5  appToken: 'ax_your_app_token',
6  automaticPageTracking: false,
7});
8
9function openDeepLink(resolution: AttriaxDeepLinkResolution) {
10  // Map the Attriax path to your real router.
11  window.history.pushState({}, '', '/' + resolution.deepLink.path);
12  window.dispatchEvent(new PopStateEvent('popstate'));
13}
14
15async function bootstrapAttriax(): Promise<void> {
16  // Wait for SDK init before bootstrapping routing-sensitive UI.
17  await attriax.init();
18
19  // Emit a manual page view when your router owns page naming.
20  await attriax.recordPageView(window.location.pathname, {
21    pageTitle: document.title,
22    source: 'web_bootstrap',
23  });
24
25  const initialDeepLink = await attriax.deepLinks.waitForInitialDeepLink();
26  const installReferrer = await attriax.installReferrer;
27
28  if (installReferrer) {
29    console.info('Install campaign', installReferrer.campaign);
30  }
31
32  if (initialDeepLink?.resolution) {
33    openDeepLink(initialDeepLink.resolution);
34  }
35
36  // Listen for deep links that resolve after startup.
37  attriax.deepLinks.stream.subscribe((event) => {
38    void (async () => {
39      const result = await event.resolve();
40      if (!result.resolution) {
41        return;
42      }
43
44      openDeepLink(result.resolution);
45    })();
46  });
47
48  // If your router already consumed the URL, report it manually.
49  const manualResolution = await attriax.recordDeepLink({
50    uri: window.location.href,
51    source: 'web_router',
52  });
53
54  if (manualResolution) {
55    openDeepLink(manualResolution);
56  }
57}
58
59void bootstrapAttriax();