The SDK is a singleton — initialize once, import the same orwel instance anywhere. Every method is safe to call after init().
Methods
| Method | Signature | Description |
|---|
init | init(config) | Initialize with your API key + options. Call once, client-side. |
track | track(code, props?) | Record a named event. |
identify | identify(traits?) | Attach identity / traits to the visitor. |
conversion | conversion(code, props?) | Record a conversion / lead. |
session | session(props?) | Update per-session state. Returns { success, sessionId }. |
monitor | monitor(opts?) | Enable performance / error / network monitoring. |
form | form(el, opts?) | Track interactions on a form element. |
experiment | experiment(key, variants) | Assign a sticky A/B variant + auto-fire exposure. |
flush | flush() | Force-send queued events (rarely needed). |
init options
| Option | Type | Description |
|---|
apiKey | string | Workspace ingest key (from env). Required. |
autoMonitor | boolean | JS errors, console errors, failed network requests, and navigation/resource performance timings. |
autoEventDetection | boolean | Auto page_view / click / scroll / element_visible. |
debug | boolean | Verbose console logging (dev only). |
import orwel from 'orwel';
orwel.init({
apiKey: process.env.NEXT_PUBLIC_ORWEL_KEY,
autoMonitor: true,
autoEventDetection: true,
debug: process.env.NODE_ENV !== 'production',
});
Validation
The SDK validates inputs at runtime and throws descriptive errors:
apiKey must start with orwel_ and be ≥ 20 characters.- Event codes match
^[a-z0-9_]{1,50}$.
- Emails inside properties / traits are validated — pass valid addresses or omit the field.
One instance. Never re-initialize. Import orwel from your wrapper module everywhere; the visitor + session are managed for you and persist across reloads.
