文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>实时音视频>无 UI 集成>接入 RoomEngine-SDK>高级功能>直播间送礼物

直播间送礼物

最近更新时间：2025-09-29 21:31:02

我的收藏

本页目录：

RoomEngine SDK 提供了完善的直播间礼物功能支持，您可以轻松实现多样化的礼物互动体验。


前提条件

在发送礼物消息之前，需要先加入一个直播间，您可以参见 观看一场直播 里的步骤加入直播间。
为直播间增加“送礼物”的功能，通常需要完成以下几个步骤：
配置 App 支持的礼物列表。
在直播间添加"送礼物"按钮，点击后弹出礼物选择面板。
观众选择礼物后，调用 RoomEngine SDK 的 API 发送礼物消息至直播间。
后台服务器验证送礼权限，检查发送者账户余额，按礼物价值扣款后放行消息。
直播间所有用户接收礼物消息并播放对应动画。

配置 App 支持的礼物列表

在介绍如何为 App 配置礼物列表前，需要先明确礼物的两个关键参数。

礼物关键参数

TUIGiftInfo 结构体描述单个礼物的属性；TUIGiftCategory 结构体定义礼物分类信息，并通过 giftList 字段聚合该类别下的所有礼物对象。
TUIGiftInfo 结构体包含以下字段：
字段名称
字段含义
数据类型
giftId
礼物 ID
字符串
name
礼物名称
字符串
desc
礼物描述
字符串
iconUrl
礼物图标 URL
字符串
resourceUrl
礼物资源 URL，例如：SVGA、GIF、MP4 等动画资源的 URL
字符串
level
礼物等级
数字
coins
礼物价格
数字
extensionInfo
礼物扩展字段
字典
TUIGiftCategory 结构体包含以下字段：
字段名称
字段含义
数据类型
categoryId
礼物分类 ID
字符串
name
礼物分类名称
字符串
desc
礼物分类描述
字符串
giftList
当前礼物分类下的礼物列表
TUIGiftInfo 类型的数组
extensionInfo
礼物分类扩展字段
字典

配置礼物列表

为 App 配置礼物列表需要按照以下步骤通过 REST API 进行操作：
使用 添加礼物 REST API 添加礼物，得到一系列的 giftId。
使用 添加礼物分类 REST API 添加礼物分类，得到若干 categoryId。
利用前两步得到的 giftId 和 categoryId，调用 添加礼物分类关系 REST API，设置礼物所属的分类。

拉取礼物列表展示礼物面板

接下来，您需要在直播间界面中添加一个"送礼物"按钮。当用户点击该按钮时弹出礼物选择面板。在实现这个功能时，您可以调用 TUILiveGiftManager 插件提供的 getGiftList 接口。这个接口会自动获取您之前配置好的礼物列表数据，包括各种礼物的名称、图标、价格等信息。礼物选择面板应该将这些信息清晰地展示给用户，让用户可以方便地浏览和选择想要赠送的礼物。
Swift
Kotlin
import RTCRoomEngine

guard let liveGiftManager = TUIRoomEngine.sharedInstance().getExtension(extensionType: .liveGiftManager) as? TUILiveGiftManager else {
    return
}

let roomId = "xxx"   // 请替换为实际的直播间 ID

liveGiftManager.getGiftList(roomId: roomId) { giftCategoryList in
    // 获取礼物列表成功
} onError: { code, message in
    // 获取礼物列表失败
}
String roomId = "xxx";   // 请替换为实际的直播间 ID

TUILiveGiftManager liveGiftManager = (TUILiveGiftManager) TUIRoomEngine.sharedInstance().getExtension(TUICommonDefine.ExtensionType.LIVE_GIFT_MANAGER);
liveGiftManager.getGiftList(roomId, new TUILiveGiftManager.GetGiftListCallback() {
    @Override
    public void onSuccess(List<TUILiveGiftManager.GiftCategory> giftCategoryList) {
        // 获取礼物列表成功
    }

    @Override
    public void onError(TUICommonDefine.Error error, String message) {
        // 获取礼物列表失败
    }
});

选择礼物并送出

当用户选择心仪的礼物并点击 "送出" 按钮时，您需要调用 TUILiveGiftManager 插件提供的 sendGift 接口来完成礼物发送操作。该接口需要传入三个关键参数：当前直播间的 ID、用户所选礼物 ID、礼物数量。调用成功后，SDK 会向指定直播间发送礼物消息。
Swift
Kotlin
import RTCRoomEngine

guard let liveGiftManager = TUIRoomEngine.sharedInstance().getExtension(extensionType: .liveGiftManager) as? TUILiveGiftManager else {
    return
}

let roomId = "xxx"   // 请替换为实际的直播间 ID
let giftId = "xxx"   // 请替换实际的礼物 ID
let count  = 1       // 请替换为实际发送数量

liveGiftManager.sendGift(roomId: roomId, giftId: giftId, count: UInt(count)) {
    // 礼物发送成功
} onError: { code, message in
    // 礼物发送失败
}
String roomId = "xxx";   // 请替换为实际的直播间 ID
String giftId = "xxx";   // 请替换实际的礼物 ID
int count  = 1;          // 请替换为实际发送数量

TUILiveGiftManager liveGiftManager = (TUILiveGiftManager)TUIRoomEngine.sharedInstance().getExtension(TUICommonDefine.ExtensionType.LIVE_GIFT_MANAGER);
liveGiftManager.sendGift(roomId, giftId, count, new TUIRoomDefine.ActionCallback() {
    @Override
    public void onSuccess() {
        // 礼物发送成功
    }
    @Override
    public void onError(TUICommonDefine.Error error, String message) {
        // 礼物发送失败
    }
});

