API Reference
Flutter is a bridge — every method below is a one-line pass-through from the
OneSygnal singleton to whichever native SDK (Android/iOS) is running underneath. Its API
surface is shaped by what the two natives agree on exposing, not by an independent design.
See Platform Parity for how each operation compares across web,
Android, iOS, and this bridge.
Access everything through the OneSygnal() factory constructor (a singleton — repeated
calls return the same instance).
| Method | Signature | Notes |
|---|---|---|
setApiKey | Future<void> setApiKey(String apiKey) | Must be called before initialize(). |
setLocale | Future<void> setLocale(String locale) | Live-reactive — triggers a fresh config/surveys fetch under the new locale if called after initialize(). |
initialize | Future<bool> initialize() | No-op if already initialized. Resolves once native init (config, user, surveys, rules engine) has fully completed, with whether it succeeded. |
track | Future<bool> track(String eventName, {Map<String, dynamic>? properties}) | Returns whether the event was actually recorded (false if not yet initialized, surveys disabled, or rate-limited). |
identify | Future<bool> identify(String userId, {Map<String, dynamic>? attributes}) | Returns whether it succeeded (false if not yet initialized). Resolves only once the native SDK has recorded the call. |
logout | Future<void> logout() | Clears the identified user, reverting to anonymous tracking. |
reset | Future<void> reset() | Mints a new anonymous ID and re-fetches surveys. |
setSurveysEnabled | Future<void> setSurveysEnabled(bool enabled) | Globally suppresses/re-enables survey overlays; doesn’t affect event tracking. |
areSurveysEnabled | Future<bool> areSurveysEnabled() | Reads back the flag above. |
isInitialized | Future<bool> isInitialized() | Reads back whether initialize() has completed. |
shutdown | Future<void> shutdown() | Flushes pending events, tears down native timers/listeners, marks the SDK uninitialized. Resolves once teardown has finished. |
addEventListener | void addEventListener(OneSygnalEventListenerInterface listener) | See Events. |
removeEventListener | void removeEventListener(OneSygnalEventListenerInterface listener) | Removes a listener added via addEventListener. |
Every Future-returning method resolves only once the native work has actually
finished — not just once the call was dispatched across the channel. This applies even to
Future<void> methods (setApiKey/setLocale/logout/reset/shutdown): the native
side answers the channel result from inside its own completion callback, it just doesn’t
surface a value. Practically: await OneSygnal().identify('u1'); OneSygnal().track('purchase')
is guaranteed to evaluate purchase against the identified user, not the outgoing
anonymous one.
flush is absent
Web has a flush() (Future<void>, forces pending events/responses to send
immediately). Flutter does not, and can’t — neither native SDK exposes a manual-flush
hook, so there’s nothing for the bridge to forward.
on/off are not bridged 1:1
Web and the natives both expose per-event on(event, callback)/off(event, callback).
Flutter does not — see Events for the listener-object model
it uses instead (addEventListener/removeEventListener above).
See Platform Parity for the full cross-platform operation/event table.