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 = hashMapOf("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) {
                    println("Card data loaded successfully!")
                } else {
                    println("Card data failed to load: ${error?.message}")
                }
            }
        }
    }

    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.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. The default applies when text is displayed on the background asset. When text is displayed below the background, the default color is {theme.colors.black.primary} in light mode and {theme.colors.white.primary} in dark mode.
  • 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. The default applies when text is displayed on the background asset. When text is displayed below the background, the default color is {theme.colors.black.secondary} in light mode and {theme.colors.white.secondary} in dark mode.
  • 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} for text on image, {theme.colors.black.primary} for text below image in light mode, {theme.colors.white.primary} for text below image in dark mode): Text color for the button. If not specified or null, uses the same color logic as the outline color.
  • 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, {theme.colors.black.primary} for text below image in light mode, {theme.colors.white.primary} for text below image 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.