tencent cloud

Feedback

Last updated: 2024-09-27 11:38:55

    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

    Overview

    Display Gifts
    Play normal gift
    Play full-screen gift
    
    
    
    
    
    
    
    
    
    
    

    Gift System

    Gift system`s Structure diagram
    Gift system`s Sequence diagram
    
    
    
    
    
    
    The client short-connection request to its own business server involves the gift billing logic.
    1. After billing, the sender directly sees that XXX sent XXX gifts (to ensure that the sender sees the gifts he sent, and the abandonment policy may be triggered when the message volume is large).
    2. After the billing is settled, call the GiftListView.sendGift to send a message to cancel the gift.

    Feature customization

    Customizable Gifts Backend Logic

    If you need custom backend services for gifts, please refer to the following path for modifications.
    // 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

    Custom Gift Panel View

    If you need a custom gift panel view, please refer to the following path for modifications.
    // 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

    Customize giftList

    Modify the gift list on the audience's gift panel:
    // 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) { mGiftListPanelView.setGiftList(result); } else { ToastUtil.toastLongMessage("query gift list error, code = " + error); } }));
    Note:
    Customers implement the logic of mGiftCloudServer.queryGiftInfoList on their own, get a custom gift list List<TUIGift>, and set the gift list through GiftListView.setGiftList.
    The animationUrl of the gift is required to be a SVGA animation.

    Customize giftPanel`s balance

    // 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) { mGiftListPanelView.setBalance(result); } else { ToastUtil.toastLongMessage("query balance error, code = " + error); } }));
    Note:
    Customers implement the logic of mGiftCloudServer.queryBalance on their own, obtain the gift balance, and update the gift balance through GiftListView.setBalance.

    Customize gift consumption logic

    // 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); } } })); }
    Note:
    Customers implement the logic of mGiftCloudServer.sendGift on their own. The main logic is to first connect to the customer's own business server to verify the balance, and after the verification is passed, the server will charge and count the consumption records, and finally call back the result to the client. After receiving the successful callback, the client sends the gift message through the sendGift of the GiftListView, and then updates the gift balance through setBalance.

    Customize load and play gift animation

    // 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); } }); }
    Note:
    Customers implement the logic of mGiftCacheService.request on their own, successfully load the animation to get the result (of InputStream type), and then play the gift animation through playGiftAnimation of TUIGiftPlayView.

    Key code

    Integration

    The gift component mainly provides 2 objects:
    TUIGiftListView: A gift panel that presents the gift list, sends gifts, and recharges.
    TUIGiftPlayView: A panel that plays gifts and 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.
    // File Location: tuilivekit/src/main/java/com/trtc/uikit/livekit/common/uicomponent/gift/TUIGiftListView.java
    TUIGiftListView giftListView = new TUIGiftListView(mContext, roomId); //generator giftListView object
    List<TUIGift> giftList = new ArrayList<>() //you can change gift materials here
    giftListView.setGiftList(giftList) //set gift materials of giftListPanleView
    Note: The parameters and descriptions 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, Object>: Custom extension information
    The interactive gift component supports setting your own gift materials. If the animationUrl is empty, the gift playing effect will be an ordinary play, and the content played will be the image linked by the imageUrl. If the animationUrl is not empty, the playing effect will be a full-screen play, and the content played will be the corresponding svga animation.

    Gift Sending and Receiving

    
    
    

    Send gift

    Implement the onSendGift callback in the OnGiftListener of TUIGiftListView, get the number of gifts and gift information, after preprocessing, you can call the sendGift function of TUIGiftListView for the actual sending of gifts.
    public void onSendGift(TUIGiftListView giftListView, TUIGift gift, int giftCount) {
    //...This operation is preprocessing, such as verifying the balance of the current user
    TUIGiftUser receiver = new TUIGiftUser();
    //...Set the gift receiver information here
    giftListView.sendGift(gift, giftCount, receiver);
    }

    Receive Gift

    The gift display component TUIGiftPlayView will receive and play gift messages by itself.
    // File Location: tuilivekit/src/main/java/com/trtc/uikit/livekit/common/uicomponent/gift/TUIGiftPlayView.java
    TUIGiftPlayView giftPlayView = new TUIGiftPlayView(mContext, roomId);
    Note:
    TUIGiftPlayView requires full-screen integration.
    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);
    //... }

    Play Gift Animation

    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);
    //... }
    Note:
    Only SVGA animations are 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.
    giftListView.setBalance(xxx);

    Recharge

    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) {
    //...to recharge
    //setup the latest balance giftListView.setBalance(balance); }
    Note:
    The gift balance is a concept of virtual currency, not real money.
    The gift recharge logic is implemented externally, and customers can connect to their own recharge system. After the recharge is completed, the gift balance is updated.

    Billing statistics

    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) {
    //...Connect to the customer's own business server here to complete balance verification, gift billing, consumption statistics, etc
    TUIGiftUser receiver = new TUIGiftUser();
    //...Set the gift receiver information here
    giftListView.sendGift(gift, giftCount, receiver);
    }
    
    Contact Us

    Contact our sales team or business advisors to help your business.

    Technical Support

    Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

    7x24 Phone Support