礼物播放器
直播送礼组件为直播场景提供完整互动解决方案,涵盖礼物素材管理、礼物扣费回调、礼物特效播放、礼物数据统计等功能。通过本文档,您可快速实现直播间礼物互动功能,并支持深度定制以满足业务需求。
核心功能
礼物素材配置:通过服务端 API 管理礼物信息、礼物分类和多语言配置。
礼物列表展示:提供开箱即用的礼物面板和播放组件,支持完整的用户交互流程。
礼物扣费回调:与您的计费系统无缝对接,完成余额校验和扣费流程。
礼物特效播放:提供基础和高级两种特效播放器,满足不同性能需求。
PK分数联动:支持礼物价值与主播 PK 分数的实时联动。
礼物数据统计:提供完整的礼物数据统计和查询能力。

组件构成
组件名称 | 具体内容 |
礼物播放组件 (GiftPlayView) | 负责礼物渲染和播放,支持特效动画,适配多场景。 |
礼物选择面板组件 (GiftListView) | 负责礼物列表展示,支持礼物发送、礼物分类,适配多设备。 |
效果演示
礼物面板 | 弹幕礼物 | 全屏礼物 |
![]() | ![]() | ![]() |
快速开始
步骤 1. 开通服务
步骤 2. 代码集成
步骤 3:接入礼物列表展示页面
在您的应用中接入礼物列表展示页面,使观众能够直观地看到可赠送的礼物列表。请参考示例代码创建
GiftListPanel
组件并添加到视图:import android.os.Bundleimport android.widget.FrameLayoutimport androidx.appcompat.app.AppCompatActivityimport com.trtc.uikit.livekit.Rimport com.trtc.uikit.livekit.component.gift.GiftListViewclass YourActivity : AppCompatActivity() {override fun onCreate(savedInstanceState: Bundle?) {super.onCreate(savedInstanceState)setContentView(R.layout.your_activity)var rootView: FrameLayout = findViewById(R.id.root_view)// 1.创建giftListView对象var giftListView = GiftListView(this)// 2.初始化giftListView对象giftListView.init("yourRoomId")// 3.将giftListView对象添加到您的页面中rootView.addView(giftListView)}}
import TUILiveKitclass YourGiftViewController: UIViewController {// 1. 创建 GiftListView 对象// - roomId: 与观众当前进入的直播间 roomId 一致lazy var giftListView = {let view = GiftListView(roomId: liveId)return view}()private let liveId: String// ... 其他代码 ...public override func viewDidLoad() {super.viewDidLoad()// 2. 将组件添加到您的视图中并设置布局view.addSubView(giftListView)giftPlayView.snp.remakeConstraints { make inmake.leading.trailing.equalToSuperview()make.height.equalTo(256)make.bottom.equalToSuperview()}}}
// 1. 构建 GiftListController 对象,请确保您在进房成功后再构建该对象// - roomId: 与观众当前进入的直播间 roomId 一致// - languageCode: 设置您在礼物系统中配置的礼物语言代码,默认为enGiftListController _giftListController = GiftListController(roomId: 'roomId', language: 'en');// 2. 添加使用 GiftDisplayWidget 组件// 2.1 单子树Widget,以 Container为例Container(child: GiftListWidget(controller: _giftSendController))// 2.2 多子树Widget,以 Column为例Column(children: [GiftPanelWidget(controller: _giftSendController)])
步骤 4:接入礼物特效播放页面
在您的应用中接入礼物特效播放页面,
GiftPlayView
组件已内置礼物消息接收与播放能力,请参考示例代码 创建 GiftPlayView
组件并添加到视图:import android.os.Bundleimport android.widget.FrameLayoutimport androidx.appcompat.app.AppCompatActivityimport com.trtc.uikit.livekit.Rimport com.trtc.uikit.livekit.component.gift.GiftPlayViewclass YourActivity : AppCompatActivity() {override fun onCreate(savedInstanceState: Bundle?) {super.onCreate(savedInstanceState)setContentView(R.layout.your_activity)var rootView: FrameLayout = findViewById(R.id.root_view)// 1.创建 giftPlayView 对象var giftPlayView = GiftPlayView(this)// 2.初始化 giftPlayView 对象giftPlayView.init("yourRoomId")// 3.将 giftPlayView 对象添加到您的页面中rootView.addView(giftPlayView)}}
import TUILiveKit// YourAnchorViewController 代表您的主播视图控制器,观众端可参考以下示例:class YourAnchorViewController: UIViewController {// 1. 创建并初始化 GiftPlayView 对象// - roomId: 与观众当前进入的直播间 roomId 一致lazy var giftPlayView = {let view = GiftPlayView(roomId: liveId)return view}()private let liveId: String// ... 其他代码 ...public override func viewDidLoad() {super.viewDidLoad()// 2. 将组件添加到您的视图中并设置布局view.addSubView(giftPlayView)giftPlayView.snp.remakeConstraints { make inmake.edges.equalToSuperview()}}}
// 1. 构建 GiftPlayController 对象,请确保您在进房成功后再构建该对象GiftPlayController _giftPlayController = GiftPlayController(roomId: 'roomId');// 2. 添加使用 GiftPlayWidget 组件// 2.1 单子树Widget,以 Container为例Container(child: GiftPlayWidget(controller: _giftPlayController))// 2.2 多子树Widget,以 Column为例Column(children: [GiftPlayWidget(controller: _giftPlayController)])
功能进阶
在直播场景中,礼物系统需要与计费系统和数据统计等业务紧密结合。本部分将详细介绍如何根据您的业务需求进行深度定制。
一、配置自定义礼物
通过 TUILiveKit 服务端 REST API,可对礼物清单进行全面管理,实现礼物系统的个性化定制,满足不同业务场景需求。
注意:
配置时序图

涉及 REST API 接口一览
二、计费与送礼扣费流程
TUILiveKit 不内置计费系统,需与您的自建计费系统对接,完成 “用户送礼 → 余额校验 → 扣费 → 结果同步” 全流程。
调用流程图

关键流程说明
1. 客户端发起送礼:用户在直播间客户端的
GiftListPanel
组件上,完成发送礼物的交互操作。2. TUILiveKit 触发回调:TUILiveKit 后台调用您配置的回调 URL,将送礼信息(例如礼物 Coins、用户标识等)传递给您的后台。
3. 计费系统余额扣费校验:您的后台系统调用您的客户计费系统,校验用户余额是否充足,并执行实际扣费操作。
4. 扣费结果返回 TUILiveKit:您的后台向 TUILiveKit 后台返回扣费结果(成功 / 失败)。
5. TUILiveKit 同步客户端:若扣费成功,TUILiveKit 后台向房间内所有客户端广播送礼结果,并触发礼物特效动画播放;若扣费失败,TUILiveKit 后台通知发起送礼的客户端 “送礼请求失败”。
涉及 REST API 接口一览
接口 | 说明 | 请求示例 |
回调配置 - 发送礼物之前回调 | 客户后台可以通过该回调决定是否通过送礼前校验等场景 |
三、数据统计
提供完整的礼物数据统计能力,帮助您了解礼物发放情况、用户行为趋势和业务运营效果。
调用流程图

关键流程说明
1. TUILiveKit 收集存储数据:TUILiveKit 后台自动收集所有礼物相关数据,并安全存储礼物发放记录和统计信息。
2. 查询数据:您的后台服务可以调用 TUILiveKit REST API 接口,查询礼物的统计数据。
3. TUILiveKit 返回结果:TUILiveKit 后台向您的后台返回格式化后的统计结果。
涉及的 REST API 接口一览
接口 | 说明 | 请求示例 |
主动接口 - 查询礼物统计 | 通过该接口获取某个用户的收礼统计 |
四、PK 分数联动(可选)
通常在直播主播 PK 场景下,需将主播收到的礼物价值与 PK 数值挂钩(例:观众送 “火箭” 礼物,主播 PK 分数增加 500 分),通过礼物互动提升 PK 竞技性与直播氛围。
重要说明:
TUILiveKit 后台的 PK 分数系统采用纯数值计算和累加机制,所以您需要根据自身的运营策略和业务需求,调用更新接口前完成 PK 分数的计算,您可以参考如下的PK 分数计算示例:
礼物类型 | 分数计算规则 | 示例 |
基础礼物 | 礼物价值 × 5 | 10元礼物 → 50分 |
中级礼物 | 礼物价值 × 8 | 50元礼物 → 400分 |
高级礼物 | 礼物价值 × 12 | 100元礼物 → 1200分 |
特效礼物 | 固定高分数 | 520元礼物 → 1314分 |
调用流程图

关键流程说明
1. 获取 PK 状态:
回调配置:您可以通过配置 PK 状态回调,由 TUILiveKit 后台在 PK 开始、结束时,主动通知您的系统 PK 状态。
主动查询:您的后台服务可主动调用 PK 状态查询 接口,随时查询当前 PK 状态。
2. PK 分数计算:您的后台服务根据业务规则(如上述示例),计算 PK 分数增量。
3. PK 分数更新:您的后台服务调用 修改 PK 分数 接口,向 TUILiveKit 后台更新 PK 分数。
4. TUILiveKit 同步客户端:TUILiveKit 后台自动将更新后的 PK 分数同步到所有客户端。
涉及的 REST API 接口一览
五、高级特效播放器 (可选)
TUILiveKit 提供了两种礼物特效播放器:基础特效播放器(内置)和 高级特效播放器(需额外集成)。
对比项 | 基础特效播放器 | 高级特效播放器 |
计费 | 免费 | |
集成方式 | 默认内置 | |
动画支持 | 点赞动画 弹幕动画 全屏动画 | 点赞动画 弹幕动画 全屏动画 |
动画格式 | 仅支持SVGA | SVGA、PAG、WebP、PAG、Lottie、PNG、MP4、VAP等 |
性能 | 支持 <=10MB SVGA文件 | 支持更大的动画文件,在播放复杂特效时,性能占用更低,确保多动画同时播放流畅,尤其在低端设备上表现优异。 |
高级特效播放器集成
您只需参考以下方式集成,即可实现 TUILiveKit 高级特效播放能力。
1. 下载组件:下载并解压 TUILiveKit,把
Android/tceffectplayerkit
文件夹拷贝到自己的工程中,和 app
同级目录。

2. 集成组件:编辑您自己工程的
settings.gradle
文件,添加下面的代码:include ':tceffectplayerkit'
3. 初始化鉴权:在您的应用初始化位置,调用 TCMediaXBase 的方法进行鉴权,
LicenseUrl
和 LicenseKey
获取请查看 License 指引。TCMediaXBase.getInstance().setLicense(context,"LicenseUrl", // 请替换 LicenseUrl"LicenseKey", // 请替换 LicenseKeynew ILicenseCallback() {@Overridepublic void onResult(int error, String message) {Log.i("TCMediaXBase", "setLicense result: " + error + " " + message);}});
4. 完成上述步骤后,TUILiveKit 会自动切到高级特效播放器,您无需做其它操作。
1. 下载组件:下载并解压 TUILiveKit,把
iOS/TCEffectPlayerKit
文件夹拷贝到自己的工程中,和 Podfile
同级目录。

2. 集成组件:编辑
Podfile
文件,添加下面的代码并在终端执行 pod install
命令:pod 'TCEffectPlayerKit',:podspec => './TCEffectPlayerKit/TCEffectPlayerKit.podspec'
3. 初始化鉴权:在您的应用初始化位置,调用 TCMediaXBase 的方法进行鉴权,
LicenseUrl
和 LicenseKey
获取请查看 License 指引。//// AppDelegate.swift//import TCMediaXfunc application(_ application: UIApplication,didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {TCMediaXBase.getInstance().setDelegate(self)TCMediaXBase.getInstance().setLicenceURL("LicenseURL
", key: "LicenseKEY")return true}func onLicenseCheckCallback(_ errcode: Int32, withParam param: [AnyHashable : Any]) {debugPrint("[TCMediaXBase] setLicense result: errcode:\(errcode), param:\(param)")}
4. 完成上述步骤后,TUILiveKit 会自动切到高级特效播放器,您无需做其它操作。
常见问题
计费系统需要我自己开发吗?
是的。
TUILiveKit
通过回调机制与您的计费系统对接,您需要自行实现用户账户系统、处理扣费验证回调、并管理积分发放规则。我需要关心 PK 联动吗?它是如何工作的?
您需要关心。
TUILiveKit
提供的 PK 分数系统是基于纯数值的累加机制,您需要根据自己的业务需求计算每次送礼所增加的 PK 分数,然后调用 TUILiveKit
的接口来更新分数,TUILiveKit 会自动将分数同步到客户端。没有服务端,只有客户端,如何配置礼物?
如果您没有自己的服务端,可以使用
Postman
或 Apifox
等 API 工具,直接调用 TUILiveKit
提供的 REST API 来配置礼物列表。送礼通知会被禁言或频控拦截吗?
不会。送礼通知不受禁言或频控影响,确保可靠投递。
特效播放卡顿怎么办?
请检查您的 SVGA 文件大小是否小于 10MB。如果文件过大,您可以考虑升级到高级特效播放器以获得更优的性能。