# Getting Started
 - 
The latest version [release notes](https://docs.firework.com/home/android-sdk/changelog)
## 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:**
1. Provide your application's package name to your Firework business or engineering contact
2. You will receive the Client ID via email
3. 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](https://repo.maven.apache.org/maven2/com/firework/sdk/). 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()`:
{% tabs %}
{% tab title="Gradle" %}
```groovy
repositories {
...
mavenCentral()
}
```
{% endtab %}
{% tab title="Kotlin DSL" %}
```kotlin
repositories {
...
mavenCentral()
}
```
{% endtab %}
{% endtabs %}
### 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](https://github.com/bumptech/glide) implementation (recommended)
#### Optional Dependencies
* **Single Host Livestream Player**: Only add if you need livestream feature
{% tabs %}
{% tab title="Gradle" %}
```groovy
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"
```
{% endtab %}
{% tab title="Kotlin DSL" %}
```kotlin
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")
```
{% endtab %}
{% endtabs %}
## SDK Initialization
Initialize the Firework SDK in your `Application` class's `onCreate()` method.
```kotlin
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)
[](https://central.sonatype.com/artifact/com.firework/firework-bom/)
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
{% tabs %}
{% tab title="Gradle" %}
```groovy
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"
```
{% endtab %}
{% tab title="Kotlin DSL" %}
```kotlin
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")
```
{% endtab %}
{% endtabs %}
## Additional Setup
### AndroidManifest.xml Configuration
Add `android:largeHeap="true"` to your application tag to ensure optimal performance with video content:
```xml
```
### Register Your Application Class
If you created a custom `Application` class for SDK initialization, ensure it's registered in your `AndroidManifest.xml`:
```xml
```
## 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.
```kotlin
val videoFeedView = findViewById(R.id.videoFeedView)
videoFeedView.init()
```
→ [Configure Video Feed View Guide](https://docs.firework.com/firework-for-developers/android-sdk/integration-guide/configure-video-feed)
#### 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.
```kotlin
val storyBlock = findViewById(R.id.storyBlock)
storyBlock.init(supportFragmentManager, lifecycle, viewOptions)
```
→ [StoryBlock Integration Guide](https://docs.firework.com/firework-for-developers/android-sdk/integration-guide/storyblock)
#### 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.
```kotlin
val result = FireworkSdk.startPlayer(viewOptions)
```
→ [Open Fullscreen Player Guide](https://docs.firework.com/firework-for-developers/android-sdk/integration-guide/fullscreen-player)
### Core Video Player
All three widgets use the **same core video player** which can be customized with `PlayerOption`:
```kotlin
val viewOptions = viewOptions {
playerOptions {
playerMode(PlayerMode.FULL_BLEED_MODE)
showShareButton(true)
enablePipMode(true)
// ... more options
}
}
```
→ [Video Player Configuration Guide](https://docs.firework.com/firework-for-developers/android-sdk/integration-guide/video-player)
### Additional Features
* **Shopping Integration**: Configure shopping callbacks with `FireworkSdk.shopping` → [Shopping Integration Guide](https://docs.firework.com/firework-for-developers/android-sdk/integration-guide/shoppable-videos)
* **Livestream Features**: Configure livestream callbacks and interactions → [Livestream Integration](https://docs.firework.com/firework-for-developers/android-sdk/integration-guide/livestream)
* **Advanced Configuration**: Explore all `ViewOptions` and customization → [Configuration Guide](https://docs.firework.com/firework-for-developers/android-sdk/integration-guide/configuration)
* **FireworkSdk API**: Complete reference of all `FireworkSdk` methods → [FireworkSdk API Reference](https://docs.firework.com/firework-for-developers/android-sdk/integration-guide/firework-sdk-api)
## 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:
```kotlin
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 = { e ->
Log.e("FireworkSDK", "Initialization failed", e)
}
)
}
}
```
### Available Versions
**Short Video Player:**
```kotlin
FireworkSdk.setVideoPlayerVersion(FwVideoPlayerVersion.V1) // Default, maintenance mode
FireworkSdk.setVideoPlayerVersion(FwVideoPlayerVersion.V2) // Recommended, actively developed
```
**Livestream Player:**
```kotlin
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