Cart & Checkout

The SDK does not manage the shopping cart internally. You are responsible for:

• Maintaining cart state

• Managing cart items

• Handling checkout flow

The SDK provides callbacks and configuration options for cart integration. This page covers:

• Shopping CTA Button - Handle add-to-cart / shop-now actions on the PDP

• Customize Shopping CTA Button - Style the CTA button

• Shopping Cart - Cart behaviors and callbacks

• Product Detail Page (PDP) - PDP link button configuration

• "Shop Now" Mode - Direct navigation without a cart

• Error Handling - Shopping error events

• Programmatic Control - Dismiss shopping UI, open cart

Shopping CTA Button

The shopping CTA button appears on the product detail page and triggers the add-to-cart or shop-now action.

Product details page - CTA button (3)

CTA Button Click Listener

Handle clicks on the shopping CTA button:

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        FireworkSdk.shopping.setOnCtaButtonClicked { productId, unitId, productWebUrl, videoInfo ->
            // Handle CTA click
            // Add product to cart, navigate to checkout, etc.
        }
     }

    override fun onDestroy() {
        FireworkSdk.shopping.setOnCtaButtonClicked(null)
        super.onDestroy()
    }
}

CTA Button Status

For long-running operations (e.g., adding to cart via API), notify the SDK of the operation status:

FireworkSdk.shopping.setOnCtaButtonClicked { productId, unitId, productWebUrl, videoInfo ->
    // Set loading state
    FireworkSdk.shopping.setCtaButtonStatus(CtaButtonStatus.Loading)
    
    try {
        val result = api.addToCart(productId, unitId)
        
        if (result.isSuccess) {
            FireworkSdk.shopping.setCtaButtonStatus(CtaButtonStatus.Success)
        } else {
            FireworkSdk.shopping.setCtaButtonStatus(CtaButtonStatus.Error)
        }
    } catch (e: Exception) {
        FireworkSdk.shopping.setCtaButtonStatus(CtaButtonStatus.Error)
    }
}

Status Types:

• CtaButtonStatus.Loading - Operation in progress

• CtaButtonStatus.Success - Operation completed successfully

• CtaButtonStatus.Error - Operation failed

Note: If status is not provided within 10 seconds, the SDK assumes the operation failed.

CTA Button Text

Choose between "Add to cart" and "Shop now" labels:

FireworkSdk.shopping.setShoppingViewOptions(
    ShoppingViewOptions(
        productDetailsOptions = ProductDetailsOptions(
                shoppingCtaButtonOptions = ShoppingCtaButtonOptions(
                        text = ShoppingCtaButtonOptions.Text.SHOP_NOW
                // or ShoppingCtaButtonOptions.Text.ADD_TO_CART
                ),
        ),
     )
 )

Usage Guidelines:

• Add to cart: Use when shopping cart is enabled

• Shop now: Use for direct navigation to product pages without cart

Customize Shopping CTA Button

You can customize the "Add to Cart" button appearance by overriding the FwShoppingCtaButtonStyle in your app's theme:

Basic Styling

<resources>
   <style name="FwShoppingCtaButtonStyle" parent="FwShoppingCtaButtonParentStyle">
        <item name="android:backgroundTint">@color/backgroundColor</item>
        <item name="android:textColor">@color/myTextColor</item>
        <item name="android:textSize">16sp</item>
    </style>
</resources>

Shape Customization

To customize button shape (rounded corners, etc.):

<resources>
    <style name="FwShoppingCtaButtonStyle" parent="FwShoppingCtaButtonParentStyle">
        <item name="shapeAppearanceOverlay">@style/MyAddToCartButtonShapeStyle</item>
    </style>
    
    <style name="MyAddToCartButtonShapeStyle">
        <item name="cornerFamily">rounded</item> <!-- "rounded" or "cut" -->
        <item name="cornerSizeTopLeft">6dp</item>
        <item name="cornerSizeBottomLeft">6dp</item>
        <item name="cornerSizeBottomRight">6dp</item>
        <item name="cornerSizeTopRight">6dp</item>
    </style>
</resources>

Shopping Cart

Cart Behavior

Configure how the shopping cart behaves using CartBehaviour:

FireworkSdk.shopping.setShoppingCartBehaviour(behaviour: CartBehaviour)

Available Behaviors:

1. CartBehaviour.NoCart (Default)

   • Shopping cart icon is hidden

   • Suitable for "Shop now" mode without cart

2. CartBehaviour.Callback

   • Cart icon is shown

   • OnCartActionListener.onCartClicked is triggered when clicked

   • Use when opening cart as a separate activity

3. CartBehaviour.Embedded

   • Cart icon is shown

   • Fragment from EmbeddedCartFactory is displayed when clicked

   • Requires calling setEmbeddedCartFactory first

Embedded Cart Example

class MainActivity : AppCompatActivity() {

    private val embeddedCartFactory = object : EmbeddedCartFactory {
        override fun getInstance(): Fragment {
            return CustomShoppingCartFragment()
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        // Set the factory
        FireworkSdk.shopping.setEmbeddedCartFactory(embeddedCartFactory)
        
        // Enable embedded cart behavior
        FireworkSdk.shopping.setShoppingCartBehaviour(
            Shopping.CartBehaviour.Embedded(title = "Shopping Cart")
        )
    }
}

Cart Click Listener

Important: This listener only works with CartBehaviour.Callback.

Product details page - Cart icon (1)

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        // Set callback behavior
        FireworkSdk.shopping.setShoppingCartBehaviour(Shopping.CartBehaviour.Callback)
        
