이 페이지는 현재 영어로만 제공되며 한국어 버전은 곧 제공될 예정입니다. 기다려 주셔서 감사드립니다.

인터랙티브 선물

Feature Introduction

The Interactive Gifts component is a virtual gift interaction platform designed to enhance the social experience of users. With this component, users can send virtual gifts to their favorite live stream hosts to show their appreciation, favoritism, and support.
The Interactive Gift Component supports setting like, gift sending panel, send gifts, play normal gift animation, play SVGA gift animation, etc.
Flutter
Android
iOS
Web
The interactive gift component provides 2 view components:
GiftSendWidget: send gift message view, clicking it can bring up the gift panel.
GiftDisplayWidget: receive gift message view, it will display gift messages on this view.
The effect is shown below:
Gift Display Panel
Normal Gift Playback Effect
Full-Screen Gift Playback Effect









The gift component mainly provides 2 APIs:
GiftListPanelView: gift panel, presents the gift list, send gifts, and top-up.
GiftPlayView: Panel for playing gifts, automatically listens to gift messages.
The effect is shown below:
Gift Display Panel
Normal Gift Playback Effect
Full-Screen Gift Playback Effect









The gift component mainly provides 2 APIs:
GiftListView: gift panel, presenting the gift list and send gifts.
GiftPlayView: A panel for playing gifts, automatically listens for gift messages.
The effect is shown below:
Gift Display Panel
Normal Gift Playback Effect
Full-Screen Gift Playback Effect









The interactive gift system mainly provides 4 components:
GiftList: The gift panel, which displays the gift list and allows sending gifts. On H5, the top-right corner of the panel also includes a recharge function.
GiftMore : The "More Gifts" button. On PC, it includes a recharge function.
GiftPopupList: On PC, when the GiftList cannot fully display all available gifts, clicking "More Gifts" will trigger this GiftPopupList: component to show the complete gift list.
GiftPlayerCardList: The gift playback panel, which automatically listens for gift messages.
Components are described in the following figure:




The effect is shown below:
Gift Display Panel
Normal Gift Playing Effect
Full-Screen Gift Playing Effect










Quick Connection

Note:
If you have already integrated the LiveKit component, we have by default included the gift component in LiveKit. You can directly experience the interactive gift feature in LiveKit.

Adding the Gift Component To the Project

Flutter
Android
iOS
Web
1. Add gift dependency in the dependencies node of the pubspec.yaml file in the project engineering.
dependencies:
flutter:
sdk: flutter
flutter_localizations:
sdk: flutter
intl: ^0.19.0
# Add gift dependency
live_uikit_gift: ^1.0.0
2. Execute the flutter pub get command.
3. Configure multilingual support. Add multilingual support for the gift component to the localizationsDelegates and supportedLocales attributes of your application's MaterialApp.
MaterialApp(localizationsDelegates: const [
...GiftLocalizations.localizationsDelegates,
], supportedLocales: const [
...GiftLocalizations.supportedLocales,
],
// ...
);
Integrate the LiveKit component for normal use, see details on GitHub.
Integrate the LiveKit component for normal use, see details on GitHub.
Integrate the LiveKit components to enable full functionality. For details, refer to the NPM directory: src/TUILive/components/Gift/.

Integrating the Gift Sending Component

Flutter
Android
iOS
Web
Construct GiftSendController and GiftSendWidget objects where you need to integrate the gift sending message, and add the constructed GiftSendWidget object to your Widget tree. Example code is as follows:
GiftSendController _giftSendController = GiftSendController(
roomId: "liveRoomId", /// liveRoomId Replace with your live room ID
owner: ownerInfo, /// ownerInfo Replace with your live room host information
self: selfInfo, /// selfInfo Replace with your login user information
);

