Skip to content

Configuring Storyteller#

Prerequisites#

Important: The initialize() method must be called before using any other Storyteller SDK methods or components. Call this method as early as possible in your app lifecycle (typically in your root component or App.tsx).

Core SDK Methods#

Initialization#

initialize(apiKey: string, externalId?: string): Promise<void>#

Initializes the Storyteller SDK with your API key and optional user identifier.

Parameters:

  • apiKey - API key provided by the Storyteller team
  • externalId - (Optional) External ID of the user for personalization and analytics

Example:

try {
  await StorytellerSdk.initialize('YOUR_API_KEY', 'user-123');
  console.log('SDK ready');
} catch (error) {
  console.error('Initialization failed:', error);
}

Status & Information#

isInitialized(): boolean#

Checks if Storyteller has been successfully initialized.

isPresentingContent(): boolean#

Returns whether any Storyteller content (stories, pages, clips, sheets) is currently being presented. Useful to avoid opening new content while something else is on screen.

Example:

if (!StorytellerSdk.isPresentingContent()) {
  await StorytellerSdk.openStory('story-id-123');
}

currentApiKey(): string#

Returns the current API key.

version(): string#

Returns the current SDK version.

Theming#

setTheme(theme: Theme): void#

Customizes the appearance of the SDK. Pass a Theme object of shape { light: Partial<ThemeType>, dark: Partial<ThemeType> }. Each mode accepts partial overrides. This sets the default fallback theming style used to render Story items in lists and activities launched from a list. For more information, see Themes.

Localization#

setLocale(locale?: string | null): void#

Sets the SDK locale for localized content. Provide an ISO language code such as "en" or "fr". Pass null or omit the argument to clear the locale preference.

Example:

StorytellerSdk.setLocale('en-US');
StorytellerSdk.setLocale(null); // clear locale preference

Deep links allow you to open specific Storyteller content programmatically. These methods open Stories or Clip Collections independently from list components rendered in your app. For more information, see Deep Links.

isStorytellerDeepLink(url: string): boolean#

Returns whether a URL is a Storyteller deep link. The legacy RN spelling isStorytellerDeeplink(url) is also available for backwards compatibility.

openDeepLink(url: string): Promise<void>#

Opens a Storyteller deep link. The legacy RN spelling openDeeplink(url) is also available for backwards compatibility.

openStory(id: string): Promise<void>#

Opens a Story by its Storyteller ID (internal ID from Storyteller CMS).

Parameters:

  • id - Story ID from Storyteller

Example:

try {
  await StorytellerSdk.openStory('story-id-123');
} catch (error) {
  console.error('Failed to open story:', error);
}

openStoryByExternalId(externalId: string): Promise<void>#

Opens a Story by its external ID (custom ID set by your organization). Use this when you want to reference stories using your own ID system.

Parameters:

  • externalId - Your custom external ID for the story

Example:

try {
  await StorytellerSdk.openStoryByExternalId('my-story-123');
} catch (error) {
  console.error('Failed to open story by external ID:', error);
}

openPage(id: string): Promise<void>#

Opens a Story Page (multi-story experience) by its ID.

Parameters:

  • id - Page ID from Storyteller

openCategory(category: string): Promise<void>#

Opens all Stories in a specific category.

Parameters:

  • category - Category name/tag

openCollection(id: string, clipId?: string, openReason?: StorytellerOpenReason, adConfiguration?: StorytellerClipsAdConfiguration): Promise<void>#

Opens a Clip Collection, optionally starting from a specific clip.

Parameters:

  • id - Collection ID
  • clipId - (Optional) Specific clip ID to start from
  • openReason - (Optional) Reason used for analytics
  • adConfiguration - (Optional) Per-presentation Clips ad placement controls

Example:

// Open collection from the beginning
await StorytellerSdk.openCollection('collection-123');

// Open collection starting from a specific clip
await StorytellerSdk.openCollection('collection-123', 'clip-456');

// Opt this presentation into Clips pre-roll and bottom banner placements
await StorytellerSdk.openCollection('collection-123', undefined, undefined, {
  preRollEnabled: true,
  bottomBannerEnabled: true,
  betweenClipsAdProviderOrder: [
    StorytellerAdProvider.vast,
    StorytellerAdProvider.gam,
  ],
});

