Skip to content

Additional Methods#

The Storyteller class exposes a broad set of utilities on top of the primary widgets. This page highlights the most popular calls grouped by scenario. All methods live in package:storyteller_sdk/storyteller_sdk.dart.

Initialize successfully before calling these methods. Use Getting Started for setup and Troubleshooting for loading or channel failures.

Installation examples use Flutter 12.2.0 (Android 12.2.0 / iOS 11.9.1). The ad-placement defaults, provider ordering and Clips-count comparisons below were audited against an earlier 12.1.2 development snapshot (Android 12.1.2 / iOS 11.8.0) and published 11.6.5 (Android 11.6.4 / iOS 11.6.1). Those audit versions are distinct from the released native dependency pins; check Changelog for your release.

Player status & control#

  • Future<bool> Storyteller.isInitialized() – check whether the native SDK has finished initialising.
  • Future<bool> Storyteller.isPlayerVisible() / isPresentingContent() – aliases that report whether Storyteller content is currently presented on either platform.
  • Future<bool> Storyteller.isPlayerMuted() – reads the current player mute state on iOS. Android throws a PlatformException with code UNSUPPORTED_PLATFORM because its native SDK has no public getter.
  • Future<void> Storyteller.mute() / unmute() – mute or unmute Story and Clip audio without pausing or resuming playback, on Android and iOS. Call after initialisation; with no player open, the choice applies to the next Story or Clip. Both throw a PlatformException with code AUDIO_CONTROL_ERROR before initialisation.
  • Future<void> Storyteller.dismissPlayer({bool animated = true, String? dismissReason}) – close the player programmatically. iOS applies animated and dismissReason; Android currently ignores both arguments.
  • Future<void> Storyteller.resumePlayer() – resume playback after dismissing your custom share UI. This is not a general-purpose pause/resume lifecycle API; use the Embedded Clips controller for inline playback.
  • Future<void> Storyteller.setUseCustomShareHandling(bool enabled) – let your app handle Storyteller share button taps instead of the native share sheet.
  • Future<void> Storyteller.openStory(String id, {StorytellerOpenReason? openReason}) – open a specific story by Storyteller identifier.
  • Future<void> Storyteller.openStoryByExternalId(String externalId, {StorytellerOpenReason? openReason}) – open a story using the external identifier you provided to Storyteller.
  • Future<void> Storyteller.openPage(String id, {StorytellerOpenReason? openReason}) / openSheet(String id) – open a particular page or sheet on iOS. Android opens pages but its current Flutter openSheet handler performs no action.
  • Future<void> Storyteller.openCategory(String category, {StorytellerOpenReason? openReason}) – launch the player scoped to a Storyteller category.
  • Future<void> Storyteller.openCollection(String id, {String? clipId, StorytellerTheme? theme, StorytellerOpenReason? openReason, StorytellerClipsAdConfiguration? adConfiguration, String? requestId}) – present a collection, optionally jump to a clip, and override ad-placement controls for that presentation.
  • Future<void> Storyteller.openCollectionWithCategory(String id, {String? category, StorytellerTheme? theme, StorytellerOpenReason? openReason, StorytellerClipsAdConfiguration? adConfiguration, String? requestId}) – apply an additional category filter when opening a collection.
  • Future<void> Storyteller.openClipByExternalId(String collectionId, String externalId, {StorytellerOpenReason? openReason, String? requestId}) – target a clip referenced by your external identifier within a collection. openCollectionByExternalId(...) is an equivalent Android-native naming alias.
  • Future<void> Storyteller.openSearch() and Future<bool> Storyteller.isSearchEnabled() – launch Storyteller search when the native configuration allows it.

StorytellerOpenReason.instanceMethod and StorytellerOpenReason.deeplink let you explicitly attribute a direct open. Omit openReason to preserve the default of the native entry point. For Clips collection opens, that omitted default is deeplink on Android and instanceMethod on iOS. Android's external-ID collection API always uses its native deep-link reason, so passing instanceMethod to either external-ID Clips alias throws UNSUPPORTED_ARGUMENT on Android.

StorytellerClipsAdConfiguration has nullable preRollEnabled, bottomBannerEnabled, betweenClipsAdProviderOrder, frequency, initialIndex, and bottomBannerFetchMode fields. Omit the entire object, or an individual field, to keep the linked native SDK's default for that platform and presentation type. Pre-roll is supported on Android and iOS; Android defaults it on and iOS defaults it off in both compared baselines. Provider ordering is Android-only: null preserves native module order, an empty list disables standard providers, and a populated list restricts and orders VAST, GAM, and AdMob. iOS ignores provider ordering. Also Android-only: a positive frequency and a non-negative initialIndex override the remote between-Clips cadence for that presentation (initialIndex 0 is the opening-ad position; positive values are one-based content positions), and bottomBannerFetchMode selects justInTime (the native default) or prefetch, which prepares the next Clip's bottom banner while the current Clip plays. iOS ignores these three fields. The theme argument on openCollection and openCollectionWithCategory is applied on iOS; the current Android bridge ignores it, so use a global theme for Android.

For 11.6.5 and 12.1.2 at the native versions above, the effective defaults are:

