Configuring a Storyteller


The Storyteller can be customized using props:

interface StorytellerSdkInterface {
  isInitialized(callback: (result: Boolean) => void): void;
  isPlayerVisible(callback: (result: Boolean) => void): void;
  customInstanceHost(callback: (result: string) => void): void;
  currentUserId(callback: (result: string) => void): void;
  currentApiKey(callback: (result: string) => void): void;
  version(callback: (result: string) => void): void;

  setTheme(theme: Theme): void;
  setAdsResult(result: { ads: Array<ClientAd>; error: Error | null }): 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;

    apiKey: string,
    externalId: string,
    customInstanceHost: string,
    callback: (result: Boolean, message: string) => void
  ): void;

Get-only Attributes

These attributes reflect static properties from the native Storyteller object.

  • isInitialized - checks if Storyteller has been successfully initialized
  • isPlayerVisible - checks if Story is being presented at the moment
  • customInstanceHost - custom instance hosting API
  • currentUserId - current user ID
  • currentApiKey - current API key set by initialize(apiKey: String, onComplete: () -> Void, onError: (Error) -> Void)
  • version - current SDK version


The appearance of the SDK can be customized by setting the theme property. For more information, please read Themes.

  • setTheme - sets the default fallback theming style used to render Story items in lists and activities launched from a list.


Ads can be integrated through the backend API or by the integrating app. When it is done by the integrating app the user needs to call setAdsResult. For more information, please read Ads.

  • setAdsResult - sets ads result after receiving callback from delegate method onGetAdsForList.

Deep Links

Deep links are opened by calling functions on Storyteller object and will open just one Story independently from the list component rendered on the app.

  • openDeeplink - opens a deep link from a URL.
  • openStory - opens a deep link with a Story ID.
  • openPage - opens a deep link with a Page ID


initialize(apiKey: string, externalId: string, customInstanceHost: string, callback: (result: Boolean, message: string) => void)

The initialize method is required to be called for Storyteller to work. It is recommended to fire this method as soon as possible in the app lifecycle.


  • apiKey - API key provided by the Storyteller team
  • externalId - ID of the user to be authorized
  • customInstanceHost - custom instance hosting API
  • callback - called when initialization has finished with either success or failure


A StorytellerDelegate has methods for managing Storyteller Story events.

To receive events from delegate, you need to subscribe the following listeners ON_USER_ACTIVITY_OCCURRED, USER_NAVIGATED_TO_APP, GET_ADS_FOR_LIST. You can get these from constants published by Storyteller object.

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

Then attach listeners to appropriate events:

const storytellerEvt = new NativeEventEmitter(Storyteller);
storytellerEvt.addListener(ON_USER_ACTIVITY_OCCURRED, this._onUserActivityOccurred);
storytellerEvt.addListener(USER_NAVIGATED_TO_APP, this._onUserNavigatedToApp);
storytellerEvt.addListener(GET_ADS_FOR_LIST, this._onGetAdsForList);

_onUserActivityOccurred = (body: { type: EventType; data: UserActivityData; }) => {
    console.log(`ActivityOccurred\n` + `type: ${body.type}, data: ${JSON.stringify(}`);

_onUserNavigatedToApp = (body: { url: string }) => {
    console.log(`UserNavigatedToApp\n` + `url: ${body.url}`);

_onGetAdsForList = (body: { stories: [ClientStory] }) => {
    console.log(`GetAdsForList\n` + `stories: ${JSON.stringify(body.stories)}`);
    Storyteller.setAdsResult({ ads: [adExample], error: null });

You can find more information about Storyteller Delegate on Android and iOS

Forward Arrow