API Reference
Web ships two distinct API surfaces — see the SDK overview if you
haven’t already. Signatures differ between them, most importantly on init, track,
identify, and logout.
Loader (onesygnal-web-sdk, npm)
| Method | Signature | Notes |
|---|---|---|
init | (apiKey: string, options?) => void | Returns void, not a Promise. Injects the bundle <script> and queues calls until it’s ready. |
track | (eventName: string, properties?) => any | Forwards the bundle’s return value once ready; undefined before that — nothing to forward yet. |
identify | (userId: string, attributes?) => any | Same pre-ready caveat as track. |
logout | () => any | Same pre-ready caveat. |
setSurveysEnabled | (enabled: boolean) => void | Queued if called before ready. |
areSurveysEnabled | () => boolean | undefined | A read, not a write — there’s no future moment to “apply” it against, so a pre-ready call returns undefined rather than being queued. |
isInitialized | () => boolean | false until the bundle is loaded and ready. |
on | (event: string, callback: Function) => any | Returns a Registration once ready, undefined if called before then (the registration doesn’t exist yet to hand back). |
off | (event: string, callback: Function) => void | |
flush | () => any | |
shutdown | () => any |
A pre-ready call is queued and replayed against the bundle once it loads — except reads
(areSurveysEnabled), which have nothing to queue against and answer undefined
immediately. This is the honest answer for “no bundle yet,” not a bug.
CDN bundle (https://repo.1sygnal.app/js/1sygnal.js)
| Method | Signature | Notes |
|---|---|---|
init | (apiKey: string, options?: InitOptions) => Promise<void> | Throws if apiKey is missing. |
track | (eventName: string, properties?) => Promise<void> | Returns Promise<void>, not boolean. |
identify | (userId: string, attributes?) => Promise<void> | |
logout | () => Promise<void> | |
setSurveysEnabled | (enabled: boolean) => void | |
areSurveysEnabled | () => boolean | |
isInitialized | () => boolean | |
on | (event: string, callback: (data) => void) => Registration | Registration.cancel() unsubscribes. |
off | (event: string, callback) => void | Second unsubscribe mechanism — matches by callback reference, first-found. |
flush | () => Promise<void> | Forces pending events/responses to send immediately. Web-only — Android/iOS expose no manual-flush hook (their periodic timers are internal). |
shutdown | () => void | Flushes pending events, tears down timers/listeners, marks uninitialized. |
See Platform Parity for what exists on every platform.