iOS SDK

This guide describes how to add and use StorySDK to your iOS app.

Installation

Swift Package Manager

To install StorySDK using Swift Package Manager, follow these steps:

1. Open your project in Xcode and go to File > Swift Packages > Add Package Dependency.

2. In the search field, enter https://github.com/StorySDK/ios-sdk.git and click Next.

3. Select the version rule "Up to Next Major" and enter "1.0.0" in the text field.

4. Click Next and then Finish.

CocoaPods

To install StorySDK using CocoaPods, add the following to your Podfile:

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '13.0'
use_frameworks!

target 'MyApp' do
  pod 'StorySDK', '~> 1.0'
end

Then, run the following command:

$ pod install

Carthage

To install StorySDK using Carthage, add the following to your Cartfile:

github "StorySDK/ios-sdk" ~> 1.0

Then, run the following command:

$ carthage update

Usage

Make sure to import the project wherever you may use it:

import StorySDK

Setup Story Witget

To use the SDK, you need to obtain a token from the StorySDK dashboard. You can find your token in the Settings section of the dashboard at https://app.storysdk.com/dashboard/.

var config = SRConfiguration(sdkId: "[YOUR_SDK_ID]")
StorySDK.shared.configuration = config

Further we consider that

storySdk = StorySDK.shared

Integration

Define Groups Widget in your UIViewController

private var widget: SRStoryWidget!

Get information about the SDK application:

storySdk.getApps { result in
    switch result {
    case .success(let app):
        print(app)
    case .failure(let error):
        print("Error:", error.localizedDescription)
    }
}

Get the groups of the app and then call widget.load():

storySdk.getGroups { result in
    switch result {
    case .success(let groups):
        print(groups)
        // Convenient place to call widget loading
        widget.load()
    case .failure(let error):
        print("Error:", error.localizedDescription)
    }
}

You can use the Groups Widget to display groups of stories in your app. Create and add the widget to your view hierarchy:

widget = SRStoryWidget()
widget.delegate = self
widget.translatesAutoresizingMaskIntoConstraints = false
view.addSubview(widget)

Layout widget:

NSLayoutConstraint.activate([
    widget.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),
    widget.widthAnchor.constraint(equalTo: view.widthAnchor),
    widget.heightAnchor.constraint(equalToConstant: 120.0),
])

Conform SRStoryWidgetDelegate protocol and implement openStories action:

func openStories(index: Int, groups: [SRStoryGroup], in vc: UIViewController,
                 delegate: SRStoryWidgetDelegate?, animated: Bool) {
    // SRNavigationController allows you to open specific group of stories
    let controller = SRNavigationController(index: index, groups: groups,
                                            backgroundColor: UIColor.gray)
    vc.present(controller, animated: animated)
}

// You can handle errors and taps on a group by conforming the `SRStoryWidgetDelegate` protocol
extension YourViewController: SRStoryWidgetDelegate {
    func onWidgetErrorReceived(_ error: Error, widget: SRStoryWidget) {}
    func onWidgetGroupPresent(index: Int, groups: [SRStoryGroup], widget: SRStoryWidget) {
        guard groups.count > index else { return }
        
        openStories(index: index, groups: groups, in: self, delegate: self, animated: true)
    }
    
    func onWidgetGroupsLoaded(groups: [SRStoryGroup]) {}
    func onWidgetGroupClose() {}
    func onWidgetMethodCall(_ selectorName: String?) {}
    func onWidgetLoading() {}
    func onWidgetLoaded() {}
}

When your app is ready to load groups, call widget.load().

⚡️ Please note that in order for stories to be displayed in the SDK, they need to be published.

Onboarding

To add onboarding to your app, follow these steps:

1. First, create an onboarding in the Onboarding section of the dashboard at https://app.storysdk.com/dashboard/ and copy your Onboarding ID from Onboarding Settings

