Skip to content

Troubleshooting#

Use this guide to identify the failing step before changing unrelated settings. Start with the Quickstart, then use each feature's reference for exact types and platform differences.

Initialization fails#

Await Storyteller.initialize(...) and inspect success and message. Confirm that the API key belongs to the intended Storyteller tenant and that the device can reach the service. Mount/load Storyteller widgets after success. A MissingPluginException points to a native-plugin build/registration issue: rebuild the supported Android/iOS app after adding plugins, and resolve iOS pods. A Flutter web/desktop target does not contain these native implementations.

Initialization succeeds but a list is empty#

Use onDataLoadComplete(success, error, dataCount) to distinguish an error from a successful zero-item response. Check that the category or collection belongs to the same tenant and that its content is published and currently available. Give row/player widgets a nonzero bounded layout. A controller reload Future is not the network-load result. See List Components, Cards and Embedded Clips for their distinct callback and sizing contracts.

A method or callback behaves differently by platform#

Check the selected package/native version and the platform notes in Additional Methods, Event Streams and Embedded Clips. An exported Dart method or callback does not establish that both native bridges implement it. Observe the documented result/event rather than treating an acknowledged command as proof of a visible native action.

An analytics handler never matches an event#

StorytellerUserActivityEvent.type preserves the native wire name. For example, use openedStory, not storyOpened. Subscribe through the SDK's analytics stream and cancel the subscription when its owner is disposed. Check tracking options, platform delivery and version availability in Analytics. Watch-time event delivery starts in 12.1.2; see the Changelog.

Theme changes are ignored or look different#

Use the exported Dart types and supported mappings in Themes. Check local theme versus global theme, the target surface, platform availability and the current bridge limitations. Native SDK catalogue entries can belong to remote/content configuration or fields the Flutter wrapper does not expose.

Confirm application-level Google Mobile Ads configuration, ad-unit type/ID, module setup before core initialization, and the selected GAM/AdMob facade. These wrappers share the native Google Ads product. VAST registration is independent. Consent-dependent PPID/KVPs, valid inventory and network fill also matter. Use Ads for exact configuration and supported diagnostics; a missing fill alone does not establish an SDK integration failure.

The Showcase is a separate application and its public main can move independently. Compare your installed package version and Changelog, and follow the Showcase README for that app's setup. Share the SDK version, platform, failing step and a minimal reproduction with [email protected] when requesting help.