Getting Started

Firework Android SDK GitHub Release - Firework Android BoM GitHub Release

Overview

The Firework Android SDK enables you to integrate shoppable video content and livestream experiences into your Android application. With this SDK, you can display video feeds, livestreams, and interactive shopping features directly within your app.

Requirements

Minimum Android SDK: 21 (Android 5.0)
Language: Kotlin or Java
Build System: Gradle
Image Loading: Glide (recommended) or custom implementation

Obtain Your Client ID

Before integrating the SDK, you need a unique Client ID to authenticate your application with the Firework platform.

Steps to obtain your Client ID:

Provide your application's package name to your Firework business or engineering contact
You will receive the Client ID via email
Use this Client ID during SDK initialization (see below)

Important: Authentication will fail if you use an incorrect Client ID. Keep your Client ID secure and do not commit it to public repositories.

Installation

The Firework Android SDK is available through Maven Central. Check the badge at the top of this page for the latest stable version.

Step 1: Add Maven Central Repository

Ensure your project's build.gradle.kts or build.gradle includes mavenCentral():

repositories {
    ...
    mavenCentral()
}

Step 2: Add Dependencies

Add the following dependencies to your app module's build.gradle.kts or build.gradle:

Required Dependencies

Firework SDK: Core SDK for video and livestream features
Image Loader: Glide implementation (recommended)

Optional Dependencies

Single Host Livestream Player: Only add if you need livestream feature

def fireworkSdkVersion = "6.26.0" // Check the latest version

// Core SDK (Required)
implementation "com.firework:sdk:$fireworkSdkVersion"

// Image Loader (Required - Glide recommended)
implementation "com.firework.external.imageloading:glide:$fireworkSdkVersion"

// Livestream Player (Optional - only if you need livestream features)
implementation "com.firework.external.livestream:singleHostPlayer:$fireworkSdkVersion"

val fireworkSdkVersion = "6.26.0" // Check the latest version

// Core SDK (Required)
implementation("com.firework:sdk:$fireworkSdkVersion")

// Image Loader (Required - Glide recommended)
implementation("com.firework.external.imageloading:glide:$fireworkSdkVersion")

// Livestream Player (Optional - only if you need livestream features)
implementation("com.firework.external.livestream:singleHostPlayer:$fireworkSdkVersion")

SDK Initialization

Initialize the Firework SDK in your Application class's onCreate() method.

import android.app.Application
import android.util.Log
import com.firework.sdk.FireworkSdk
import com.firework.sdk.FireworkSdkConfig
import com.firework.sdk.FireworkInitError
import com.firework.imageloading.glide.GlideImageLoaderFactory
import com.firework.external.livestream.singlehost.SingleHostLivestreamPlayerInitializer

class MyApp : Application() {

    override fun onCreate() {
        super.onCreate()
        
        // Build SDK configuration
        val config = FireworkSdkConfig.Builder(context = this)
            .clientId("YOUR_CLIENT_ID") // Required: Your Firework Client ID
            .imageLoader(GlideImageLoaderFactory.createInstance(context = this)) // Required: Glide recommended
            .enableCache(true) // Optional: Enable video cache (default: true)
            .maxCacheSizeBytes(50 * 1024 * 1024) // Optional: Max cache size, e.g., 50MB (default: 25MB)
            .muteOnLaunch(true) // Optional: Start videos muted (default: false)
            .addLivestreamPlayerInitializer(SingleHostLivestreamPlayerInitializer()) // Optional: Only if you need livestream
            .build()
        
        // Initialize SDK
        FireworkSdk.init(
            fireworkSdkConfig = config,
            onSuccess = {
                // SDK initialized successfully
                Log.d("FireworkSDK", "Initialization successful")
            },
            onError = { error ->
                when (error) {
                    is FireworkInitError.InitializationError -> {
                        // Handle initialization error
                        Log.e("FireworkSDK", "Initialization failed", error.cause)
                    }
                    is FireworkInitError.AlreadyInitializedError -> {
                        // SDK is already initialized
                        Log.w("FireworkSDK", "SDK already initialized")
                    }
                }
            }
        )
    }
}

Note: Remove optional configuration lines that you don't need. The minimum required configuration only needs clientId and imageLoader.

Configuration Options

Parameter

Type

Required

Default

Description

clientId

String

✅

Your unique Firework Client ID

imageLoader

ImageLoader

✅

Image loading implementation (Glide recommended)

enableCache

Boolean

❌

true

Enable video cache for offline playback

maxCacheSizeBytes

Long

❌

26,214,400 (25MB)

Maximum cache size in bytes

muteOnLaunch

Boolean

❌

false

Start videos muted

addLivestreamPlayerInitializer

LivestreamPlayerInitializer

❌

Add livestream player support (only if needed)

