Docs Overview/
Interactive Gifts (TUILiveKit)/

Interactive Gifts (TUILiveKit)

Description of the Feature

The Interactive Gift Component is a virtual gift interaction platform designed to add more fun to users' social experiences. With this component, users can send virtual gifts to their favorite live streamers to express their appreciation, love, and support. The Interactive Gift Component supports settings for gift materials, balance display, normal gift playback and full-screen gift playback, recharge button, etc. The feature of interactive gifts has been implemented in TUILiveKit through Chat.

Use Instructions

Gift Effect

Gift Display Panel
Normal Gift Playback Effect
Full-Screen Gift Playback Effect










Gift System

Gift System Architecture Diagram
Gift System Sequence Diagram






Non-persistent connection requests from the client are sent to its own business server, involving gift billing logic.
1. After billing, the sender directly sees that XXX sent a gift to XXX (to ensure the sender sees their own sent gift. When the message volume is large, it may trigger an abandonment strategy).
2. After the fees are settled, call GiftListView.sendGift to send the gift message.

Feature Customization

Customizable Gifts Backend Logic

If you need custom backend services for gifts, please refer to the following path for modifications.
Android
iOS
// File Location: tuilivekit/src/main/java/com/trtc/uikit/livekit/common/uicomponent/gift/

giftcloudserver            // Self Definition gift backend service directory
  ├── GiftCloudServer.java  // Default implementation class, interacts with the gift backend, responsible for balance verification, settlement, statistics, etc. Clients are advised to implement their custom version
  └── IGiftCloudServer.java // Gift backend service interface
// File Location: iOS/TUILiveKit/Sources/Component/Gift

GiftCloudServer                    // Custom Gifts Backend Services Directory
  ├── CloudServerConfig.swift      // Service Layer Data Source for Gift Component
  ├── GiftCloudServer.swift        // Default implementation class, interacting with the gift backend, responsible for verifying balance, settlement, statistics, etc. Custom implementation is recommended for clients
  └── IGiftCloudServer.swift       // Gift backend service interface

Custom Gift Panel View

If you need a custom gift panel view, please refer to the following path for modifications.
Android
iOS
// File Location: tuilivekit/src/main/java/com/trtc/uikit/livekit/common/uicomponent/gift

view
  ├── TUIGiftListView.java             // Gift panel view
  ├── TUIGiftPlayView.java             // Gift playback view
  └── adapter                          // Gift panel adapter directory
         ├── GiftPanelAdapter.java     // Gift panel view for each page
         └── GiftViewPagerAdapter.java // Adapter supporting page turning
// File Location: iOS/TUILiveKit/Sources/Component/Gift

Gift      
  ├── TUIGiftListView.swift                  // Gift Panel View
  ├── TUIGiftPlayView.swift                  // Gift Playback View
  └── View                                   // View Layer Directory of Gift Component
       └── Views                             // Custom Category Directory of Gift Component
           ├── TUIGiftBulletView.swift       // General Gift Playback Category of Gift Component
           ├── TUIGiftCell.swift             // Customizable Gift Cell of Gift Component
           ├── TUIGiftSideslipLayout.swift   // Custom Layout Class of Gift Component
           └── TUIGiftView.swift             // Gift Display View Class of Gift Component


Custom Gift List

Modify the gift list of the Audience Gift Panel:
Android
iOS
// File Location: tuilivekit/src/main/java/com/trtc/uikit/livekit/liveroom/view/audience/component/AudienceFunctionView.java

mGiftCloudServer.queryGiftInfoList((error, result) -> post(() -> {
    if (error == Error.NO_ERROR) {
        mGiftListView.setGiftList(result);
    } else {
        ToastUtil.toastLongMessage("query gift list error, code = " + error);
    }
}));
// File Location: iOS/TUILiveKit/Sources/Component/Gift/Store/TUIGiftStore.swift

class TUIGiftStore {
    static let shared = TUIGiftStore()
    
    private init() {
        giftCloudServer.queryGiftInfoList { [weak self] error, giftList in
            guard let self = self else { return }
            if error == .noError {
                self.giftList = giftList
            }
        }
    }
    var giftList: [TUIGift] = []
    let giftCloudServer: IGiftCloudServer = GiftCloudServer()
}


