文档概览/
Live/
UIKit/
iOS/
Universal Features/
互动礼物/

互动礼物

功能介绍

互动礼物组件是一款虚拟礼物互动平台，旨在为用户的社交体验增添更多乐趣。借助这一组件，用户能够向自己欣赏的直播主播送上虚拟礼物，以此展示他们的赞赏、喜爱以及支持。
互动礼物组件支持设置点赞、礼物发送面板、发送礼物、播放普通礼物动画、播放 svga 礼物动画等。
Flutter
Android
iOS
互动礼物组件提供 2 个视图组件：
GiftSendWidget：发送礼物消息视图，点击后可以拉起礼物面板。
GiftDisplayWidget：接收礼物消息视图，会显示礼物消息到该视图上。
效果如下图所示：
礼物展示面板
普通礼物播放效果
全屏礼物播放效果









礼物组件主要提供2个 API：
GiftListPanelView：礼物面板，呈现礼物列表，发送礼物及充值。
GiftPlayView：播放礼物的面板，自动监听礼物消息。
效果如下图所示：
礼物展示面板
普通礼物播放效果
全屏礼物播放效果









礼物组件主要提供2个 API：
GiftListView：礼物面板，呈现礼物列表，发送礼物。
GiftPlayView：播放礼物的面板，自动监听礼物消息。
效果如下图所示：
礼物展示面板
普通礼物播放效果
全屏礼物播放效果










快速接入

说明：
如果您已经集成了 LiveKit 组件，我们在 LiveKit 中默认已经接入了 gift 组件，您可以直接在 LiveKit 中体验互动礼物功能。

添加 Gift 组件到项目中

Flutter
Android
iOS
1. 从 github下载 gift 组件到本地，并将 gift (TUILiveKit/Flutter/gift) 目录拷贝到您的工程目录中，例如 livekit 中接入 gift 组件，目录如下图所示：



2. 在您的项目工程的 pubspec.yaml 文件的 dependencies 节点下中，添加 barrage 的本地依赖。
dependencies:
  flutter:
    sdk: flutter
  flutter_localizations:
    sdk: flutter
  intl: ^0.19.0
  # 添加 gift 本地依赖
  gift:
    path: ../gift
3. 配置多语言支持，在您应用 MaterialApp 的 localizationsDelegates 和 supportedLocales 属性上添加 gift 组件的多语言支持。
MaterialApp(localizationsDelegates: const [
  ...GiftLocalizations.localizationsDelegates,
], supportedLocales: const [
  ...GiftLocalizations.supportedLocales,
], theme: ThemeData.dark(), home: const HomeScreen());
集成 LiveKit 组件即可正常使用，详情见 GitHub。
集成 LiveKit 组件即可正常使用，详情见 GitHub。

接入发送礼物组件

Flutter
Android
iOS
在您需要接入发送礼物消息的地方构建 GiftSendController 和 GiftSendWidget 对象，并将构建的 GiftSendWidget 对象添加到您的 Widget 树上。示例代码如下：
GiftSendController _giftSendController = GiftSendController(
  roomId: "liveRoomId",             /// liveRoomId   替换为您的直播间ID
  owner: ownerInfo,                 /// ownerInfo    替换为您的直播间主播信息
  self: selfInfo,                   /// selfInfo     替换为您的登录用户信息
);

GiftSendWidget(controller: _giftSendController);
实现 GiftListPanelView 的 OnSendGiftListener 中的 onSendGift 回调 ，获取礼物个数和礼物信息，在预处理完后可调用 GiftListPanelView 的 sendGift 函数用于礼物的实际发送。
public void onSendGift(GiftListPanelView giftListView, Gift gift, int giftCount) {
   //...此处为预处理，如校验当前用户的余额等操作
   GiftUser receiver = new GiftUser();
   //...此处设置礼物接受者信息
   giftListView.sendGift(gift, giftCount, receiver);
}
创建 GiftListView 对象，并将其添加到您的视图上，同时还需要实现GiftListViewDelegate中的 onSendGift 回调方法。
当您点击GiftListView 面板上的发送按钮时，您会收到该回调方式，您可在该方法中获取准备发送的礼物个数和礼物信息，在预处理完后可调用 GiftListView 的 sendGift 函数用于礼物的实际发送。
lazy var giftListView = GiftListView(roomId: roomId, delegate: self)
// ...此处将giftListView添加到您的父视图上并调整布局

