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)

• 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:

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:

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):

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:

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:

// 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:

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

Username Update Listener

Listen for username change requests from users:

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

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

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

StoryBlock with Livestream

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

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

FireworkSdk.startPlayer(viewOptions)

Livestream Player Configuration

Countdown Timer

Display a countdown timer for upcoming livestreams:

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:

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

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

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:

   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 - Complete callback API reference

• Livestream Chat - Chat management and username configuration

Related Features

• Getting Started - SDK initialization

• Video Player Configuration - Player customization

• Configure Video Feed - Video feed setup

• StoryBlock Integration - StoryBlock widget

• FireworkSdk API Reference - 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.