Skip to content

Changelog#

12.2.0 - 05/11/2026#

Native SDKs#

  • Updated the iOS Storyteller SDK, GAM integration and VAST integration dependencies to 11.9.1 in all four packages. Android stays on 12.2.0. See the iOS 11.9.1 changelog for the native changes.
  • iOS 11.9.1 changes these events and methods in Flutter apps:
  • Story bufferingStarted and bufferingEnded events report timeSinceBufferingBegan in milliseconds instead of seconds, as on Android. isInitialBuffering is true only for buffering before a Page's video starts playing.
  • readyToPlay, mediaStarted and buffering events also fire for Clips. Check clipId and storyId to tell Clip events from Story events. finishedClip is recorded once, when the user leaves the Clip.
  • openDeeplink records a new openedDeepLink event. openDeeplink and isStorytellerDeeplink also recognise Storyteller share links on your own share domain.
  • dismissPlayer passes its dismissReason to the Story Player, which reported swipedDown before.
  • setLocale accepts a language with a region, such as pt-BR; before, only a language code such as pt was applied.
  • Clips can show a timestamp when Storyteller supplies one. The existing showTimestamp theme setting controls it, as it does for Stories.

New Features#

  • StorytellerGAMModuleConfiguration has a new requestCustomKvps callback that receives the StorytellerAdRequestInfo of each GAM ad request, so custom KVPs can depend on the Clips collection or Stories list an ad is shown with. Storyteller calls it for every GAM request, including ads it loads ahead of time, and it can complete asynchronously. On iOS the GAM plugin no longer blocks while it waits for Dart targeting. See Configure the GAM module.

Bug Fixes#

  • Fixed an iOS crash on the first AdMob ad request when the app links Google Mobile Ads SDK 13.4.0 or later. Google Mobile Ads 13.4.0–13.11.0 ship an outdated Swift runtime helper that, when Flutter links the plugins statically, could return an invalid type pointer to the AdMob plugin. The GAM and VAST plugins now avoid the same code pattern on iOS.

12.1.2 - 30/10/2026#

Native SDKs#

  • Updated the Flutter core SDK dependencies to Android Storyteller 12.2.0 and iOS Storyteller 11.9.0.
  • Moved Android to the Storyteller 12.x release line. Android apps now need Kotlin 2.1 or later, compileSdk 35 or later and Android Gradle Plugin 8.6.0 or later; the native SDK brings Jetpack Compose 1.11.4 (BOM 2026.06.01). The minimum Android API level stays 24.
  • Updated the Flutter GAM and AdMob SDK dependencies to Android core and GAM v24 12.2.0, and iOS Storyteller SDK and GAM integration 11.9.0.
  • Updated the Flutter VAST SDK dependencies to Android core and VAST 12.2.0, and iOS core and VAST integration 11.9.0.
  • See the Android 12.0.0–12.2.0 changelogs, which include the shared 11.7.0–11.8.1 changes, and the iOS 11.7.0–11.9.0 changelogs for the complete list of native changes included in this release.

New Features#

  • Added Storyteller.mute() and unmute() to control Story and Clip audio without pausing or resuming playback on Android and iOS.
  • Added Android frequency, initialIndex, and bottomBannerFetchMode fields to StorytellerClipsAdConfiguration, plus the StorytellerBottomBannerFetchMode enum, to override remote between-Clips cadence and opt in to next-Clip bottom-banner prefetch per presentation.
  • Added the optional contentId of the current Story or Clip to GAM, AdMob and VAST ad request item info on Android and iOS.
  • Added the tapped content's title, one-based tileIndex and custom metadata to StorytellerTileType in list onTileTapped callbacks on Android and iOS.
  • Added theme options: ThemeType.sheets (ThemeSheets.cornerRadius) for the top corner radius of Storyteller sheets, ThemePlayerClips.embeddedVideoSizing (legacy or widthConstrained) for Embedded Clips, ThemeRectangularTile.titleGradient for the rectangular tile title scrim, and Android-only textSize and lineHeight on ThemeInstructionButton.
  • Added multi-stop theme gradients on Android and iOS: ThemeGradient.withStops takes two or more ThemeGradientStop values, and an unusable stop list falls back to the gradient's start and end colors.
  • Added ThemePlayerClips.modal (ThemePlayerClipsModal) to override the full-screen Clips layout on Android and iOS: status-bar drawing, spacing, progress bar position and size, gradient heights, navigation sizing and the Search icon.

