Skip to content

iOS 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 StorytellerStoriesRowView to your app.

For tvOS integrations, use the dedicated tvOS Guide.

Resources#

You can use the Storyteller Swift Showcase 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#

CocoaPods#

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'

use_frameworks!

target 'MyAwesomeApp' do
   # Pods for MyAwesomeApp
   pod 'StorytellerSDK'
end

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

2. 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.

XCFrameworks#

Another way of integrating the iOS SDK is using XCFrameworks.

  1. Make sure you are using Xcode 15.x or above
  2. Download zipped binaries from here, unzip and add them to your project files.
  3. Add Lottie 4.5.2 or later, below 5.0, to the same app target. CocoaPods and Swift Package Manager integrations add this automatically, but manual XCFramework integrations must embed it explicitly.
  4. 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 Storyteller by calling Storyteller.shared.initialize(apiKey:userInput:eventTrackingOptions:).

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

import StorytellerSDK

...

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

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

    Task {
        do {
            try await Storyteller.shared.initialize(apiKey: "[APIKEY]", userInput: userInput)
        } catch {
            // handle error
        }
    }

    return true
}

See the Showcase initialization flow in StorytellerService.setup where the SDK is initialized with StorytellerEventTrackingOptions.

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

Storyteller.shared.initialize is asynchronous, so Storyteller.shared.isInitialized will change its value to true only when the asynchronous call finishes. For any subsequent Storyteller.shared.initialize call, Storyteller.shared.isInitialized will already be true.

Implementing StorytellerDelegate Callbacks#

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

StorytellerUserInput#

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

  • userInput: details of the user to be authenticated

The StorytellerUserInput model contains:

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

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

Adding a StorytellerStoriesRowView#

The StorytellerStoriesRowView can be added to your app with coding views.

Code#

1. Create a StorytellerStoriesRowView instance

let storytellerRow = StorytellerStoriesRowView()

2. Add the created view to the view hierarchy

view.addSubview(storytellerRow)

3. Finally, you have to call reloadData

storytellerRow.reloadData()