Implementing Storyteller Delegate Callbacks

The Flutter SDK uses Dart Streams to deliver Storyteller events to your app. You subscribe to event streams provided by the Storyteller class to handle events throughout your app. This stream-based approach replaces the delegate pattern used in native iOS and Android SDKs.

Available Event Streams

Subscribe before the interaction you need to observe and keep each StreamSubscription so you can cancel it when its owner is disposed. These broadcast streams deliver live events; do not use them as a history or initialization-success signal.

You can subscribe to the following optional event streams to handle Storyteller events:

Need a full reference implementation? The Showcase StorytellerService._setupEventListeners demonstrates subscription and routing patterns and forwards the payloads to its router/logging hooks.

onUserActivityOccurred

The onUserActivityOccurred stream emits events when analytics events are triggered within the SDK. This allows your app to observe and potentially forward these events to your own analytics systems. Delivery depends on enableUserActivityTracking, ad tracking gates and metadata-redaction choices. Native sdkInitialized is internal and is not delivered on this stream. See the Analytics page for details on event types and data.

Type: Stream<StorytellerUserActivityEvent>

Example:

Storyteller.onUserActivityOccurred.listen((event) {
  print('Activity: ${event.type}');
  print('Data: ${event.data}');
  // Forward to your analytics system
});

userNavigatedToApp

The userNavigatedToApp stream emits URLs when a user presses an action button on a page which should direct them to a specific place within your app.

Type: Stream<String>

Example:

Storyteller.userNavigatedToApp.listen((url) {
  print('Navigate to: $url');
  // Handle navigation using your app's routing system
  // Example: Navigator.pushNamed(context, url);
});

See Deep Linking for deep link handling patterns and how to route these URLs.

categoryFollowActionTaken

The categoryFollowActionTaken stream emits events when a user follows or unfollows a category of clips (the category can represent a player, a team, etc.) from within the SDK's UI.

Type: Stream<CategoryFollowEvent>

The CategoryFollowEvent contains: - category - A StorytellerCategory containing externalId, type, optional placement, name, and displayTitle - isFollowing - A boolean value indicating whether the user is following or unfollowing the specified category

Example:

Storyteller.categoryFollowActionTaken.listen((event) {
  print('Category ${event.category.name} followed: ${event.isFollowing}');

  if (event.isFollowing) {
    // Add the category to your list of followed categories
  } else {
    // Remove the category from your list of followed categories
  }
});

onShareButtonTapped

The onShareButtonTapped stream emits share payloads when custom share handling is enabled. Call Storyteller.setUseCustomShareHandling(true) before presenting Storyteller content, then show your own share UI when the stream emits.

Type: Stream<StorytellerShareEvent>

The StorytellerShareEvent contains: - text - The share text generated by Storyteller - title - The share title, or an empty string when Storyteller provides none - url - The share URL, or an empty string when Storyteller provides none

Example:

await Storyteller.setUseCustomShareHandling(true);

Storyteller.onShareButtonTapped.listen((event) {
  print('Share title: ${event.title}');
  print('Share url: ${event.url}');
  // Present your own share flow, then call Storyteller.resumePlayer().
});

onPlayerPresented

The onPlayerPresented stream emits an event when a story or clip player is about to be presented on screen. On iOS, this can be useful for pausing background media. The current Android Flutter bridge exposes the stream but does not emit presentation events; use list onTileTapped callbacks for list-triggered opens and Storyteller.isPlayerVisible() when you need to query visibility.

Type: Stream<void>

Example:

Storyteller.onPlayerPresented.listen((_) {
  print('Player is being presented');
  // Pause your app's media playback
});

onPlayerDismissed

The onPlayerDismissed stream emits an event when a story or clip player has been dismissed from screen. iOS emits this global event. The current Android Flutter bridge does not emit it; its Stories/Clips list widgets still expose onPlayerDismissed callbacks. Use those callbacks for list-owned playback and query Storyteller.isPlayerVisible() for visibility.

Type: Stream<void>

Example:

Storyteller.onPlayerDismissed.listen((_) {
  print('Player was dismissed');
  // Resume your app's media playback
  // audioPlayer.resume();
});

onLog

The onLog stream emits debug log messages from the Storyteller SDK. iOS emits these messages. The current Android Flutter bridge exposes this stream but does not emit messages; inspect native Android logs instead.

Type: Stream<String>

Example:

Storyteller.onLog.listen((message) {
  print('Storyteller SDK Log: $message');
  // Forward to your logging system
});

onClipsOpenError

Stream<StorytellerOpenError> reports sanitized programmatic Clips-open failures. Subscribe before calling openCollection, openCollectionWithCategory, or openClipByExternalId; supply a requestId when correlation matters. The event contains requestId, operation (collection, collectionWithCategory, clipByExternalId, or unknown), and code (contentNotFound, clipNotFound, network, or unknown). It contains no raw error message. Catch the open call's Future failures as well: Android callback-style errors can arrive after that Future completes. See Additional Methods.

StorytellerListView Delegate

For handling events specific to StorytellerStoriesRowView and StorytellerStoriesGridView widgets, please refer to the StorytellerListViews documentation for details on widget-specific callbacks like: - onDataLoadStarted - onDataLoadComplete - onTileTapped - onPlayerDismissed

For callbacks that do not arrive, check platform availability above and the Troubleshooting guide. Analytics delivery also depends on Privacy and Tracking.