Presentation Android 11.6.4 / 12.1.2 pre-roll / bottom banner iOS 11.6.1 / 11.8.0 pre-roll / bottom banner
Direct Clips collection open true / true false / false
Embedded Clips true / false false / false
Player opened from Clips list true / true Flutter list ad configuration ignored

The Dart ad configuration fields default to null; those are bridge omissions, not false values.

Clips open calls generate a request ID when one is not supplied. Invalid arguments and native failures that complete the call reject its Future. Android can additionally report callback-style failures through Storyteller.onClipsOpenError, potentially after the Future completes, so subscribe before opening when those events matter. Correlate stream events using StorytellerOpenError.requestId; each event exposes only the request ID, operation, and allowlisted error code.

For an explicit per-presentation override after initialization:

await Storyteller.openCollection(
  'YOUR_COLLECTION_ID',
  adConfiguration: const StorytellerClipsAdConfiguration(
    preRollEnabled: true,
    bottomBannerEnabled: true,
    betweenClipsAdProviderOrder: [StorytellerAdProvider.gam],
  ),
);

Placement flags allow eligible ads; an enabled flag does not register a provider or guarantee ad fill. See Ads for module registration and provider selection.

  • Future<bool> Storyteller.isStorytellerDeeplink(String url) / isStorytellerDeepLink(String url) – equivalent spelling aliases that detect whether a URL should be handled by Storyteller.
  • Future<void> Storyteller.openDeeplink(String url) / openDeepLink(String url) – equivalent spelling aliases that forward Storyteller URLs to the native SDK.
  • Stream<String> Storyteller.userNavigatedToApp – emits URLs when a user taps a Storyteller deep link that should be handled by your Flutter router.

See Deep Linking for end-to-end integration guidance.

SDK diagnostics#

  • Future<String> Storyteller.version() – read the linked native SDK version, which may differ between Android and iOS and from the Flutter package version.
  • Future<String> Storyteller.currentApiKey() – read the current native API key. Keep this value out of logs and analytics.

Analytics & counts#

  • Stream<StorytellerUserActivityEvent> Storyteller.onUserActivityOccurred – receive detailed interaction payloads for analytics use-cases.
  • Stream<StorytellerShareEvent> Storyteller.onShareButtonTapped – receive share button payloads after enabling custom share handling.
  • Future<int> Storyteller.getStoriesCount(List<String> categoryIds) – fetch the number of stories for the supplied categories.
  • Future<int> Storyteller.getClipsCount(String collectionId) – fetch a Clips count using the source-compatible helper. iOS treats the value as a collection ID; Android treats it as a single category ID in both compared baselines.
  • Future<int> Storyteller.getClipsCountForCategories(List<String> categoryIds) – fetch a Clips count for categories on Android. iOS throws UNSUPPORTED_PLATFORM.
  • Future<String?> Storyteller.preloadClips(String collectionId, {List<String> clipIds = const [], bool preloadVideos = false}) – begin Android Clips preloading and return an opaque cancellation handle. iOS returns null because it has no public native preloader.
  • Future<void> Storyteller.cancelPreloadClips(String handle) – cancel and release an Android preload handle. It is a no-op on iOS.
  • Future<StorytellerEventTrackingOptions> Storyteller.eventTrackingOptions() – inspect the current tracking configuration.
  • Stream<String> Storyteller.onLog – subscribe to iOS native SDK log output. Android exposes the stream but the current bridge does not emit messages; inspect Android native logs when debugging.

Categories & following#

  • Future<void> Storyteller.addFollowedCategory(String category) / addFollowedCategories(List<String>) – mark categories as followed for the current user.
  • Future<void> Storyteller.removeFollowedCategory(String category) / removeFollowedCategories(List<String>) – remove one or more followed categories.
  • Future<void> Storyteller.setFollowedCategories(List<String> categories) – replace the followed-category set and await native category resolution. Unknown IDs are omitted from the resolved subset; a request failure throws and preserves the previous native state.
  • Future<List<String>> Storyteller.followedCategories() – read the current list, typically to sync with your own profile service.
  • Future<bool> Storyteller.isCategoryFollowed(String categoryId) – convenience helper for toggles.
  • Future<StorytellerFollowableCategories> Storyteller.getFollowableCategories() – fetch a flat categories list of StorytellerFollowableCategory values, including isFollowed and optional placement metadata.
  • Stream<CategoryFollowEvent> Storyteller.categoryFollowActionTaken – observe follow/unfollow events triggered from Storyteller UI.

Appearance & localisation#

  • Future<void> Storyteller.setTheme(StorytellerTheme theme) – override colours and typography for any subsequent Storyteller UI. Build the theme map using StorytellerTheme helpers or JSON.
  • Future<void> Storyteller.setLocale(String? locale) – override the language using an ISO language code (e.g. "en") or pass null to clear the override and return locale selection to the native SDK.

Each method returns a Future that completes when the native method channel responds. For presentation and reload methods, this does not guarantee content is visible or loading has completed. The add/remove follow methods start native asynchronous work; setFollowedCategories awaits resolution. Follow mutations require tenant configuration for app-managed following. See Working with Users. Wrap your invocations in try/catch blocks to surface platform exceptions gracefully.