Skip to content

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#

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

Need a full reference implementation? The Showcase StorytellerService._setupEventListeners attaches listeners for every stream below 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. 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 - An object representing the clip category - 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.
});

onPlayerPresented#

The onPlayerPresented stream emits an event when a story or clip player is about to be presented on screen. This can be useful for pausing background audio, videos, or animations in your app while the player is visible.

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. This can be useful for resuming background audio, videos, or animations in your app that were paused when the player was presented.

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. This can be useful for debugging and monitoring SDK behavior.

Type: Stream<String>

Example: 

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

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