StorytellerClipsAdConfiguration has two optional booleans and an Android-only provider order:

  • preRollEnabled - Allows an opening Clips pre-roll request when Clips ads are available for the tenant
  • bottomBannerEnabled - Allows a bottom banner ad when Clips bottom banner ads are available for the tenant
  • betweenClipsAdProviderOrder - Selects and orders the standard Android between-Clips providers using StorytellerAdProvider.vast, .gam, and .admob

When adConfiguration is omitted, the native SDK platform default is preserved. When the object is supplied, omitted flags are treated as false. For betweenClipsAdProviderOrder, omit it or pass null to preserve native module order, pass [] to disable standard between-Clips ads, or pass a populated array to define the allowlist and fallback order. IMA opening pre-roll is separate from this list. iOS ignores the provider-order property.

preloadClips(collectionId: string, clipIds?: string[], preloadVideos?: boolean): Promise<string | null>#

Starts Android Clips preloading for a collection. Pass an empty or omitted clipIds array to let the native SDK choose clips, and set preloadVideos to true to include video assets. The promise resolves with a handle that can be passed to cancelPreloadClips(handle).

const preloadHandle = await StorytellerSdk.preloadClips(
  'collection-123',
  ['clip-1', 'clip-2'],
  true
);

if (preloadHandle) {
  StorytellerSdk.cancelPreloadClips(preloadHandle);
}

The linked iOS SDK does not expose Clips preloading, so this method resolves null on iOS and cancelPreloadClips() is a no-op.

openClipByExternalId(collectionId: string, externalId: string): Promise<void>#

Opens a specific clip within a collection using external IDs.

Parameters:

  • collectionId - Collection ID
  • externalId - Clip external ID

openCollectionByExternalId(collectionId, externalId) is also available as an alias for the Android native API naming.

openSearch(): void#

Opens the Storyteller search interface, allowing users to search through available content.

isSearchEnabled(): boolean#

Checks if search is available for the current API key and configuration. Use this to conditionally show a Search button.

Example:

if (StorytellerSdk.isSearchEnabled()) {
  StorytellerSdk.openSearch();
}

openSheet(id: string): Promise<void>#

Opens a Sheet by its ID. Sheets are bottom or full-screen surfaces used to show additional content and actions.

Parameters:

  • id - Sheet ID from Storyteller

Example:

try {
  await StorytellerSdk.openSheet('sheet-id-123');
} catch (e) {
  console.warn('Failed to open sheet', e);
}

openCollectionWithCategory(id: string, category?: string, openReason?: StorytellerOpenReason, adConfiguration?: StorytellerClipsAdConfiguration): Promise<void>#

Opens a Clip Collection with an optional category context.

Parameters:

  • id - Collection ID
  • category - (Optional) Category identifier to scope the collection
  • openReason - (Optional) Reason used for analytics
  • adConfiguration - (Optional) Per-presentation Clips ad placement controls

Example:

await StorytellerSdk.openCollectionWithCategory('collection-123', 'sports');

await StorytellerSdk.openCollectionWithCategory('collection-123', 'sports', undefined, {
  bottomBannerEnabled: true,
});

Content Counts#

Methods to query counts for UI badges, tabs, or prefetch logic.

getStoriesCount(categoryIds: string[]): Promise<number>#

Returns the number of available stories for the specified categories.

Parameters:

  • categoryIds - Array of category identifiers

Example:

const count = await StorytellerSdk.getStoriesCount(['news', 'sports']);
setStoriesBadge(count);

getClipsCount(collectionId: string): Promise<number>#

Returns the number of clips available in the specified collection.

Parameters:

  • collectionId - Collection identifier

Example:

const clips = await StorytellerSdk.getClipsCount('collection-123');
console.log('Clips available:', clips);

getClipsCountForCategories(categoryIds: string[]): Promise<number>#

Returns the number of clips available for the specified categories on Android. On iOS, use getClipsCount(collectionId).

const clips = await StorytellerSdk.getClipsCountForCategories(['news', 'sports']);
console.log('Clips available:', clips);

