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

Related Documentation

• 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