Using BoM (Bill of Materials)

If your app uses multiple Firework SDKs or open-source libraries, use the Bill of Materials (BoM) to manage dependency versions automatically. This prevents version conflicts.

Benefits

Automatically manages compatible versions across all Firework libraries
Simplifies version updates (update BoM version only)
Prevents dependency conflicts

Implementation

def fireworkBomVersion = "2025.10.21" // Check the latest BoM version

// Import BoM
implementation platform("com.firework:firework-bom:$fireworkBomVersion")

// Add dependencies without version numbers (Core SDK)
implementation "com.firework:sdk"
implementation "com.firework.external.imageloading:glide"

// Optional: Only if you need livestream features
implementation "com.firework.external.livestream:singleHostPlayer"

val fireworkBomVersion = "2025.10.21" // Check the latest BoM version

// Import BoM
implementation(platform("com.firework:firework-bom:$fireworkBomVersion"))

// Add dependencies without version numbers (Core SDK)
implementation("com.firework:sdk")
implementation("com.firework.external.imageloading:glide")

// Optional: Only if you need livestream features
implementation("com.firework.external.livestream:singleHostPlayer")

Additional Setup

AndroidManifest.xml Configuration

Add android:largeHeap="true" to your application tag to ensure optimal performance with video content:

<application
    android:name=".MyApp"
    android:largeHeap="true"
    ...>

    <!-- Your activities and other components -->

</application>

Register Your Application Class

If you created a custom Application class for SDK initialization, ensure it's registered in your AndroidManifest.xml:

<application
    android:name=".MyApp"
    ...>
</application>

Next Steps

Now that your SDK is initialized, you can display videos using one of three widget types. Each widget is designed for specific use cases but all use the same core video player.

Display Video Content

The Firework SDK provides three ways to display video content:

1. FwVideoFeedView - Video Feed (Carousel or Grid)

Displays a scrollable feed of video thumbnails. Users tap on thumbnails to launch the fullscreen player.

Use when: You want users to browse and select from multiple videos.

val videoFeedView = findViewById<FwVideoFeedView>(R.id.videoFeedView)
videoFeedView.init()

→ Configure Video Feed View Guide

2. FwStoryBlockView - Embedded Player

An inline video player that embeds directly into your layout with auto-play, similar to stories on social platforms.

Use when: You want an immersive, single-video experience within your layout.

val storyBlock = findViewById<FwStoryBlockView>(R.id.storyBlock)
storyBlock.init(supportFragmentManager, lifecycle, viewOptions)

→ StoryBlock Integration Guide

3. FireworkSdk.startPlayer() - Launch Fullscreen Player

Launches a fullscreen video player as a separate activity without embedding any UI.

Use when: You want to play videos directly from buttons, deep links, or custom UI.

val result = FireworkSdk.startPlayer(viewOptions)

→ Open Fullscreen Player Guide

Core Video Player

All three widgets use the same core video player which can be customized with PlayerOption:

val viewOptions = viewOptions {
    playerOptions {
        playerMode(PlayerMode.FULL_BLEED_MODE)
        showShareButton(true)
        enablePipMode(true)
        // ... more options
    }
}

→ Video Player Configuration Guide

Additional Features

Shopping Integration: Configure shopping callbacks with FireworkSdk.shopping → Shopping Integration Guide
Livestream Features: Configure livestream callbacks and interactions → Livestream Integration
Advanced Configuration: Explore all ViewOptions and customization → Configuration Guide
FireworkSdk API: Complete reference of all FireworkSdk methods → FireworkSdk API Reference

Player Versions (Important)

The Firework SDK provides two versions for both the Livestream Player and Short Video Player:

V1 (Default) - The original player version
V2 (Recommended) - The latest player version with enhanced features and performance

Why Use V2?

✅ All future updates and new features will only be added to V2. ⚠️ V1 is in maintenance mode and will not receive new features.

We strongly recommend using V2 for both players to ensure you have access to:

Latest performance improvements
New features and enhancements
Ongoing bug fixes and updates
Better user experience

How to Enable V2

Set the player versions before calling FireworkSdk.init() in your Application class:

class MyApp : Application() {

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

Available 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 recommend using V2 for both to get the best experience
V1 will continue to work but will not receive new features

Troubleshooting

Common Issues

SDK fails to initialize:

Verify your Client ID is correct
Check network connectivity
Ensure image loader is properly configured
Check logcat for detailed error messages

Videos not loading:

Verify SDK initialization completed successfully
Check internet connection
Ensure proper feed resource is configured
Review ViewOptions configuration

Livestream not working:

Verify livestream player initializers are added
Check that required livestream dependencies are included
Ensure livestream features are enabled for your Client ID

PreviousIntegration Guide for Android SDK NextFireworkSdk API Reference

Last updated 14 hours ago