Player Control#

mute(): Promise<void> / unmute(): Promise<void>#

Change Story and Clip audio from your app on iOS and Android, including full-screen and embedded Clips. Muting keeps video playing. Both commands work when the SDK's audio controls are hidden.

Wait for SDK initialization before calling either method. The promise resolves after native audio state is accepted and applied to an active presentation. To start silently, await mute() before opening content or mounting an embedded Clips view:

await StorytellerSdk.initialize(apiKey, externalId);
await StorytellerSdk.mute();
await StorytellerSdk.openStory(storyId);

For runtime control, call await StorytellerSdk.mute() while playback continues, then explicitly call await StorytellerSdk.unmute() when your app wants sound again. Repeated commands are supported. An uninitialized or still-initializing SDK rejects with code SDK_NOT_INITIALIZED; handle the rejection before presenting content.

These commands follow the SDK's ordinary audio behavior and configured persistence. Later user controls and eligible device changes can change the state again. There is no forced mute lock or automatic restoration of an earlier choice. unmute() does not resume paused playback, change device volume or guarantee audible output when device settings prevent it.

See starting embedded Clips silently for the mount sequence.

isPlayerVisible(): boolean#

Returns whether the native player is visible. This is an alias for isPresentingContent() in React Native.

isPlayerMuted(): Promise<boolean>#

Returns whether the player is currently muted on iOS. Android does not expose a matching native API in the linked SDK version and rejects this method.

dismissPlayer(animated: boolean, reason: string): void#

Programmatically closes the currently open Story player.

Parameters:

  • animated - Whether to animate the dismissal
  • reason - Reason for dismissal (for analytics)

Example:

StorytellerSdk.dismissPlayer(true, 'user_action');

resumePlayer(): void#

Resumes playback after the player has been paused due to overlays, app lifecycle changes, or custom logic.

Example:

// When your overlay/modal closes or app regains focus
StorytellerSdk.resumePlayer();

setUseCustomShareHandling(useCustomShareHandling: boolean): void#

Controls whether Storyteller opens the platform share sheet itself or emits shareButtonTapped so your app can present a custom share flow. When custom handling is enabled, call resumePlayer() after your share UI is dismissed.

Example:

StorytellerSdk.setUseCustomShareHandling(true);

const subscription = StorytellerSdk.shareButtonTapped(({ text, title, url }) => {
  // Present your own share UI with the payload, then resume Storyteller playback.
  StorytellerSdk.resumePlayer();
});

Custom Attributes#

Custom attributes allow you to associate metadata with users for personalization and targeting. For more information, see User Customization.

setCustomAttribute(key: string, value: string): void#

Sets or updates a single user attribute.

setCustomAttributes(attributes: Record<string, string>): void#

Replaces the current custom attributes with the supplied string key/value map.

removeCustomAttribute(key: string): void#

Removes a single user attribute.

customAttributes(): Promise<Record<string, string>>#

Returns the current custom attributes.

Followable Categories#

Followable categories allow you to associate metadata with users for personalization and targeting. For more information, see User Customization.

addFollowedCategory(category: string): void#

Marks one category as followed.

addFollowedCategories(categories: string[]): void#

Marks multiple categories as followed.

setFollowedCategories(categories: string[]): Promise<void>#

Atomically replaces the complete app-managed followed-category set. Await the Promise before reloading content when the new follow state must be applied first; pass an empty array to clear the set.

removeFollowedCategory(category: string): void#

Removes one followed category.

removeFollowedCategories(categories: string[]): void#

Removes multiple followed categories.

isCategoryFollowed(category: string): boolean#

Returns whether a category is currently followed.

followedCategories(): Promise<string[]>#

Returns the current followed category identifiers.

getFollowableCategories(): Promise<StorytellerFollowableCategories>#

Fetches the backend-backed category catalog for the current user, including category metadata and isFollowed state for custom category management UIs.

Ads Integration#

For more information on integrating ads, see Ads.

Event Handling#

The Storyteller SDK emits events for user interactions, navigation, and ad requests. With React Native's New Architecture, these events are exposed as callable EventEmitter functions on the StorytellerSdk object.

