Docs Overview/
Live/
iOS/
Basic Features/
Interactive Gift/

Interactive Gift

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 show their appreciation, love, and support. The interactive gift component supports setting gift materials, displaying balance, playing ordinary gifts and full-screen gifts, and adding a recharge button, etc.

Overview




Display Gifts



Play normal gift



Play full-screen gift
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.

Gift System







Gift system`s Structure diagram
Gift system`s Sequence diagram

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.
let giftListView: TUIGiftListView = TUIGiftListView(groupId: xxx) //generator giftListView object
let giftList: [TUIGift] = ... //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: AnyCodable]: 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.

Send gift

Implement the onSendGift delegate function in the TUIGiftListViewDelegate of TUIGiftListView to get the gift count and gift information. After preprocessing, you can call the sendGift function of TUIGiftListView for the actual sending of gifts.
giftListView.delegate = self

extension ViewController: TUIGiftListViewDelegate {
    func onSendGift(giftListView view: TUIGiftListView, giftModel: TUIGift, giftCount: Int) {
        //...Here is the preprocessing, such as verifying the current user's balance and other operations.
        let receiver = TUIGiftUser()
        //...Set the gift recipient information here.
        view.sendGift(giftModel: giftModel, giftCount: giftCount, receiver: receiver)
    }
}

ReceiveGift

The gift display component TUIGiftPlayView will receive and play gift messages by itself.
let giftDisplayView: TUIGiftPlayView = TUIGiftPlayView(groupId:xxx)
Note：
TUIGiftPlayView requires full-screen integration.
If you need to get the callback information of receiving gifts, you can implement the giftPlayView:onPlayGift delegate function in the TUIGiftPlayViewDelegate of TUIGiftPlayView.

extension ViewController: TUIGiftPlayViewDelegate {
    func giftPlayView(_ giftPlayView: TUIGiftPlayView, onPlayGift gift: TUIGift, giftCount: Int, sender: TUIGiftUser, receiver: TUIGiftUser) {
     //...You can handle this on your own here.
    }   
}

Play Gift Animation

You need to actively invoke the playGiftAnimation method of TUIGiftPlayView when you receive onPlayGiftAnimation callback from the TUIGiftPlayViewDelegate of TUIGiftPlayView.
extension ViewController: TUIGiftPlayViewDelegate {
    func giftPlayView(_ giftPlayView: TUIGiftPlayView, onPlayGiftAnimation gift: TUIGift) {
      //...
    }   
}
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

Implement the onRecharge delegate function in the TUIGiftListViewDelegate of TUIGiftListView, which can be used to receive the click event of the recharge button thrown by the gift display panel, and connect to your own recharge system here.
extension ViewController: TUIGiftListViewDelegate {
   func onRecharge(giftListView view: TUIGiftListView) {
        //...This can be used to connect to your own recharge system. After the recharge is completed, 
        //you can call view.setBalance(xxx) to set the balance display of the gift display panel.
    }
}
Note：
1. The gift balance is a concept of virtual currency, not real money.
2. 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 delegate function in the TUIGiftListViewDelegate 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.
giftListView.delegate = self

extension ViewController: TUIGiftListViewDelegate {
    func onSendGift(giftListView view: TUIGiftListView, giftModel: TUIGift, giftCount: Int) {
        //...Connect to the customer's own business server here to complete balance verification, gift billing, consumption statistics, etc
        let receiver = TUIGiftUser()
        //...Set the gift recipient information here.
        view.sendGift(giftModel: giftModel, giftCount: giftCount, receiver: receiver)
    }
}

Customize giftList

Modify the gift list on the audience's gift panel:
// Source code path：TUILiveKit/Source/LiveRoom/View/Audience/Component/AudienceLivingView.swift

private lazy var giftPanelView: TUIGiftListView = {
    let view = TUIGiftListView(groupId: liveRoomInfo.roomId.value)
    giftCloudServer.queryGiftInfoList { [weak self] error, giftList in
        guard let self = self else { return }
        DispatchQueue.main.async {
            if error == .noError {
                view.setGiftList(giftList)
            } else {
                self.makeToast("query gift list error, code = \(error)")
            }
        }
    }
    return view
}()

Note：
1. Customers implement the logic of giftCloudServer.queryGiftInfoList on their own, get a custom gift list [TUIGift] , and set the gift list through view.setGiftList.
2. The animationUrl of the gift is required to be a SVGA animation.

Customize giftPanel`s balance

// Source code path：TUILiveKit/Source/LiveRoom/View/Audience/Component/AudienceLivingView.swift

private lazy var giftPanelView: TUIGiftListView = {
    let view = TUIGiftListView(groupId: liveRoomInfo.roomId.value)
    giftCloudServer.queryBalance { [weak self] error, balance in
        guard let self = self else { return }
        DispatchQueue.main.async {
            if error == .noError {
                view.setBalance(balance)
            } else {
                self.makeToast("query balance error, code = \(error)")
            }
        }
    }
    return view
}()
Note：
Customers implement the logic of giftCloudServer.queryBalance on their own, obtain the gift balance, and update the gift balance through view.setBalance.

Customize gift consumption logic

// Source code path：TUILiveKit/Source/LiveRoom/View/Audience/Component/AudienceLivingView.swift

func onSendGift(giftListView view: TUIGiftListView, giftModel: TUIGift, giftCount: Int) {
    let receiver = TUIGiftUser()
    receiver.userId = liveRoomInfo.anchorInfo.value.userId
    receiver.userName = liveRoomInfo.anchorInfo.value.name.value
    receiver.avatarUrl = liveRoomInfo.anchorInfo.value.avatarUrl.value
    receiver.level = "0"
    giftCloudServer.sendGift(sender: TUILogin.getUserID() ?? "",
                             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 {
            self.makeToast(.balanceInsufficientText)
        }
    }
}

Note：
Customers implement the logic of giftCloudServer.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


// Source code path：
// TUILiveKit/Source/LiveRoom/View/Audience/Component/AudienceLivingView.swift
// TUILiveKit/Source/LiveRoom/View/Anchor/Living/AudienceLivingView.swift

func giftPlayView(_ giftPlayView: TUIGiftPlayView, onPlayGiftAnimation gift: TUIGift) {
    giftCacheService.request(urlString: gift.animationUrl) { error, data in
        guard let data = data else { return }
        if error == 0 {
            DispatchQueue.main.async {
                giftPlayView.playGiftAnimation(animationData: data)
            }
        }
    }
}

Note：
Customers implement the logic of giftCacheService.request on their own, successfully load the animation to get the data (of Data type), and then play the gift animation through playGiftAnimation of TUIGiftPlayView.