//  File Location: iOS/TUILiveKit/Sources/LiveStream/Main/Audience/AudienceView.swift
func getRouteView(route: Route) -> UIView? {
    if route == .giftView {
        giftPanelView.setGiftList(TUIGiftStore.shared.giftList)
        return giftPanelView
    } else {
        return nil
    }
}
Note:
The client implements the logic of giftCloudServer.queryGiftInfoList to get a custom gift list List<TUIGift>, and sets the gift list via GiftListView.setGiftList.
The animationUrl of the gift requires an SVGA animation.

Customizable gift balance recharge

Android
iOS
// File Location: tuilivekit/src/main/java/com/trtc/uikit/livekit/liveroom/view/audience/component/AudienceFunctionView.java

mGiftCloudServer.queryBalance((error, result) -> post(() -> {
    if (error == Error.NO_ERROR) {
        mGiftListView.setBalance(result);
    } else {
        ToastUtil.toastLongMessage("query balance error, code = " + error);
    }
}));
// File Location: iOS/TUILiveKit/Sources/LiveStream/Main/Audience/AudienceView.swift

lazy var giftPanelView: TUIGiftListView = {
        let view = TUIGiftListView(groupId: roomId)
        view.delegate = self
        TUIGiftStore.shared.giftCloudServer.queryBalance { error, balance in
            if error == .noError {
                view.setBalance(balance)
            }
        }
        return view
}()

Note:
Clients need to implement the logic of giftCloudServer.queryBalance to get the gift balance and update the balance through GiftListView.setBalance.

Customizable gift consumption logic

Android
iOS
// File Location: tuilivekit/src/main/java/com/trtc/uikit/livekit/liveroom/view/audience/component/AudienceFunctionView.java

@Override
public void onSendGift(TUIGiftListView view, TUIGift gift, int giftCount) {
    TUIGiftUser receiver = new TUIGiftUser();
    receiver.userId = mLiveRoomInfo.anchorInfo.userId;
    receiver.userName = mLiveRoomInfo.anchorInfo.name.get();
    receiver.avatarUrl = mLiveRoomInfo.anchorInfo.avatarUrl.get();
    receiver.level = "0";
    mGiftCloudServer.sendGift(TUILogin.getUserId(), receiver.userId, gift, giftCount,
            (error, result) -> post(() -> {
       if (error == Error.NO_ERROR) {
           view.sendGift(gift, giftCount, receiver);
           view.setBalance(result);
       } else {
           if (error == Error.BALANCE_INSUFFICIENT) {
               String info = getResources().getString(R.string.livekit_gift_balance_insufficient);
               ToastUtil.toastLongMessage(info);
           } else {
               ToastUtil.toastLongMessage("send gift error, code = " + error);
           }
       }
    }));
}
// File Location: iOS/TUILiveKit/Sources/LiveStream/Main/Audience/AudienceView.swift

func onSendGift(giftListView view: TUIGiftListView, giftModel: TUIGift, giftCount: Int) {
    let anchorInfo = store.selectCurrent(RoomSelectors.getRoomOwnerInfo)
    let receiver = TUIGiftUser()
    receiver.userId = anchorInfo.userId
    receiver.userName = anchorInfo.name
    receiver.avatarUrl = anchorInfo.avatarUrl
    receiver.level = "0"

    let selfInfo = store.selectCurrent(UserSelectors.getSelfInfo)
    TUIGiftStore.shared.giftCloudServer.sendGift(sender: selfInfo.userId,
                                               receiver: receiver.userId,
                                              giftModel: giftModel,
                                              giftCount: giftCount) { [weak self] error, balance in
            guard let self = self else { return }
            if error == .noError {
                view.sendGift(giftModel: giftModel, giftCount: giftCount, receiver: receiver)
                view.setBalance(balance)
            } else {
                let toastInfo = ToastInfo(message: .balanceInsufficientText)
                store.dispatch(action: ViewActions.toastEvent(payload: toastInfo))
            }
        }
    }
Note:
Clients need to implement the logic of giftCloudServer.sendGift. The main process is to first connect to the client’s business server for balance verification. After verification, the server performs billing and records the consumption. Finally, it calls back the result to the client. Upon receiving the successful callback, the client sends the gift message through GiftListView's sendGift and updates the gift balance via setBalance.

