Android SDK: Component Reference

Complete reference for all UI components available in the Digital Card Engine SDK through the UILibrary object.

High-Level Components

CardListView

Full-featured card list with built-in ViewModel, loading states, and error handling.

@Composable
fun UILibrary.CardListView(
    sdk: DigitalCardEngineSDK,
    onCardSelected: (CardListItem) -> Unit = {},
    onAddCard: (() -> Unit)? = null
)

Parameters:

Parameter	Type	Required	Description
`sdk`	`DigitalCardEngineSDK`	Yes	Initialized SDK instance
`onCardSelected`	`(CardListItem) -> Unit`	No	Callback when card is tapped (default: no-op)
`onAddCard`	`(() -> Unit)?`	No	Callback for "Add Card" button (null hides button)

Features:

Automatic card fetching via sdk.getCards()
Loading indicator during fetch
Error state with retry button
Empty state when no cards
"Add Card" action button (optional)
Sorting (primary cards first)

Example:

@Composable
fun CardsScreen(sdk: DigitalCardEngineSDK, navController: NavController) {
    UILibrary.CardListView(
        sdk = sdk,
        onCardSelected = { cardItem ->
            navController.navigate("card/${cardItem.card.receivedCard.giftCardId}")
        },
        onAddCard = {
            navController.navigate("addCard")
        }
    )
}

CardPageView

Combined card overview and transactions view for a full card details screen.

@Composable
fun UILibrary.CardPageView(
    sdk: DigitalCardEngineSDK,
    card: CardEntity
)

Parameters:

Parameter	Type	Required	Description
`sdk`	`DigitalCardEngineSDK`	Yes	SDK instance for MCD/data fetching
`card`	`CardEntity`	Yes	Card to display

Includes:

CardOverview with secure fields (MCD)
TransactionsCardView with recent transactions
EventList with card events
Loading and error states for all sections

Example:

@Composable
fun CardDetailsScreen(
    sdk: DigitalCardEngineSDK,
    cardId: String
) {
    val card = remember { /* fetch card by ID */ }
    
    if (card != null) {
        UILibrary.CardPageView(
            sdk = sdk,
            card = card
        )
    }
}

CardOverview

Detailed card information card with optional secure fields and action buttons.

@Composable
fun UILibrary.CardOverview(
    card: CardEntity,
    properties: CardOverviewProperties = CardOverviewProperties(),
    style: CardOverviewStyleProperties = CardOverviewStyleProperties(),
    styleConfiguration: StyleConfiguration = LocalStyleConfiguration.current,
    isLoading: Boolean = false,
    errorMessage: String? = null,
    onRetry: (() -> Unit)? = null,
    onDetails: (() -> Unit)? = null,
    onLock: (() -> Unit)? = null,
    onManage: (() -> Unit)? = null,
    sdk: DigitalCardEngineSDK? = null
)

Key Parameters:

Parameter	Type	Description
`card`	`CardEntity`	Card to display
`properties`	`CardOverviewProperties`	Display configuration (info level, buttons, etc.)
`style`	`CardOverviewStyleProperties`	Visual styling (padding, radius, etc.)
`sdk`	`DigitalCardEngineSDK?`	Required for MCD secure fields
`onDetails`	`(() -> Unit)?`	"View Details" callback (toggles MCD view)
`onLock`	`(() -> Unit)?`	"Lock Card" callback
`onManage`	`(() -> Unit)?`	"Manage Card" callback

CardOverviewProperties:

data class CardOverviewProperties(
    val cardInfo: CardInfo = CardInfo.Detail,          // Brief | Detail
    val actionButton: Boolean = true,
    val cardStatus: CardStatus = CardStatus.Default,    // Default | Details | Locked
    val cardWidgetStyle: CardWidgetStyle = CardWidgetStyle.Default, // Default | Large | Minimal
    val slider: Boolean = false,
    val showCardDetails: Boolean = true,
    val showActions: Boolean = true,
    val currencySymbol: String? = null
)

Example:

@Composable
fun CustomCardOverview(card: CardEntity, sdk: DigitalCardEngineSDK) {
    var showingDetails by remember { mutableStateOf(false) }
    
    UILibrary.CardOverview(
        card = card,
        properties = CardOverviewProperties(
            cardInfo = CardInfo.Detail,
            cardWidgetStyle = CardWidgetStyle.Large,
            actionButton = true
        ),
        style = CardOverviewStyleProperties(
            externalPadding = 16f,
            radius = 16f
        ),
        sdk = sdk,
        onDetails = { showingDetails = !showingDetails },
        onLock = { /* lock card logic */ },
        onManage = { /* navigate to settings */ }
    )
}

TransactionsCardView

Transactions summary with built-in ViewModel and data fetching.

@Composable
fun UILibrary.TransactionsCardView(
    sdk: DigitalCardEngineSDK,
    card: CardEntity,
    transactionLimit: Int = 5,
    onSeeMoreClick: (() -> Unit)? = null,
    onTransactionClick: ((Transaction) -> Unit)? = null
)