GiftSendWidget(controller: _giftSendController);
Implement the GiftListPanelView OnSendGiftListener callback onSendGift to get the number of gifts and gift information. After preprocessing, you can call the GiftListPanelView function sendGift for the actual sending of gifts.
public void onSendGift(GiftListPanelView giftListView, Gift gift, int giftCount) {
//...Here is the pre-processing, such as verifying the current user's balance, etc
GiftUser receiver = new GiftUser();
//...Here set the gift recipient information
giftListView.sendGift(gift, giftCount, receiver);
}
Create a GiftListView object and add it to your view. You also need to implement the GiftListViewDelegate callback method onSendGift .
When you click the send button on the GiftListView panel, you will receive this callback. You can get the number of gifts to be sent and the gift information in this method. After preprocessing, you can call the GiftListView function sendGift for the actual sending of gifts.
lazy var giftListView = GiftListView(roomId: roomId, delegate: self)
// ...Add giftListView to your parent view and adjust the layout here

func onSendGift(gift model: TUIGift, giftCount: Int) {
//... Preprocessing here, such as verifying the current user's balance
let receiver = TUIGiftUser()
//... Set gift recipient information here
giftListView.sendGift(model: giftModel, giftCount: giftCount, receiver: receiver, completion: completion)
}\
In the component where you need to send gifts, import and execute the useGiftList hook. Destructure the handleSendGift method from the execution result. When clicking the send button on the GiftList panel, simply pass the prepared gift data as a parameter to the handleSendGift method to send successfully. Refer to the GiftList component's gift-sending logic for implementation.
import { ref } from "vue";
import { useGiftList, type Gift } from "src/TUILive/components/Gift/useGiftList.ts";

const { handleSendGift } = useGiftList();
const selectedGift = ref<Gift>({} as Gift);

// The method is bound to the click event of the send button on the GiftList panel.
const handleSendSelectedGift = async (gift: Gift) => {
if (selectedGift.value !== gift) return;
try {
// Call handleSendGift to send the gift.
await handleSendGift(gift);
selectedGift.value = {} as Gift;
} catch (error) {
selectedGift.value = {} as Gift;
throw error;
}
}

Integrating the Gift Display Component

Flutter
Android
iOS
Web
Construct GiftDisplayController and GiftDisplayWidget objects where you need to integrate the gift display message, and add the constructed GiftDisplayWidget object to your Widget tree. Example code is as follows:
GiftDisplayController _giftDisplayController = GiftDisplayController(
rroomId: "liveRoomId", /// liveRoomId Replace with your live room ID
owner: ownerInfo, /// ownerInfo Replace with your live room host information
self: selfInfo, /// selfInfo Replace with your login user information
);

GiftDisplayWidget(controller: _giftDisplayController!);
The gift display component GiftPlayView itself will receive and play gift messages.
GiftPlayView giftPlayView = new GiftPlayView(mContext, roomId);
The gift display component GiftPlayView will receive and play gift messages.
You only need to create a GiftPlayView object and add it to your view.
let giftPlayView = GiftPlayView(groupId: roomId)
// ...Add giftPlayView to your parent view and adjust the layout here
The gift display component GiftPlayerCardList automatically receives and plays gift messages.
Simply import and embed it in your target component where gift display is needed.
<template>
// After placing the GiftPlayerCardList component, you can adjust its layout according to your specific business requirements.
<GiftPlayerCardList/>
</template>

<script setup lang="ts">
import GiftPlayerCardList from 'src/TUILive/components/Gift/GiftPlayerCardList.vue';
</script>

Listening To Gift Sending and Receiving Messages

