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

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:

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:

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

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:

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

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

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:

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

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:

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