# Livestream Chat

The Firework SDK provides chat management APIs for livestream content. This guide covers username configuration, chat message handling, and related features.

## Overview

Livestream chat allows viewers to interact with hosts and other viewers during live. The SDK provides methods to:

* Update and retrieve user display names
* Configure username visibility and editability

All chat management APIs are accessed through `FireworkSdk.livestream`.

## Username Management

### updateUsername()

Updates the user's display name in livestream chat.

**Signature:**

```kotlin
fun updateUsername(username: String?)
```

**Parameters:**

* `username` - The new username to set (null to clear)

**Description:** Sets or updates the display name shown in livestream chat. This name will be visible to other viewers when the user sends chat messages.

**Example:**

```kotlin
// Set username
FireworkSdk.livestream.updateUsername("JohnDoe")
```

**With Success/Failure Handling:**

To monitor the result of username updates, use `setOnUpdateUsernameListener()`:

```kotlin
// Set update listener first
FireworkSdk.livestream.setOnUpdateUsernameListener(
    object : Livestream.OnUpdateUsernameListener {
        override fun onUsernameUpdateSuccessfully(
            videoInfo: VideoInfo,
            username: String
        ) {
            Log.d("Chat", "Username updated: $username")
            showToast("Welcome, $username!")
        }
        
        override fun onUsernameUpdateFailed(
            videoInfo: VideoInfo,
            username: String?,
            error: String?
        ) {
            Log.e("Chat", "Failed to update username: $error")
            showError(error ?: "Username update failed")
        }
    }
)

// Then update username
FireworkSdk.livestream.updateUsername("JohnDoe")
```

**Use Cases:**

* Set username when user logs in
* Allow users to change their display name
* Personalize chat experience
* Sync with your app's user profile

**Important Notes:**

* Username changes are applied to all active livestream sessions
* Previous chat messages will still show the old username
* Username validation (length, characters) is handled by the SDK
* Set the update listener before calling `updateUsername()` to receive callbacks

***

### getUsername()

Retrieves the current username.

**Signature:**

```kotlin
fun getUsername(): String?
```

**Returns:**

* `String?` - Current username, or null if not set

**Description:** Returns the currently configured username for livestream chat. This is the name that will be displayed when the user sends messages.

**Example:**

```kotlin
val currentUsername = FireworkSdk.livestream.getUsername()

if (currentUsername != null) {
    Log.d("Chat", "Current username: $currentUsername")
    displayUsername(currentUsername)
} else {
    Log.d("Chat", "No username set")
    promptForUsername()
}
```

***

### updateUsernameConfiguration()

Configures username display and editing behavior.

**Signature:**

```kotlin
fun updateUsernameConfiguration(config: UsernameConfiguration)
```

**Parameters:**

* `config` - Configuration object controlling username behavior

**Description:** Updates the configuration for how usernames are displayed and whether users can edit them. This affects the chat UI behavior.

**UsernameConfiguration Data Class:**

```kotlin
data class UsernameConfiguration(
    // Indicates whether the username is editable
    val isEditable: Boolean = true,
    
    // Indicates whether the username is hidden
    // If set to true, hint "Chat as XXX" will be hidden on the Chat input view
    val isHidden: Boolean = false
)
```

**Properties:**

#### isEditable

* **Type:** `Boolean`
* **Default:** `true`
* **Description:** Controls whether users can edit their username
* **When `true`:** Users can tap their username to change it
* **When `false`:** Username is locked and cannot be changed

#### isHidden

* **Type:** `Boolean`
* **Default:** `false`
* **Description:** Controls username visibility in chat input
* **When `true`:** The "Chat as XXX" hint is hidden from the chat input view
* **When `false`:** Username is displayed in the chat input hint

## Related Documentation

* [Livestream Overview](https://docs.firework.com/firework-for-developers/android-sdk/integration-guide/livestream) - Complete livestream integration guide
* [Livestream Callbacks](https://docs.firework.com/firework-for-developers/android-sdk/integration-guide/livestream/livestream-callbacks) - Complete callback API reference
* [FireworkSdk API Reference](https://docs.firework.com/firework-for-developers/android-sdk/integration-guide/firework-sdk-api) - Complete API documentation

## API Summary

| Method                          | Description                 | Returns   |
| ------------------------------- | --------------------------- | --------- |
| `updateUsername()`              | Update user display name    | `Unit`    |
| `getUsername()`                 | Get current username        | `String?` |
| `updateUsernameConfiguration()` | Configure username behavior | `Unit`    |

### Data Classes

| Class                   | Properties                                                                                          | Description                    |
| ----------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------ |
| `UsernameConfiguration` | <p><code>isEditable: Boolean</code><br><code>isHidden: Boolean</code></p>                           | Username display configuration |
| `ChatMessage`           | <p><code>username: String</code><br><code>messageId: String</code><br><code>text: String</code></p> | Chat message data              |