Skip to content

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.

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. 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 by using the initialize(apiKey: String, userInput: StorytellerUserInput) 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")

   Task {
      do {
            try await Storyteller.shared.initialize(apiKey: <apiKey>, userInput: userInput)
      } catch {
            // handle 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

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()