Developers / iOS SDK / Quickstart Guide

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.

Resources

Storyteller Swift Sample 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 Dependencies

Currently, the iOS SDK contains dependencies to the following frameworks:

AsyncDisplayKit
PINCache
PINOperation
PINRemoteImage

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.

If you have already installed CocoaPods, skip to step 2
If you have already set up CocoaPods for your project, skip to step 3

Install CocoaPods
```
gem install cocoapods
```
Set up CocoaPods for your project
```
pod init
pod repo update
```

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

Download and install all pods specified in the Podfile
```
pod install
```

After running pod install, 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.

Note: Our binaries are built using Xcode 12.1 with Swift 5.3. If you need to use a different version, please contact us using [email protected] or reach out to your Storyteller contact.

Carthage

We can provide Carthage version if necessary by contacting [email protected] or your Storyteller contact.

XCFrameworks

Another way of integrating the iOS SDK is using XCFrameworks.

Make sure you are using:
```
   Xcode 11.x
   Swift 5.1 and above
```
Download zipped binaries from here, unzip and add them to your project files.
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 project as a Swift Package dependency.

Click
```
   File -> Add Packages...
```
On newly prompted screen paste link https://github.com/getstoryteller/storyteller-sdk-swift-package. After some loading time SDK will appear as a new dependency in Swift Package Dependencies section inside Project Navigator

Project Setup

Storyteller's share functionality requires access to the user's Photo Library. Apple requires all applications to provide a reason for accessing this feature, so before you start using SDK, add the following key to your Info.plist file:

    <key>NSPhotoLibraryUsageDescription</key>
    <string>$(PRODUCT_NAME) can save images and videos to your Photos library</string>

Note that this is a sample value for this key and should be tailored to meet your app's specific needs.

If you do not wish to use this sharing method, please reach out to your Storyteller contact.

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.

UserInput

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: (Required) id which 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.

Storyboard

Add a View to your Storyboard from the Objects Library
Select the View. In the Identity Inspector tab, under the Custom Class section, enter StorytellerRowView as Class name and Storyteller as Module name
(Optional) Customize the View in the Attributes Inspector, under the Storyteller Row View section, see StorytellerRowView for more details.

Code

Create a StorytellerRowView instance

   let storytellerRow = StorytellerRowView()

Add the created view to the view hierarchy
```
   view.addSubview(storytellerRow)
```
Finally you have to call reloadData
```
   storytellerRow.reloadData()
```

Note: - Before iOS 11, if a StorytellerRowView is the first view in a parent's hierarchy, it needs to have at least a 114pt height or it will not render correctly.