> For the complete documentation index, see [llms.txt](https://docs.firework.com/firework-for-developers/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.firework.com/firework-for-developers/android-sdk/integration-guide/livestream.md).

# Livestream Support

The Firework Android SDK provides comprehensive livestream features including live broadcasts, replays, trailers, interactive chat, polls, questions, and giveaways. This guide covers livestream setup, configuration, and usage.

## Overview

The `FireworkSdk.livestream` object provides access to all livestream-related functionality. Through this interface, you can:

* Handle user interactions during livestreams
* Manage chat and username display
* Respond to links clicked within livestream content
* Configure livestream-specific UI elements
* Handle giveaways, polls, and questions

## Livestream Content Types

The SDK supports three types of livestream content:

### 1. Livestream/Restream/VideoToLive

Real-time streaming content with interactive features:

* Live chat
* Real-time polls and questions
* Giveaways and promotions
* Interactive product links

### 2. Livestream Replays

Recorded livestream content that can be played on-demand:

* Preserved chat messages
* Historical poll results
* Recorded interactions
* Full shopping integration

### 3. Trailers

Preview content for upcoming livestreams:

* Countdown timer
* Calendar reminder integration
* Teaser content
* Schedule information

## Prerequisites

* Firework SDK properly initialized (see [Getting Started](/firework-for-developers/android-sdk/integration-guide/getting-started.md))
* Livestream features enabled for your Client ID
* Livestream dependency added to your project

## Installation

### Add Livestream Dependency

Add the livestream player dependency to your `build.gradle.kts`:

```kotlin
dependencies {
    // Core Firework SDK
    implementation(platform("com.firework:firework-bom:$fireworkBomVersion"))
    implementation("com.firework:sdk")
    
    // Image loader (recommended: Glide)
    implementation("com.firework.external.imageloading:glide")
    
    // Livestream support (only add when needed)
    implementation("com.firework.external.livestream:singleHostPlayer")
}
```

**Note:** Only add the livestream dependency when you need livestream features. It's not required for regular video playback.

## SDK Configuration

### Initialize with Livestream Support

Configure the SDK with livestream player initializer in your Application class:

```kotlin
import android.app.Application
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 with livestream support
        val config = FireworkSdkConfig.Builder(context = this)
            .clientId("YOUR_CLIENT_ID")
            .imageLoader(GlideImageLoaderFactory.createInstance(context = this))
            .addLivestreamPlayerInitializer(SingleHostLivestreamPlayerInitializer())
            .build()
        
        // Use the latest livestream player version (V2 - recommended)
        FireworkSdk.setLivestreamPlayerVersion(FwLivestreamPlayerVersion.V2)
        
        // Initialize SDK
        FireworkSdk.init(
            fireworkSdkConfig = config,
            onSuccess = {
                setupLivestreamCallbacks()
            },
            onError = { error ->
                // Handle initialization error
            }
        )
    }
    
    private fun setupLivestreamCallbacks() {
        // Configure livestream callbacks here
        // See Livestream Callbacks section below
    }
}
```

**Important:** Call `setLivestreamPlayerVersion()` before `FireworkSdk.init()`.

## Livestream Features

### Link Handling

Handle links clicked within livestream content (e.g., product links, external URLs):

```kotlin
FireworkSdk.livestream.setOnLinkClickListener { link ->
    // Open link in browser or handle deep link
    openUrl(link)
    true // Return true if handled, false to let SDK handle
}
```

### User Interactions

Handle interactive features like polls, questions, and giveaways:

```kotlin
FireworkSdk.livestream.setOnInteractionListener { interaction ->
    when (interaction) {
        is QuestionInteraction -> {
            // User submitted an answer to a question
            Log.d("Livestream", "Question: ${interaction.question}")
            Log.d("Livestream", "Answer: ${interaction.answer}")
        }
        is PollInteraction -> {
            // User voted in a poll
            Log.d("Livestream", "Poll: ${interaction.pollId}")
            Log.d("Livestream", "Option: ${interaction.selectedOption}")
        }
        is GiveawayInteraction -> {
            // User joined a giveaway
            Log.d("Livestream", "Giveaway: ${interaction.giveawayId}")
        }
    }
}
```

### Chat Management

Manage user display names in livestream chat:

```kotlin
// Update username
FireworkSdk.livestream.updateUsername(
    username = "JohnDoe",
    onSuccess = {
        Log.d("Livestream", "Username updated successfully")
    },
    onError = { error ->
        Log.e("Livestream", "Failed to update username: ${error.message}")
    }
)

// Get current username
val currentUsername = FireworkSdk.livestream.getUsername()

// Configure username display settings
FireworkSdk.livestream.updateUsernameConfiguration(
    UsernameConfiguration(
        isEditable = true,  // Allow users to edit their username
        isHidden = false    // Show username in chat
    )
)
```

### Giveaway Terms and Conditions

Handle clicks on giveaway terms and conditions:

```kotlin
FireworkSdk.livestream.setOnGiveawayTermsAndConditionsClickListener { url ->
    // Open T&C page
    openUrl(url)
}
```

### Username Update Listener

Listen for username change requests from users:

```kotlin
FireworkSdk.livestream.setOnUpdateUsernameListener { newUsername, onComplete ->
    // Validate username with your backend
    if (isValidUsername(newUsername)) {
        // Accept the username
        onComplete(true)
    } else {
        // Reject the username
        onComplete(false)
        showError("Username not available")
    }
}
```

## Display Livestream Content

Livestream content can be displayed using any Firework widget:

### Video Feed with Livestream

```kotlin
val viewOptions = viewOptions {
    baseOptions {
        feedResource(FeedResource.Discovery) // Can include livestream content
    }
}

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

### StoryBlock with Livestream

```kotlin
val viewOptions = viewOptions {
    baseOptions {
        feedResource(FeedResource.Channel(channelId = "your_channel_id"))
    }
    storyBlockOptions {
        enableAutoPlay(true)
    }
}

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

### Direct Fullscreen Player

```kotlin
val viewOptions = viewOptions {
    baseOptions {
        feedResource(FeedResource.Discovery)
    }
}

FireworkSdk.startPlayer(viewOptions)
```

## Livestream Player Configuration

### Countdown Timer

Display a countdown timer for upcoming livestreams:

```kotlin
val viewOptions = viewOptions {
    playerOptions {
        livestreamCountDownOption(
            LivestreamCountDownOption.Builder()
                .isHidden(false) // Show countdown
                .theme(Theme.DARK) // or Theme.LIGHT
                .build()
        )
    }
}
```

Users can tap the countdown to set a calendar reminder for the livestream.

**Note:** Calendar reminders require calendar permissions in AndroidManifest.xml:

```xml
<uses-permission android:name="android.permission.READ_CALENDAR" />
<uses-permission android:name="android.permission.WRITE_CALENDAR" />
```

### Player Version

Use V2 for the latest livestream features:

```kotlin
// Set before SDK initialization
FireworkSdk.setLivestreamPlayerVersion(FwLivestreamPlayerVersion.V2)
```

**V2 Benefits:**

* Improved performance and stability
* Better error handling
* Enhanced interactive features
* Active support and updates

## Complete Integration Example

```kotlin
class MyApp : Application() {

    override fun onCreate() {
        super.onCreate()
        
        // Configure livestream player version
        FireworkSdk.setLivestreamPlayerVersion(FwLivestreamPlayerVersion.V2)
        
        // Build configuration
        val config = FireworkSdkConfig.Builder(context = this)
            .clientId("YOUR_CLIENT_ID")
            .imageLoader(GlideImageLoaderFactory.createInstance(context = this))
            .addLivestreamPlayerInitializer(SingleHostLivestreamPlayerInitializer())
            .build()
        
        // Initialize SDK
        FireworkSdk.init(
            fireworkSdkConfig = config,
            onSuccess = {
                setupLivestreamFeatures()
            }
        )
    }
    
    private fun setupLivestreamFeatures() {
        // Link handling
        FireworkSdk.livestream.setOnLinkClickListener { link ->
            openBrowser(link)
            true
        }
        
        // Interaction handling
        FireworkSdk.livestream.setOnInteractionListener { interaction ->
            when (interaction) {
                is QuestionInteraction -> handleQuestion(interaction)
                is PollInteraction -> handlePoll(interaction)
                is GiveawayInteraction -> handleGiveaway(interaction)
            }
        }
        
        // Giveaway T&C
        FireworkSdk.livestream.setOnGiveawayTermsAndConditionsClickListener { url ->
            openBrowser(url)
        }
        
        // Username updates
        FireworkSdk.livestream.setOnUpdateUsernameListener { newUsername, onComplete ->
            validateUsername(newUsername) { isValid ->
                onComplete(isValid)
            }
        }
        
        // Configure username display
        FireworkSdk.livestream.updateUsernameConfiguration(
            UsernameConfiguration(
                isEditable = true,
                isHidden = false
            )
        )
    }
}
```

## Important Notes

* Livestream dependency should only be added when needed
* Always use V2 player version for latest features
* Set player version before SDK initialization
* Livestream chat and some features only work in fullscreen mode (not in StoryBlock compact mode)
* Calendar reminders require appropriate Android permissions
* Return `true` from link click listener if you handle the link, `false` to let SDK handle it

## Troubleshooting

### Livestream Not Playing

**Issue:** Livestream content doesn't play or shows an error.

**Solutions:**

1. Verify livestream dependency is added:

   ```kotlin
   implementation("com.firework.external.livestream:singleHostPlayer")
   ```
2. Ensure `SingleHostLivestreamPlayerInitializer()` is added to SDK config
3. Confirm `setLivestreamPlayerVersion()` is called before `init()`
4. Check that livestream features are enabled for your Client ID

### Missing Chat or Interactive Features

**Issue:** Chat, polls, or other interactive features not visible.

**Solutions:**

1. Ensure you're using V2 player version
2. For StoryBlock, ensure you're in fullscreen mode (tap fullscreen icon)
3. Verify livestream is actually live (not a trailer or replay without interactions)

## Related Documentation

### Detailed Guides

* [Livestream Callbacks](/firework-for-developers/android-sdk/integration-guide/livestream/livestream-callbacks.md) - Complete callback API reference
* [Livestream Chat](/firework-for-developers/android-sdk/integration-guide/livestream/livestream-chat.md) - Chat management and username configuration

### Related Features

* [Getting Started](/firework-for-developers/android-sdk/integration-guide/getting-started.md) - SDK initialization
* [Video Player Configuration](/firework-for-developers/android-sdk/integration-guide/video-player.md) - Player customization
* [Configure Video Feed](/firework-for-developers/android-sdk/integration-guide/configure-video-feed.md) - Video feed setup
* [StoryBlock Integration](/firework-for-developers/android-sdk/integration-guide/storyblock.md) - StoryBlock widget
* [FireworkSdk API Reference](/firework-for-developers/android-sdk/integration-guide/firework-sdk-api.md) - Complete API documentation

## API Summary

| Method                                           | Description                        |
| ------------------------------------------------ | ---------------------------------- |
| `setOnLinkClickListener()`                       | Handle link clicks in livestream   |
| `setOnInteractionListener()`                     | Handle polls, questions, giveaways |
| `setOnGiveawayTermsAndConditionsClickListener()` | Handle T\&C clicks                 |
| `setOnUpdateUsernameListener()`                  | Listen for username updates        |
| `updateUsername()`                               | Update user's display name         |
| `getUsername()`                                  | Get current username               |
| `updateUsernameConfiguration()`                  | Configure username settings        |

For complete API details, see [FireworkSdk API Reference](/firework-for-developers/android-sdk/integration-guide/firework-sdk-api.md#livestream-features).