Quickstart Guide

This is a developers' guide for setting up Storyteller for native iOS apps. This guide will cover the basic technical steps for initializing the Storyteller SDK, authenticating a user, and adding a StorytellerRowView to your app.


You can use the Storyteller Swift Sample App to help you set up Storyteller in your iOS app.

How to Add the SDK to Your Project

Before you can add the iOS SDK to your app, you will need to obtain an API Key. This is a secret key used to authenticate the SDK in your app. Throughout this document it will be marked as [APIKEY].

SDK Installation


The iOS SDK can be included in your project using CocoaPods. If you are having problems with CocoaPods check out the troubleshooting guide.

After setting up CocoaPods:

  1. Update the Podfile to include the SDK

    source 'https://github.com/getstoryteller/storyteller-sdk-ios-podspec.git'
    source 'https://github.com/CocoaPods/Specs.git'
    target 'MyAwesomeApp' do
       # Pods for MyAwesomeApp
       pod 'StorytellerSDK'

Note: The source line is important as the Storyteller SDK is distributed through our own host rather than being hosted through CocoaPods.

  1. Download and install all pods specified in the Podfile

    pod install

After installing the Podfile, an Xcode workspace (MyAwesomeApp.xcworkspace) will be generated. Make sure to always open it instead of the project file (MyAwesomeApp.xcodeproj) when building your projects.


Another way of integrating the iOS SDK is using XCFrameworks.

Make sure you are using:

  1. Make sure you are using:

       Xcode 11.x
       Swift 5.1 and above
  2. Download zipped binaries from here, unzip and add them to your project files.

  3. Ensure that in Frameworks and Libraries, in your app's target section, “Embed & Sign” is selected for each of the newly added .xcframework files.

Swift Package Manager

The SDK can be included in your project as a Swift Package dependency.

  1. Click File -> Add Packages...

  2. Paste https://github.com/getstoryteller/storyteller-sdk-swift-package into the screen prompt.

The SDK will appear as a new dependency in the Swift Package Dependencies section inside your Project Navigator.

SDK Initialization

Before using the iOS SDK in your app, initialize a Storyteller shared instance by using the initialize(apiKey: String, userInput: UserInput, onComplete: (Void) -> Void, onError: (Error) -> Void) method.

Note: It is recommended to do this inside your AppDelegate's application:didFinishLaunchingWithOptions: method

    import StorytellerSDK


    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
        // Override point for customization after application launch.

        let userInput = UserInput(externalId: "user-id")

        Storyteller.sharedInstance.initialize(apiKey: <apiKey>, userInput: userInput onComplete: {
            // Do something on completion...
        }, onError: { error in
            // Handle the error

        return true

Initialization errors:

  • invalidAPIKeyError: when an invalid API key is used
  • networkError: when the call to load the settings for the SDK fails (i.e. a non-success HTTP status code is returned)
  • networkTimeoutError: when the call to load the settings for the SDK times out
  • jsonParseError: when a malformed settings response is received from the server

Implementing StorytellerDelegate Callbacks

Storyteller has callbacks for events which can be implemented, see StorytellerDelegate for more details.


You can optionally use UserInput to authenticate a user on the API. It takes the following parameter:

  • userInput: details of the user to be authenticated

The UserInput model contains:

  • externalId: ID that uniquely identifies the user, this is normally a UUID string
    let userInput = UserInput(externalId: "user-id")

For more information about Users and External IDs please see Working with Users

Adding a StorytellerRowView

The StorytellerRowView can be added to your app using a Storyboard or in code.


  1. Add a View to your Storyboard from the Objects Library

  2. Select the View. In the Identity Inspector tab, under the Custom Class section, enter StorytellerRowView as Class name and Storyteller as Module name

  3. (Optional) Customize the View in the Attributes Inspector, under the Storyteller Row View section, see StorytellerRowView section for more details.


  1. Create a StorytellerRowView instance

       let storytellerRow = StorytellerRowView()
  2. Add the created view to the view hierarchy

  3. Finally you have to call reloadData


Further Reading

Customizing StorytellerRowView

The StorytellerRowView can be customized and provides methods for interactive functionality, see the StorytellerRowView section for more details.

Customizing StorytellerGridView

The StorytellerGridView can be customized and provides methods for interactive functionality, see the StorytellerGridView section for more details.

Forward Arrow