Skip to content

Migration Guide: v11.0 to v11.2#

This guide covers the React Native API changes between 11.0.x and 11.2.0.

The change audit in this guide is based on the 11.0.10 and 11.2.0 tags.

This release aligns the React Native SDK with the native Storyteller SDK 11.x behavior (replacing several legacy 10.13.x bridge semantics).

Note: the repository was reorganized internally, but the public npm import path stays the same: @getstoryteller/react-native-storyteller-sdk.

At a Glance#

Breaking / Behavior Changes#

  1. setEventTrackingOptions has been removed.
  2. Event tracking options are now applied via initialize(apiKey, externalId, eventTrackingOptions).
  3. open* navigation methods now accept an optional openReason.
  4. Ad request payloads no longer include adRequest.clips.clip.id / adRequest.stories.story.id.
  5. onTileTapped payloads now include richer metadata (type, story/clip IDs, categories).

Additive Changes#

  1. context support was added to Home, list, card, and embedded clips configurations.
  2. StorytellerOpenReason and StorytellerAnalyticsContext are now exported.
  3. StorytellerClipCollectionConfiguration now supports theme and context.

API Diff Matrix#

Area 11.0.10 11.2.0 Migration Action
Initialization initialize(apiKey, externalId?) initialize(apiKey, externalId?, eventTrackingOptions?) Pass tracking options at init time when needed
Event tracking mutation setEventTrackingOptions(options) existed setEventTrackingOptions removed Re-initialize SDK with updated options
Navigation open reason No openReason parameter Optional openReason on major open* methods Optionally pass StorytellerOpenReason
Tile tap event { id } { id, type, storyId, clipId, collectionId, categories } Update callbacks if you need richer context
Ad request payload adRequest.*.*.id available adRequest.*.*.id removed Stop reading story.id / clip.id; use categories + placement/collection
List/Home/Card/Embedded config No analytics context field context?: StorytellerAnalyticsContext supported Add context where attribution is needed
Clip collection config openedReason?: string, no theme, no context openedReason?: StorytellerOpenReason, plus theme and context Update typing and pass optional context/theme

1. Update Package Version#

# Core SDK
npm install @getstoryteller/[email protected]

# Optional GAM package
npm install @getstoryteller/[email protected]

2. Event Tracking Options: Apply on Initialize#

In 11.0.10, you could initialize once and later call setEventTrackingOptions(...).

In 11.2.0, options are passed to initialize(...) directly.

import StorytellerSdk, {
  type StorytellerEventTrackingOptions,
  DisabledFeatures,
} from '@getstoryteller/react-native-storyteller-sdk';

const trackingOptions: StorytellerEventTrackingOptions = {
  enablePersonalization: false,
  enableStorytellerTracking: true,
  enableUserActivityTracking: true,
  enableAdTracking: true,
  enableFullVideoAnalytics: true,
  enableRemoteViewingStore: true,
  disabledFeatures: [DisabledFeatures.clipLikes],
};

await StorytellerSdk.initialize('YOUR_API_KEY', 'USER_ID', trackingOptions);

import StorytellerSdk, {
  DisabledFeatures,
} from '@getstoryteller/react-native-storyteller-sdk';

await StorytellerSdk.initialize('YOUR_API_KEY', 'USER_ID');

StorytellerSdk.setEventTrackingOptions({
  enablePersonalization: false,
  disabledFeatures: [DisabledFeatures.clipLikes],
});

If your privacy settings can change at runtime, persist the new options and re-initialize the SDK with the updated options.

3. Navigation APIs: Optional openReason#

The following methods now support an optional openReason:

  • openStory
  • openPage
  • openCategory
  • openStoryByExternalId
  • openClipByExternalId
  • openCollection
  • openCollectionWithCategory
import StorytellerSdk, {
  StorytellerOpenReason,
} from '@getstoryteller/react-native-storyteller-sdk';

await StorytellerSdk.openStory('story-id', StorytellerOpenReason.instanceMethod);
await StorytellerSdk.openCollection('collection-id', undefined, StorytellerOpenReason.deeplink);

await StorytellerSdk.openStory('story-id');
await StorytellerSdk.openCollection('collection-id');

4. Collection/Category Inputs: Use IDs for Native 11.x Parity#

The 11.2.0 bridge aligns Android collection/category opening behavior with native 11.x APIs.

Use Storyteller IDs for:

  • openCollection(id, ...)
  • openCollectionWithCategory(id, category, ...)
  • openCategory(category, ...)

Continue using the explicit external-ID methods when needed:

  • openStoryByExternalId(externalId, ...)
  • openClipByExternalId(collectionId, externalId, ...)

5. Ad Request Payload Shape Update#

adRequest.clips.clip.id and adRequest.stories.story.id are no longer emitted.

const subscription = StorytellerSdk.getAdsForList((adRequest) => {
  if (adRequest.clips) {
    console.log('Collection:', adRequest.clips.collection);
    console.log('Clip categories:', adRequest.clips.clip.categories);
  }

  if (adRequest.stories) {
    console.log('Placement:', adRequest.stories.placement);
    console.log('Story categories:', adRequest.stories.story.categories);
  }
});

const subscription = StorytellerSdk.getAdsForList((adRequest) => {
  if (adRequest.clips) {
    console.log('Clip id:', adRequest.clips.clip.id);
  }

  if (adRequest.stories) {
    console.log('Story id:', adRequest.stories.story.id);
  }
});

6. onTileTapped Event Is Now Richer#

List component onTileTapped callbacks now provide more than a tile id.

onTileTapped={(event) => {
  console.log(event.id);
  console.log(event.type); // 'story' | 'clip'
  console.log(event.storyId);
  console.log(event.clipId);
  console.log(event.collectionId);
  console.log(event.categories);
}}

onTileTapped={(event) => {
  console.log(event.id);
}}

7. Analytics context Added to View Configurations#

11.2.0 adds optional analytics context to major view configurations:

  • Stories row/grid
  • Clips row/grid
  • Home view
  • Card view
  • Embedded clips
import type { StorytellerAnalyticsContext } from '@getstoryteller/react-native-storyteller-sdk';

const context: StorytellerAnalyticsContext = {
  location: 'Home',
  placementId: 'hero-stories-row',
};

<StorytellerStoriesRowView
  configuration={{
    categories: ['news'],
    context,
  }}
/>

8. Embedded Clips / Clip Collection Configuration Additions#

StorytellerClipCollectionConfiguration now supports:

  • openedReason?: StorytellerOpenReason
  • theme?: Theme
  • context?: StorytellerAnalyticsContext

This enables per-view theme and analytics context when opening clips collections in embedded flows.

Migration Checklist#

  • Update SDK package(s) to 11.2.0.
  • Replace setEventTrackingOptions(...) calls with initialize-time options.
  • If privacy settings change at runtime, re-initialize with new options.
  • Update any ad request code that reads story.id / clip.id.
  • Adopt richer onTileTapped payloads where useful.
  • Pass context where analytics attribution is required.