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#

The code samples below show how to use the StorytellerHome component in both SwiftUI and UIKit. It includes a pull-to-refresh (PTR) mechanism, but you can also use the reloadData method to refresh data on your side.

Step 1: Create a configuration object#

Begin by constructing a StorytellerHomeConfiguration. During the initialization process, pass the homeId parameter into the model's configuration. 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.
var 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"
  ]
)

Step 2: Using SwiftUI#

To display the data, initialize a view and supply it with the configuration object that was constructed at the first step. The view includes built-in support for the pull-to-refresh feature, which is available starting with iOS version 15.

struct ContentView: View {
  // Initialize model with configuration
  @State var model = StorytellerHomeModel(configuration: config)

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

Step 3: Using UIKit#

To display the data, initialize a view and supply it with the configuration object that was constructed at the first step. Pass the model's configuration parameters to the view to ensure it is appropriately set up with the necessary data context.

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

    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)
    ])
  }
}