Customizable loading and playing of gift animations

Android
iOS
// File Location: 
// tuilivekit/src/main/java/com/trtc/uikit/livekit/liveroom/view/audience/component/AudienceLivingView.java
// tuilivekit/src/main/java/com/trtc/uikit/livekit/liveroom/view/anchor/component/livestreaming/AnchorLivingView.java

@Override
public void onPlayGiftAnimation(TUIGiftPlayView view, TUIGift gift) {
    mGiftCacheService.request(gift.animationUrl, (error, result) -> {
        if (error == 0) {
            view.playGiftAnimation(result);
        }
    });
}
// File Location: 
// iOS/TUILiveKit/Sources/LiveStream/Main/Audience/Component/AudienceLiving.swift
// iOS/TUILiveKit/Sources/LiveStream/Main/Anchor/LivingView/AnchorLivingView.swift

func giftPlayView(_ giftPlayView: TUIGiftPlayView, onPlayGiftAnimation gift: TUIGift) {
        guard let url = URL(string: gift.animationUrl) else { return }
        giftCacheService.request(withURL: url) { error, fileUrl in
            if error == 0 {
                DispatchQueue.main.async {
                    giftPlayView.playGiftAnimation(playUrl: fileUrl)
                }
            }
        }
    }
Note:
Clients need to implement the logic of giftCacheService.request. After successfully loading the animation, get the fileUrl (String type) and play the gift animation through TUIGiftPlayView's playGiftAnimation.

Key code

Quick Integration

The gift component mainly provides 2 APIs:
TUIGiftListView: Gift Panel, presents the gift list, sends gifts, and recharges.
TUIGiftPlayView: Panel for playing gifts, automatically listens to gift messages.

Set gift materials

The gift panel component TUIGiftListView provides the setGiftList interface, which can be used to set gift materials.
Android
iOS
// File Location: tuilivekit/src/main/java/com/trtc/uikit/livekit/common/uicomponent/gift/TUIGiftListView.java
TUIGiftListView giftListView = new TUIGiftListView(mContext, roomId); // Create gift panel object
List<TUIGift> giftList = new ArrayList<>() // Replace this with your own gift materials array
giftListView.setGiftList(giftList) // Set the materials for the gift panel
let view = TUIGiftListView(groupId: roomId)   // Create gift panel object
let giftList:[TUIGift] = []                   // Replace this with your own gift materials array
giftList.setGiftList(giftList)                // Set the materials for the gift panel
Note:
The parameters and description of TUIGift are as follows:
giftId: String: Gift ID
giftName: String: Gift Name
imageUrl: String: Image displayed on the gift panel
animationUrl: String: SVGA Animation URL
price: int: Gift Price
extInfo: <String, AnyCodable>: Custom extension information.
The Interactive Gift Component supports setting your own gift media. If animationUrl is empty, the gift playback effect is standard, and the content played is the image linked by imageUrl; if animationUrl is not empty, the playback effect is full-screen, and the content played is the corresponding svga animation.

Gift Sending and Receiving





Send Gift

Implement the callback TUIGiftListView delegate TUIGiftListViewDelegate in onSendGift:giftListView:gift:giftCount to get the gift count and gift information. After pre-processing, you can call the TUIGiftListView 's sendGift function for the actual gift sending.
Android
iOS
public void onSendGift(TUIGiftListView giftListView, TUIGift gift, int giftCount) {
   //...Here is the pre-processing, such as verifying the current user's balance, etc
   TUIGiftUser receiver = new TUIGiftUser();
   //...Here set the gift recipient information
   giftListView.sendGift(gift, giftCount, receiver);
}
func onSendGift(giftListView view: TUIGiftListView, giftModel: TUIGift, giftCount: Int) {
        //...Here is the pre-processing, such as verifying the current user's balance, etc
        let receiver = TUIGiftUser()
        //...Here set the gift recipient information
        view.sendGift(giftModel: giftModel, giftCount: giftCount, receiver: receiver)
}

Receive gift