Parameters:

Parameter	Type	Description
`sdk`	`DigitalCardEngineSDK`	SDK for fetching transactions
`card`	`CardEntity`	Card to fetch transactions for
`transactionLimit`	`Int`	Max transactions to show (default: 5)
`onSeeMoreClick`	`(() -> Unit)?`	"See More" callback (defaults to SDK activity)
`onTransactionClick`	`((Transaction) -> Unit)?`	Transaction tap callback (defaults to SDK activity)

Example:

@Composable
fun RecentTransactions(sdk: DigitalCardEngineSDK, card: CardEntity) {
    UILibrary.TransactionsCardView(
        sdk = sdk,
        card = card,
        transactionLimit = 10,
        onSeeMoreClick = { /* navigate to full list */ },
        onTransactionClick = { txn ->
            /* navigate to transaction details */
        }
    )
}

Lower-Level Components

DCECardListView

Customizable card list without built-in data fetching.

@Composable
fun UILibrary.DCECardListView(
    cards: List<CardListItem>,
    isLoading: Boolean = false,
    errorMessage: String? = null,
    properties: CardListViewProperties = CardListViewProperties(),
    style: CardListViewStyleProperties = CardListViewStyleProperties(),
    styleConfiguration: StyleConfiguration = LocalStyleConfiguration.current,
    onCardSelected: (CardListItem) -> Unit = {},
    onAddCard: (() -> Unit)? = null,
    onRetry: (() -> Unit)? = null
)

Use when: You want full control over data fetching and state management.

Example:

@Composable
fun CustomCardList(viewModel: MyCardViewModel) {
    val cards by viewModel.cards.collectAsState()
    val isLoading by viewModel.isLoading.collectAsState()
    
    UILibrary.DCECardListView(
        cards = cards,
        isLoading = isLoading,
        properties = CardListViewProperties(
            title = true,
            cardListStyle = CardListViewStyle.LargeStyle
        ),
        style = CardListViewStyleProperties(
            radius = 16f,
            externalPadding = 20f
        ),
        onCardSelected = { cardItem ->
            viewModel.selectCard(cardItem.card)
        },
        onRetry = {
            viewModel.loadCards()
        }
    )
}

TransactionsCard

Standalone transactions card without data fetching.

@Composable
fun UILibrary.TransactionsCard(
    transactions: List<Transaction>,
    isLoading: Boolean = false,
    errorMessage: String? = null,
    onRetry: (() -> Unit)? = null,
    transactionLimit: Int = 10,
    hasMoreTransactions: Boolean = false,
    onSeeMore: (() -> Unit)? = null,
    properties: TransactionsCardProperties = TransactionsCardProperties(),
    style: TransactionsCardStyleProperties = TransactionsCardStyleProperties(),
    styleConfiguration: StyleConfiguration = LocalStyleConfiguration.current
)

Example:

@Composable
fun TransactionsSummary(transactions: List<Transaction>) {
    UILibrary.TransactionsCard(
        transactions = transactions,
        transactionLimit = 5,
        hasMoreTransactions = transactions.size > 5,
        properties = TransactionsCardProperties(
            title = "Recent Activity",
            showTitle = true
        ),
        style = TransactionsCardStyleProperties(
            externalPadding = 16f,
            radius = 12f
        ),
        onSeeMore = { /* navigate */ }
    )
}

TransactionList

Pure transaction list without container card.

@Composable
fun UILibrary.TransactionList(
    transactions: List<Transaction>,
    isLoading: Boolean = false,
    currencySymbol: String? = null,
    itemLimit: Int = 10,
    hasMoreTransactions: Boolean = false,
    onSeeMore: (() -> Unit)? = null,
    styleConfiguration: StyleConfiguration = LocalStyleConfiguration.current
)

Use when: You want to embed transactions in a custom container.

Example:

@Composable
fun CustomTransactionSection(transactions: List<Transaction>) {
    Column {
        Text("Transactions", style = MaterialTheme.typography.titleLarge)
        
        UILibrary.TransactionList(
            transactions = transactions,
            currencySymbol = "$",
            itemLimit = 20,
            hasMoreTransactions = false
        )
    }
}

EventList

Display card lifecycle events.

@Composable
fun UILibrary.EventList(
    events: List<CardEvent>,
    styleConfiguration: StyleConfiguration = LocalStyleConfiguration.current
)

Example:

@Composable
fun CardEventsSection(events: List<CardEvent>) {
    Column {
        Text("Card Activity", style = MaterialTheme.typography.titleMedium)
        
        UILibrary.EventList(
            events = events.take(10)
        )
    }
}

CardCarousel

Horizontal scrolling card carousel.

@Composable
fun UILibrary.CardCarousel(
    cards: List<CardListItem>,
    selectedIndex: Int,
    onCardClicked: (Int) -> Unit,
    onCenteredIndexChanged: ((Int) -> Unit)? = null
)

Parameters:

