Web SDK reference

The Origamy Web SDK ships in two parts, following the Segment/RudderStack pattern: a tiny snippet you paste into <head> that stubs the API and queues calls, and the full engine (analytics.min.js, ~25 KB gzipped) the snippet loads asynchronously from https://cdn.origamy.io. Your page never blocks on analytics.

The API is Segment-compatible: if you have existing analytics.track(...) instrumentation, the call signatures carry over unchanged.

Installation

Paste the snippet from the Quickstart into your <head>. Calls made before the engine arrives are queued and replayed in order.

`load(writeKey, config?)`

Initializes the SDK. Must be called before events are delivered; calls made earlier are queued.

await origamy.load("YOUR_WRITE_KEY", {
  apiHost: "https://events.origamy.io", // where events are delivered
  cdnHost: "https://cdn.origamy.io",    // where plugin bundles load from
  flushInterval: 10000,                 // ms between automatic flushes
  maxQueueSize: 20,                     // events per batch before an early flush
  retryLimit: 3,                        // delivery attempts per batch
  debug: false,                         // verbose console logging
  autoTrack: {
    clicks: { enabled: true },          // see Auto-tracking below
    pages: { enabled: true },
  },
});

Option	Default	Description
`apiHost`	`https://events.origamy.io`	Ingestion endpoint. Point this at your own gateway on a self-hosted (BYOD) data plane.
`cdnHost`	`https://cdn.origamy.io`	Host device-mode plugin bundles are loaded from.
`flushInterval`	`10000`	How often (ms) the queue flushes to `/v1/batch`.
`maxQueueSize`	`20`	Queue flushes early once it holds this many events.
`retryLimit`	`3`	Failed batches retry with exponential backoff up to this many attempts.
`debug`	`false`	Logs every event, flush, and retry to the console.
`autoTrack`	off	Opt-in automatic `page` and click tracking.

Event methods

All five methods share the same optional last argument, options:

{
  context?: object,      // merged into the event's context
  timestamp?: string,    // ISO-8601 override (for late/imported events)
  anonymousId?: string,  // override the stored anonymous ID
  integrations?: { [destination: string]: boolean }, // per-event routing
}

See the Event spec for what each event looks like on the wire.

`track(eventName, properties?, options?)`

Records an action the user performed. Name events in Object Action title case ("Order Completed", not "order-completed") — downstream destinations expect it.

origamy.track("Order Completed", {
  orderId: "12345",
  amount: 99.99,
  currency: "USD",
}, {
  integrations: { GoogleAnalytics: false }, // skip GA for this event
});

`identify(userId?, traits?, options?)`

Ties the current visitor to a known user and records traits. Traits persist locally and merge across calls. Calling identify with no userId updates traits on the current identity.

origamy.identify("user_123", {
  email: "ada@example.com",
  name: "Ada Lovelace",
  plan: "premium",
});

`page(name?, properties?, options?)`

Records a page view. The SDK fills in url, path, title, referrer, and search automatically; anything you pass is merged on top.

origamy.page("Pricing", { experiment: "pricing-v2" });

`group(groupId, traits?, options?)`

Associates the current user with an account, company, or team.

origamy.group("company_456", {
  name: "Acme Corp",
  plan: "enterprise",
  employees: 100,
});

`alias(userId, previousId?, options?)`

Links two identities — typically the pre-signup anonymous ID to the new user ID — so identity resolution can merge their history. previousId defaults to the stored anonymous ID.

origamy.alias("user_123");

Auto-tracking

Both surfaces are off by default and opt-in via load() config.

Clicks

Emits an Element Clicked track event when the user clicks an element carrying a data-origamy-event attribute (or a custom selector). Deliberately not track-everything — opt-in per element keeps your event stream high-signal.

origamy.load("KEY", { autoTrack: { clicks: { enabled: true } } });

<button data-origamy-event="Upgrade Clicked">Upgrade</button>

Option	Default	Description
`enabled`	`false`	Turn click auto-tracking on.
`selector`	`[data-origamy-event]`	CSS selector matched against the click target and its ancestors.

Pages

Auto-fires page() on initial load, back/forward navigation, and SPA route changes (history.pushState/replaceState are patched and restored on destroy()).

Option	Default	Description
`enabled`	`false`	Turn page auto-tracking on.
`skipInitial`	`false`	Skip the auto event on first load if you call `page()` explicitly at boot.

Middleware — `use(fn)`

Middleware runs on every event before delivery. Return the (possibly modified) event, or null to drop it. Async middleware is supported.

// Enrich every event
origamy.use((event) => {
  event.context.appVersion = "1.2.3";
  return event;
});

// Drop internal traffic
origamy.use((event) => {
  if (event.type === "track" && event.event.startsWith("Internal ")) return null;
  return event;
});

Plugins (device-mode destinations)

Plugins load a destination’s native script in the browser and forward events to it directly. Which plugins load is controlled by your source’s destination configuration in the Origamy dashboard, fetched from /v1/config at load time.

Built-in plugins: Google Analytics and Mixpanel.

origamy.registerPlugin("CustomDestination", () => ({
  name: "CustomDestination",
  initialize(config) {
    // load vendor script, init client
  },
  track(event) {
    // forward the event
  },
  identify(event) {},
}));

Use the per-event integrations option to skip a destination for a single event.

Delivery, batching, and retries

Events queue in memory and flush to POST /v1/batch every flushInterval ms, or earlier once maxQueueSize events accumulate.
Failed batches retry with exponential backoff, up to retryLimit attempts.
On page unload, the SDK drains the queue with navigator.sendBeacon (falling back to a synchronous XHR) so trailing events aren’t lost.
Requests authenticate with your write key — see Ingestion API.

Utility methods

Method	Description
`ready(callback)`	Runs the callback once the SDK is loaded (immediately if it already is).
`reset()`	Clears the stored user ID, traits, and anonymous ID — call on logout.
`getAnonymousId()`	Returns the current anonymous ID.
`getUserId()`	Returns the identified user ID, or `null`.
`isLoaded()`	`true` once `load()` has completed.
`arePluginsLoaded()`	`true` once device-mode plugins have initialized.
`destroy()`	Tears down timers, listeners, and history patches. Mostly useful in tests and SPAs that hot-swap the SDK.

Browser support

Modern evergreen browsers (Chrome, Firefox, Safari 11+, Edge). The SDK has zero runtime dependencies, uses no eval, and is CSP-compatible.