Web SDK reference

After following the Web setup tutorial, use these exports in any SPA or SSR project.

Package: @li-nk.me/web-sdk

Installation

npm install @li-nk.me/web-sdk

Exports

`configure(options)`

Initializes the SDK. Call once on the client.

Option	Type	Notes
`appId`	`string`	Required.
`appKey`	`string`	Optional read-only key if your Edge instance enforces auth.
`fetch`	`FetchLike`	Provide a custom `fetch` implementation (e.g. for SSR).
`autoResolve`	`boolean`	Defaults to `true` in browser. Automatically resolves the current URL on load.
`autoListen`	`boolean`	Defaults to `true` in browser. Hooks into `popstate`/`pushState` to fire listeners.
`stripCid`	`boolean`	Defaults to `true`. Strips `cid` query parameter from the URL after resolution.
`sendDeviceInfo`	`boolean`	Defaults to `true`. Includes device metadata in resolution requests.
`resolveUniversalLinks`	`boolean`	Defaults to `true`. Resolves same-origin URLs as universal links.
`debug`	`boolean`	Defaults to `false`. When enabled, the SDK logs URL parsing and deferred-claim requests to the console.

`resolveFromUrl(url?: string)`

Resolves the provided URL (or window.location.href) and returns a LinkMePayload | null.

`handleLink(url: string)`

Resolves a specific URL without stripping the location. Returns LinkMePayload | null.

`onLink(callback)`

Registers a listener for future payloads (history navigation, pushState, manual triggers). Returns { remove: () => void }.

`claimDeferredIfAvailable()`

Attempts to match anonymous visitors to deferred payloads using device fingerprints. Returns LinkMePayload | null.

`track(event, properties?)`

Sends analytics events tied to the current visitor.

`setUserId(userId)`

Associates a user identifier with subsequent events.

`getLastPayload()`

Returns the most recently resolved LinkMePayload, or null.

`extractCidFromUrl(url: string)`

Extracts a cid parameter from a URL string. Returns string | null.

Payload shape

type LinkMePayload = {
  linkId?: string;
  path?: string;
  params?: Record<string, string>;
  utm?: Record<string, string>;
  custom?: Record<string, string>;
  url?: string;
  isLinkMe?: boolean;
  cid?: string;
  duplicate?: boolean;
};

Advanced: class API

For dependency injection or testing, use LinkMeController or LinkMeWebClient directly:

import { LinkMeWebClient } from '@li-nk.me/web-sdk';

const client = new LinkMeWebClient();
await client.configure({ appId: 'app_123' });
const payload = await client.resolveFromUrl();

LinkMeWebClient extends LinkMeController and exposes the same methods as the top-level functions. You can also provide custom environment and httpClientFactory via LinkMeControllerDeps.

Additional exports: BrowserEnvironment, LinkMeEnvironment (interface), LinkMeControllerDeps, LinkListener, FetchLike.

Example

import { configure, resolveFromUrl, onLink } from '@li-nk.me/web-sdk';

await configure({
  appId: process.env.NEXT_PUBLIC_LINKME_APP_ID!,
});

const initial = await resolveFromUrl();
if (initial?.path) {
  router.replace(initial.path);
}

const sub = onLink((payload) => {
  if (payload?.path) router.replace(payload.path);
});

// Later
sub.remove();