Bug Fixes#

  • Fixed adjacent Clips remaining visible beneath between-Clips ads in the Android modal player after paging settles.
  • Fixed Android Home, Stories and Clips list views retaining native ViewModels and automatic reload jobs after the Flutter view is disposed.
  • Fixed hidden Android Embedded Clips players consuming first-run Instructions before a visible full-screen or embedded player could display them. Hidden players also pause native playback while retaining their state.
  • Fixed web content in Android link modals and Sheets collapsing when pages use CSS viewport-height units such as vh or svh.
  • Fixed an Android video-preloading crash on Android 14 and earlier when the preload queue reaches capacity.
  • Android GAM and AdMob keep serving ads when the Storyteller SDK cancels in-flight ad requests, for example when closing the player or swiping past Clips whose bottom banners are still loading.
  • Fixed iOS client ads omitting contentId from StorytellerClientAdItemInfo.

  • Fixed Android ignoring these local theme settings: lists.title.textColor, rectangular tile padding, circular tile indicator border colours, tile live chip border colours, and the rectangular tile unread indicator borderColor.

  • Fixed uncovered right edges in the Android StorytellerHomeView and StorytellerEmbeddedClipsView at fractional display densities.

Analytics#

  • Story and Clip watch-time events (storyHeartbeat, storyPageQuartile, clipVideoHeartbeat, and clipVideoQuartile) are now delivered through onUserActivityOccurred on Android and iOS. Applications that forward every event to their own analytics will receive these additional events.
  • Added typed quartile, actionType, searchResultId, searchResultTitle, and searchResultSource properties to StorytellerUserActivityData on Android and iOS.

Documentation#

  • Corrected Flutter integration examples, analytics wire names, theme defaults and platform limitations; added a first-content quickstart and troubleshooting. Installation examples use 12.1.2.

11.6.5 - 20/08/2026#

  • Simplified package READMEs to direct installation, configuration, and usage guidance to the public Flutter documentation and Showcase.

11.6.4 - 19/08/2026#

Native SDKs#

  • Updated the Flutter core SDK dependencies to Android Storyteller 11.6.4 and iOS Storyteller 11.6.1.
  • Updated the Flutter GAM SDK dependencies to Android core and GAM v24 11.6.4, and iOS Storyteller SDK and GAM integration 11.6.1.
  • Added a separate Flutter AdMob package using Android core and shared ads v24 11.6.4, with iOS Storyteller SDK and GAM integration 11.6.1.
  • Added a separate Flutter VAST package using Android core and VAST 11.6.4, and iOS core and VAST integration 11.6.1.
  • iOS consumers must add the Storyteller Lottie podspec source to their Podfile; Storyteller SDK 11.6.1 resolves StorytellerLottie 4.6.0 from that repository.

