TUILiveKit delivers a complete solution for live streaming gift interactions, including gift asset management, gift billing callbacks, gift effect playback, and gift data statistics. This guide walks you through implementing interactive gifting features in your live room, with support for deep customization to fit your business requirements.
Note：
This guide introduces the gift system for UI-based integration. If you are integrating without UI components, please refer to the following integration approaches:
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.
Step 2: Code Integration
Complete TUILiveKit code integration before using the gift system. Multiple integration options are available; see Integration Method Description for details. After integration, both host and audience pages will include the Gift List page and gift effect playback by default.
Android: See Live Gift Components to integrate the Gift Selection Panel and Gift Playback Component.
iOS: See Live Gift Components to integrate the Gift Selection Panel and Gift Playback Component.
Feature Usage
For live streaming, the gift system should be integrated with your billing and data statistics systems. This section explains how to customize the system for your business.
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
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
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
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.
Gift AR SDK 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 Gift AR SDK for better performance.
