Troubleshooting

I found a navigatorKey requirement in older material — do I still need it?

No. Older versions of this package inserted survey OverlayEntrys into the host app’s OverlayState, which is only reachable through a Navigator — so the host app had to hand the SDK a GlobalKey<NavigatorState> (OneSygnal().navigatorKey = ...) or surveys would silently never appear.

That requirement has been removed. Surveys now render as a native, OS-level window overlay, which doesn’t touch the Flutter widget tree at all — there’s nothing to wire up. Ignore any navigatorKey setup steps you find in older docs or blog posts.

initialize() is slow / my UI looks hung

initialize()’s Future<bool> only resolves once native init has fully finished — config fetched, user ensured, surveys fetched, rules engine loaded. On a poor network this is bounded by the native HTTP timeouts (Android: 10s connect / 15s read; iOS: 15s request / 30s resource) times up to four sequential calls, so it can take tens of seconds in the worst case. Don’t block your UI on await initialize() — show an “Initializing…” state and let it resolve in the background, or use the ready event (Events) if you don’t need the returned bool.

track()/identify() returned false

Both are documented to return false rather than throwing when the call can’t be recorded: track() if the SDK isn’t initialized yet, surveys are disabled, or the call is rate-limited; identify() if the SDK isn’t initialized yet. Check await OneSygnal().isInitialized() if you’re unsure whether initialize() has actually completed before you call either.

A native-side error surfaced as a PlatformException

The bridge does no error handling of its own — every method is a direct methodChannel.invokeMethod(...) call with no try/catch around it. If the native Android/iOS SDK throws internally, it propagates to Dart as a normal PlatformException, uncaught. Wrap calls in your own try/catch if you need to handle that instead of letting it bubble up.

Events aren’t arriving

• Confirm you called addEventListener — you can do this before initialize(), since subscribing just attaches to the event stream and doesn’t require the SDK to be running yet. Events won’t start arriving until initialize() completes.
• Confirm you’re checking the right callback field. There’s no generic on('survey:shown', ...) on Flutter — see Events for the five-callback listener object shape.
• survey:step doesn’t exist on Flutter. If you ported analytics-forwarding code from web, the closest equivalent is onQuestionAnswered (survey:question_answered), which has no step index in its payload.