New Features#

  • Added custom share handling with setUseCustomShareHandling and onShareButtonTapped.
  • Added getFollowableCategories for retrieving followable category metadata.
  • Added Flutter mappings for target-native analytics payload fields, including ad session, paid ad, audio toggle, mute state, and analytics exclusion fields.
  • Added Clips like button Lottie animation theme support and poll image answer gradient overlay configuration.
  • Added category metadata to list tile callbacks via categoryDetails, while preserving existing category ID lists.
  • Added bottomBannerAdUnit support for Clips bottom banner GAM placements.
  • Added the optional storyteller_admob_sdk package with dynamic native and banner units, native/banner fallback priority, Clips bottom banners, custom KVPs, and runtime GAM/AdMob facade selection in a shared dependency graph.
  • Added Google-facade disable() APIs so integrating-app Client Ads can own eligible inventory while VAST remains registered.
  • Added StorytellerCardView for native Cards collections on Android and iOS, including analytics context, data-load callbacks, controller-driven reload, and dynamic native sizing.
  • Added setClientAdProvider with typed Stories/Clips requests and URL-based image/video responses for host-supplied integrating-app ads, including tracking pixels, actions, source attribution, timeout, and stale-response protection on Android and iOS.
  • Added Flutter theme mappings for Cards audio icons, player mute/captions/back icons, Clips presentation and spacing, and the expanded Search appearance contract available in the target native SDKs.
  • Added typed tileIndex, analytics context, list-position, and SDK initialization fields while preserving raw event names and every payload key delivered by the platform bridge.
  • Added cross-platform player-presentation aliases and iOS player mute-state access with explicit unsupported behavior on Android.
  • Added full custom-attribute replacement, nullable locale clearing, batch followed-category removal, and awaited followed-category replacement.
  • Added explicit open-reason attribution, native-spelling deep-link and collection-external-ID aliases, and optional per-presentation Clips ad controls for fullscreen and Embedded Clips entry points.
  • Added Android category-based Clips counts and cancellable Clips preloading with documented iOS capability behavior.
  • Added Android 11.6.3 between-Clips provider ordering for fullscreen, Embedded, row, and grid presentations.
  • Added request-correlated, sanitized late Clips-open errors and optional Android client-ad contentId payloads.
  • Added the optional storyteller_vast_sdk package for generic and GAM VAST full-screen ads, typed static/dynamic request parameters, safe timeout fallback, deterministic VAST-only module replacement, and sanitized diagnostics.

Bug Fixes#

  • Fixed isCategoryFollowed on Android, which previously resulted in a MissingPluginException.
  • Fixed internal Story and Clip CTAs in Android Stories Rows and Grids so dismissing the current player continues to open the selected target.
  • Preserved the published StorytellerCardView constructor surface while introducing collection-backed native Cards, so existing applications remain source-compatible when upgrading.
  • Allowed main-content and bottom-banner ad-unit callbacks to resolve independently instead of sharing one timeout queue on Android.
  • Fixed Android GAM requests made on the main thread skipping dynamic full-screen ad-unit callbacks.
  • Prevented immediate Clips-open failures from also being emitted as late-error events; those failures continue to reject the returned Future.
  • Restored the prior Android custom-attribute map when full replacement fails, then returned a structured CUSTOM_ATTRIBUTES_ERROR.

Behavior Notes#

  • The core storyteller_sdk iOS podspec remains at iOS 13.0 to match the native StorytellerSDK support floor; the example app and GAM integration target iOS 15.0.
  • Cards are rendered by the native SDKs. Flutter owns the platform-view bridge, callback mapping, and height updates after native content loads.
  • StorytellerCardView.collectionId must be non-blank to render Cards content. The older storyId, clipId, theme, and onTileTapped arguments remain as deprecated source-compatibility shims and do not enable legacy card content.
  • Android analytics now surfaces adIndex as an int in the raw fields map, matching the typed Dart API and iOS payload shape.
  • Android analytics no longer emits collectionOffset, which is not exposed by the native Android 11.6.3 activity data contract.
  • StorytellerCategoryDetail.placement now preserves absent native placement values as null instead of converting them to an empty string.
  • Search filter visibility, Following-feed selection style, modal Clips anchoring, and followable-category profile content remain tenant/native settings rather than local Flutter theme fields.
  • Cards unavailableIcon, player showMoreButton, and player close/more icons are Android-only; iOS safely ignores those optional map keys.
  • Omitting a Clips ad configuration preserves the linked native SDK's defaults; an explicitly supplied configuration sends only its supported, non-null fields. Android provider order distinguishes native order, an empty disabled provider set, and an explicitly ordered provider list.
  • Android's native external-ID collection open always uses deep-link attribution and rejects an explicit instanceMethod reason. iOS supports both reasons for the equivalent Flutter helper.
  • getClipsCount(String) remains source compatible: iOS interprets its value as a collection ID, while Android 11.6.3 interprets it as one category ID. Use getClipsCountForCategories for explicit Android category queries.
  • Programmatic Clips opens continue to reject their Future for invalid arguments and immediate/awaited native failures. Android callback-style late failures use onClipsOpenError; subscribe before opening when those events matter.
  • VAST request construction, fetching, parsing, wrapper resolution, media selection, playback, tracking, fallback, and analytics remain native-owned.