Flutter
Android
iOS
Web
If you need to get callback information for sending and receiving gifts, you can call the GiftDisplayController's setGiftCallback method. Example code is as follows:
_giftDisplayController?.setGiftCallback(
onReceiveGiftCallback: _onReceiveGiftCallback, /// _onReceiveGiftCallback can be replaced with your custom handling method
onSendGiftCallback: _onSendGiftCallback, /// _onSendGiftCallback can be replaced with your custom handling method
);
If you need to receive callback information for receiving gifts, implement the GiftPlayView TUIGiftPlayViewListener function onReceiveGift.
public interface TUIGiftPlayViewListener {
void onReceiveGift(Gift gift, int giftCount, GiftUser sender, GiftUser receiver);
//...
}
If you need to get callback information for receiving gifts, you can implement the GiftPlayView's delegate GiftPlayViewDelegate's giftPlayView:onReceiveGift:gift:giftCount:sender:receiver function.
func giftPlayView(_ giftPlayView: GiftPlayView, onReceiveGift gift: TUIGift, giftCount: Int, sender: TUIGiftUser, receiver: TUIGiftUser)
// Custom Processing
}
To view received gift information, navigate to:src/TUILive/components/Chat/MessageList/useMessageListHook.tsand check the onReceiveMessage function.
// File location: src/TUILive/components/Chat/MessageList/useMessageListHook.ts

const onReceiveMessage = (options: { data: any }) => {
if (!options || !options.data) {
return;
}
const currentConversationId = `GROUP${roomId.value}`;
options.data.forEach((message: any) => {
// ..
if (isGiftMsg(message.payload?.data)) {
// If the condition enters this branch, it indicates a gift message. You may customize it according to your specific business requirements.
}
// ..
});
};

Custom Gift Panel

Flutter
Android
iOS
Web
If you need to modify the gift list of the gift panel, you can call the GiftSendController's setGiftList method, as shown below:
List<GiftModel> giftList = [ /// Customize your gift list data source
GiftModel(giftId: "1", giftName: "Egg", imageUrl: "giftImageUrl", price: 10),
GiftModel(giftId: "2", giftName: "Star", imageUrl: "giftImageUrl", price: 10),
];

_giftSendController.setGiftList(giftList);
If you need to modify the gift list of the gift panel:
mGiftCloudServer.queryGiftInfoList((error, result) -> post(() -> {
if (error == Error.NO_ERROR) {
mGiftListView.setGiftList(result);
} else {
ToastUtil.toastLongMessage("query gift list error, code = " + error);
}
}));
Note:
Customers implement the logic of the queryGiftInfoList method themselves to obtain a custom gift list List<Gift>, and set the gift list through GiftListView.setGiftList.
The animationUrl of the gift requires an SVGA animation.
If you need to modify the gift list of the gift panel:
// 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/Manager/LSRouterControlCenter.swift
private func getRouteDefaultView(route: LSRoute) -> UIView?
{
switch route {
case .giftView:
let giftPanel = GiftListPanel(roomId: manager.roomState.roomId, dataSource: manager)
giftPanel.setGiftList(TUIGiftStore.shared.giftList)
view = giftPanel
}
}
Note:
Customers implement the logic of the queryGiftInfoList method themselves to obtain a custom gift list List<TUIGift>, and set the gift list through GiftListView.setGiftList.
The animationUrl of the gift requires an SVGA animation.
If you need to modify the gift list in the gift panel:
// File location: src/TUILive/components/Gift/useGiftList.ts

// Gift backup data
const giftListDataBackup = {
"giftList": [
{
"giftId": "1",
"imageUrl": "Gift image URL",
"animationUrl": "Gift animation effect URL", // Requires an SVGA format animation.
"price": 99,
"giftName": "Heart",
"giftName_en": "Heart gesture",
"type": 0
},
// ...
]
}

// Replace the gift data URLs in the getGiftList method.
const getGiftList = async (): Promise<Gift[]> => {
const giftDataUrl = 'Gift image URL';
const { giftList } = await safelyFetchGiftData(giftDataUrl);
// Cross-domain issues may prevent the browser from retrieving API data when requesting resources. In such cases, you can use the gift backup data instead.
return giftList || giftListDataBackup;
}

FAQs

Gift Component Initialization Timing

Since the gift component's controller needs to integrate some live room information parameters and user information, it should be loaded after the audience enters the live broadcast room or the anchor creates a live streaming room.