@somar-labs/sdk

Somar SDK for the web

Send your product's events, sessions, errors, and feature-flag reads to your Somar workspace — where they become live analytics pages, AI insights, and automations.

Install

Script tag

<script src="https://trysomar.com/somar.js"></script>
<script>
  somar.somar.init({ apiKey: "somar_pk_…" });
</script>

npm

npm install @somar-labs/sdk

import somar from "@somar-labs/sdk";

somar.init({ apiKey: "somar_pk_…" });

Find your project key in Somar → Settings → Product SDK. The key is a public, ingestion-scoped credential — safe to ship in client code.

Use

somar.capture("signup_completed", { plan: "pro" });   // something happened
somar.identify("user-42", { name: "Ada" });           // who this is
somar.group("company", "acme-inc");                   // their organisation
somar.page();                                          // sent automatically on navigation

if (somar.isEnabled("new-onboarding")) {              // feature flags
  // …
}

somar.captureRevenue(49, { currency: "AUD", plan: "builder" });
somar.register({ app_area: "dashboard" });            // persistent properties
somar.optOut();                                        // honour a privacy request
somar.captureError(err);                               // errors (window errors are automatic)
somar.reset();                                         // on logout

Events batch (20 events / 10 s) and survive page closes via sendBeacon and a localStorage queue. Sessions rotate after 30 minutes of inactivity. The SDK automatically captures privacy-scrubbed page context, attribution, device/browser context, errors, and Core Web Vitals. Enable privacy-safe click/form autocapture explicitly with autocapture: true; it records structural element metadata and data-somar-* attributes, never field values or element text.

Privacy controls

Three switches, in the order they apply:

somar.init({
  apiKey: "somar_pk_…",

  // 1. Redact by property key, anywhere in props/context, case-insensitive.
  mask: ["email", "phone", "token"],

  // 2. Last look at every event. Mutate it, or return null to drop it.
  //    Runs AFTER masking, so masking is a floor a hook can't undo.
  //    If this throws, the event is dropped — a redaction hook that broke
  //    must not fall through to sending unredacted data.
  before_send: (event) => {
    if (event.name === "internal_ping") return null;
    event.props.tenant = currentTenant();
    return event;
  },

  // 3. The SDK swallows every error so it can never break your app.
  //    This is the one channel that reports them.
  debug: import.meta.env.DEV,
});

reset() on logout rotates the anonymous id and clears super properties and cached flags, while keeping the opt-out preference — a privacy choice belongs to the device, not the account that just signed out. Calling identify() with a different user than this device last identified as rotates automatically, so two people sharing a browser are never merged into one person.

The SDK never records field values, element text, IP addresses, or session recordings, and it strips non-attribution query parameters from every URL.

Build

npm install
npm run build     # dist/index.js (ESM), dist/index.cjs, dist/index.global.js (script tag)

Open example/index.html from a local server to test end-to-end.