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 and subtitle. 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.

Showcase examples#

Usage#

You can integrate Storyteller Cards into your app using Jetpack Compose.

Jetpack Compose#

For Jetpack Compose, use the StorytellerCard composable.

  1. Data Model: Create a StorytellerCardDataModel object, specifying the collectionId for the Card collection you want to display. 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. State: Initialize a StorytellerCardState using rememberStorytellerCardState() to manage the card's state and reload functionality.
  3. View: Create the StorytellerCard composable, passing in the StorytellerCardDataModel instance and state.
  4. Delegate (Optional): Provide an optional StorytellerCardViewDelegate to handle events like onDataLoadComplete. This allows you to react to data loading success or failure (e.g., by hiding the component).
import androidx.compose.runtime.Composable
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import com.storyteller.ui.compose.components.cards.StorytellerCard
import com.storyteller.ui.compose.components.cards.StorytellerCardDataModel
import com.storyteller.ui.compose.components.cards.StorytellerCardViewDelegate
import com.storyteller.ui.compose.components.cards.rememberStorytellerCardState
import com.storyteller.domain.entities.StorytellerError

@Composable
fun MyCardSection() {
    val dataModel = StorytellerCardDataModel(
        collectionId = "card-collection-id",
        context = mapOf("placementId" to "home_card", "location" to "Home")
    )
    val cardState = rememberStorytellerCardState(dataModel.collectionId)

    val cardViewDelegate = remember {
        object : StorytellerCardViewDelegate {
            override fun onDataLoadComplete(success: Boolean, error: StorytellerError?, dataCount: Int) {
                if (!success) {
                    // Example: update your UI state here (e.g., hide this section on failure).
                }
            }
        }
    }

    StorytellerCard(
        dataModel = dataModel,
        state = cardState,
        delegate = cardViewDelegate,
        modifier = Modifier
    )

    // Optional: Add a reload button
    Button(onClick = { cardState.reloadData() }) {
        Text("Reload Card")
    }
}

Reloading#

The StorytellerCardState provides a reloadData() 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.

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:

  • 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 (optional): Vertical spacing between the headings block and the button. When omitted, Android preserves the previous effective gap of style.padding * 2.
  • style.dynamicTypeEnabled (default: true): Whether cards typography participates in Android Dynamic Type scaling. When false, cards keep fixed text sizes, line heights, and letter spacing regardless of system font scale.
  • 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: 28): Line height for the heading.
  • 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: 21): Line height for the subheading.
  • 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.
  • 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.

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 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, otherwise the resolved button title below-content color when present, falling back to {theme.colors.black.primary} in light mode and {theme.colors.white.primary} in dark mode): Color of the button outline/border.
  • 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.