Livestream Callbacks

The Firework SDK provides comprehensive callback interfaces for handling user interactions during livestreams. This guide covers all available callbacks and their usage.

Overview

Livestream callbacks allow you to respond to user actions during live broadcasts, replays, and trailers. All callbacks are accessed through FireworkSdk.livestream and provide video context information via the VideoInfo parameter.

Link Click Listener

setOnLinkClicked()

Handles clicks on links within livestream content (e.g., product links, external URLs, promotional links).

Signature:

fun setOnLinkClicked(listener: OnLinkClickListener?)

Listener Interface:

fun interface OnLinkClickListener {
    fun onLinkClick(title: String?, url: String?, videoInfo: VideoInfo)
}

Parameters:

title - Link title or description (can be null)
url - The URL to open (can be null)
videoInfo - Context information about the current video

Example:

FireworkSdk.livestream.setOnLinkClicked { title, url, videoInfo ->
    Log.d("Livestream", "Link clicked: $title")
    Log.d("Livestream", "URL: $url")
    Log.d("Livestream", "Video ID: ${videoInfo.videoId}")
    
    // Open the link in browser or handle deep link
    url?.let { openUrl(it) }
}

Use Cases:

Open product pages when users tap product links
Handle deep links to specific app screens
Track link click analytics
Open external promotional content

Remove Listener:

// Set null to remove the listener
FireworkSdk.livestream.setOnLinkClicked(null)

Interaction Listener

setOnInteractionListener()

Handles various user interactions during livestreams including questions, polls, giveaways, chat messages, and likes.

Signature:

fun setOnInteractionListener(listener: OnInteractionListener?)

Listener Interface:

interface OnInteractionListener {
    fun onUserSubmitAnswerToQuestion(videoInfo: VideoInfo, question: QuestionInteraction): Boolean
    
    fun onUserSelectOptionForPoll(videoInfo: VideoInfo, poll: PollInteraction): Boolean
    
    fun onUserJoinGiveaway(videoInfo: VideoInfo, giveaway: GiveawayInteraction): Boolean
    
    fun onUserSendMessage(videoInfo: VideoInfo, message: ChatMessage): Boolean
    
    fun onUserSendLike(videoInfo: VideoInfo): Boolean
}

onUserSubmitAnswerToQuestion()

Called when a user submits an answer to a question during a livestream.

Parameters:

videoInfo - Context information about the current video
question - Question interaction details

Question Interaction:

data class QuestionInteraction(
    val prompt: String  // The question prompt text
)

Returns: Boolean

true - Interaction handled by your app
false - Let SDK handle the interaction (default behavior)

Example:

FireworkSdk.livestream.setOnInteractionListener(object : Livestream.OnInteractionListener {
    override fun onUserSubmitAnswerToQuestion(
        videoInfo: VideoInfo,
        question: QuestionInteraction
    ): Boolean {
        Log.d("Livestream", "Question answered: ${question.prompt}")
        return false  // Let SDK handle
    }
    
    // Other methods...
})

onUserSelectOptionForPoll()

Called when a user selects an option in a poll during a livestream.

Parameters:

videoInfo - Context information about the current video
poll - Poll interaction details

Poll Interaction:

data class PollInteraction(
    val prompt: String  // The poll question/prompt text
)

Returns: Boolean

true - Interaction handled by your app
false - Let SDK handle the interaction (default behavior)

Example:

override fun onUserSelectOptionForPoll(
    videoInfo: VideoInfo,
    poll: PollInteraction
): Boolean {
    Log.d("Livestream", "Poll voted: ${poll.prompt}")
    
    // Track poll participation
    trackPollVote(videoInfo.videoId, poll.prompt)
    
    // Show confirmation
    showToast("Your vote has been recorded!")
    
    return false  // Let SDK handle the default behavior
}

onUserJoinGiveaway()

Called when a user joins a giveaway during a livestream.

Parameters:

videoInfo - Context information about the current video
giveaway - Giveaway interaction details

Giveaway Interaction:

data class GiveawayInteraction(
    val name: String  // The giveaway name/title
)

Returns: Boolean

true - Interaction handled by your app
false - Let SDK handle the interaction (default behavior)

Example:

