The Live Gifting Component provides a complete interactive solution for live streaming scenarios, covering features such as gift asset management, gift deduction callbacks, gift effect playback, and gift data analytics. With this document, you can quickly implement gift interaction features in your live room and support deep customization to meet your business needs.
Core Features
Gift Asset Configuration: Manage gift information, gift categories, and multi-language configurations via server-side APIs.
Gift List Display: Provides an out-of-the-box gift panel and playback component, supporting a complete user interaction flow.
Gift Deduction Callback: Seamlessly integrates with your billing system to complete balance verification and deduction processes.
Gift Effect Playback: Offers both basic and advanced effect players to meet different performance requirements.
PK Score Integration: Supports real-time linkage between gift value and host PK scores.
Gift Data Analytics: Provides comprehensive gift data statistics and query capabilities.
Component Composition
Component Name
Description
Gift Playback Component (GiftPlayView)
Responsible for rendering and playing gifts, supports special effect animations, and adapts to multiple scenarios.
Gift Selection Panel Component (GiftListView)
Responsible for displaying the gift list, supports gift sending and gift categories, and adapts to multiple devices.
Effect Demonstration
Gift Panel
Barrage Gift
Full-Screen Gift
Quick Start
Step 1: Activate the Service
Refer to the Activate Service document to activate the Trial or Official package.
Step 2: Code Integration
Refer to Prerequisites to integrate TUILiveKit. Version requirement: TUILiveKit >= 3.2.0.
Step 3: Integrate the Gift List Display Page
Integrate the gift list display page into your application so that viewers can intuitively see the list of available gifts. Refer to the sample code to create a GiftListView component and add it to your view:
Integrate the gift effects playback page into your application. The GiftPlayView component has built-in capabilities for receiving and playing gift messages. Refer to the sample code to create a GiftPlayView component and add it to your view:
In live streaming scenarios, the gift system needs to be tightly integrated with business logic such as billing systems and data analytics. This section details how to perform deep customization based on your business requirements.
1. Configuring Custom Gifts
Through the TUILiveKit server-side REST API, you can fully manage the gift inventory, achieving personalized customization of the gift system to meet the needs of different business scenarios.
Custom gift configuration is only supported through server-side REST API calls. For more configuration details, please refer to the
TUILiveKit does not have a built-in billing system. It needs to be integrated with your own billing system to complete the entire flow of "user sends gift → balance check → deduction → result synchronization".
Call Flow Diagram
Key Process Description
1. Client Initiates Gifting: The user completes the gift sending interaction on the GiftListPanel component in the live room client.
2. TUILiveKit Triggers Callback: The TUILiveKit backend calls the callback URL you configured, passing the gifting information (such as gift Coins, user identifier, etc.) to your backend.
3. Billing System Balance Deduction and Verification: Your backend system calls your customer billing system to verify if the user's balance is sufficient and performs the actual deduction.
4. Deduction Result Returned to TUILiveKit: Your backend returns the deduction result (success/failure) to the TUILiveKit backend.
5. TUILiveKit Synchronizes with Client: If the deduction is successful, the TUILiveKit backend broadcasts the gifting result to all clients in the room and triggers the playback of the gift effect animation. If the deduction fails, the TUILiveKit backend notifies the initiating client that the "gift sending request failed".
Overview of REST API Interfaces
Interface
Description
Request Example
Callback Configuration - Callback before sending a gift
The customer's backend can use this callback to decide whether to pass pre-gifting checks, etc.
We provide comprehensive gift data analytics capabilities to help you understand gift distribution, user behavior trends, and business operational effectiveness.
Call Flow Diagram
Key Process Description
1. TUILiveKit Collects and Stores Data: The TUILiveKit backend automatically collects all gift-related data and securely stores gift sending records and statistical information.
2. Query Data: Your backend service can call TUILiveKit REST API interfaces to query gift statistics.
3. TUILiveKit Returns Results: The TUILiveKit backend returns the formatted statistical results to your backend.Overview of REST API Interfaces
Overview of REST API Interfaces
Interface
Description
Request Example
Active Interface - Query Gift Statistics
Use this interface to get the gift receiving statistics for a specific user.
Typically, in live host PK scenarios, the value of gifts received by a host needs to be linked to their PK score (e.g., a viewer sends a "rocket" gift, and the host's PK score increases by 500 points). This enhances the competitiveness of PK and the atmosphere of the live stream through gift interaction.
Note:
The PK score system in the TUILiveKit backend uses a pure numerical calculation and accumulation mechanism. Therefore, you need to complete the PK score calculation according to your own operational strategies and business needs before calling the update interface. You can refer to the following PK score calculation example:
Gift Type
Score Calculation Rule
Example
Basic Gift
Gift value × 5
1 USD gift → 50 points
Intermediate Gift
Gift value × 8
5 USD gift → 400 points
Senior Gift
Gift value × 12
10 USD gift → 1,200 points
Special Effect Gift
Fixed high score
99 USD gift → 12000 points
Call Flow Diagram
Key Process Description
1. Get PK Status:
Callback Configuration: You can configure the PK Status Callback, allowing the TUILiveKit backend to actively notify your system of the PK status when a PK starts or ends.
Active Query: Your backend service can actively call the Query PK Status interface to check the current PK status at any time.
2. PK Score Calculation: Your backend service calculates the PK score increment based on business rules (like the example above).
3. PK Score Update: Your backend service calls the Modify PK Score interface to update the PK score in the TUILiveKit backend.
4. TUILiveKit Synchronizes with Client: The TUILiveKit backend automatically synchronizes the updated PK score to all clients.
Overview of REST API Interfaces
Interface
Description
Request Example
Active Interface - Query PK Status
Use this interface to check if the current room is in a PK.
Supports larger animation files. Performance overhead is lower when playing complex effects, ensuring smooth playback of multiple animations simultaneously, especially on low-end devices.
Advanced Effects Player Integration
You only need to follow the steps below to integrate the TUILiveKit advanced effects playback capability.
Android
iOS
1. Download Component:Download and unzip TUILiveKit, and copy the Android/tceffectplayerkit folder into your project, at the same level as your app directory.
2. Integrate Component:Edit your project's settings.gradle file and add the following code:
include ':tceffectplayerkit'
3. Initialize Authentication: In your app's initialization location, call the method from TCMediaXBase for authentication. To get the LicenseUrl and LicenseKey, please see the License Guide.
TCMediaXBase.getInstance().setLicense(context,
"LicenseUrl",// Please replace with your LicenseUrl
"LicenseKey",// Please replace with your LicenseKey
4. After completing the above steps, TUILiveKit will automatically switch to the advanced effects player. You do not need to do anything else.
1. Download Component:Download and unzip TUILiveKit, and copy the iOS/TCEffectPlayerKit folder into your project, at the same level as your Podfile.
2. Integrate Component:Edit your Podfile, add the following code, and run pod install in the terminal:
pod 'TCEffectPlayerKit',:podspec=>'./TCEffectPlayerKit/TCEffectPlayerKit.podspec'
3. Initialize Authentication:In your app's initialization location, call the method from TCMediaXBase for authentication. To get the LicenseUrl and LicenseKey, please see the License Guide.
4. After completing the above steps, TUILiveKit will automatically switch to the advanced effects player. You do not need to do anything else.
FAQ
Do I need to develop the billing system myself?
Yes. TUILiveKit integrates with your billing system via a callback mechanism. You need to implement your own user account system, handle the deduction verification callback, and manage the points distribution rules.
Do I need to care about PK integration? How does it work?
Yes, you need to care about it. The PK score system provided by TUILiveKit is based on a pure numerical accumulation mechanism. You need to calculate the PK score increase for each gift according to your business needs, and then call the TUILiveKit interface to update the score. TUILiveKit will automatically synchronize the score to the client.
How do I configure gifts if I only have a client and no server?
If you do not have your own server, you can use API tools like Postman or Apifox to directly call the REST APIs provided by TUILiveKit to configure the gift list.
Will gift notifications be blocked by muting or frequency control?
No. Gift notifications are not affected by muting or frequency control, ensuring reliable delivery.
What should I do if the special effect playback is lagging?
Please check if your SVGA file size is less than 10MB. If the file is too large, you might consider upgrading to the advanced effects player for better performance.