The UMAP360 Web SDK (@umap360/sdk-web) is a small, dependency-free browser client that batches, retries, and enriches events for you, then sends them to the same POST /v1-batch endpoint you can call directly via the REST API. On top of that endpoint it adds automatic pageview tracking, identity persistence, attribution capture, and privacy controls.

Install

npm

npm install @umap360/sdk-web
# or: yarn add @umap360/sdk-web
# or: pnpm add @umap360/sdk-web

import umap360 from '@umap360/sdk-web';

umap360.init({
  writeKey: 'uk_live_YOUR_WRITE_KEY',
  apiHost: 'https://YOUR_PROJECT_REF.supabase.co/functions/v1',
});

The package ships an ES module, a CommonJS build, and TypeScript types, so the same import works in any modern bundler (Vite, webpack, esbuild, Next.js, …).

CDN (script tag)

If you don't use a bundler, load the pre-built bundle from a CDN. The UMD build exposes the SDK on the global umap360.default:

<script src="https://cdn.jsdelivr.net/npm/@umap360/sdk-web@1/dist/umap360.min.js"></script>
<script>
  // The UMD global is the module namespace — the client is `umap360.default`.
  const umap = window.umap360.default;
  umap.init({
    writeKey: 'uk_live_YOUR_WRITE_KEY',
    apiHost: 'https://YOUR_PROJECT_REF.supabase.co/functions/v1',
  });
</script>

The two required options

init() needs exactly two things; everything else has a sensible default (see the API reference).

Use it in a framework

The SDK is framework-agnostic, but it touches window and document, so initialise it in the browser only — never during server-side rendering. In the Next.js App Router, do that from a Client Component mounted once near the root:

'use client';

import { useEffect } from 'react';
import umap360 from '@umap360/sdk-web';

export function Analytics() {
  useEffect(() => {
    umap360.init({
      writeKey: process.env.NEXT_PUBLIC_UMAP_WRITE_KEY!,
      apiHost: process.env.NEXT_PUBLIC_UMAP_API_HOST!,
    });
  }, []);

  return null;
}

init() is idempotent — a second call is a no-op — so a remount won't double-initialise. In a plain bundler app without SSR (Vite, CRA), there's no SSR guard to worry about — just import umap360 and call init() once in your entry module.

Identify and track from your app

The default export is a shared singleton — import it anywhere and call its methods; no need to thread it through props or context:

'use client';
import umap360 from '@umap360/sdk-web';

export function SignupButton() {
  function onSignup(userId: string, email: string) {
    umap360.identify(userId, { email });          // tie events to the known user
    umap360.track('Signed Up', { plan: 'pro' });  // a custom event
  }
  return <button onClick={() => onSignup('user_456', 'a@example.com')}>Sign up</button>;
}

Call umap360.reset() on logout to start a fresh anonymous identity. To auto-capture link/button clicks without writing handlers, pass trackClicks: true to init() (see the reference).

Verify it's working

With the defaults, the SDK tracks the first pageview automatically. Open Events in the dashboard and you should see a page event within a few seconds. To force a send immediately (for example in a test), await umap360.ready() and then umap360.flush(). If nothing arrives, set debug: true in init() and check the console — a 401 means the write key or apiHost is wrong.

Versioning & upgrading

This page documents @umap360/sdk-web 1.5.1 (the current npm release). Pin a major range — @umap360/sdk-web@^1 (npm) or @1 (CDN) — to get non-breaking updates automatically; a breaking change bumps the major. Release history is on npm.

Next steps

• API reference — every method, every configuration option, and the consent + privacy controls.
• Event ingestion — the wire format each SDK method maps to.
• Guides — identity, attribution, and consent patterns.

Last updated 2026-06-09