        // Handle cart clicks
        FireworkSdk.shopping.setOnCartClickListener { videoInfo ->
            // Open cart activity or fragment
            startActivity(Intent(this, CartActivity::class.java))
        }
    }

    override fun onDestroy() {
        FireworkSdk.shopping.setOnCartClickListener(null)
        super.onDestroy()
    }
}

Product Detail Page (PDP)

PDP Link Button Click Listener

Product details page - PDP link (2)

Handle clicks on the PDP link button:

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        FireworkSdk.shopping.setOnProductLinkClickListener { productId, unitId, productWebUrl, videoInfo ->

            // Let fullscreen player jump into picture in picture mode
            FireworkSdk.enterPip()
            // Handle custom navigation
            // Return true to handle it yourself, false to let SDK handle it
            
            openProductPage(productWebUrl)
            return true
        }
    }

    override fun onDestroy() {
        FireworkSdk.shopping.setOnProductLinkClickListener(null)
        super.onDestroy()
    }
}

Return Value:

• true - Your app handles the navigation

• false - SDK opens the product page

PDP Link Button Visibility

Control whether the PDP link button is shown:

FireworkSdk.shopping.setShoppingViewOptions(
        ShoppingViewOptions(
        productDetailsOptions = ProductDetailsOptions(
                    linkButtonOptions = LinkButtonOptions(isVisible = false),
                )
        )
 )

"Shop Now" Mode

Configure the SDK for direct product page navigation without a shopping cart:

private fun setupShopNowMode() {
    with(FireworkSdk.shopping) {
        // Hide cart button
        setShoppingCartBehaviour(Shopping.CartBehaviour.NoCart)
        
        // Configure PDP options
        setShoppingViewOptions(
            ShoppingViewOptions(
                productDetailsOptions = ProductDetailsOptions(
                    linkButtonOptions = LinkButtonOptions(isVisible = false),
                    shoppingCtaButtonOptions = ShoppingCtaButtonOptions(
                        text = ShoppingCtaButtonOptions.Text.SHOP_NOW
                    ),
                ),
            ),
        )
        
        // Handle CTA clicks
        setOnCtaButtonClicked { productId, unitId, productWebUrl, videoInfo ->
            openWebUrlInBrowser(productWebUrl)
            FireworkSdk.enterPip()  // Move player to PIP
        }
    }
}

Error Handling

Implement OnShoppingErrorListener to receive shopping error events:

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        FireworkSdk.shopping.setOnShoppingErrorListener { error ->
            when (error) {
                is ShoppingError.AddToCartError -> handleCartError(error)
                is ShoppingError.ShowProductInfoError -> handleProductError(error)
            }
        }
    }
    
    private fun handleCartError(error: ShoppingError.AddToCartError) {
        when (error) {
            ShoppingError.AddToCartError.NullProductId -> 
                Log.e(TAG, "Product ID is null")
            ShoppingError.AddToCartError.NullProductUnitId -> 
                Log.e(TAG, "Product unit ID is null")
            ShoppingError.AddToCartError.NullCartActionListener -> 
                Log.e(TAG, "Cart listener not set")
            ShoppingError.AddToCartError.Timeout -> 
                Log.e(TAG, "Add to cart timeout")
        }
    }
    
    private fun handleProductError(error: ShoppingError.ShowProductInfoError) {
        when (error) {
            ShoppingError.ShowProductInfoError.FailedToLaunchUrl -> 
                Log.e(TAG, "Failed to launch product URL")
            ShoppingError.ShowProductInfoError.NullProductId -> 
                Log.e(TAG, "Product ID is null")
            ShoppingError.ShowProductInfoError.NullUnitId -> 
                Log.e(TAG, "Unit ID is null")
            ShoppingError.ShowProductInfoError.NullProductWebUrl -> 
                Log.e(TAG, "Product URL is null")
        }
    }

    override fun onDestroy() {
        FireworkSdk.shopping.setOnShoppingErrorListener(null)
        super.onDestroy()
    }
}

Error Types

sealed interface ShoppingError {
    sealed interface AddToCartError : ShoppingError {
        object NullProductId : AddToCartError
        object NullProductUnitId : AddToCartError
        object NullCartActionListener : AddToCartError
        object Timeout : AddToCartError
    }

    sealed interface ShowProductInfoError : ShoppingError {
        object FailedToLaunchUrl : ShowProductInfoError
        object NullProductId : ShowProductInfoError
        object NullUnitId : ShowProductInfoError
        object NullProductWebUrl : ShowProductInfoError
    }
}

Programmatic Control

Dismiss Shopping UI

Close the shopping interface programmatically:

FireworkSdk.shopping.dismiss()

Open Shopping Cart

Open the shopping cart programmatically:

FireworkSdk.shopping.openShoppingCart()

Related Documentation

• Shoppable Videos - Overview and enabling Player Version 2

• Product Cards - Product card appearance and click behavior

• Purchase Tracking - Conversion tracking

• Product Hydration - Real-time product data integration