礼物播放器

直播送礼组件为直播场景提供完整互动解决方案,涵盖礼物素材管理礼物扣费回调、礼物特效播放、礼物数据统计等功能。通过本文档,您可快速实现直播间礼物互动功能,并支持深度定制以满足业务需求。

核心功能

礼物素材配置:通过服务端 API 管理礼物信息、礼物分类和多语言配置。
礼物列表展示:提供开箱即用的礼物面板和播放组件,支持完整的用户交互流程。
礼物扣费回调:与您的计费系统无缝对接,完成余额校验和扣费流程。
礼物特效播放:提供基础和高级两种特效播放器,满足不同性能需求。
PK分数联动:支持礼物价值与主播 PK 分数的实时联动。
礼物数据统计:提供完整的礼物数据统计和查询能力。


组件构成

组件名称
具体内容
礼物播放组件 (GiftPlayView)
负责礼物渲染和播放,支持特效动画,适配多场景。
礼物选择面板组件 (GiftListView)
负责礼物列表展示,支持礼物发送、礼物分类,适配多设备。

效果演示

礼物面板
弹幕礼物
全屏礼物










快速开始

步骤 1. 开通服务

参考 开通服务 文档开通体验版大规模直播版套餐。

步骤 2. 代码集成

参考 准备工作 接入 TUILiveKit,版本限制: TUILiveKit >= 3.2.0

步骤 3:接入礼物列表展示页面

在您的应用中接入礼物列表展示页面,使观众能够直观地看到可赠送的礼物列表。请参考示例代码创建 GiftListPanel 组件并添加到视图:
Android
iOS
Flutter
import android.os.Bundle
import android.widget.FrameLayout
import androidx.appcompat.app.AppCompatActivity
import com.trtc.uikit.livekit.R
import com.trtc.uikit.livekit.component.gift.GiftListView


class 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 TUILiveKit

class 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 in
make.leading.trailing.equalToSuperview()
make.height.equalTo(256)
make.bottom.equalToSuperview()
}
}
}
// 1. 构建 GiftListController 对象,请确保您在进房成功后再构建该对象
// - roomId: 与观众当前进入的直播间 roomId 一致
// - languageCode: 设置您在礼物系统中配置的礼物语言代码,默认为en
GiftListController _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 组件并添加到视图:
Android
iOS
Flutter
import android.os.Bundle
import android.widget.FrameLayout
import androidx.appcompat.app.AppCompatActivity
import com.trtc.uikit.livekit.R
import com.trtc.uikit.livekit.component.gift.GiftPlayView

class 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 in
make.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 调用,更多配置详情可参考 礼物配置指引文档

配置时序图



涉及 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 接口一览

接口
说明
请求示例
主动接口 - 查询 PK 状态
可根据此接口查询当前房间是否在 PK
主动接口 - 修改 PK 分数
将计算后的 PK 数值通过此接口更新
回调配置 - PK 开始时回调
客户后台可以通过该回调及时知晓 PK 开启
回调配置 - PK 结束时回调
客户后台可以通过该回调及时知晓 PK 结束

五、高级特效播放器​ (可选)

TUILiveKit 提供了两种礼物特效播放器:基础特效播放器(内置)高级特效播放器(需额外集成)
对比项
基础特效播放器
高级特效播放器
计费
免费
付费,请参考付费指引
集成方式
默认内置
需额外集成,可参考高级特效播放器集成指引
动画支持
点赞动画
弹幕动画
全屏动画
点赞动画
弹幕动画
全屏动画
动画格式
仅支持SVGA
SVGA、PAG、WebP、PAG、Lottie、PNG、MP4、VAP等
性能
支持 <=10MB SVGA文件
支持更大的动画文件,在播放复杂特效时,性能占用更低,确保多动画同时播放流畅,尤其在低端设备上表现优异。

高级特效播放器集成

您只需参考以下方式集成,即可实现 TUILiveKit 高级特效播放能力。
Android
iOS
1. 下载组件:下载并解压 TUILiveKit,把Android/tceffectplayerkit 文件夹拷贝到自己的工程中,和 app 同级目录。



2. 集成组件:编辑您自己工程的 settings.gradle 文件,添加下面的代码:
include ':tceffectplayerkit'
3. 初始化鉴权:在您的应用初始化位置,调用 TCMediaXBase 的方法进行鉴权,LicenseUrlLicenseKey 获取请查看 License 指引
TCMediaXBase.getInstance().setLicense(context,
"LicenseUrl", // 请替换 LicenseUrl
"LicenseKey", // 请替换 LicenseKey
new ILicenseCallback() {
@Override
public 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 的方法进行鉴权,LicenseUrlLicenseKey 获取请查看 License 指引
//
// AppDelegate.swift
//

import TCMediaX

func 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 会自动将分数同步到客户端。

没有服务端,只有客户端,如何配置礼物?

如果您没有自己的服务端,可以使用 PostmanApifox 等 API 工具,直接调用 TUILiveKit 提供的 REST API 来配置礼物列表。

送礼通知会被禁言或频控拦截吗?

不会。送礼通知不受禁言或频控影响,确保可靠投递。

特效播放卡顿怎么办?

请检查您的 SVGA 文件大小是否小于 10MB。如果文件过大,您可以考虑升级到高级特效播放器以获得更优的性能。