func onSendGift(gift model: TUIGift, giftCount: Int) {
    //...此处为预处理，如校验当前用户的余额等操作
    let receiver = TUIGiftUser()
    //...此处设置礼物接受者信息
    giftListView.sendGift(model: giftModel, giftCount: giftCount, receiver: receiver, completion: completion)
}

接入显示礼物组件

Flutter
Android
iOS
在您需要接入显示礼物消息的地方构建 GiftDisplayController 和 GiftDisplayWidget 对象，并将构建的 GiftDisplayWidget 对象添加到您的 Widget 树上。示例代码如下：
GiftDisplayController _giftDisplayController = GiftDisplayController(
  rroomId: "liveRoomId",             /// liveRoomId   替换为您的直播间ID
  owner: ownerInfo,                  /// ownerInfo    替换为您的直播间主播信息
  self: selfInfo,                    /// selfInfo     替换为您的登录用户信息
);

GiftDisplayWidget(controller: _giftDisplayController!);
礼物展示组件 GiftPlayView 自身会接收并播放礼物消息。
GiftPlayView giftPlayView = new GiftPlayView(mContext, roomId);
礼物展示组件 GiftPlayView 自身会接收并播放礼物消息。
您只需要创建 GiftPlayView 对象并将其添加到您的视图上即可。
let giftPlayView = GiftPlayView(groupId: roomId)
// ...此处将giftPlayView添加到您的父视图上并调整布局

监听礼物收发消息

Flutter
Android
iOS
若需要获取收发礼物的回调信息，您可以调用 GiftDisplayController 的 setGiftCallback 方法, 示例代码如下所示：
_giftDisplayController?.setGiftCallback(
  onReceiveGiftCallback: _onReceiveGiftCallback,     /// _onReceiveGiftCallback 可以替换为您的自定义处理方法
  onSendGiftCallback: _onSendGiftCallback,           /// _onSendGiftCallback    可以替换为您的自定义处理方法
);
若需要获取接收礼物的回调信息，可实现 GiftPlayView 的 TUIGiftPlayViewListener 中的 onReceiveGift 函数。

public interface TUIGiftPlayViewListener {
    void onReceiveGift(Gift gift, int giftCount, GiftUser sender, GiftUser receiver);
    //...
}
若需要获取接收礼物的回调信息，可实现 GiftPlayView 的 代理GiftPlayViewDelegate 中的 giftPlayView:onReceiveGift:gift:giftCount:sender:receiver 函数。
func giftPlayView(_ giftPlayView: GiftPlayView, onReceiveGift gift: TUIGift, giftCount: Int, sender: TUIGiftUser, receiver: TUIGiftUser)
    // 自定义处理
}

自定义礼物面板

Flutter
Android
iOS
如果您需要修改礼物面板的礼物列表，您可以调用 GiftSendController 的 setGiftList 方法，示例如下： 
         List<GiftModel> giftList = [     /// 自定义您的礼物列表数据源
  GiftModel(giftId: "1", giftName: "鸡蛋", imageUrl: "giftImageUrl", price: 10),
  GiftModel(giftId: "2", giftName: "星星", imageUrl: "giftImageUrl", price: 10),
];     

_giftSendController.setGiftList(giftList);
如果您需要修改礼物面板的礼物列表：
mGiftCloudServer.queryGiftInfoList((error, result) -> post(() -> {
    if (error == Error.NO_ERROR) {
        mGiftListView.setGiftList(result);
    } else {
        ToastUtil.toastLongMessage("query gift list error, code = " + error);
    }
}));
说明：
客户自行实现 queryGiftInfoList方法的逻辑，得到一个自定义的礼物列表 List<Gift> ，通过GiftListView.setGiftList设置礼物列表即可。
礼物的animationUrl 要求是一个SVGA动画。
如果您需要修改礼物面板的礼物列表：
// 文件位置：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()
}


//  文件位置：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
    }
}
说明：
客户自行实现 queryGiftInfoList方法的逻辑，得到一个自定义的礼物列表 List<TUIGift> ，通过GiftListView.setGiftList设置礼物列表即可。
礼物的animationUrl 要求是一个SVGA动画。
客户自行实现 queryGiftInfoList方法的逻辑，得到一个自定义的礼物列表 List<TUIGift> ，通过GiftListView.setGiftList设置礼物列表即可。
礼物的animationUrl 要求是一个SVGA动画

常见问题

礼物组件初始化时机

由于礼物组件的 controller 需要接入一些直播间信息参数 和 自己的用户信息，所以需要在观众进入直播间或者主播创建直播间后，在加载礼物组件。