Browser SDK

The Inslytic Browser SDK (@inslytic/sdk-browser) is a lightweight tracking library for web applications. At 2.5KB gzipped, it adds zero meaningful overhead to your bundle.

Installation

npm install @inslytic/sdk-browser

init(config)

Initializes the SDK. Must be called once before any other method. Calling init() multiple times is safe — subsequent calls are ignored.

import { init } from "@inslytic/sdk-browser";

init({
  apiKey: "your-api-key",
  endpoint: "https://api.inslytic.com", // optional
  flushInterval: 5000,                 // optional, ms
  maxBatchSize: 20,                    // optional
});

Parameter	Type	Required	Description
apiKey	string	Required	Your project API key from the dashboard settings.
endpoint	string	Optional	Ingestion API URL. Defaults to "https://api.inslytic.com".
flushInterval	number	Optional	How often to flush the event queue in ms. Default: 5000.
maxBatchSize	number	Optional	Max events per batch. Default: 20.
debug	boolean	Optional	Enable debug logging. Default: false.
autoPageTracking	boolean	Optional	Automatically track page views on navigation. Default: true.

track(eventName, options?)

Tracks a custom event with optional properties. No-op if init() hasn't been called.

import { track } from "@inslytic/sdk-browser";

track("button_clicked", {
  properties: {
    button: "signup",
    location: "header",
  },
});

Parameter	Type	Required	Description
eventName	string	Required	Name of the event to track.
options.properties	Record<string, string>	Optional	Key-value pairs attached to the event.

page(properties?)

Tracks a $pageview event. Automatically captures URL, title, referrer, and UTM parameters. Page views are tracked automatically by default — the SDK detects SPA navigations via history.pushState, history.replaceState, and popstate. Use this method only if you need to track additional pageviews manually or pass custom properties.

import { page } from "@inslytic/sdk-browser";

// Manual pageview with custom properties
page({ section: "blog" });

identify(userId, traits?)

Links the current anonymous session to a known user. Sends a $identify event. Call this after the user logs in.

import { identify } from "@inslytic/sdk-browser";

identify("user-123");

Parameter	Type	Required	Description
userId	string	Required	Unique identifier for the user.
traits	Record<string, string>	Optional	User traits (reserved for future use).

setConsent(granted)

Controls the consentGiven flag on all subsequent events. Use this to integrate with your cookie consent banner.

import { setConsent } from "@inslytic/sdk-browser";

// User accepts cookies
setConsent(true);

// User declines
setConsent(false);

reset()

Clears all state: user ID, anonymous ID, session, and event queue. You must call init() again after reset() to resume tracking. Use this on logout.

import { reset, init } from "@inslytic/sdk-browser";

// On logout
reset();

// To resume tracking (e.g., after new login)
init({ apiKey: "your-api-key" });

Auto-captured data

Every event automatically includes:

Page context — URL, title, referrer
UTM parameters — source, medium, campaign (from URL query params)
Device info — device type (desktop/mobile/tablet), browser, OS
Session — anonymous ID (localStorage), session ID (sessionStorage, 30-min timeout)
Timestamp — ISO 8601 UTC

Batching & offline resilience

Events are queued and flushed automatically every 5 seconds or when the batch reaches 20 events (both configurable). If the network is unavailable, events stay in the queue and are retried on the next flush.