Quickstart Guide

This is a developer's guide for setting up Storyteller for React Native apps. This guide will cover the basic technical steps for initializing the Storyteller SDK, authenticating a user, and adding a Storyteller component to your app.

Installation

Our React Native SDK is distributed through npm. To add it to your current project you only need to run

npm install @getstoryteller/react-native-storyteller-sdk --save

or

yarn add @getstoryteller/react-native-storyteller-sdk

Android

After installation, add the following to your android/build.gradle file.

allprojects {
    repositories {
        mavenCentral()
        mavenLocal()
        maven {
            // All of React Native (JS, Obj-C sources, Android binaries) is installed from npm
            url("$rootDir/../node_modules/react-native/android")
        }
        maven {
            // Android JSC is installed from npm
            url("$rootDir/../node_modules/jsc-android/dist")
        }

        // Required for Storyteller SDK native dependencies
        maven { url 'https://www.myget.org/F/storyteller-android-sdk/maven' }
        jcenter()

        google()
        maven { url 'https://www.jitpack.io' }
        exclusiveContent {
           // We get React Native's Android binaries exclusively through npm,
           // from a local Maven repo inside node_modules/react-native/.
           // (The use of exclusiveContent prevents looking elsewhere like Maven Central
           // and potentially getting a wrong version.)
           filter {
               includeGroup "com.facebook.react"
           }
           forRepository {
               maven {
                   url "$rootDir/../node_modules/react-native/android"
               }
           }
       }
    }
}

iOS

After installation, your Podfile should look like this

require_relative '../node_modules/react-native/scripts/react_native_pods'
require_relative '../node_modules/@react-native-community/cli-platform-ios/native_modules'

platform :ios, '11.0'

target 'MyAwesomeApp' do
  config = use_native_modules!

  use_react_native!(
    :path => config[:reactNativePath],
    # to enable hermes on iOS, change `false` to `true` and then install pods
    :hermes_enabled => false
  )

  target 'MyAwesomeAppTests' do
    inherit! :complete
    # Pods for testing
  end

  # Enables Flipper.
  #
  # Note that if you have use_frameworks! enabled, Flipper will not work and
  # you should disable the next line.
  use_flipper!()

  post_install do |installer|
    react_native_post_install(installer)
    __apply_Xcode_12_5_M1_post_install_workaround(installer)

end

Add the following sources in order to access SDK

source 'https://cdn.cocoapods.org/'
source 'https://github.com/getstoryteller/storyteller-sdk-ios-podspec.git'

Result

Your final Podfile should now look like:

source 'https://cdn.cocoapods.org/'
source 'https://github.com/getstoryteller/storyteller-sdk-ios-podspec.git'

require_relative '../node_modules/react-native/scripts/react_native_pods'
require_relative '../node_modules/@react-native-community/cli-platform-ios/ native_modules'

platform :ios, '11.0'
#use_frameworks!

target 'MyAwesomeApp' do
 config = use_native_modules!

 use_react_native!(
   :path => config[:reactNativePath],
   # to enable hermes on iOS, change `false` to `true` and then install pods
   :hermes_enabled => false
 )

 target 'MyAwesomeAppTests' do
   inherit! :complete
   # Pods for testing
 end

 # Enables Flipper.
 #
 # Note that if you have use_frameworks! enabled, Flipper will not work and
 # you should disable the next line.
 use_flipper!()

 post_install do |installer|
   react_native_post_install(installer)
   __apply_Xcode_12_5_M1_post_install_workaround(installer)
 end

end
  1. Install the native dependencies:

React Native version >= 0.60

Install the native dependencies via CocoaPods by running the following command from your ios directory

pod install

React Native < 0.60

Note: If you haven't already created Bridging Header, then you will need to do it by adding an empty swift file. This will allow compilation of native files written in .swift

Use the React Native CLI to link the native dependencies:

react-native link @getstoryteller/react-native-storyteller-sdk

Then, install them from your ios directory by running the following command:

pod install --repo-update

If you prefer linking manually, check the official guidance on doing so React Native - Linking Libraries to link your libraries that contain native code.

Import Storyteller

Now it is enough to just import Storyteller to your project.

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

and use it in your render function:


constructor(props: any) {
  super(props);
  this._initializeStoryteller()
}

_  _initializeStoryteller = () => {
    Storyteller.initialize({
      apiKey: 'test-key',
      externalId: 'test-user',
      customInstanceHost: '', // URL of custom instance to run API
    },
      (callback: {result: Boolean; message: string}) => {
        console.log(`result: ${callback.result} message: ${callback.message}`);
        this._reloadDataIfNeeded();
      },
    );
  };

 render() {
    return (
      <SafeAreaView style={backgroundStyle}>
        <StatusBar barStyle={isDarkMode ? 'light-content' : 'dark-content'} />
        <ScrollView
          contentInsetAdjustmentBehavior="automatic"
          style={backgroundStyle}>
          <View
            style={{
              flex: 1,
              backgroundColor: isDarkMode ? Colors.black : Colors.white,
            }}>
            <StorytellerRowView
              ref={(ref: any) => {
                if (ref) this.rowRef = ref;
              }}
              style={styles.storyContainer}
 )}

You can find the API Key for your platform in the CMS.

For more information on what to set for your externalUserId, please see the documentation regarding Users.

Typescript

If you are using TypeScript, you can import types and enums used by the libraries for better syntax of code. For example:

import type {
  EventType,
  UserActivityData,
  ClientStory,
  ClientAd,
  Theme,
} from '@getstoryteller/react-native-storyteller-sdk';
import {
  ClientAdActionKind,
  ThemeRowViewStyle,
  ElementAlignment,
  TextAlignment,
} from '@getstoryteller/react-native-storyteller-sdk';

Further Reading

Customizing StorytellerListComponent

The Storyteller component can be customized and provides methods for interactive functionality, see StorytellerListComponent for more details.

PREVIOUS
Forward Arrow