> 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.sdk.FwLivestreamPlayerVersion
import com.firework.imageloading.glide.GlideImageLoaderFactory
import com.firework.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.setOnLinkClicked { title, url, videoInfo ->
    url?.let { openUrl(it) } // Your app's navigation function.
}
```

### User Interactions

Handle interactive features like polls, questions, and giveaways:

```kotlin
import com.firework.analyticsevents.VideoInfo
import com.firework.player.pager.livestreamplayer.Livestream

FireworkSdk.livestream.setOnInteractionListener(object : Livestream.OnInteractionListener {
    override fun onUserSubmitAnswerToQuestion(
        videoInfo: VideoInfo, question: Livestream.QuestionInteraction,
    ): Boolean {
        // question.prompt contains the displayed question.
        return false // Let the SDK handle submission.
    }

    override fun onUserSelectOptionForPoll(
        videoInfo: VideoInfo, poll: Livestream.PollInteraction,
    ): Boolean = false

    override fun onUserJoinGiveaway(
        videoInfo: VideoInfo, giveaway: Livestream.GiveawayInteraction,
    ): Boolean = false

    override fun onUserSendMessage(
        videoInfo: VideoInfo, message: Livestream.ChatMessage,
    ): Boolean = false

    override fun onUserSendLike(videoInfo: VideoInfo): Boolean = false
})
```

### Chat Management

Manage user display names in livestream chat:

```kotlin
// Register an update listener first if you need success/failure notifications.
FireworkSdk.livestream.updateUsername("JohnDoe")
val currentUsername: String? = FireworkSdk.livestream.getUsername()
FireworkSdk.livestream.updateUsernameConfiguration(
    Livestream.UsernameConfiguration(isEditable = true, isHidden = false)
)
```

### Giveaway Terms and Conditions

Handle clicks on giveaway terms and conditions:

```kotlin
FireworkSdk.livestream.setOnGiveawayTermsAndConditionsClickListener { type, title, url, videoInfo ->
    url?.let { openUrl(it) }
}
```

### Username Update Listener

Receive the outcome of username updates. This listener reports results; it is not a host validation callback:

```kotlin
FireworkSdk.livestream.setOnUpdateUsernameListener(object : Livestream.OnUpdateUsernameListener {
    override fun onUsernameUpdateSuccessfully(videoInfo: VideoInfo, username: String) {
        // The SDK has updated the username.
    }

    override fun onUsernameUpdateFailed(videoInfo: VideoInfo, username: String?, error: String?) {
        // Show or log the optional error message.
    }
})
FireworkSdk.livestream.updateUsername("JohnDoe")
```

## 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, this, 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.

The reminder opens the device's calendar editor for the user to save the event. The SDK does not require your app to read or write the calendar provider for this flow; a compatible calendar app must be available.

### 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

After initializing the SDK as shown above, a host Activity can own its listeners. `openBrowser` is your app's URL navigation function; callbacks should not perform blocking work.

```kotlin
class LiveActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        FireworkSdk.livestream.setOnLinkClicked { _, url, _ ->
            url?.let { openBrowser(it) }
        }
        FireworkSdk.livestream.setOnGiveawayTermsAndConditionsClickListener { _, _, url, _ ->
            url?.let { openBrowser(it) }
        }
        FireworkSdk.livestream.setOnUpdateUsernameListener(
            object : Livestream.OnUpdateUsernameListener {
                override fun onUsernameUpdateSuccessfully(videoInfo: VideoInfo, username: String) {
                    Log.d("Live", "Username updated: $username")
                }
                override fun onUsernameUpdateFailed(videoInfo: VideoInfo, username: String?, error: String?) {
                    Log.w("Live", "Username update failed: $error")
                }
            }
        )
        FireworkSdk.livestream.updateUsernameConfiguration(
            Livestream.UsernameConfiguration(isEditable = true, isHidden = false)
        )
    }

    override fun onDestroy() {
        FireworkSdk.livestream.setOnLinkClicked(null)
        FireworkSdk.livestream.setOnGiveawayTermsAndConditionsClickListener(null)
        FireworkSdk.livestream.setOnUpdateUsernameListener(null)
        super.onDestroy()
    }
}
```

For interaction interception, register the five-method listener shown above and remove it with `setOnInteractionListener(null)` when its owner is destroyed.

## 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 depend on a compatible calendar app being available.
* Link callbacks return `Unit`. Interaction callbacks return `Boolean`: `true` handles the interaction in your app, `false` allows SDK handling.
* Listeners are global; the screen registering a listener should also remove it when destroyed.

## 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                        |
| ------------------------------------------------ | ---------------------------------- |
| `setOnLinkClicked()`                             | 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).