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.

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.dismissPlayer({bool animated = true, String? dismissReason}) – close the player programmatically.
  • Future<void> Storyteller.resumePlayer() – resume playback after your app temporarily paused it.
  • 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.
  • 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, and betweenClipsAdProviderOrder 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 11.6.3 defaults it on and iOS 11.6.1 defaults it off. 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.

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.

  • 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.

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's native 11.6.3 API treats it as a single category ID.
  • 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 native SDK log output (useful while 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 followable category metadata grouped by the native SDK.
  • 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) – force the locale (e.g. "en-US") or pass null to clear the override and return locale selection to the native SDK.

Each call returns a Future that completes when the native method channel responds. Wrap your invocations in try/catch blocks to surface platform exceptions gracefully.