Important: Always remove event listeners when components unmount to prevent memory leaks.

Available Events#

The SDK provides six event emitters:

  • onUserActivityOccurred - Fires for all user engagement events (views, taps, swipes, completions, etc.)
  • userNavigatedToApp - Fires when user taps an action button that navigates to your app
  • shareButtonTapped - Fires when custom share handling is enabled and the user taps a Story or Clip share button
  • categoryFollowActionTaken - Fires when user follows or unfollows a category
  • onPlayerOpenFailed - Fires on Android when a programmatic Clips open reports an asynchronous native failure after its Promise has accepted the request
  • getAdsForList - Fires when SDK requests ads for stories or clips

Android programmatic Clips methods resolve their Promise after native accepts the open request. Subscribe to onPlayerOpenFailed to observe validation failures that arrive later. On iOS, the corresponding failure rejects the method Promise instead; cross-platform callers should handle both the Promise rejection and the Android event.

const subscription = StorytellerSdk.onPlayerOpenFailed(({ method, code, message }) => {
  console.error(`${method} failed (${code}): ${message}`);
});

// Remove the subscription when the host component unmounts.
subscription.remove();

Event Subscription Pattern#

Each event emitter is a function that accepts a callback and returns a subscription object with a remove() method:

const subscription = StorytellerSdk.eventName((event) => {
  // Handle event
});

// Clean up when done
subscription.remove();

Event Examples#

1. User Activity Tracking#

Track all user interactions within the Storyteller experience:

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

function MyComponent() {
  useEffect(() => {
    const subscription = StorytellerSdk.onUserActivityOccurred((event) => {
      console.log('Event type:', event.type);
      console.log('Event data:', event.data);

      // Send to your analytics service
      analytics.track(event.type, event.data);
    });

    return () => {
      subscription.remove(); // Cleanup
    };
  }, []);

  return (/* ... */);
}

2. App Navigation Events#

Handle when users tap action buttons that navigate to your app:

import { useEffect } from 'react';
import { Alert } from 'react-native';
import StorytellerSdk from '@getstoryteller/react-native-storyteller-sdk';

function MyComponent() {
  useEffect(() => {
    const subscription = StorytellerSdk.userNavigatedToApp((event) => {
      console.log('Navigation URL:', event.url);

      // Parse the URL and navigate within your app
    });

    return () => {
      subscription.remove();
    };
  }, []);

  return (/* ... */);
}

3. Category Follow/Unfollow Events#

Track when users follow or unfollow categories:

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

function MyComponent() {
  useEffect(() => {
    const subscription = StorytellerSdk.categoryFollowActionTaken((event) => {
      console.log('Category:', event.category.name);
      console.log('Is Following:', event.isFollowing);

      // handle the follow/unfollow action
    });

    return () => {
      subscription.remove();
    };
  }, []);

  return (/* ... */);
}

4. Ad Request Events#

Handle ad requests for client-side ad integration

For complete ad integration details, see Ads.

Privacy & Analytics#

Event Tracking Options#

The eventTrackingOptions property customizes Storyteller's analytics and tracking behavior. This is an object of type StorytellerEventTrackingOptions which allows certain features to be disabled based on user privacy choices and regulatory requirements.

Note: By default, all tracking options are enabled.

Methods#

eventTrackingOptions(): Promise<StorytellerEventTrackingOptions>#

Retrieves the current tracking options configuration.

Example:

const options = await StorytellerSdk.eventTrackingOptions();
console.log('Tracking enabled:', options.enableStorytellerTracking);

To change tracking options, pass the new configuration into initialize(...) again. The linked native SDKs expose eventTrackingOptions as read-only after initialization.

API Reference#

Type Definitions#

Recommended imports to use SDK types directly and avoid drift:

import type {
  Theme,
  StorytellerEventTrackingOptions,
  StorytellerClipsAdConfiguration,
  StorytellerFollowableCategories,
  StorytellerFollowableCategory,
  StorytellerFollowableCategoryPlacement,
  StorytellerAd,
  StorytellerAdActionType,
  DataLoadCompletedEvent,
  ShareButtonTappedEvent,
  Category,
  ItemInfo,
  StoriesGridDimensionsState,
} from '@getstoryteller/react-native-storyteller-sdk';
import {
  EventType,
  StorytellerAdProvider,
} from '@getstoryteller/react-native-storyteller-sdk';

