Skip to content

Storyteller Home#

StorytellerHome is a component that allows multiple Stories and Clips Rows or Grids to be embedded in a single screen in your application in a list.

How to Use#

Create one shared configuration, then choose either the SwiftUI or UIKit implementation below. Both routes display the same CMS-configured Home content and support manual refresh through reloadData; pull-to-refresh is available in the SwiftUI component from iOS 15.

Step 1: Create a configuration object#

Begin by constructing a StorytellerHomeConfiguration. Pass this configuration to the model or view for the framework you use. It has the following properties:

  • homeId - an identifier of the home configuration you want to load.
  • theme - an optional theme parameter to be used for styling. If no theme is supplied, the theme set on the Storyteller.shared.theme property is used.
  • uiStyle - an optional parameter for overriding the appearance of the component. Possible values are light, dark, and auto. The default styling is auto and it uses the system setting value.
  • context - optional context data that will be included in analytics callbacks for attribution. This allows you to track which sources drive engagement with your home content. See Analytics for more details.
let theme = StorytellerTheme()
// Customize the theme
let config = StorytellerHomeConfiguration(
    homeId: "YOUR_HOME_ID",
    theme: theme,
    uiStyle: .auto,
    context: [
      "source": "main-tab",
      "user_segment": "premium",
      "variant": "personalized"
  ]
)

Choose Your UI Framework#

The framework routes are alternatives; follow only the tab that matches your app.

Using UIKit#

Create a StorytellerHomeView from the shared configuration and add it to a view hierarchy with non-zero constraints.

For a UIKit sample that renders multiple Storyteller lists in a table view, see the CocoaPods Showcase implementation in MultipleListsViewController.

class MyViewController: UIViewController {
  override func viewDidLoad() {
    super.viewDidLoad()

    let config = StorytellerHomeConfiguration(homeId: "YOUR_HOME_ID")
    let storytellerHomeView = StorytellerHomeView(configuration: config)
    storytellerHomeView.translatesAutoresizingMaskIntoConstraints = false
    view.addSubview(storytellerHomeView)

    // Set up constraints
    NSLayoutConstraint.activate([
        storytellerHomeView.topAnchor.constraint(equalTo: view.topAnchor),
        storytellerHomeView.bottomAnchor.constraint(equalTo: view.bottomAnchor),
        storytellerHomeView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
        storytellerHomeView.trailingAnchor.constraint(equalTo: view.trailingAnchor)
    ])
  }
}

Using SwiftUI#

Create a StorytellerHomeModel from the shared configuration and retain it as view state. The StorytellerHome view includes built-in pull-to-refresh support from iOS 15.

@available(iOS 14.0, *)
struct ContentView: View {
  // Initialize model with configuration
  @StateObject private var model = StorytellerHomeModel(
    configuration: StorytellerHomeConfiguration(homeId: "YOUR_HOME_ID")
  )

  var body: some View {
    StorytellerHome(model: model)
  }
}

Continue Your Integration#