override fun onUserJoinGiveaway(
    videoInfo: VideoInfo,
    giveaway: GiveawayInteraction
): Boolean {
    Log.d("Livestream", "Giveaway joined: ${giveaway.name}")
    
    // Verify user eligibility
    if (!isUserEligibleForGiveaway()) {
        showError("You must be logged in to join giveaways")
        return true  // Prevent default behavior
    }
    
    // Track giveaway participation
    trackGiveawayEntry(videoInfo.videoId, giveaway.name)
    
    // Show confirmation
    showSuccessDialog("You're entered in the giveaway!")
    
    return false  // Let SDK handle
}

onUserSendMessage()

Called when a user sends a chat message during a livestream.

Parameters:

videoInfo - Context information about the current video
message - Chat message details

Chat Message:

data class ChatMessage(
    val username: String,   // The sender's username
    val messageId: String,  // Unique message identifier
    val text: String       // The message content
)

Returns: Boolean

true - Message handled by your app (message will not be sent to chat)
false - Let SDK handle the message (message will be sent)

Example:

override fun onUserSendMessage(
    videoInfo: VideoInfo,
    message: ChatMessage
): Boolean {
    Log.d("Livestream", "Message from ${message.username}: ${message.text}")
    
    // Filter inappropriate content
    if (containsInappropriateContent(message.text)) {
        showError("Message contains inappropriate content")
        return true  // Block the message
    }
    
    // Enforce rate limiting
    if (isUserSpamming(message.username)) {
        showError("You're sending messages too quickly")
        return true  // Block the message
    }
    
    // Track chat activity
    trackChatMessage(videoInfo.videoId, message.messageId)
    
    return false  // Allow message to be sent
}

onUserSendLike()

Called when a user sends a like/heart during a livestream.

Parameters:

videoInfo - Context information about the current video

Returns: Boolean

true - Like handled by your app (like will not be sent)
false - Let SDK handle the like (like will be sent)

Example:

override fun onUserSendLike(videoInfo: VideoInfo): Boolean {
    Log.d("Livestream", "Like sent for video: ${videoInfo.videoId}")
    
    // Track engagement
    trackLikeAction(videoInfo.videoId)
    
    return false  // Let SDK handle the default behavior
}

Complete Interaction Listener Example:

FireworkSdk.livestream.setOnInteractionListener(object : Livestream.OnInteractionListener {
    override fun onUserSubmitAnswerToQuestion(
        videoInfo: VideoInfo,
        question: QuestionInteraction
    ): Boolean {
        handleQuestion(videoInfo, question)
        return false
    }
    
    override fun onUserSelectOptionForPoll(
        videoInfo: VideoInfo,
        poll: PollInteraction
    ): Boolean {
        handlePoll(videoInfo, poll)
        return false
    }
    
    override fun onUserJoinGiveaway(
        videoInfo: VideoInfo,
        giveaway: GiveawayInteraction
    ): Boolean {
        handleGiveaway(videoInfo, giveaway)
        return false
    }
    
    override fun onUserSendMessage(
        videoInfo: VideoInfo,
        message: ChatMessage
    ): Boolean {
        return handleChatMessage(videoInfo, message)
    }
    
    override fun onUserSendLike(videoInfo: VideoInfo): Boolean {
        handleLike(videoInfo)
        return false
    }
})

Remove Listener:

// Set null to remove the listener
FireworkSdk.livestream.setOnInteractionListener(null)

Giveaway Terms and Conditions Listener

setOnGiveawayTermsAndConditionsClickListener()

Handles clicks on giveaway terms and conditions links.

Signature:

fun setOnGiveawayTermsAndConditionsClickListener(
    listener: OnGiveawayTermsAndConditionsClickListener?
)

Listener Interface:

fun interface OnGiveawayTermsAndConditionsClickListener {
    fun onGiveawayTermsAndConditionsClick(
        type: WidgetType,
        title: String,
        url: String?,
        videoInfo: VideoInfo
    )
}

Parameters:

type - Widget type where the click occurred
title - Title of the terms and conditions
url - URL to the terms and conditions page (can be null)
videoInfo - Context information about the current video

Example:

FireworkSdk.livestream.setOnGiveawayTermsAndConditionsClickListener { 
    type, title, url, videoInfo ->
    
    Log.d("Livestream", "T&C clicked: $title")
    Log.d("Livestream", "Widget type: $type")
    
    // Open terms and conditions in a custom WebView or browser
    url?.let { 
        openTermsAndConditions(it)
    } ?: run {
        showError("Terms and conditions not available")
    }
}

Use Cases:

Open terms and conditions in a WebView
Display terms in a custom dialog
Track T&C view analytics
Enforce user agreement before giveaway entry

Remove Listener:

FireworkSdk.livestream.setOnGiveawayTermsAndConditionsClickListener(null)

