Shoppable Videos

The shopping feature enables your audience to browse and purchase products while watching videos. With this feature, users can view product details, explore available options (colors, sizes, etc.), and add items to their cart without leaving the video experience.

Note: The SDK does not provide payment processing. You are responsible for managing the shopping cart and checkout flow through the provided callbacks.

Overview

Firework SDK provides:

• Product Display: Built-in UI to display product lists and handle user interactions

• Shopping Cart: Callbacks for cart management and checkout flow

• Product Details: Integrated product detail pages (PDP) with customizable actions

• Purchase Tracking: Analytics integration for conversion tracking

The shopping documentation is organized into the following pages:

• Product Cards - Card appearance (V2 styling, indicators), click behavior, V1 options, and custom card views

• Cart & Checkout - Shopping cart behaviors, CTA button, PDP configuration, "Shop Now" mode, and error handling

• Purchase Tracking - Conversion tracking with trackPurchase

• Product Hydration - Real-time product data from your backend

UI Themes

The SDK provides two color themes for the shopping interface:

FireworkSdk.shopping.setShoppingViewOptions(
    ShoppingViewOptions(
        theme = ShoppingTheme.LIGHT  // or ShoppingTheme.DARK
    )
)

Dark Theme	Light Theme

New Product Cards

Important: New Product Cards are only available when using Player Version 2 (V2). The Version 1 product cards are maintained for backward compatibility but will not receive new features.

The Firework SDK provides an enhanced product card experience in Player Version 2 with improved UI, better performance, and new features. To access the new product cards, you must enable V2 for both the video player and livestream player.

Single Product Card(V2)	Single Product Card(V1)	Multiple Product Card(V2)	Multiple Product Card(V1)

Why Use Player Version 2?

✅ All future updates and new features are only available in V2 &#xNAN;⚠️ V1 is in maintenance mode and will not receive new features

Player Version 2 provides:

• Enhanced Product Cards: Improved UI with better animations and interactions

• Better Performance: Faster rendering and smoother scrolling

• Modern Design: Updated visual design aligned with current standards

• Active Development: Ongoing improvements and new features

• Bug Fixes: Priority bug fixes and updates

How to Enable Player Version 2

To use the new product cards, enable V2 for both video player and livestream player before SDK initialization:

Step 1: Set Player Versions in Application Class

import android.app.Application
import com.firework.sdk.FireworkSdk
import com.firework.sdk.FireworkSdkConfig
import com.firework.sdk.player.FwVideoPlayerVersion
import com.firework.sdk.player.FwLivestreamPlayerVersion
import com.firework.imageloading.glide.GlideImageLoaderFactory

class MyApp : Application() {

    override fun onCreate() {
        super.onCreate()
        
        // ✅ STEP 1: Set player versions to V2 (BEFORE SDK initialization)
        FireworkSdk.setVideoPlayerVersion(FwVideoPlayerVersion.V2)
        FireworkSdk.setLivestreamPlayerVersion(FwLivestreamPlayerVersion.V2)
        
        // STEP 2: Build SDK configuration
        val config = FireworkSdkConfig.Builder(context = this)
            .clientId("YOUR_CLIENT_ID")
            .imageLoader(GlideImageLoaderFactory.createInstance(context = this))
            .build()
        
        // STEP 3: Initialize SDK
        FireworkSdk.init(
            fireworkSdkConfig = config,
            onSuccess = {
                Log.d("FireworkSDK", "SDK initialized with V2 players")
            },
            onError = { error ->
                Log.e("FireworkSDK", "Initialization failed", error)
            }
        )
    }
}

Step 2: Enable Livestream Support (If Needed)

If you're using livestream features, also add the livestream player dependency:

dependencies {
    // Video player (required)
    implementation("com.firework.external:FireworkSDK:X.Y.Z")
    
    // Livestream player (only if you need livestream features)
    implementation("com.firework.external.livestream:singleHostPlayer:X.Y.Z")
}

And configure the livestream initializer:

import com.firework.external.livestream.singlehost.SingleHostLivestreamPlayerInitializer

val config = FireworkSdkConfig.Builder(context = this)
    .clientId("YOUR_CLIENT_ID")
    .imageLoader(GlideImageLoaderFactory.createInstance(context = this))
    .addLivestreamPlayerInitializer(SingleHostLivestreamPlayerInitializer())
    .build()

Available Player Versions

Short Video Player:

FireworkSdk.setVideoPlayerVersion(FwVideoPlayerVersion.V1)  // Default, maintenance mode
FireworkSdk.setVideoPlayerVersion(FwVideoPlayerVersion.V2)  // Recommended, actively developed

Livestream Player:

FireworkSdk.setLivestreamPlayerVersion(FwLivestreamPlayerVersion.V1)  // Default, maintenance mode
FireworkSdk.setLivestreamPlayerVersion(FwLivestreamPlayerVersion.V2)  // Recommended, actively developed

Important Notes

• ⚠️ Player versions must be set before FireworkSdk.init()

• ✅ Both players are independent - you can use V2 for one and V1 for the other

• ✅ However, we strongly recommend using V2 for both players

• ✅ V1 will continue to work but will not receive new features

• ✅ New product cards are automatically enabled when using V2 players

Verification

After enabling V2, you can verify the product cards are using the new version by observing:

• Improved animations when scrolling through products

• Enhanced visual design with updated spacing and typography

• Better touch feedback on product card interactions

• Smoother transitions when opening product details

Customizing V2 Product Cards

V2 product cards can be customized through ShoppingViewOptions:

• Card appearance (background color, corner radius, border, name/price text colors) via ProductCardV2Configuration - see Product Card Appearance (V2)

• Carousel indicator size via ProductCardIndicatorConfiguration - see Product Indicator Customization (V2)

• Click behavior via setOnProductCardClickListener or ProductCardClickBehavior - see Product Card Click Handler

Related Documentation

• Product Cards - Card appearance and click behavior

• Cart & Checkout - Shopping cart, CTA button, and PDP configuration

• Purchase Tracking - Conversion tracking

• Product Hydration - Real-time product data integration

• Analytics - Event tracking and analytics