@tencent-rtc/mcp 1.3.2 → 1.3.4

package/resource/doc/livekit/live/android/live-gift.md

@@ -0,0 +1,822 @@
+`GiftStore` is a dedicated module within **AtomicXCore** for managing live room gifting features. It enables you to build a complete gifting system for your live streaming application, supporting robust monetization and interactive experiences.
+<table>
+<tr>
+<td rowspan="1" colSpan="1" >**Gift Panel**</td>
+
+<td rowspan="1" colSpan="1" >**Barrage Gift**</td>
+
+<td rowspan="1" colSpan="1" >**Full-Screen Gift**</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027182498/7b61daa5c6bc11f0b011525400bf7822.png)</td>
+
+<td rowspan="1" colSpan="1" >![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027182498/7afa1bb7c6bc11f0a93d52540044a08e.png)</td>
+
+<td rowspan="1" colSpan="1" >![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027182498/7b633146c6bc11f09e745254007c27c5.gif)</td>
+</tr>
+</table>
+
+
+## Core Features
+- **Gift List Retrieval**: Retrieve gift panel data from the server, including gift categories and details.
+
+- **Send Gift**: Viewers can send selected gifts and specify the quantity to the host.
+
+- **Gift Event Broadcast:** Receive real-time gift events in the room for displaying gift animations and barrage notifications.
+
+
+## Core Concepts
+<table>
+<tr>
+<td rowspan="1" colSpan="1" >**Core Concept**</td>
+
+<td rowspan="1" colSpan="1" >**Type**</td>
+
+<td rowspan="1" colSpan="1" >**Core Responsibilities & Description**</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >`Gift`</td>
+
+<td rowspan="1" colSpan="1" >`data class`</td>
+
+<td rowspan="1" colSpan="1" >Represents a gift data model, including ID, name, icon URL, animation resource URL (resourceURL), price (coins), and more.</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >`GiftCategory`</td>
+
+<td rowspan="1" colSpan="1" >`data class`</td>
+
+<td rowspan="1" colSpan="1" >Represents a gift category (e.g., "Popular", "Luxury"). Contains the category name and a list of Gift objects.</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >`GiftState`</td>
+
+<td rowspan="1" colSpan="1" >`data class`</td>
+
+<td rowspan="1" colSpan="1" >Represents the current state of the gift module. The core property, usableGifts, is a StateFlow containing the full gift list from the server.</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >`GiftEvent`</td>
+
+<td rowspan="1" colSpan="1" >`abstract class`</td>
+
+<td rowspan="1" colSpan="1" >Defines the event listener for gift events in the live room. Currently, only onReceiveGift is available; all users in the room receive this event when any user sends a gift.</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >`GiftStore`</td>
+
+<td rowspan="1" colSpan="1" >`abstract class`</td>
+
+<td rowspan="1" colSpan="1" >The core management class for gift features. Use it to fetch the gift list, send gifts, and receive gift events via listeners.</td>
+</tr>
+</table>
+
+
+## Implementation
+
+### Step 1: Component Integration
+
+> **Note：**
+> 
+
+> To use the gifting system, activate either the **Free Trial,** or **Pro **edition. The number of configurable gifts depends on the selected package. For details, see the **Gift System** section in [Feature and Billing Description](https://write.woa.com/document/137771241658241024) and choose the package that fits your needs.
+> 
+
+- **Video Live Streaming**: Please refer to [Quick Start](https://write.woa.com/document/194571606056804352) to integrate AtomicXCore.
+
+- **Voice Chat Room**: Please refer to [Quick Start](https://write.woa.com/document/194571595678187521) to integrate AtomicXCore.
+
+
+### Step 2: Initialize and Listen for Gift Events
+
+Obtain a `GiftStore` instance and set up listeners to receive gift events and updates to the gift list.
+
+#### Implementation
+1. **Get Instance**: Use `GiftStore.create(liveID) `to obtain a `GiftStore` instance for the current live room.
+
+2. **Add Listener**: Add a `GiftListener` to receive `onReceiveGift` events.
+
+3. **Subscribe to State**: Subscribe to `giftStore.giftState.usableGifts`to receive gift list updates.
+
+
+#### Code Example
+``` kotlin
+import io.trtc.tuikit.atomicxcore.api.gift.Gift
+import io.trtc.tuikit.atomicxcore.api.gift.GiftCategory
+import io.trtc.tuikit.atomicxcore.api.gift.GiftListener
+import io.trtc.tuikit.atomicxcore.api.gift.GiftStore
+import io.trtc.tuikit.atomicxcore.api.live.LiveUserInfo
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.launch
+
+class GiftManager(
+    private val liveId: String
+) {
+    private val giftStore: GiftStore = GiftStore.create(liveId)
+    private val coroutineScope = CoroutineScope(Dispatchers.Main)
+    // Expose gift list externally
+    private val _giftList = MutableStateFlow<List<GiftCategory>>(emptyList())
+    val giftList: StateFlow<List<GiftCategory>> = _giftList.asStateFlow()
+
+    init {
+        setupGiftListener()
+        subscribeToGiftState()
+    }
+
+    // Subscribe to gift events
+    private fun setupGiftListener() {
+        giftStore.addGiftListener(object : GiftListener() {
+            override fun onReceiveGift(liveID: String, gift: Gift, count: Int, sender: LiveUserInfo) {
+                // Forward event to UI layer for processing
+            }
+        })
+    }
+
+    // Subscribe to gift list state
+    private fun subscribeToGiftState() {
+        coroutineScope.launch(Dispatchers.Main) {
+            giftStore.giftState.usableGifts.collect { giftList ->
+                _giftList.value = giftList
+            }
+        }
+    }
+}
+```
+
+#### Gift List Structure Parameters
+- **GiftCategory Parameter Description**
+
+<table>
+<tr>
+<td rowspan="1" colSpan="1" >**Parameter**</td>
+
+<td rowspan="1" colSpan="1" >**Type**</td>
+
+<td rowspan="1" colSpan="1" >**Description**</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >`categoryID`</td>
+
+<td rowspan="1" colSpan="1" >`String`</td>
+
+<td rowspan="1" colSpan="1" >Unique ID of the gift category.</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >`name`</td>
+
+<td rowspan="1" colSpan="1" >`String`</td>
+
+<td rowspan="1" colSpan="1" >Display name of the gift category.</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >`desc`</td>
+
+<td rowspan="1" colSpan="1" >`String`</td>
+
+<td rowspan="1" colSpan="1" >Description of the gift category.</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >`extensionInfo`</td>
+
+<td rowspan="1" colSpan="1" >`Map<String, String>`</td>
+
+<td rowspan="1" colSpan="1" >Extension information field.</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >`giftList`</td>
+
+<td rowspan="1" colSpan="1" >`List`</td>
+
+<td rowspan="1" colSpan="1" >Array of Gift objects in this category.</td>
+</tr>
+</table>
+
+- **Gift Parameter Description**
+
+<table>
+<tr>
+<td rowspan="1" colSpan="1" >**Parameter**</td>
+
+<td rowspan="1" colSpan="1" >**Type**</td>
+
+<td rowspan="1" colSpan="1" >**Description**</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >`giftID`</td>
+
+<td rowspan="1" colSpan="1" >`String`</td>
+
+<td rowspan="1" colSpan="1" >Unique ID of the gift.</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >`name`</td>
+
+<td rowspan="1" colSpan="1" >`String`</td>
+
+<td rowspan="1" colSpan="1" >Display name of the gift.</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >`desc`</td>
+
+<td rowspan="1" colSpan="1" >`String`</td>
+
+<td rowspan="1" colSpan="1" >Description of the gift.</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >`iconURL`</td>
+
+<td rowspan="1" colSpan="1" >`String`</td>
+
+<td rowspan="1" colSpan="1" >Gift icon URL.</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >`resourceURL`</td>
+
+<td rowspan="1" colSpan="1" >`String`</td>
+
+<td rowspan="1" colSpan="1" >Gift animation resource URL.</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >`level`</td>
+
+<td rowspan="1" colSpan="1" >`Long`</td>
+
+<td rowspan="1" colSpan="1" >Gift level.</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >`coins`</td>
+
+<td rowspan="1" colSpan="1" >`Long`</td>
+
+<td rowspan="1" colSpan="1" >Gift price.</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >`extensionInfo`</td>
+
+<td rowspan="1" colSpan="1" >`Map<String, String>`</td>
+
+<td rowspan="1" colSpan="1" >Extension information field.</td>
+</tr>
+</table>
+
+
+### Step 3: Retrieve Gift List
+
+Call the `refreshUsableGifts` method to fetch gift data from the server.
+
+#### Implementation
+1. **Call API**: Call `giftStore.refreshUsableGifts()` at the appropriate time (e.g., after entering the live room).
+
+2. **Handle Callback**: Optionally handle the completion callback to determine the result.
+
+3. **Receive Data**: After a successful fetch, the updated usableGifts list is delivered automatically via your subscription to `giftStore.giftState.usableGifts`.
+
+
+#### Code Example
+``` kotlin
+class GiftManager(
+    private val liveId: String
+) {
+    private val giftStore: GiftStore = GiftStore.create(liveId)
+
+    // Refresh the gift list from the server
+    fun fetchGiftList() {
+        giftStore.refreshUsableGifts(object : CompletionHandler {
+            override fun onSuccess() {
+                println("Gift list fetched successfully")
+                // Data will be updated via the giftState subscription
+            }
+
+            override fun onFailure(code: Int, desc: String) {
+                println("Failed to fetch gift list: $desc")
+            }
+        })
+    }
+}
+```
+
+### Step 4: Send Gift
+
+When a user selects a gift and clicks send, call the `sendGift` API.
+
+#### Implementation
+1. **Get Parameters**: Obtain the selected `giftID` and `quantity (count)` from the UI.
+
+2. **Call API**: Call `giftStore.sendGift(giftID, count, completion)`.
+
+3. **Handle Callback**: Use the completion `callback` to handle failures (e.g., insufficient balance). UI updates (animations, barrage) after a successful send should be triggered by the `onReceiveGift` event.
+
+
+#### Code Example
+``` kotlin
+class GiftManager(
+    private val liveId: String
+) {
+    private val giftStore: GiftStore = GiftStore.create(liveId)
+
+    // Send a gift
+    fun sendGift(giftID: String, count: Int) {
+        giftStore.sendGift(giftID, count, object : CompletionHandler {
+            override fun onSuccess() {
+                println("Gift $giftID sent successfully")
+                // All users, including the sender, will receive the onReceiveGift event
+            }
+
+            override fun onFailure(code: Int, desc: String) {
+                println("Gift send failed: $desc")
+                // Prompt user if needed, e.g., "Insufficient balance" or "Network error"
+            }
+        })
+    }
+}
+```
+
+#### **sendGift API Parameters**
+<table>
+<tr>
+<td rowspan="1" colSpan="1" >**Parameter Name**</td>
+
+<td rowspan="1" colSpan="1" >**Type**</td>
+
+<td rowspan="1" colSpan="1" >**Description**</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >`giftID`</td>
+
+<td rowspan="1" colSpan="1" >`String`</td>
+
+<td rowspan="1" colSpan="1" >Unique ID of the gift to send.</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >`count`</td>
+
+<td rowspan="1" colSpan="1" >`Int`</td>
+
+<td rowspan="1" colSpan="1" >Number of gifts to send.</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >`completion`</td>
+
+<td rowspan="1" colSpan="1" >`CompletionHandler?`</td>
+
+<td rowspan="1" colSpan="1" >Callback invoked after sending completes.</td>
+</tr>
+</table>
+
+
+## Advanced Features
+
+The capabilities of `GiftStore` are closely tied to your backend services. This section explains how to build a feature-rich gifting system through server-side configuration and client integration.
+
+### Gift Asset Configuration
+
+Customize available gift types, categories, names, icons, prices, and animation effects to meet your operational and branding requirements.
+
+#### Implementation
+1. **Server-Side Configuration**: Use the `LiveKit` server REST API to manage gift information, categories, and multi-language support. See the [Gift Configuration Guide](https://write.woa.com/document/185130564680273920).
+
+2. **Client Fetch**: On the client, call `refreshUsableGifts` to retrieve configuration data.
+
+3. **UI Display**: Use the retrieved `List<GiftCategory>` to populate the gift panel.
+
+
+#### Configuration Sequence Diagram
+
+![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027182498/8c76ea1ec6bc11f0aedb525400454e06.png)
+
+
+#### Related REST API Interfaces Overview
+<table>
+<tr>
+<td rowspan="1" colSpan="1" >**Interface Category**</td>
+
+<td rowspan="1" colSpan="1" >**Interface**</td>
+
+<td rowspan="1" colSpan="1" >**Request Example**</td>
+</tr>
+
+<tr>
+<td rowspan="3" colSpan="1" >**​Gift Management**</td>
+
+<td rowspan="1" colSpan="1" >Add Gift Information</td>
+
+<td rowspan="1" colSpan="1" >[Example](https://write.woa.com/document/185130814885187584)</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >Delete Gift Information</td>
+
+<td rowspan="1" colSpan="1" >[Example](https://write.woa.com/document/185131021432451072)</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >Query Gift Information</td>
+
+<td rowspan="1" colSpan="1" >[Example](https://write.woa.com/document/185130925608591360)</td>
+</tr>
+
+<tr>
+<td rowspan="3" colSpan="1" >**Gift Category Management**</td>
+
+<td rowspan="1" colSpan="1" >Add Gift Category Information</td>
+
+<td rowspan="1" colSpan="1" >[Example](https://write.woa.com/document/185131054187974656)</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >Delete Specific Gift Category Information</td>
+
+<td rowspan="1" colSpan="1" >[Example](https://write.woa.com/document/185131288984932352)</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >Get Specific Gift Category Information</td>
+
+<td rowspan="1" colSpan="1" >[Example](https://write.woa.com/document/185131164168736768)</td>
+</tr>
+
+<tr>
+<td rowspan="3" colSpan="1" >**Gift Relationship Management**</td>
+
+<td rowspan="1" colSpan="1" >Add Relationship between a Specific Gift Category and Gift</td>
+
+<td rowspan="1" colSpan="1" >[Example](https://write.woa.com/document/185131388068356096)</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >Delete Relationship between a Specific Gift Category and Gift</td>
+
+<td rowspan="1" colSpan="1" >[Example](https://write.woa.com/document/185131491225227264)</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >Get Gift Relationships under a Specific Gift Category</td>
+
+<td rowspan="1" colSpan="1" >[Example](https://write.woa.com/document/185131634710056960)</td>
+</tr>
+
+<tr>
+<td rowspan="6" colSpan="1" >**Gift Multi-language Management**</td>
+
+<td rowspan="1" colSpan="1" >Add Gift Multi-language Information</td>
+
+<td rowspan="1" colSpan="1" >[Example](https://write.woa.com/document/185131766094020608)</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >Delete Specific Gift Multi-language Information</td>
+
+<td rowspan="1" colSpan="1" >[Example](https://write.woa.com/document/185132041665441792)</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >Get Gift Multi-language Information</td>
+
+<td rowspan="1" colSpan="1" >[Example](https://write.woa.com/document/185131910582956032)</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >Add Gift Category Multi-language Information</td>
+
+<td rowspan="1" colSpan="1" >[Example](https://write.woa.com/document/185132145524985856)</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >Delete Specific Gift Category Multi-language Information</td>
+
+<td rowspan="1" colSpan="1" >[Example](https://write.woa.com/document/185132396568891392)</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >Get Gift Category Multi-language Information</td>
+
+<td rowspan="1" colSpan="1" >[Example](https://write.woa.com/document/185132283123777536)</td>
+</tr>
+</table>
+
+
+### Billing and Gift Deduction Process
+
+When a viewer sends a gift, ensure their account balance is sufficient and complete the deduction before triggering the gift effect playback and broadcast.
+
+#### Implementation
+1. **Backend Callback Configuration**: Configure your billing system's callback URL in the LiveKit backend. See [Callback Configuration Documentation](https://write.woa.com/document/155612057789870080).
+
+2. **Client Send**: The client calls `sendGift`.
+
+3. **Backend Interaction**: The LiveKit backend calls your callback URL; your billing system processes the deduction and returns the result.
+
+4. **Result Synchronization**: If successful, **AtomicXCore** broadcasts the `onReceiveGift` event; if failed, the completion callback of sendGift receives an error.
+
+
+#### Call Flow
+
+![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027182498/997f5343c6bc11f0a93d52540044a08e.png)
+
+
+#### Related REST API Interfaces Overview
+<table>
+<tr>
+<td rowspan="1" colSpan="1" >**Interface**</td>
+
+<td rowspan="1" colSpan="1" >**Description**</td>
+
+<td rowspan="1" colSpan="1" >**Request Example**</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >**Callback Configuration - Callback before sending a gift**</td>
+
+<td rowspan="1" colSpan="1" >The customer's backend can use this callback to decide whether to pass pre-gifting checks, etc.</td>
+
+<td rowspan="1" colSpan="1" >[Example](https://write.woa.com/document/183772991768039424)</td>
+</tr>
+</table>
+
+
+### Implement Full-Screen Gift Animation Playback
+
+When a user sends a luxury gift (e.g., "Rocket", "Carnival"), play a full-screen animation (such as SVGA) to enhance engagement.
+
+#### Implementation
+
+**AtomicXCore** does not include a built-in gift animation player. Integrate a third-party library based on your requirements. Below is a comparison of two options:
+<table>
+<tr>
+<td rowspan="1" colSpan="1" >**Comparison Item**</td>
+
+<td rowspan="1" colSpan="1" >**Basic Solution (SVGAPlayer)**</td>
+
+<td rowspan="1" colSpan="1" >**Gift AR (TCEffectPlayerKit)**</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >Billing</td>
+
+<td rowspan="1" colSpan="1" >Free (open source)</td>
+
+<td rowspan="1" colSpan="1" >Paid (requires license). See [Billing Guide](https://trtc.io/document/69949?product=beautyar&menulabel=core%20sdk&platform=android#X-Series-Capabilities)</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >Integration Method</td>
+
+<td rowspan="1" colSpan="1" >Manual integration via Gradle</td>
+
+<td rowspan="1" colSpan="1" >Requires additional integration and authentication</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >Supported Animation Formats</td>
+
+<td rowspan="1" colSpan="1" >SVGA only</td>
+
+<td rowspan="1" colSpan="1" >SVGA, PAG, WebP, Lottie, MP4, and more</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >Performance</td>
+
+<td rowspan="1" colSpan="1" >Recommended SVGA file size ≤ 10MB</td>
+
+<td rowspan="1" colSpan="1" >Supports larger files, better performance for complex/multiple/low-end scenarios</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >Recommended Scenario</td>
+
+<td rowspan="1" colSpan="1" >Uniform SVGA format, controllable file size</td>
+
+<td rowspan="1" colSpan="1" >Multiple formats or higher performance/device compatibility needs</td>
+</tr>
+</table>
+
+
+This section demonstrates the basic solution. For the **Gift AR** see the [TCEffectPlayer Integration Guide](https://trtc.io/document/70531?product=beautyar&menulabel=core%20sdk&platform=android).
+
+#### Basic Solution: Using SVGAPlayer
+1. **Integrate SVGAPlayer**: Add the SVGAPlayer dependency to your build.gradle and sync the project.
+
+   ``` gradle
+   dependencies {
+       // ... other dependencies
+       implementation 'com.github.yyued:SVGAPlayer-Android:2.6.1'
+   }
+   ```
+2. **Listen for Gift Events**: Subscribe to the `GiftListener` in `GiftStore`.
+
+3. **Parse and Play**: On `onReceiveGift`, check if `gift.resourceURL` is a valid SVGA file. Use `SVGAParser` to parse and play the animation.
+
+
+#### Code Example
+``` kotlin
+import android.os.Bundle
+import androidx.appcompat.app.AppCompatActivity
+import com.opensource.svgaplayer.SVGAParser
+import com.opensource.svgaplayer.SVGAVideoEntity
+import com.opensource.svgaplayer.SVGAImageView
+import io.trtc.tuikit.atomicxcore.api.gift.Gift
+import io.trtc.tuikit.atomicxcore.api.gift.GiftListener
+import io.trtc.tuikit.atomicxcore.api.gift.GiftStore
+import io.trtc.tuikit.atomicxcore.api.live.LiveUserInfo
+import java.net.URL
+
+class LiveRoomActivity : AppCompatActivity() {
+    private lateinit var giftStore: GiftStore
+    private lateinit var svgaImageView: SVGAImageView
+    private lateinit var svgaParser: SVGAParser
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContentView(R.layout.activity_live_room)
+        setupSVGAPlayer()
+    }
+
+private fun setupSVGAPlayer() {
+        svgaImageView = findViewById(R.id.svga_player)
+        svgaParser = SVGAParser(this)
+        svgaImageView.visibility = android.view.View.GONE
+        
+        // Set the gift animation to play only once.
+        svgaImageView.loops = 1
+        
+        // Set a completion callback to hide and clean up resources after playback.
+        svgaImageView.callback = object : SVGACallback {
+            override fun onFinished() {
+                svgaImageView.visibility = android.view.View.GONE
+                svgaImageView.clear()
+            }
+            override fun onPause() {}
+            override fun onRepeat() {}
+            override fun onStep(frame: Int, percentage: Double) {}
+        }
+    }
+
+    fun setupGiftSubscription(liveId: String) {
+        giftStore = GiftStore.create(liveId)
+
+        giftStore.addGiftListener(object : GiftListener() {
+            override fun onReceiveGift(liveID: String, gift: Gift, count: Int, sender: LiveUserInfo) {
+                if (gift.resourceURL.isNotEmpty()) {
+                    try {
+                        val url = URL(gift.resourceURL)
+                        playAnimation(url)
+                    } catch (e: Exception) {
+                        println("Invalid animation URL: ${gift.resourceURL}")
+                    }
+                }
+            }
+        })
+    }
+    
+    private fun playAnimation(url: URL) {
+        svgaParser.decodeFromURL(url, object : SVGAParser.ParseCompletion {
+            override fun onComplete(videoItem: SVGAVideoEntity) {
+                runOnUiThread {
+                    svgaImageView.setVideoItem(videoItem)
+                    svgaImageView.visibility = android.view.View.VISIBLE
+                    svgaImageView.startAnimation()
+                }
+            }
+            
+            override fun onError() {
+                println("SVGA animation parsing failed")
+                // Optionally add retry or error reporting
+            }
+        })
+    }
+}
+```
+
+### Display Gift Messages in the Barrage Area
+
+When a user sends a gift, display a system message in the public barrage area (e.g., "[Viewer Nickname] sent [Gift Name] x [Quantity]") for all viewers.
+
+#### Implementation
+1. **Listen for Events**: Subscribe to the `GiftListener` in `giftStore`.
+
+2. **Obtain Information**: On `onReceiveGift`, extract the sender, gift, and count.
+
+3. **Get Barrage Store**: Use `BarrageStore.create(liveID)` for the current room.
+
+4. **Compose Message**: Create a Barrage object, set `messageType = BarrageType.TEXT`, and set textContent to your message.
+
+5. **Insert Locally**: Call `barrageStore.appendLocalTip(message: giftTip)` to add the message to the local barrage list.
+
+
+#### Code Example
+``` kotlin
+import io.trtc.tuikit.atomicxcore.api.barrage.Barrage
+import io.trtc.tuikit.atomicxcore.api.barrage.BarrageStore
+import io.trtc.tuikit.atomicxcore.api.barrage.BarrageType
+import io.trtc.tuikit.atomicxcore.api.gift.Gift
+import io.trtc.tuikit.atomicxcore.api.gift.GiftListener
+import io.trtc.tuikit.atomicxcore.api.gift.GiftStore
+import io.trtc.tuikit.atomicxcore.api.live.LiveUserInfo
+
+class LiveRoomManager(
+    private val liveId: String
+) {
+    private val giftStore: GiftStore = GiftStore.create(liveId)
+    private val barrageStore: BarrageStore = BarrageStore.create(liveId)
+
+    private fun setupGiftToBarrageFlow() {
+        giftStore.addGiftListener(object : GiftListener() {
+            override fun onReceiveGift(liveID: String, gift: Gift, count: Int, sender: LiveUserInfo) {
+                val tipText = "sent ${gift.name} x $count"
+                val giftTip = Barrage(
+                    liveID = liveID,
+                    messageType = BarrageType.TEXT,
+                    textContent = tipText
+                    sender = sender
+                )
+                barrageStore.appendLocalTip(giftTip)
+            }
+        })
+    }
+}
+```
+
+## API Documentation
+
+For complete details on all public interfaces, properties, and methods of [GiftStore](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.gift/-gift-store/index.html) and related classes, see the official API documentation for [AtomicXCore](https://tencent-rtc.github.io/TUIKit_Android/index.html). Key stores referenced in this guide include:
+<table>
+<tr>
+<td rowspan="1" colSpan="1" >**Store/Component**</td>
+
+<td rowspan="1" colSpan="1" >**Feature Description**</td>
+
+<td rowspan="1" colSpan="1" >**API Documentation**</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >GiftStore</td>
+
+<td rowspan="1" colSpan="1" >Gift interactions: fetch gift list, send/receive gifts, listen for gift events (including sender and gift details).</td>
+
+<td rowspan="1" colSpan="1" >[API Documentation](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.gift/-gift-store/index.html)</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >BarrageStore</td>
+
+<td rowspan="1" colSpan="1" >Barrage features: send text/custom barrage, maintain barrage list, listen to barrage status in real time.</td>
+
+<td rowspan="1" colSpan="1" >[API Documentation](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.barrage/-barrage-store/index.html)</td>
+</tr>
+</table>
+
+
+## FAQs
+
+### The gift list in GiftStore is empty. What should I do?
+
+You must call `refreshUsableGifts(completion)` to fetch gift data from your backend. Ensure your backend is configured with gift data via the server REST API.
+
+### How do I implement multi-language display for gifts (e.g., Chinese, English)?
+
+Use the `GiftStore.setLanguage(language: String)` API before calling `refreshUsableGifts`, passing the target language code (e.g., "en" or "zh-CN"). The server will return gift names and descriptions in the specified language.
+
+### I called sendGift, but the gift animation plays twice. Why?
+
+The `onReceiveGift` event is broadcast to all room members, including the sender. If you update the UI both in the sendGift completion callback and in the `onReceiveGift` event, the animation will play twice.
+- **Best Practice**: Only update the UI (e.g., play animations, show barrage) in the `onReceiveGift` event handler. Use the `sendGift` completion callback only for handling failures (such as "Send failed" or "Insufficient balance").
+
+
+### Where is the gift deduction logic implemented?
+
+Gift deduction is handled entirely by your billing system. AtomicXCore integrates with your billing system via a backend callback. When the client calls sendGift, your backend performs the deduction. After returning the result to the AtomicXCore backend, it determines whether to broadcast the gift event.
+
+### Will gift notifications be blocked by mute or message frequency controls?
+
+No. Gift notifications (`onReceiveGift` events) are not affected by mute or frequency controls and are always delivered reliably.
+
+### What should I do if gift animation playback stutters?
+
+Check your SVGA file size; the basic player recommends files no larger than 10MB. For large or complex animations, consider integrating the **Gift AR** provided by TUILiveKit for improved performance.