The gift display component TUIGiftPlayView itself will receive and play gift messages.
Android
iOS
// File Location: tuilivekit/src/main/java/com/trtc/uikit/livekit/common/uicomponent/gift/TUIGiftPlayView.java
TUIGiftPlayView giftPlayView = new TUIGiftPlayView(mContext, roomId);
let giftPlayView = GiftPlayView(groupId: roomId)
Note:
TUIGiftPlayView needs full-screen integration.
Android
iOS
If you need to get the callback information of receiving gifts, you can implement the onReceiveGift callback in the TUIGiftPlayViewListener of TUIGiftPlayView.
public interface TUIGiftPlayViewListener {
    void onReceiveGift(TUIGift gift, int giftCount, TUIGiftUser sender, TUIGiftUser receiver);
    //...
}
If you need to obtain callback information for receiving gifts, you can implement the TUIGiftPlayView delegate TUIGiftPlayViewDelegate function giftPlayView:onReceiveGift:gift:giftCount:sender:receiver.
func giftPlayView(_ giftPlayView: TUIGiftPlayView, onReceiveGift gift: TUIGift, giftCount: Int, sender: TUIGiftUser, receiver: TUIGiftUser) {
    // Custom Processing
}

Play gift animation

Android
iOS
You need to actively invoke the playGiftAnimation method of TUIGiftPlayView when you receive onPlayGiftAnimation callback from the TUIGiftPlayViewListener of TUIGiftPlayView.
public interface TUIGiftPlayViewListener {
    void onPlayGiftAnimation(TUIGiftPlayView view, TUIGift gift);
    //...
}
It is required to actively call TUIGiftPlayView 's playGiftAnimation to play the animation. The appropriate time to call is upon receiving the TUIGiftPlayViewDelegate's giftPlayView:onPlayGiftAnimation callback.
func giftPlayView(_ giftPlayView: TUIGiftPlayView, onPlayGiftAnimation gift: TUIGift) {
    giftPlayView.playGiftAnimation(playUrl: fileUrl)
}
Note:
Only SVGA animation is supported.

Set balance

The gift panel component TUIGiftListView provides the setBalance interface, which can be used to set the balance value displayed on the gift panel.
Android
iOS
giftListView.setBalance(xxx);
giftListView.setBalance(xxx);

Recharge

Android
iOS
Implementing the onRecharge callback in the OnGiftListener of TUIGiftListView can be used to receive the click event of the recharge button thrown by the gift display panel. Here, you can connect to your own recharge system.
public void onRecharge(TUIGiftListView giftListView) {
    //...go to recharge
    //Set the latest balance
    giftListView.setBalance(balance);
}
Implement the delegate TUIGiftListViewDelegate in TUIGiftListView, the onRecharge:view callback can be used to receive the recharge button click event thrown by the gift display panel, where you can integrate your own recharge system.
func onRecharge(giftListView view: TUIGiftListView) {
    //...go to recharge
    //Set the latest balance
    view.setBalance(balance)
}
Note:
Gift balance is a virtual currency concept, not real money.
The gift recharge logic is implemented externally. Customers can integrate their own recharge systems. After recharging, the gift balance is updated.

Billing Statistics

Android
iOS
Implement the onSendGift callback in the OnGiftListener of TUIGiftListView, connect to the customer's own business server, complete the balance verification, gift billing, and consumption statistics, and then call the sendGift of TUIGiftListView to send the gift message.
public void onSendGift(TUIGiftListView giftListView, TUIGift gift, int giftCount) {
   //... Here, connect to the customer's own business server to complete balance verification, gift billing, consumption statistics, etc
   TUIGiftUser receiver = new TUIGiftUser();
   //...Here set the gift recipient information
   giftListView.sendGift(gift, giftCount, receiver);
}
Implement the TUIGiftListView delegate TUIGiftListViewDelegate callback onSendGift:view:giftModel:giftCount to connect to the customer's own business server. After completing balance verification, gift billing, and consumption statistics, call TUIGiftListView 's sendGift to send the gift message.
func onSendGift(giftListView view: TUIGiftListView, giftModel: TUIGift, giftCount: Int) {
    //... Here, connect to the customer's own business server to complete balance verification, gift billing, consumption statistics, etc
    let receiver = TUIGiftUser()
    //...Here set the gift recipient information
    view.sendGift(giftModel: giftModel, giftCount: giftCount, receiver: receiver)
}