Skip to content

Configuring Storyteller#

Prerequisites#

Await initialize() before mounting content components or opening content. Start initialization in your root component or App.tsx, and keep loading and failure states visible until it completes. Event subscriptions and status getters can be used to observe SDK setup. See the first-content example.

Core SDK Methods#

Initialization#

Derive the accepted tracking-options type from the exported method:

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

type InitializationTrackingOptions = NonNullable<Parameters<typeof StorytellerSdk.initialize>[2]>;

initialize(apiKey: string, externalId?: string | null, eventTrackingOptions?: InitializationTrackingOptions): Promise<void>#

Initializes the Storyteller SDK with your API key, optional user identifier and optional tracking configuration. The Promise resolves after initialization succeeds and rejects on failure. Serialize repeated calls, including when switching users.

Parameters:

  • apiKey - API key provided by the Storyteller team
  • externalId - (Optional) External ID of the user for personalization and analytics; null or omission selects the SDK-managed guest user
  • eventTrackingOptions - (Optional) Tracking configuration; see Event Tracking Options

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#

On iOS, returns whether a Storyteller presentation host is active. On Android, returns the native isPlayerVisible state. This is a presentation-state check, not a guarantee that no SDK surface or embedded view is visible.

Example:

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

currentApiKey(): string#

Returns the current API key, or an empty string when no API key is available.

version(): string#

Returns the linked native SDK version for the current platform. It is not the React Native npm package 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. Use a language code such as "en" or "fr", rather than a regional tag such as "en-US". iOS validates the code against its supported ISO language codes and ignores invalid codes. Pass null or omit the argument to clear the locale preference.

Example:

StorytellerSdk.setLocale('en');
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.

On iOS, open-method Promises settle after the native open operation completes or fails. Android resolves after invoking the native open request; resolution does not confirm that content finished loading or appeared. For Android programmatic Clips opens, handle both Promise rejection and onPlayerOpenFailed. Later Android errors from Story, Page, category, Sheet and deep-link opens are not exposed through that event and may occur after their Promise has resolved.

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, openReason?: StorytellerOpenReason | null): 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, openReason?: StorytellerOpenReason | null): 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, openReason?: StorytellerOpenReason | null): Promise<void>#

Opens the Story containing the specified Page, starting at that Page.

Parameters:

  • id - Page ID from Storyteller

openCategory(category: string, openReason?: StorytellerOpenReason | null): Promise<void>#

Opens all Stories in a specific category.

Parameters:

  • category - Story category identifier

The optional openReason argument on Story, Page and category methods is StorytellerOpenReason.instanceMethod by default, or StorytellerOpenReason.deeplink when your app is opening content from a deep link.

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, openReason?: StorytellerOpenReason | null): Promise<void>#

Opens a clip by its external ID with a collection ID providing the collection context.

Parameters:

  • collectionId - Collection ID
  • externalId - Clip external ID

openCollectionByExternalId(collectionId, externalId, openReason?) is a React Native alias for the same method on both platforms. iOS applies openReason; Android ignores this argument for external-ID Clips opens.

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. Handle Promise rejection at the call site. Some native count paths return zero on failure, so a zero count is not an authoritative content-load success signal. Use component load callbacks for content-load errors.

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(collectionIdOrCategoryIds: string | string[]): Promise<number>#

The argument has different native semantics by platform:

  • iOS: a string counts Clips in that collection. Passing an array rejects with UNSUPPORTED_PLATFORM.
  • Android: a string is treated as one category identifier; an array counts the specified categories. The current Android bridge does not provide collection-count semantics.

For example, use StorytellerSdk.getClipsCount('collection-123') for an iOS collection count and StorytellerSdk.getClipsCountForCategories(['sports']) for an Android category count. Do not use a collection identifier as an Android category identifier unless your content configuration explicitly uses the same identifier for both.

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

Returns the sum of Clip counts for the specified categories on Android. The same Clip can contribute to more than one category count. On iOS, this method rejects with UNSUPPORTED_PLATFORM; use getClipsCount(collectionId) to count a collection.

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 manage user follow state for Clips. App mutation methods require following to be configured as managed by your integrating app; they have no effect when Storyteller manages following. See User Customization for configuration, completion and personalization requirements.

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 app-managed followed-category set with resolvable category identifiers. Unknown identifiers are omitted. Await the Promise before reloading content when the new follow state must be applied first; pass an empty array to clear the set. On Android, this method also requires personalization to be enabled. A resolved Promise does not imply a mutation occurred when these requirements are not met.

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 null; // Render your app UI here.
}

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 null; // Render your app UI here.
}

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 null; // Render your app UI here.
}

4. Ad Request Events#

Handle ad requests for client-side ad integration

For complete ad integration details, see Ads.

Privacy & Analytics#

Event Tracking Options#

Pass tracking options as the third initialize() argument to customize analytics and tracking behavior. Use InitializationTrackingOptions derived above for the accepted method type. The separately exported StorytellerEventTrackingOptions uses a different TypeScript enum for disabledFeatures and is currently not directly assignable to this argument; the boolean options can be supplied inline.

Note: By default, all tracking options are enabled.

Methods#

eventTrackingOptions(): Promise<InitializationTrackingOptions>#

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';

// The initialize method and getter use the native-spec tracking-options type.
type InitializationTrackingOptions = NonNullable<Parameters<typeof StorytellerSdk.initialize>[2]>;

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?, eventTrackingOptions?) Promise<void> Initialize SDK
isInitialized() boolean Check if initialized
isPresentingContent() boolean iOS presentation host state; Android player visibility
currentApiKey() string Get current API key
version() string Get the platform native 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, openReason?) Promise<void> Open story by ID
openStoryByExternalId(externalId, openReason?) Promise<void> Open story by external ID
openPage(id, openReason?) Promise<void> Open story page
openSheet(id) Promise<void> Open sheet by ID
openCategory(category, openReason?) 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, openReason?) Promise<void> Open clip by external ID
openCollectionByExternalId(collectionId, externalId, openReason?) Promise<void> Cross-platform alias for openClipByExternalId
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(collectionIdOrCategoryIds) Promise<number> iOS collection count (string); Android category count (string or array)
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<InitializationTrackingOptions> Get tracking options

Legacy Storyteller Methods (v10.x)#

The reference below reflects historical declarations. In the checked v10.8.2 package, the declared boolean openDeeplink callback differs from native responses: iOS sends a result object and Android reports only errors. See the legacy deep-link example for runtime-safe handling.

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.