11.1.0 - 03/02/2026#

Breaking changes#

  • onTileTapped in list views now provides a StorytellerTileType instead of a raw String id

Bug fixes#

  • Resolved an issue where KVPs were missing on Android
  • Resolved an issue where the onTileTapped delegate callback was not invoked on iOS

11.0.2 - 17/12/2025#

Bug fixes#

  • Fixed an issue where the customKvps callback was called only once in the GAM adapter
  • Fixed a rare issue related to the mute state on Android

11.0.1 - 04/12/2025#

Improvements#

  • Decreased the minimum required version of the GAM dependency for the GAM module on iOS to 12.2

11.0.0 - 14/11/2025#

New Features#

Bug fixes#

  • Fixed grid height calculations for non-scrollable layouts when the data count is lower than the display limit on Android

11.0.0-alpha.3 - 06/11/2025#

Improvements#

  • Added support for Xcode 16.2

11.0.0-alpha.2 - 29/10/2025#

Bug fixes#

  • Fixed issue where adUnit callback was not being invoked on iOS

11.0.0-alpha.1 - 29/10/2025#

storyteller_sdk#

SDK Initialization#

  • Storyteller.initialize() with API key authentication and optional external ID
  • StorytellerEventTrackingOptions for personalization and ad tracking configuration
  • SDK state queries: isInitialized(), version(), currentApiKey()

Widget Components#

  • StorytellerStoriesGridView - Grid layout for stories with category filtering
  • StorytellerStoriesRowView - Horizontal scrolling row of stories
  • StorytellerClipsGridView - Grid layout for clips with collection support
  • StorytellerClipsRowView - Horizontal scrolling row of clips
  • StorytellerEmbeddedClipsView - Embedded clips player with playback controls

Controllers#

  • StorytellerEmbeddedClipsController for programmatic playback control
  • StorytellerListViewController for list and grid view management

Content Navigation#

  • Direct content opening: openStory(), openPage(), openSheet(), openSearch()
  • Collection support: openCollection(), openCollectionWithCategory()
  • External ID support: openStoryByExternalId(), openClipByExternalId()
  • Category navigation: openCategory(), isCategoryFollowed()
  • Content counts: getStoriesCount(), getClipsCount()

User Management#

  • Custom attributes: setCustomAttribute(), removeCustomAttribute(), customAttributes()
  • Locale configuration: setLocale()
  • Category following: addFollowedCategory(), removeFollowedCategory(), followedCategories()

Theming System#

  • StorytellerTheme with light/dark mode support
  • Component-specific themes: instructions, engagement units, polls, quizzes, search
  • Per-collection theme support in openCollection()

Deep Linking#

  • isStorytellerDeeplink() for URL validation
  • openDeeplink() for navigation handling
  • isSearchEnabled() query

Player Controls#

  • dismissPlayer() with animation and reason support
  • resumePlayer() for playback continuation
  • Player state queries: isPlayerVisible(), isPresentingContent()

Event Streams#

  • onUserActivityOccurred - All user interaction events
  • userNavigatedToApp - Link tap navigation events
  • categoryFollowActionTaken - Category follow/unfollow events
  • onPlayerPresented - Player presentation lifecycle
  • onPlayerDismissed - Player dismissal lifecycle
  • onLog - SDK debug logging

storyteller_gam_sdk#

  • StorytellerGAMModule.setup() for native SDK integration configuration
  • StorytellerGAMModuleConfiguration with dynamic ad unit callback
  • StorytellerAdRequestInfo providing placement, category, and experiment context
  • StorytellerCustomNativeTemplateIds for stories and clips ad templates

Features#

  • Dynamic ad unit selection per request based on placement/category/experiment
  • Custom native template ID mapping for stories and clips
  • Platform channel bridge to native GAM SDKs