文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>实时音视频>直播与语聊房（含 UI）>功能指南>礼物系统

礼物系统

最近更新时间：2025-12-03 10:57:22

我的收藏

本页目录：

TUILiveKit 提供了一套完整的礼物系统解决方案。除客户端 UI 组件外，还涵盖了素材管理、扣费回调、数据统计、高级特效等能力。
本文档将指导您如何深度定制礼物系统，使其与您的业务系统（例如计费、运营后台）无缝连接。
说明：
若您使用的是无 UI 集成接入方式，请参考 无 UI 集成 - 礼物（视频直播）和 无 UI 集成 - 礼物（语聊房）。

核心功能

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


效果演示

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










快速接入

本部分将介绍如何将礼物系统接入到您的项目中，令您的项目具备礼物列表展示、发送礼物、礼物特效播放能力。

步骤 1：开通服务

请参考 开通服务，领取 TUILiveKit 体验版或者开通付费版。
说明：
使用礼物系统要求开通 TUILiveKit 体验版、多人连麦版或大规模直播版，不同套餐中可配置的礼物数量有所不同，详细参见 功能与计费说明 中的礼物系统说明，您可按需选购。

步骤 2：代码集成

您需要首先完成 TUILiveKit 代码集成，目前提供多种接入方式，具体差异可见 接入方式说明。
接入方式
接入说明
视频直播
Android：
主播端：请参考 主播开播。
观众端：请参考 观众观看。
iOS:
主播端：请参考 主播开播。
观众端：请参考 观众观看。
版本限制： TUILiveKit >= 3.2.0
接入完成后，在对应的主播页和观众页将默认包含礼物列表页与礼物特效播放能力。
语聊房
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 分数计算示例：
礼物类型
分数计算规则
示例
​基础礼物​
礼物价值 × 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 结束

礼物动画特效 SDK

TUILiveKit 默认内置了轻量级 SVGA 播放器。如果您需要播放更高质量、更复杂的动画（例如 PAG, MP4, VAP 格式），或者 SVGA 文件超过 10MB，建议集成 礼物动画特效 SDK (TCEffectPlayerKit)。

功能对比

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

礼物动画特效 SDK 集成

您只需参考以下方式集成，即可在 TUILiveKit 内使用礼物动画特效 SDK。
Android
iOS
1. 下载组件：下载并解压 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 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 会自动切到礼物动画特效 SDK，您无需做其它操作。

​常见问题

计费系统需要我自己开发吗？

是的。TUILiveKit 通过回调机制与您的计费系统对接，您需要自行实现用户账户系统、处理扣费验证回调、并管理积分发放规则。

我需要关心 PK 联动吗？它是如何工作的？

您需要关心。TUILiveKit 提供的 PK 分数系统是基于纯数值的累加机制，您需要根据自己的业务需求计算每次送礼所增加的 PK 分数，然后调用 TUILiveKit 的接口来更新分数，TUILiveKit 会自动将分数同步到客户端。

没有服务端，只有客户端，如何配置礼物？

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

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

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

特效播放卡顿怎么办？

请检查您的 SVGA 文件大小是否小于 10MB。如果文件过大，您可以考虑升级到礼物动画特效 SDK 以获得更优的性能。

中国站
目录