服务器校验送礼权限

礼物消息成功发出之后，您需要在自己的后台服务器拦截该消息。首先，根据礼物的单价和用户发送的数量，精确计算出本次礼物的总金额。然后，查询发送者的账户余额信息，并尝试执行扣款操作。如果扣款成功，则放行该条礼物消息，使其正常发送到直播间内。否则，终止礼物消息的发送，同时给发送者返回“账户余额不足”的提示信息。
您可以通过向 RoomEngine 后台服务器注册 发送礼物前回调 来完成上述操作。注册该回调功能后，当 RoomEngine 后台服务器接收到用户发送的礼物消息时，会首先触发对您指定服务器的回调请求。在您的服务器端完成权限校验流程后，根据您服务器的返回结果，决定是否继续发送该礼物消息。

接收礼物通知消息

成功通过服务器校验的礼物消息将发送给直播间所有用户。您可以通过 TUILiveGiftObserver 的 onReceiveGiftMessage 回调接收礼物消息通知，该回调会返回礼物信息 giftInfo、礼物数量 giftCount 和发送者信息。收到礼物消息后，您可以播放礼物动画或在弹幕消息列表中添加提示消息。
Swift
Kotlin
import RTCRoomEngine

class LiveGiftObserver: NSObject, TUILiveGiftObserver {
    func onReceiveGiftMessage(roomId: String, giftInfo: TUIGiftInfo, giftCount: UInt, sender: TUIUserInfo) {
        // 接收到礼物消息
    }
}

guard let liveGiftManager = TUIRoomEngine.sharedInstance().getExtension(extensionType: .liveGiftManager) as? TUILiveGiftManager else {
    return
}

let liveGiftObserver = LiveGiftObserver()
liveGiftManager.addObserver(liveGiftObserver)
public class LiveGiftObserver extends TUILiveGiftManager.Observer {
    public void onReceiveGiftMessage(String roomId, TUILiveGiftManager.GiftInfo giftInfo, long giftCount, TUIRoomDefine.UserInfo sender) {
        // 接收到礼物消息
    }
}

LiveGiftObserver observer = new LiveGiftObserver();

TUILiveGiftManager liveGiftManager = (TUILiveGiftManager) TUIRoomEngine.sharedInstance().getExtension(TUICommonDefine.ExtensionType.LIVE_GIFT_MANAGER);
liveGiftManager.addObserver(observer);

获取礼物统计信息

在直播间中，礼物主要赠送给主播。主播可以通过调用 TUILiveGiftManager 插件的 getGiftCountByAnchor 接口获取礼物统计信息，包括累计礼物数量、累计礼物金额和累计送礼人数等数据。该接口仅限主播调用，观众无权限调用。
Swift
Kotlin
import RTCRoomEngine

guard let liveGiftManager = TUIRoomEngine.sharedInstance().getExtension(extensionType: .liveGiftManager) as? TUILiveGiftManager else {
    return
}

let roomId = "xxx"   // 请替换为实际的直播间 ID
liveGiftManager.getGiftCountByAnchor(roomId: roomId) { totalGiftsSent, totalGiftCoins, totalUniqueGiftSenders in
    // 获取礼物统计信息成功
} onError: { code, message in
    // 获取礼物统计信息失败
}
String roomId = "xxx";   // 请替换为实际的直播间 ID

TUILiveGiftManager liveGiftManager = (TUILiveGiftManager) TUIRoomEngine.sharedInstance().getExtension(TUICommonDefine.ExtensionType.LIVE_GIFT_MANAGER);        
liveGiftManager.getGiftCountByAnchor(roomId, new TUILiveGiftManager.GetGiftCountCallback() {
    @Override
    public void onSuccess(long totalGiftsSent, long totalGiftCoins, long totalUniqueGiftSenders) {
        // 获取礼物统计信息成功
    }
    @Override
    public void onError(TUICommonDefine.Error error, String message) {
        // 获取礼物统计信息失败
    }
});
主播还可以通过 TUILiveGiftObserver 的 onGiftCountChanged 回调实时接收礼物统计信息变化的通知。
Swift
Kotlin
import RTCRoomEngine

class LiveGiftObserver: NSObject, TUILiveGiftObserver {
    func onGiftCountChanged(roomId: String, totalGiftsSent: UInt, totalGiftCoins: UInt, totalUniqueGiftSenders: UInt) {
        // 礼物统计信息变化通知
    }
}

guard let liveGiftManager = TUIRoomEngine.sharedInstance().getExtension(extensionType: .liveGiftManager) as? TUILiveGiftManager else {
    return
}

let liveGiftObserver = LiveGiftObserver()
liveGiftManager.addObserver(liveGiftObserver)
public class LiveGiftObserver extends TUILiveGiftManager.Observer {
    public void onGiftCountChanged(String roomId, long totalGiftsSent, long totalGiftCoins, long totalUniqueGiftSenders) {
        // 礼物统计信息变化通知
    }
}

LiveGiftObserver observer = new LiveGiftObserver();

TUILiveGiftManager liveGiftManager = (TUILiveGiftManager) TUIRoomEngine.sharedInstance().getExtension(TUICommonDefine.ExtensionType.LIVE_GIFT_MANAGER);
liveGiftManager.addObserver(observer);
中国站
目录