注意：说明：
注意：若你使用的是无 UI 集成接入方式，请参考 无 UI 集成 – 礼物。
一、核心功能
·礼物素材配置：通过服务端 API 管理礼物信息、礼物分类和多语言配置。
·礼物列表展示：客户端提供开箱即用的礼物面板和播放组件，支持完整的用户交互流程。
·礼物扣费回调：可与你的计费系统无缝对接，完成余额校验和扣费流程。
·礼物特效播放：提供基础和高级两种特效播放器，满足不同性能需求。
·PK 分数联动：支持礼物价值与主播 PK 分数的实时联动。
·礼物数据统计：提供完整的礼物数据统计和查询能力。
二、效果演示
| 礼物面板 | 弹幕礼物 | 全屏礼物 |
| | | |
三、快速接入
本部分将介绍如何将礼物系统接入到你的项目中，令你的项目具备礼物列表展示、发送礼物、礼物特效播放能力。
四、步骤 1：开通服务
请参考 开通服务，领取 TUILiveKit 体验版或者开通付费版。
注意：说明：
注意：使用礼物系统要求开通 TUILiveKit 体验版、多人连麦版或大规模直播版，不同套餐中可配置的礼物数量有所不同，详细参见 功能与计费说明 中的礼物系统说明，你可按需选购。
五、步骤 2：代码集成
你需要首先完成 TUILiveKit 代码集成，目前提供多种接入方式，具体差异可见 接入方式说明。
| 接入方式 | 接入说明 |
| 视频直播 | Android：主播端：请参考 主播开播。观众端：请参考 观众观看。iOS:主播端：请参考 主播开播。观众端：请参考 观众观看。版本限制： TUILiveKit >= 3.2.0接入完成后，在对应的主播页和观众页将默认包含礼物列表页与礼物特效播放能力。 |
| UI 自定义 | Android： 在对应的主播页和观众页请参考 直播送礼组件 接入礼物选择面板组件与礼物播放组件。iOS: 请参考 直播送礼组件 接入礼物选择面板组件与礼物播放组件。接入完成后，在对应的主播页和观众页将默认包含礼物列表页与礼物特效播放能力。 |
六、功能指南
在直播场景中，礼物系统需要与你的计费系统和数据统计等业务紧密结合。本部分将详细介绍如何根据你的业务需求进行深度定制。
七、配置自定义礼物
通过 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 分数计算示例：
21、关键流程说明
1. 获取 PK 状态：
·回调配置：你可以通过配置 PK 状态回调，由 TUILiveKit 后台在 PK 开始、结束时，主动通知你的系统 PK 状态。
·主动查询：你的后台服务可主动调用 PK 状态查询 接口，随时查询当前 PK 状态。
2. PK 分数计算：你的后台服务根据业务规则（如上述示例），计算 PK 分数增量。
3. PK 分数更新：你的后台服务调用 修改 PK 分数 接口，向 TUILiveKit 后台更新 PK 分数。
4. TUILiveKit 同步客户端：TUILiveKit 后台自动将更新后的 PK 分数同步到所有客户端。
22、涉及的 REST API 接口一览
| 接口 | 说明 | 请求示例 |
| 主动接口 – 查询 PK 状态 | 可根据此接口查询当前房间是否在 PK | 请求示例 |
| 主动接口 – 修改 PK 分数 | 将计算后的 PK 数值通过此接口更新 | 请求示例 |
| 回调配置 – PK 开始时回调 | 客户后台可以通过该回调及时知晓 PK 开启 | 回调示例 |
| 回调配置 – PK 结束时回调 | 客户后台可以通过该回调及时知晓 PK 结束 | 回调示例 |
23、礼物动画特效 SDK
TUILiveKit 默认内置了轻量级 SVGA 播放器。如果你需要播放更高质量、更复杂的动画（例如 PAG, MP4, VAP 格式），或者 SVGA 文件超过 10MB，建议集成 礼物动画特效 SDK (TCEffectPlayerKit)。
24、功能对比
| 对比项 | 基础特效播放器 | 礼物动画特效 SDK |
| 计费 | 开通 TUILiveKit 即可使用 | 除 TUILiveKit 外需另外付费，请参考 付费指引 |
| 集成方式 | 默认内置 | 需额外集成，可参考 礼物动画特效SDK集成 |
| 动画支持 | 点赞动画弹幕动画全屏动画 | 点赞动画弹幕动画全屏动画 |
| 动画格式 | 仅支持SVGA | SVGA、PAG、WebP、PAG、Lottie、PNG、MP4、VAP等 |
| 性能 | 支持 <=10MB SVGA文件 | 支持更大的动画文件，在播放复杂特效时，性能占用更低，确保多动画同时播放流畅，尤其在低端设备上表现优异。 |
25、礼物动画特效 SDK 集成
你只需参考以下方式集成，即可在 TUILiveKit 内使用礼物动画特效 SDK。
AndroidiOS1. 下载组件：下载并解压 TUILiveKit，把Android/tceffectplayerkit 文件夹拷贝到自己的工程中，和 app 同级目录。2. 集成组件：编辑你自己工程的 settings.gradle 文件，添加下面的代码： include ':tceffectplayerkit'3. 初始化鉴权：在你的应用初始化位置，调用 TCMediaXBase 的方法进行鉴权，LicenseUrl 和 LicenseKey 获取请查看 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 会自动切到礼物动画特效 SDK，你无需做其它操作。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 会自动切到礼物动画特效 SDK，你无需做其它操作。
27、计费系统需要我自己开发吗？
是的。TUILiveKit 通过回调机制与你的计费系统对接，你需要自行实现用户账户系统、处理扣费验证回调、并管理积分发放规则。
28、我需要关心 PK 联动吗？它是如何工作的？
你需要关心。TUILiveKit 提供的 PK 分数系统是基于纯数值的累加机制，你需要根据自己的业务需求计算每次送礼所增加的 PK 分数，然后调用 TUILiveKit 的接口来更新分数，TUILiveKit 会自动将分数同步到客户端。
29、没有服务端，只有客户端，如何配置礼物？
如果你没有自己的服务端，可以使用 Postman 或 Apifox 等 API 工具，直接调用 TUILiveKit 提供的 REST API 来配置礼物列表。
30、送礼通知会被禁言或频控拦截吗？
不会。送礼通知不受禁言或频控影响，确保可靠投递。
31、特效播放卡顿怎么办？
请检查你的 SVGA 文件大小是否小于 10MB。如果文件过大，你可以考虑升级到礼物动画特效 SDK 以获得更优的性能。