API Reference
Flutter is a bridge, not a fourth independent implementation of the OneSygnal
pipeline — every method below is a one-line pass-through from the OneSygnal singleton to
whichever native SDK (Android/iOS) is running underneath, via a single method channel
(onesygnal) and event channel (onesygnal_events). 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.
Source: apps/flutter-sdk/lib/src/onesygnal.dart. 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. EventTracker/ResponseFlusher’s periodic timers are internal to
apps/android-sdk/apps/ios-sdk, with nothing public for a caller to trigger early on
either platform. 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).
Not public
- The
OneSygnalPlatform/OneSygnalChannelsclasses (onesygnal_platform_interface.dart,onesygnal_platform_channels.dart) — an internal seam so tests can substitute a fake platform implementation. Integrators should only ever touch theOneSygnalfacade. - The underlying
MethodChannel('onesygnal')/EventChannel('onesygnal_events')— exposed only as@visibleForTestingfields onOneSygnalChannels, not part of the integrator surface.
See Platform Parity for the full cross-platform operation/event table.