Skip to content

Storyteller Cards#

Storyteller Cards are flexible, themeable components designed to promote content or direct users to key sections within your app. They can display a background image or video, along with an optional title, subtitle, and button. Tapping on a Card can trigger various actions, such as opening a specific Story, a Story Category, a Clip, a Clip Collection or any other action defined in the CMS. The server or personalization engine can choose which Cards to return for a given user.

Cards currently support 1:1, 2:3, 3:4, 4:5, 9:16, 16:9, and 4:1 aspect ratios from CMS payloads.

Usage#

You can integrate Storyteller Cards into your app using either SwiftUI or UIKit.

SwiftUI#

For SwiftUI, use the StorytellerCard view component.

  1. Configuration: Create a StorytellerCardConfiguration object, specifying the collectionId for the Card collection you want to display. You can also provide optional context data for analytics attribution. When configured, context will be included in all analytics events when users interact with the Card. See Analytics for more details.
  2. Model: Initialize a StorytellerCardModel (which conforms to ObservableObject) with the configuration.
  3. View: Create the StorytellerCard view, passing in the StorytellerCardModel instance.
  4. Actions (Optional): Provide an optional callback closure to the StorytellerCard initializer to handle events like onDataLoadComplete. This allows you to react to data loading success or failure (e.g., by hiding the component).
import SwiftUI
import StorytellerSDK

@available(iOS 14.0, *)
struct SwiftUIView: View {
    @StateObject private var cardModel = StorytellerCardModel(
        configuration: StorytellerCardConfiguration(
            collectionId: "card-collection-id",
            context: ["source": "hero-banner"]
        )
    )

    var body: some View {
        VStack {
            Text("Storyteller Card Section")
            StorytellerCard(model: cardModel) { action in
                switch action {
                case .onDataLoadComplete(let result):
                    switch result {
                    case .success:
                        print("Card data loaded successfully!")
                    case .failure(let error):
                        print("Card data failed to load: \(error.localizedDescription)")
                    }
                @unknown default:
                    break
                }
            }

            Button("Reload Card") {
                cardModel.reload()
            }
        }
        .padding()
    }
}

See the Showcase StorytellerCard integration in StorytellerItemView.

See the Showcase card callback handling in StorytellerItemView.cardAction.

UIKit#

For UIKit, use the StorytellerCardView class, which subclasses UIView.

  1. Configuration: Create a StorytellerCardConfiguration with the desired collectionId. You can also provide optional context data for analytics. When configured, context will be included in all analytics events when users interact with the Card. See Analytics for more details.
  2. View Initialization: Instantiate StorytellerCardView using the configuration.
  3. Delegate (Optional): Assign an object conforming to StorytellerCardViewDelegate to the view's delegate property to receive callbacks like onDataLoadComplete.
  4. Add to View Hierarchy: Add the StorytellerCardView instance as a subview.
class CardView: UIView, StorytellerCardViewDelegate {

    private var storytellerCardView: StorytellerCardView?

    // ...

    func configure(with collectionId: String, delegate: StorytellerCardViewDelegate?) {
        let configuration = StorytellerCardConfiguration(
            collectionId: collectionId,
            context: [
                "source": "hero-banner",
            ]
        )
        let cardView = StorytellerCardView(configuration: configuration)
        cardView.delegate = delegate

        addSubview(cardView)
        // Add constraints

        self.storytellerCardView = cardView
    }

    func reloadCard() {
        storytellerCardView?.reload()
    }

    nonisolated func onDataLoadComplete(result: Result<Void, Error>) {
        // Respond to the load result as needed.
    }
}

For UIKit integration patterns using table view cells, see the CocoaPods sample in MultipleListsDataSource.

We also provide cells to include inside collection and table views - StorytellerCardCollectionViewCell and StorytellerCardTableViewCell. They also follow the above pattern to setup.

Reloading#

Both StorytellerCardModel (for SwiftUI) and the UIKit flavours provide a reload() method. Call this method to manually trigger a refresh of the Card data from the server.

Viewed/Tapped Ordering#

In the CMS you can make Card collections be ordered based on viewed or tapped status, so that once a Card is viewed/tapped, the next Card from the collection will be shown to the user. This will enable users to always see fresh content.

Video Card Audio#

Video Cards start from the Cards audio behavior in tenant settings. For the usual muted-toggle setup, the active video Card shows a mute/unmute control and starts muted. The selected Cards audio state is shared across the current Cards surface, so if a user unmutes one video Card, newly active video Cards stay unmuted until the user mutes again or an audio interruption occurs.

Only the active video Card can be audible. Inactive video Cards stay muted, and image Cards do not show an audio control. If the API marks a video Card as having no audio, the active Card does not show an audio control and remains muted.

Cards audio behavior is controlled by the CMS/API settings theme under theme.behavior.cards:

  • showMuteToggle: set true to show the toggle for active audio-capable video Cards. False, nil, or missing keeps Cards muted with no icon.
  • persistMuteState: set true to persist the user's Cards mute choice. False, nil, or missing keeps Cards state session-scoped.
  • defaultMuteState: uses soundOff, soundOn, or respectDeviceSilentToggle. Missing, nil, or unrecognized values default to soundOff for Cards.

Theming#

Card appearance and behavior are primarily configured directly within the Storyteller CMS for each Card Collection. The following properties can be configured in the CMS and influence the Card's presentation and behaviour:

