TUILiveKit 产品动态
云直播推拉流 SDK 产品动态
礼物系统（TUILiveKit）
TUILiveKit 提供了一套点赞送礼系统解决方案，涵盖礼物素材管理、礼物扣费回调、礼物特效播放、礼物数据统计等功能。通过本文档，您可快速实现直播间礼物互动功能，并支持深度定制以满足业务需求。
说明：
本文将针对含 UI 的接入方式介绍礼物系统；若您使用的接入方式为无 UI 集成，请参考以下接入方式：
视频直播：请参考 无 UI 集成 > 礼物（视频直播）。
语聊房：请参考 无 UI 集成 > 礼物（语聊房）。
核心功能
礼物素材配置：通过服务端 API 管理礼物信息、礼物分类和多语言配置。
礼物列表展示：客户端提供开箱即用的礼物面板和播放组件，支持完整的用户交互流程。
礼物扣费回调：可与您的计费系统无缝对接，完成余额校验和扣费流程。
礼物特效播放：提供基础和高级两种特效播放器，满足不同性能需求。
PK分数联动：支持礼物价值与主播 PK 分数的实时联动。
礼物数据统计：提供完整的礼物数据统计和查询能力。
效果演示
礼物面板 | 弹幕礼物 | 全屏礼物 |
 |  |  |
快速接入
本部分将介绍如何将礼物系统接入到您的项目中，以实现具备礼物列表展示、发送礼物、礼物特效播放的能力。
步骤 1：开通服务
步骤 2：代码集成
功能使用
在直播场景中，礼物系统需要与您的计费系统和数据统计等业务紧密结合。本部分将详细介绍如何根据您的业务需求进行深度定制。
一、配置自定义礼物
通过 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 接口一览
五、礼物动画特效 SDK (可选)
TUILiveKit 提供了两种礼物特效播放器：基础特效播放器（内置）和 礼物动画特效 SDK（需额外集成）。
对比项 | 基础特效播放器 | 礼物动画特效 SDK |
计费 | 免费 | |
集成方式 | 默认内置 | |
动画支持 | 点赞动画 弹幕动画 全屏动画 | 点赞动画 弹幕动画 全屏动画 |
动画格式 | 仅支持SVGA | SVGA、WebP、PAG、Lottie、PNG、MP4、VAP等。 |
性能 | 支持 <=10MB SVGA文件 | 支持更大的动画文件，在播放复杂特效时，性能占用更低，确保多动画同时播放流畅，尤其在低端设备上表现优异。 |
礼物动画特效 SDK集成
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。如果文件过大，您可以考虑升级到礼物动画特效 SDK 以获得更优的性能。
文档反馈