2. Then conform SRStoryWidgetDelegate protocol and fill some methods such implementation (here we've added dismiss func that call paywall screen and rate func that request rate the app on second onboarding screen, this is a standard approach, you can implement similar or completely different behavior as you wish)

import StorySDK
import StoreKit

extension YourViewController: SRStoryWidgetDelegate {
    func onWidgetErrorReceived(_ error: Error, widget: SRStoryWidget) {}
    func onWidgetGroupPresent(index: Int, groups: [SRStoryGroup], widget: SRStoryWidget) {
        guard groups.count > index else { return }
        let group = groups[index]
        
        let controller = SRStoriesViewController(group, asOnboarding: true)
        controller.view.backgroundColor = UIColor.gray
        controller.delegate = self
        
        present(controller, animated: false)
    }
    
    func onWidgetGroupsLoaded(groups: [SRStoryGroup]) {
        widget?.openAsOnboarding(groupId: Constants.onboardingGroup)
    }

    func onWidgetGroupClose() {
        dismiss()
    }

    func onWidgetMethodCall(_ selectorName: String?) {
        guard let selectorName = selectorName else { return }
        
        let sel = NSSelectorFromString(selectorName)
        if canPerformAction(sel, withSender: self) {
            performSelector(onMainThread: sel, with: nil, waitUntilDone: true)
        }
    }

    func onWidgetLoading() {}
    func onWidgetLoaded() {}

    @objc func dismiss() {
        let vc = YourPaywallViewController(paywallID: "YOUR_PAYWALL_ID")
        let pvc = presentedViewController ?? self
        pvc.present(vc, animated: false)
    }
    
    @objc func scrollNext() {
        // NB: this method is called every time you move to the next story in onboarding
        // add a condition so that rate is called only once
        rate()
    }

    private func rate() {
        guard let scene = UIApplication.shared.connectedScenes
            .first(where: { $0.activationState == .foregroundActive }) as? UIWindowScene else {
            return
        }
        
        SKStoreReviewController.requestReview(in: scene)
    }
}

1. Caching (optional but useful step)

Often, to load stories faster, for example, to build onboarding in an app especially if you have video files in your stories, you may need to get them without waiting for loading from the server. In this case, caching will help you:

Caching is provided using a couple of lanes fastlane and consists of a few simple steps:

Install fastlane first (by running the fastlane command in the root of the project) and then follow the step above.

After run

fastlane prepare_story_cache group:"groupId"

where groupId is the id of the group that contains the media files you want to cache. If successful, you will see your media files in the "fastlane/cached" directory.

Now it’s enough to add these files to the Xcode project, like resources via Add Files to... action so that they end up in the bundle of your app, that’s all - in this form StorySDK can already see them. Caching is now complete.

Direct API

To show the stories of a selected group using the top view controller:

storySdk.getStories(group) { [weak self] result in
    switch result {
    case .success(let stories):
        guard !stories.isEmpty else { break } // No active stories
        // Present stories
    case .failure(let error):
         print("Error:", error.localizedDescription)
    }
}

Configuration

a) Set language

storySdk.configuration.language = "en"

b) Set full screen on / off

storySdk.configuration.needFullScreen = true / false

c) Show title on / off

storySdk.configuration.needShowTitle = true / false

d) Filter (hide) onboarding on / off

storySdk.configuration.onboardingFilter = true / false

e) Set show time duration for each story

storySdk.configuration.storyDuration = 10 // 10 seconds

f) Set progress color

storySdk.configuration.progressColor = .green

Advanced

StorySDK has a nice default loader. If you prefer to replace it with another one, that it also possible. Ensure your custom loader confirms SRLoader protocol:

public protocol SRLoadingIndicator: AnyObject {
    func startAnimating()
    func stopAnimating()
}

public protocol SRLoader: SRLoadingIndicator where Self: UIView {}

You can just remove the loader if you don't need it:

storySdk.configuration.loader = nil

Or use the your own custom loaders, here are some examples:

NVExtentedActivityIndicatorView

    import UIKit
    import StorySDK
    import NVActivityIndicatorView

    class NVExtentedActivityIndicatorView: UIView, SRLoader {
        var indicator: NVActivityIndicatorView = NVActivityIndicatorView.ballSpin()
        
        init() {
            super.init(frame: CGRect(x: 0, y: 0, width: 72, height: 72))
            addSubview(indicator)
        }
        
        required init?(coder: NSCoder) {
            fatalError("init(coder:) has not been implemented")
        }
        
        func startAnimating() {
            indicator.startAnimating()
        }
        func stopAnimating() {
            indicator.stopAnimating()
        }
    }

Lottie

import UIKit
import StorySDK
import Lottie

class LottieLoadingIndicatorView: UIView, SRLoader {
    var indicator: LottieAnimationView!
    
    init() {
        super.init(frame: CGRect(x: 0, y: 0, width: 24, height: 24))
        
        indicator = LottieAnimationView(name: "equalizer-icon")
        addSubview(indicator)
    }
    
    required init?(coder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }
    
    func startAnimating() {
        indicator.play()
    }
    
    func stopAnimating() {
        indicator.stop()
    }
}

or even

Rive

import UIKit
import StorySDK
import RiveRuntime

class RiveLoadingIndicatorView: UIView, SRLoader {
    var model = RiveViewModel(fileName: "Screencut_Logo_Loader")
    var indicator: RiveView!
    
    init() {
        super.init(frame: CGRect(x: 0, y: 0, width: 80, height: 80))
        
        indicator = model.createRiveView()
        addSubview(indicator)
        indicator.frame = bounds
    }
    
    required init?(coder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }
    
    func startAnimating() {
        model.play()
    }
    
    func stopAnimating() {
        model.stop()
    }
}

---

In additional you also can handle custom method defined in dashboard (using onWidgetMethodCall from SRStoryWidgetDelegate protocol) for instance define action on onboarding close event or request rate your during onboarding. Like this:

    func onWidgetMethodCall(_ selectorName: String?) {
        guard let selectorName else { return }
        
        switch selectorName {
        case "onboarding-finished":
            setupFinished()
        case "scrollNext":
            if !onRateDisplayed {
                onRateDisplayed = true
                rate()
            }
        default:
            break
        }
    }

License

StorySDK is available under the MIT license. See the LICENSE file for more info.

Example project

You can see an example of usage here.