Button Behavior#

  • Button positioning: Buttons are optional visual elements that follow the textOverContent property:
  • When textOverContent = true: Button appears on the card (overlaying the content), positioned below the title/subtitle
  • When textOverContent = false: Button appears below the card (below the title/subtitle section)
  • Button functionality: Buttons do not change the tappability of Cards - the entire card remains tappable and executes the same action as the button when tapped
  • Button text: The button text is defined in the Card data, not the theme

  • Button content inset: Buttons apply a built-in horizontal content inset when the button text is edge-aligned (start or end), using the resolved style.padding value so the label does not sit flush against the border.

  • style.textLengthMode (default: truncate): How text that exceeds the available space is handled.

  • truncate: Display text at the specified size; truncate with an ellipsis (...) if it doesn't fit.
  • resize: Start at the specified text size and reduce the font size until the text fits (up to two lines for heading and subheading).
  • style.textAlignment (default: start): Horizontal alignment of the heading and subheading. Can be start, center, or end.
  • style.padding (default: 12): Inner padding around the text content. For full-bleed cards ( marginHorizontal = 0) with text below the image and all cards with text on the image, padding is applied to all sides of the text. For cards with text below the image where marginHorizontal > 0, padding is applied only to the top and bottom of the text.
  • style.marginHorizontal (default: 0): Horizontal margin around the card. 0 means full-bleed.
  • style.cornerRadius (default: {theme.primitives.cornerRadius}): Corner radius of the card. The application depends on marginHorizontal and text position. Not applied for full-bleed cards (marginHorizontal=0) with text below the image. Applied to the image for cards with text below the image and marginHorizontal > 0. Applied to the whole card for cards with text on the image and marginHorizontal > 0.
  • style.headingsSpacing (default: 3): Vertical spacing between the heading and subheading.
  • style.buttonSpacing (default: 12): Vertical spacing before the button when a card button is present. In the common title/subtitle case, this is the spacing between the headings block and the button.
  • style.dynamicTypeEnabled (default: true): Whether cards typography participates in Dynamic Type scaling. When false, heading, subheading, and button text use fixed font sizes and fixed line-height behavior.
  • style.backgroundColorLight (optional): Light-mode background color for the text container when textOverContent = false and the card is full-bleed (marginHorizontal = 0).
  • style.backgroundColorDark (optional): Dark-mode background color for the text container when textOverContent = false and the card is full-bleed (marginHorizontal = 0).
  • style.heading.font (default: {theme.customFont}): Font family for the heading.
  • style.heading.textSize (default: 22): Font size for the heading.
  • style.heading.lineHeight (default: nil): Line height for the heading. If not specified, the font's default line height is used.
  • style.heading.textCase (default: default): Text case transformation (upper, lower, default).
  • style.heading.letterSpacing (default: 0): Letter spacing for the heading.
  • style.heading.textColor (default: {theme.colors.white.primary}): Text color for the heading when text is displayed on the background asset.
  • style.heading.textBelowContentColorLight (optional): Light-mode heading text color override when textOverContent = false.
  • style.heading.textBelowContentColorDark (optional): Dark-mode heading text color override when textOverContent = false.
  • style.subHeading.font (default: {theme.customFont}): Font family for the subheading.
  • style.subHeading.textSize (default: 16): Font size for the subheading.
  • style.subHeading.lineHeight (default: nil): Line height for the subheading. If not specified, the font's default line height is used.
  • style.subHeading.textCase (default: default): Text case transformation (upper, lower, default).
  • style.subHeading.letterSpacing (default: 0): Letter spacing for the subheading.
  • style.subHeading.textColor (default: {theme.colors.white.secondary}): Text color for the subheading when text is displayed on the background asset.
  • style.subHeading.textBelowContentColorLight (optional): Light-mode subheading text color override when textOverContent = false.
  • style.subHeading.textBelowContentColorDark (optional): Dark-mode subheading text color override when textOverContent = false.

Button Theme Properties#

  • style.button.title.font (default: uses heading font): Font family for the button text. If not specified or null, uses the heading font with the button's text size and line height.
  • style.button.title.textSize (default: 16): Font size for the button text.
  • style.button.title.lineHeight (default: 21): Line height for the button text.
  • style.button.title.textCase (default: default): Text case transformation for the button text (upper, lower, default).
  • style.button.title.letterSpacing (default: 0): Letter spacing for the button text.
  • style.button.title.textColor (default: {theme.colors.white.primary}): Text color for the button when text is displayed on the background asset.
  • style.button.title.textBelowContentColorLight (optional): Light-mode button text color override when textOverContent = false.
  • style.button.title.textBelowContentColorDark (optional): Dark-mode button text color override when textOverContent = false.
  • style.button.backgroundColor (optional): Background color of the button. If not set, the button will have a transparent background with an outline.
  • style.button.outlineColor (default: {theme.colors.white.primary} for text on image, resolved style.button.title.textBelowContentColorLight / style.button.title.textBelowContentColorDark for text below image when provided, otherwise {theme.colors.black.primary} in light mode and {theme.colors.white.primary} in dark mode): Color of the button outline/border. If not specified or null, it follows the theme defaults for text-over-content cards and matches the resolved button title color for text-below-content cards.
  • style.button.outlineWidth (default: 1): Width of the button outline/border in points.
  • style.button.cornerRadius (optional, default: {theme.primitives.cornerRadius}): Corner radius of the button. If null or not set, falls back to the theme's default corner radius.
  • style.button.textAlignment (default: uses card textAlignment): Text alignment for the button text. If not specified or null, uses the card's text alignment setting.

Behavior Properties#

  • behavior.reloading.reloadOnExit (default: true): Whether the Card Collection reloads after returning from tapping a Card (e.g., after dismissing the Story/Clip Player).
  • behavior.reloading.reloadOnForeground (default: true): Whether the Card Collection reloads when the app comes to the foreground.