interface StorytellerEventTrackingOptions {
  enablePersonalization?: boolean;
  enableStorytellerTracking?: boolean;
  enableUserActivityTracking?: boolean;
  enableAdTracking?: boolean;
  enableFullVideoAnalytics?: boolean;
  enableRemoteViewingStore?: boolean;
  disabledFeatures?: string[]; // e.g., ['all', 'clipLikes', 'pollVotes']
}

interface CustomAttributesResult {
  [key: string]: string;
}

interface StorytellerFollowableCategories {
  categories: StorytellerFollowableCategory[];
}

interface StorytellerFollowableCategory {
  id: string;
  name?: string;
  displayTitle?: string;
  externalId?: string;
  type?: string;
  placement?: StorytellerFollowableCategoryPlacement;
  thumbnailUrl?: string;
  isFollowed: boolean;
}

interface StorytellerFollowableCategoryPlacement {
  title: string;
  code: string;
}

interface StorytellerClipsAdConfiguration {
  preRollEnabled?: boolean;
  bottomBannerEnabled?: boolean;
  betweenClipsAdProviderOrder?: StorytellerAdProvider[] | null; // Android only
}

interface ShareButtonTappedEvent {
  text: string;
  title: string;
  url: string;
}

// Selected exported types (see package exports for the complete definitions)
interface Category {
  name: string;
  externalId: string;
  displayTitle: string;
  type: string;
  placement: string;
}

interface ItemInfo {
  contentId?: string; // Android 11.6.3+ and iOS 11.7.0+ dynamic ad callbacks
  categories: Category[];
}

interface AdRequestInfo {
  stories?: {
    placement: string;
    categories: string[];
    story: ItemInfo;
  };
  clips?: {
    collection: string;
    clip: ItemInfo;
  };
}

// EventType is an enum exported from the SDK (e.g., 'openedStory', 'dismissedStory', ...)
// UserActivityData is a structured object; see Analytics.md for field documentation

Summary of All Methods#

Method Return Type Description
initialize(apiKey, externalId?) Promise<void> Initialize SDK
isInitialized() boolean Check if initialized
isPresentingContent() boolean Check if any content is presenting
currentApiKey() string Get current API key
version() string Get SDK version
setTheme(theme: Theme) void Apply custom theme
setLocale(locale?: string \| null) void Set or clear SDK locale
isStorytellerDeepLink(url) boolean Validate deep link URL
isStorytellerDeeplink(url) boolean Backwards-compatible deep link validator alias
openDeepLink(url) Promise<void> Open deep link
openDeeplink(url) Promise<void> Backwards-compatible deep link opener alias
openStory(id) Promise<void> Open story by ID
openStoryByExternalId(externalId) Promise<void> Open story by external ID
openPage(id) Promise<void> Open story page
openSheet(id) Promise<void> Open sheet by ID
openCategory(category) Promise<void> Open category
openCollection(id, clipId?, openReason?, adConfiguration?) Promise<void> Open collection
openCollectionWithCategory(id, category?, openReason?, adConfiguration?) Promise<void> Open collection for a category
openClipByExternalId(collectionId, externalId) Promise<void> Open clip by external ID
openCollectionByExternalId(collectionId, externalId) Promise<void> Alias for Android native collection external ID naming
openSearch() void Open search interface
isSearchEnabled() boolean Check if search is enabled
isPlayerVisible() boolean Alias for isPresentingContent()
isPlayerMuted() Promise<boolean> Check iOS player mute state
mute() / unmute() Promise<void> Change Story and Clip audio while preserving playback
dismissPlayer(animated, reason) void Close player
resumePlayer() void Resume a paused player
setUseCustomShareHandling(enabled) void Enable or disable app-managed share handling
setCustomAttribute(key, value) void Set user attribute
setCustomAttributes(attributes) void Replace all custom attributes
removeCustomAttribute(key) void Remove user attribute
customAttributes() Promise<CustomAttributesResult> Get all attributes
addFollowedCategory(category) void Follow category
addFollowedCategories(categories) void Follow multiple categories
setFollowedCategories(categories) Promise<void> Atomically replace all followed categories
removeFollowedCategory(category) void Unfollow category
removeFollowedCategories(categories) void Unfollow multiple categories
isCategoryFollowed(category) boolean Check whether a category is followed
followedCategories() Promise<string[]> Get followed categories
getFollowableCategories() Promise<StorytellerFollowableCategories> Get followable category metadata and follow state
getStoriesCount(categoryIds) Promise<number> Get count of stories for categories
getClipsCount(collectionId) Promise<number> Get count of clips in a collection
getClipsCountForCategories(categoryIds) Promise<number> Get count of clips for Android categories
preloadClips(collectionId, clipIds?, preloadVideos?) Promise<string \| null> Start Android Clips preloading and return a cancel handle; resolves null on iOS
cancelPreloadClips(handle) void Cancel Android Clips preloading; no-op on iOS
completeAdRequest(ad) void Complete a client-supplied ad request
failAdRequest(error) void Fail a client-supplied ad request
eventTrackingOptions() Promise<StorytellerEventTrackingOptions> Get tracking options

