• 製品
  • 価格
  • リソース
  • サポート
このページは現在英語版のみで提供されており、日本語版も近日中に提供される予定です。ご利用いただきありがとうございます。

Live Gifting Component

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:
Android
iOS
Flutter
import android.os.Bundle;
import android.widget.FrameLayout;
import androidx.appcompat.app.AppCompatActivity;
import com.trtc.uikit.livekit.R;
import com.trtc.uikit.livekit.component.gift.GiftListView;

public class YourActivity extends AppCompatActivity {

@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.your_activity);

FrameLayout rootView = findViewById(R.id.root_view);
// 1. Create a GiftListView object
GiftListView giftListView = new GiftListView(this);
// 2. Initialize the GiftListView object
giftListView.init("yourRoomId");
// 3. Add the GiftListView object to your page
rootView.addView(giftListView);
}
}
import TUILiveKit

class YourGiftViewController: UIViewController {
// 1. Create a GiftListView object
// - roomId: Must be the same as the roomId of the live room the audience is currently in
lazy var giftListView = {
let view = GiftListView(roomId: liveId)
return view
}()

private let liveId: String
// ... other code ...

public override func viewDidLoad() {
super.viewDidLoad()
// 2. Add the component to your view and set its layout
view.addSubview(giftListView)
giftListView.snp.remakeConstraints { make in
make.leading.trailing.equalToSuperview()
make.height.equalTo(256)
make.bottom.equalToSuperview()
}
}
}
// 1. Construct the GiftListController object. Please ensure you create this object after successfully entering the room.
// - roomId: The ID of the live room the user is currently in.
// - language: Set the language code for gifts as configured in your gift system. Defaults to 'en'.
GiftListController _giftListController = GiftListController(roomId: 'roomId', language: 'en');


// 2. Add and use the GiftDisplayWidget component.
// 2.1 For single-child widgets, e.g., Container:
Container(
child: GiftListWidget(controller: _giftSendController)
)
// 2.2 For multi-child widgets, e.g., Column:
Column(
children: [GiftPanelWidget(controller: _giftSendController)]
)

Step 4: Integrate the Gift Effects Playback Page

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:
Android
iOS
Flutter
import android.os.Bundle;
import android.widget.FrameLayout;
import androidx.appcompat.app.AppCompatActivity;
import com.trtc.uikit.livekit.R;
import com.trtc.uikit.livekit.component.gift.GiftPlayView;

public class YourActivity extends AppCompatActivity {

@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.your_activity);

FrameLayout rootView = findViewById(R.id.root_view);
// 1. Create a GiftPlayView object
GiftPlayView giftPlayView = new GiftPlayView(this);
// 2. Initialize the GiftPlayView object
giftPlayView.init("yourRoomId");
// 3. Add the GiftPlayView object to your page
rootView.addView(giftPlayView);
}
}
import TUILiveKit
// YourAnchorViewController represents your host view controller. Audience-side integration can refer to this example:
class YourAnchorViewController: UIViewController {
// 1. Create and initialize a GiftPlayView object
// - roomId: Must be the same as the roomId of the live room the audience is currently in
lazy var giftPlayView = {
let view = GiftPlayView(roomId: liveId)
return view
}()

private let liveId: String
// ... other code ...

public override func viewDidLoad() {
super.viewDidLoad()
// 2. Add the component to your view and set its layout
view.addSubview(giftPlayView)
giftPlayView.snp.remakeConstraints { make in
make.edges.equalToSuperview()
}
}
}
// 1. Construct the GiftPlayController object. Please ensure you create this object after successfully entering the room.
GiftPlayController _giftPlayController = GiftPlayController(roomId: 'roomId');

// 2. Add and use the GiftPlayWidget component.
// 2.1 For single-child widgets, e.g., Container:
Container(
child: GiftPlayWidget(controller: _giftPlayController)
)
// 2.2 For multi-child widgets, e.g., Column:
Column(
children: [GiftPlayWidget(controller: _giftPlayController)]
)

Advanced Features

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

Configuration Sequence Diagram



Overview of REST API Interfaces

Interface Category
Interface
Request Example
​Gift Management
Add Gift Information
Example
Delete Gift Information
Example
Query Gift Information
Example
Gift Category Management
Add Gift Category Information
Example
Delete Specific Gift Category Information
Example
Get Specific Gift Category Information
Example
Gift Relationship Management
Add Relationship between a Specific Gift Category and Gift
Example
Delete Relationship between a Specific Gift Category and Gift
Example
Get Gift Relationships under a Specific Gift Category
Example
Gift Multi-language Management
Add Gift Multi-language Information
Example
Delete Specific Gift Multi-language Information
Example
Get Gift Multi-language Information
Example
Add Gift Category Multi-language Information
Example
Delete Specific Gift Category Multi-language Information
Example
Get Gift Category Multi-language Information
Example

2. Billing and Gift Deduction Process

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.
Example

3. Data Analytics

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.
Example

4. PK Score Integration (Optional)

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.
Example
Active Interface - Modify PK Score
Update the calculated PK value through this interface.
Example
Callback Configuration - Callback when PK starts
The customer's backend can be timely informed when a PK starts through this callback.
Example
Callback Configuration - Callback when PK ends
The customer's backend can be timely informed when a PK ends through this callback.
Example

5. Advanced Effects Player (Optional)

TUILiveKit provides two types of gift effect players: Basic Effects Player (built-in) and Advanced Effects Player (requires extra integration).
Comparison Item
Basic Effect Player
Advanced Effect Player
Billing
Free
Official. Please refer to the Billing Guide.
integration method
Built-in by default
Requires extra integration. See Advanced Effect Player Integration Guide.
Animation support
Like animation
Barrage animation
Full-screen animation
Like animation
Barrage animation
Full-screen animation
Animation Format
Only supports SVGA
SVGA, PAG, WebP, PAG, Lottie, PNG, MP4, VAP, etc.
Performance
Supports SVGA files <=10MB
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
new ILicenseCallback() {
@Override
public void onResult(int error, String message) {
Log.i("TCMediaXBase", "setLicense result: " + error + " " + message);
}
});
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.
//
// AppDelegate.swift
//

import TCMediaX

func application(_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
TCMediaXBase.getInstance().setDelegate(self)
TCMediaXBase.getInstance().setLicenceURL("LicenseURL", key: "LicenseKEY")
return true
}

func onLicenseCheckCallback(_ errcode: Int32, withParam param: [AnyHashable : Any]) {
debugPrint("[TCMediaXBase] setLicense result: errcode:\(errcode), param:\(param)")
}
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.