Username Update Listener

setOnUpdateUsernameListener()

Monitors username update results (success or failure).

Signature:

fun setOnUpdateUsernameListener(listener: OnUpdateUsernameListener?)

Listener Interface:

interface OnUpdateUsernameListener {
    fun onUsernameUpdateSuccessfully(videoInfo: VideoInfo, username: String)
    
    fun onUsernameUpdateFailed(videoInfo: VideoInfo, username: String?, error: String?)
}

onUsernameUpdateSuccessfully()

Called when username is updated successfully.

Parameters:

videoInfo - Context information about the current video
username - The new username that was set

Example:

override fun onUsernameUpdateSuccessfully(videoInfo: VideoInfo, username: String) {
    Log.d("Livestream", "Username updated to: $username")
    
    // Show success message
    showToast("Username updated to $username")
    
    // Save to preferences
    saveUsername(username)
    
    // Update UI
    updateUserProfileDisplay(username)
}

onUsernameUpdateFailed()

Called when username update fails.

Parameters:

videoInfo - Context information about the current video
username - The username that failed to update (can be null)
error - Error message describing why the update failed (can be null)

Example:

override fun onUsernameUpdateFailed(
    videoInfo: VideoInfo,
    username: String?,
    error: String?
) {
    Log.e("Livestream", "Failed to update username to: $username")
    Log.e("Livestream", "Error: $error")
    
    // Show error message
    val errorMsg = error ?: "Failed to update username"
    showError(errorMsg)
    
    // Revert UI changes
    revertUsernameDisplay()
}

Complete Example:

FireworkSdk.livestream.setOnUpdateUsernameListener(object : Livestream.OnUpdateUsernameListener {
    override fun onUsernameUpdateSuccessfully(videoInfo: VideoInfo, username: String) {
        // Handle success
        showToast("Welcome, $username!")
        saveUsernameToPreferences(username)
    }
    
    override fun onUsernameUpdateFailed(
        videoInfo: VideoInfo,
        username: String?,
        error: String?
    ) {
        // Handle failure
        val message = error ?: "Username update failed"
        showErrorDialog(message)
    }
})

Remove Listener:

FireworkSdk.livestream.setOnUpdateUsernameListener(null)

VideoInfo Context

All callbacks provide a VideoInfo object containing context about the current video:

data class VideoInfo(
    val videoId: String,           // Unique video identifier
    val channelId: String?,        // Channel identifier
    val title: String?,            // Video title
    val description: String?,      // Video description
    val thumbnailUrl: String?,     // Thumbnail image URL
    // ... additional properties
)

Common Uses:

Track analytics with video context
Implement video-specific logic
Display video information in custom UI
Link interactions to specific content

Best Practices

Return Values

Return true when you handle the interaction completely and want to prevent default SDK behavior
Return false when you want SDK to handle the interaction after your custom logic

Performance

Keep callback implementations lightweight
Avoid blocking operations
Use coroutines for async work
Cache frequently accessed data

Livestream Overview - Complete livestream integration guide
Livestream Chat - Chat management and username configuration
FireworkSdk API Reference - Complete API documentation
Getting Started - SDK initialization

API Summary

Callback

Description

Return Type

setOnLinkClicked()

Handle link clicks

void

setOnInteractionListener()

Handle all user interactions

void

onUserSubmitAnswerToQuestion()

Handle question submissions

Boolean

onUserSelectOptionForPoll()

Handle poll votes

Boolean

onUserJoinGiveaway()

Handle giveaway entries

Boolean

onUserSendMessage()

Handle chat messages

Boolean

onUserSendLike()

Handle like actions

Boolean

setOnGiveawayTermsAndConditionsClickListener()

Handle T&C clicks

void

setOnUpdateUsernameListener()

Monitor username updates

void

PreviousLivestream Support NextLivestream Chat

Last updated 1 day ago

Overview

Link Click Listener

setOnLinkClicked()

Interaction Listener

setOnInteractionListener()

onUserSubmitAnswerToQuestion()

onUserSelectOptionForPoll()

onUserJoinGiveaway()

onUserSendMessage()

onUserSendLike()

Giveaway Terms and Conditions Listener

setOnGiveawayTermsAndConditionsClickListener()

Username Update Listener

setOnUpdateUsernameListener()

onUsernameUpdateSuccessfully()

onUsernameUpdateFailed()

VideoInfo Context

Best Practices

Return Values

Performance

Related Documentation

API Summary