Parameter	Type	Description
`cards`	`List<CardListItem>`	Cards to display
`selectedIndex`	`Int`	Currently selected card index
`onCardClicked`	`(Int) -> Unit`	Callback with tapped card index
`onCenteredIndexChanged`	`((Int) -> Unit)?`	Callback when centered card changes (scrolling)

Use when: You want a horizontal card selector/viewer.

Example:

@Composable
fun HorizontalCardSelector(cards: List<CardListItem>) {
    var selectedIndex by remember { mutableStateOf(0) }
    
    Column {
        UILibrary.CardCarousel(
            cards = cards,
            selectedIndex = selectedIndex,
            onCardClicked = { index ->
                selectedIndex = index
            },
            onCenteredIndexChanged = { index ->
                // Update when user scrolls
                selectedIndex = index
            }
        )
        
        // Show details for selected card
        Text("Selected: ${cards[selectedIndex].card.receivedCard.cardLabel}")
    }
}

CardListItemDefaultView

Individual card list item in compact style.

@Composable
fun UILibrary.CardListItemDefaultView(
    card: CardListItem,
    style: CardListViewStyleProperties,
    styleConfiguration: StyleConfiguration,
    onClick: (() -> Unit)? = null,
    showOverline: Boolean = false,
    overlineText: String = "Primary card"
)

Use when: Building a custom card list with individual items.

Example:

@Composable
fun CustomCardList(cards: List<CardListItem>) {
    LazyColumn {
        items(cards) { cardItem ->
            UILibrary.CardListItemDefaultView(
                card = cardItem,
                style = CardListViewStyleProperties(),
                styleConfiguration = LocalStyleConfiguration.current,
                showOverline = cardItem.card.receivedCard.cardLabel == "Primary",
                overlineText = "Primary Card",
                onClick = { /* handle click */ }
            )
            
            Divider()
        }
    }
}

Component Comparison

When to use which component?

Component	Use Case	Data Fetching	State Management
`CardListView`	Quick integration, standard card list	Built-in	Built-in
`DCECardListView`	Custom data/state logic	Manual	Manual
`CardPageView`	Full card details screen	Built-in	Built-in
`CardOverview`	Custom card details layout	Manual	Manual
`TransactionsCardView`	Quick transaction display	Built-in	Built-in
`TransactionsCard`	Custom transactions with own data	Manual	Manual
`TransactionList`	Embed in custom container	Manual	Manual
`CardCarousel`	Horizontal card browser	Manual	Manual

Composition Patterns

Pattern 1: Fully Managed

Use high-level components with built-in data fetching.

@Composable
fun EasyIntegration(sdk: DigitalCardEngineSDK) {
    Column {
        UILibrary.CardListView(
            sdk = sdk,
            onCardSelected = { /* ... */ }
        )
    }
}

Pros: Quick, minimal code Cons: Less control over state/fetching

Pattern 2: Custom ViewModel

Use lower-level components with your own ViewModel.

class CardViewModel(private val sdk: DigitalCardEngineSDK) : ViewModel() {
    var cards by mutableStateOf<List<CardListItem>>(emptyList())
    var isLoading by mutableStateOf(false)
    
    fun loadCards() {
        viewModelScope.launch {
            isLoading = true
            cards = sdk.getCards().map { /* map to CardListItem */ }
            isLoading = false
        }
    }
}

@Composable
fun CustomIntegration(viewModel: CardViewModel) {
    UILibrary.DCECardListView(
        cards = viewModel.cards,
        isLoading = viewModel.isLoading,
        onCardSelected = { /* ... */ },
        onRetry = { viewModel.loadCards() }
    )
}

Pros: Full control, testable Cons: More boilerplate

Pattern 3: Hybrid

Mix high and low-level components.

@Composable
fun HybridApproach(sdk: DigitalCardEngineSDK, card: CardEntity) {
    Column {
        // High-level component
        UILibrary.CardOverview(
            card = card,
            sdk = sdk
        )
        
        // Custom section
        CustomAnalyticsSection(card)
        
        // Low-level component with custom data
        val transactions = remember { /* custom fetch */ }
        UILibrary.TransactionList(
            transactions = transactions
        )
    }
}

Styling All Components

Apply consistent styling globally:

@Composable
fun ThemedApp(sdk: DigitalCardEngineSDK) {
    CompositionLocalProvider(
        UILibrary.LocalStyleConfiguration provides sdk.styleConfiguration
    ) {
        // All components inherit styling
        NavHost(/*...*/) {
            composable("cards") {
                UILibrary.CardListView(sdk = sdk, /*...*/)
            }
            composable("details/{id}") {
                UILibrary.CardPageView(sdk = sdk, card = /*...*/)
            }
        }
    }
}

Android SDK: Component Reference

High-Level Components

CardListView

CardPageView

CardOverview

TransactionsCardView

Lower-Level Components

DCECardListView

TransactionsCard

TransactionList

EventList

CardCarousel

CardListItemDefaultView

Component Comparison

When to use which component?

Composition Patterns

Pattern 1: Fully Managed

Pattern 2: Custom ViewModel

Pattern 3: Hybrid

Styling All Components

See Also