Troubleshooting

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

No. ADR 0002 (“mobile-sdk requires the host app to supply a navigatorKey”) describes an old design where 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 ADR is explicitly marked superseded (by ADR 0004), and the current source confirms it: there is no navigatorKey anywhere in apps/flutter-sdk/lib, and apps/flutter-sdk/ARCHITECTURE.md’s “What’s gone” section lists navigatorKey/OneSygnalObserver as removed outright. 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. If you’re integrating against version 0.4.0 or later, 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 (onesygnal_platform_channels.dart). 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.

Local-dev / native dependency issues

This package’s native halves aren’t always resolving from public artifact repositories in every environment: apps/flutter-sdk/ARCHITECTURE.md documents that, absent a real published release, the Android side resolves the native AAR via mavenLocal() and the iOS side compiles apps/ios-sdk’s Swift source directly into the same pod target (copied in by tool/sync-native-source.sh, run from the podspec’s prepare_command). If you’re building this repo locally rather than consuming a released onesygnal package from pub.dev and hit a missing-AAR or stale-native-source build failure, that’s the mechanism to check first — re-run publishToMavenLocal for Android, or pod install (which re-triggers prepare_command) for iOS.