Legacy Storyteller Methods (<v10.x)#

interface StorytellerSdkInterface
  extends NativeModulesStatic,
    NativeModule,
    EventSubscriptionVendor {
  isInitialized(callback: ({result}: {result: boolean}) => void): void;
  isStorytellerDeeplink(url: string, callback: (result: {result: boolean}) => void): void;
  currentUserId(callback: ({result}: {result: string}) => void): void;
  currentApiKey(callback: ({result}: {result: string}) => void): void;
  version(callback: ({result}: {result: string}) => void): void;

  setTheme(theme: Partial<Theme>): void;

  openDeeplink(url: string, callback: (result: boolean) => void): void;
  openStory(id: string, errorCallback: (error: string) => void): void;
  openPage(id: string, errorCallback: (error: string) => void): void;
  openCategory(category: string, errorCallback: (error: string) => void): void;
  openStoryByExternalId(
    id: string,
    errorCallback: (error: string) => void
  ): void;
  openClipByExternalId(
    collectionId: string,
    externalId: string,
    errorCallback: (error: string) => void
  ): void;
  openCollection(
    id: string,
    clipId?: string,
    errorCallback?: (error: string) => void
  ): void;
  openSearch(): void;

  eventTrackingOptions(callback: (options: StorytellerEventTrackingOptions) => void): void;
  setEventTrackingOptions(options: StorytellerEventTrackingOptions): void;

  dismissPlayer(animated: boolean, reason: string): void;

  setCustomAttribute(key: string, value: string): void;
  removeCustomAttribute(key: string): void;
  customAttributes(
    callback: (result: { [key: string]: string | number | boolean }) => void
  ): void;

  setLocale(locale?: string): void;
  addFollowedCategory(category: string): void;
  addFollowedCategories(categories: string[]): void;
  removeFollowedCategory(category: string): void;
  followedCategories(callback: (categories: string[]) => void): void;

  initialize(
    data: {
      apiKey: string;
      externalId?: string | null;
    },
    callback: (callback: { result: boolean; message: string }) => void
  ): void;
};

Event Handlers#

Event Handler Callback Parameter Description
onUserActivityOccurred(callback) (event: { type: EventType, data: UserActivityData }) => void Subscribe to user activity events
userNavigatedToApp(callback) (event: { url: string }) => void Subscribe to app navigation events
shareButtonTapped(callback) (event: { text: string, title: string, url: string }) => void Subscribe to custom share payloads
categoryFollowActionTaken(callback) (event: { category: Category, isFollowing: boolean }) => void Subscribe to category follow/unfollow events
onPlayerOpenFailed(callback) (event: { method: PlayerOpenMethod, code: string, message: string }) => void Subscribe to asynchronous Android programmatic Clips-open failures
getAdsForList(callback) (adRequest: AdRequestInfo) => void Subscribe to ad request events

All event handlers return a subscription object with a remove() method for cleanup.