SDK Reference

Every method and init option of the Orwel JavaScript SDK (1.7.1).

View as Markdown Open in Claude Open in ChatGPT

The SDK is a singleton: initialize once, then import the same orwel instance anywhere (import orwel from 'orwel' or import { orwel } from 'orwel'). On the server (no window) every method is a no-op, so imports are safe in SSR code.

Methods

Method	Returns	Description
`init(config)`	`void`	Configure the SDK with your key and options. Call once, in the browser. Throws on an invalid config.
`track(code, props?)`	`{ success, eventId }`	Queue a named event. The code must be in the workspace catalog.
`identify(traits?)`	`{ success, visitorId }`	Attach identity and traits to the visitor.
`conversion(code, props?)`	`Promise<{ success, reason? }>`	Record a conversion. Waits for the visitor id, adds a `conversionId` and attribution, sends immediately, and resolves with the acknowledged result. `reason` is `visitor_unresolved`, `delivery_failed` or `error`.
`session(props?, final?)`	`{ success, sessionId }`	Merge custom properties into the current session.
`monitor(opts?)`	`{ success }`	Start error, console, network and performance monitoring.
`form(el, opts?)`	`{ success, error? }`	Observe a form element.
`flush()`	`Promise<{ success, count }>`	Send the queue now, in batches of up to 100. Rarely needed.

`init` options

Option	Type	Default	Description
`apiKey`	`string`		Production API key (`orwel_pk_...`) or development key (`orwel_dev_...`). Required. Read it from an environment variable.
`autoMonitor`	`boolean`	`false`	Same as calling `monitor()`: JS errors, console errors, network requests and navigation and resource timings.
`autoEventDetection`	`boolean`	`true`	Automatic `page_view`, `click`, `scroll`, `element_visible` and other catalog events. Pass `false` to turn it off.
`eventDetectionOptions`	`object`		`enabledCategories` (for example `['navigation', 'form', 'ecommerce']`) and `confidenceThreshold` (0 to 1).
`debug`	`boolean`	`false`	SDK logs in the browser console.
`verbose`	`boolean`	`false`	More detailed logs.

typescript

import orwel from 'orwel';

orwel.init({
  apiKey: process.env.NEXT_PUBLIC_ORWEL_KEY,
  autoMonitor: true,
  debug: process.env.NODE_ENV !== 'production',
});

`monitor` options

All default to true when you call monitor() with no options.

Option	Description
`errors`	JS errors and unhandled promise rejections.
`console`	Console errors and warnings.
`network`	Fetch and XHR requests (URL, method, status, duration).
`performance`	Navigation and resource timings.

`form` options

Option	Description
`formId`	Identifier for the form (generated if omitted).
`trackFocus`, `trackInput`, `trackChange`	Field level interaction events.
`trackSubmit`	`form_submit_attempt`, `form_submit_success`, `form_submit_error`.
`trackAbandon`	`form_abandon` when the visitor leaves without submitting.
`submitCallback`	Called with `{ success, error? }` after a submit attempt.

Validation

The SDK validates inputs at runtime and throws descriptive errors:

apiKey must start with orwel_ and be at least 20 characters.
config, traits and properties must be objects.
Event codes match ^[a-z0-9_]+$ and are at most 50 characters.
Emails inside properties and traits must be valid addresses. Pass a valid one or omit the field.

Storage

Key	Storage	Content
`__orwel_visitor__`	`localStorage`	Visitor id and traits.
`__orwel_session__`	`localStorage`	Current session.
`__orwel_queue__`	`localStorage`	Events waiting to be sent (up to 1000).
`__orwel_attribution`	`localStorage`	First and last touch UTMs and click ids.
`__orwel_utm`, `__orwel_click_ids`	`sessionStorage`	UTMs and click ids of the current session.

One instance. Never re-initialize. Import orwel from your wrapper module everywhere; the visitor and session are managed for you and persist across reloads.