> 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/livestream-callbacks.md).

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

```kotlin
fun setOnLinkClicked(listener: OnLinkClickListener?)
```

**Listener Interface:**

```kotlin
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:**

```kotlin
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:**

```kotlin
// 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:**

```kotlin
fun setOnInteractionListener(listener: OnInteractionListener?)
```

**Listener Interface:**

```kotlin
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:**

```kotlin
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:**

```kotlin
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:**

```kotlin
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:**

```kotlin
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:**

```kotlin
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:**

```kotlin
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:**

```kotlin
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:**

```kotlin
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:**

```kotlin
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:**

```kotlin
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:**

```kotlin
// 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:**

```kotlin
fun setOnGiveawayTermsAndConditionsClickListener(
    listener: OnGiveawayTermsAndConditionsClickListener?
)
```

**Listener Interface:**

```kotlin
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:**

```kotlin
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:**

```kotlin
FireworkSdk.livestream.setOnGiveawayTermsAndConditionsClickListener(null)
```

***

## Username Update Listener

### setOnUpdateUsernameListener()

Monitors username update results (success or failure).

**Signature:**

```kotlin
fun setOnUpdateUsernameListener(listener: OnUpdateUsernameListener?)
```

**Listener Interface:**

```kotlin
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:**

```kotlin
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:**

```kotlin
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:**

```kotlin
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:**

```kotlin
FireworkSdk.livestream.setOnUpdateUsernameListener(null)
```

***

## VideoInfo Context

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

```kotlin
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](/firework-for-developers/android-sdk/integration-guide/livestream.md) - Complete livestream integration guide
* [Livestream Chat](/firework-for-developers/android-sdk/integration-guide/livestream/livestream-chat.md) - Chat management and username configuration
* [FireworkSdk API Reference](/firework-for-developers/android-sdk/integration-guide/firework-sdk-api.md) - Complete API documentation
* [Getting Started](/firework-for-developers/android-sdk/integration-guide/getting-started.md) - 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`      |