11 KiB
11 KiB
语音房火箭接口对接
规则
- 火箭最高 5 级。
- 房间送礼成功后，按礼物
heat_value增加当前等级火箭燃料。 - 当前等级满后立刻点火，并把该等级火箭放入
pending_launches等待发射。 - 点火后下一等级马上开始累计燃料。
- 单次送礼超过当前等级阈值时，超过部分直接作废，不顺延到下一等级。
- 发射延迟由后台
launch_delay_ms配置。 - 发射结算三类奖励：点火人、贡献第一、在房用户。在房用户按发射瞬间房间 presence 抽奖。
获取火箭
地址：GET /api/v1/rooms/{room_id}/rocket
参数：
| 参数 | 位置 | 必填 | 说明 |
|---|---|---|---|
room_id |
path | 是 | 房间 ID |
返回值：
| 字段 | 说明 |
|---|---|
enabled |
火箭是否开启 |
levels |
1 到 5 级配置 |
levels[].fuel_threshold |
等级燃料阈值 |
levels[].cover_url |
火箭小封面图 |
levels[].animation_url |
常态动效 |
levels[].launch_animation_url |
发射动效 |
levels[].launched_image_url |
发射后图 |
levels[].in_room_rewards |
在房奖励候选 |
levels[].top1_rewards |
贡献第一奖励候选 |
levels[].igniter_rewards |
点火人奖励候选 |
levels[].*_rewards[].resource_group_id |
奖励资源组 ID |
levels[].*_rewards[].resource_group |
奖励资源组详情 |
levels[].*_rewards[].resource_group.items |
资源组明细 |
levels[].*_rewards[].resource_group.items[].item_type |
wallet_asset 或 resource |
levels[].*_rewards[].resource_group.items[].wallet_asset_type |
金币等奖励资产类型，例如 COIN |
levels[].*_rewards[].resource_group.items[].wallet_asset_amount |
金币等奖励数量 |
levels[].*_rewards[].resource_group.items[].resource |
聊天气泡、麦位特效等资源素材 |
levels[].*_rewards[].resource_group.items[].resource.resource_type |
资源类型，例如 chat_bubble、mic_effect |
levels[].*_rewards[].resource_group.items[].resource.asset_url |
资源主素材 |
levels[].*_rewards[].resource_group.items[].resource.preview_url |
资源预览图 |
levels[].*_rewards[].resource_group.items[].resource.animation_url |
资源动效 |
levels[].*_rewards[].resource_group.items[].duration_ms |
资源有效期毫秒，0 表示永久 |
state.current_level |
当前正在累计的等级 |
state.current_fuel |
当前等级已累计燃料 |
state.fuel_threshold |
当前等级阈值 |
state.status |
charging 或 completed |
state.rocket_id |
当前正在累计火箭 ID |
state.pending_launches |
已点火待发射火箭列表 |
state.pending_launches[].rocket_id |
待发射火箭 ID |
state.pending_launches[].level |
待发射等级 |
state.pending_launches[].ignited_at_ms |
点火 UTC 毫秒 |
state.pending_launches[].launch_at_ms |
预计发射 UTC 毫秒 |
state.pending_launches[].top1_user_id |
点火时锁定贡献第一 |
state.pending_launches[].igniter_user_id |
点火人 |
state.pending_launches[].cover_url |
小封面图 |
state.last_rewards |
最近一次发射奖励结果 |
state.last_rewards[].resource_group_id |
本次中奖资源组 ID |
state.last_rewards[].resource_group |
本次中奖资源组详情，字段同上 |
server_time_ms |
服务端 UTC 毫秒 |
levels[].*_rewards 表示 in_room_rewards、top1_rewards、igniter_rewards 三个奖励池。客户端展示金币数量、奖励天数、聊天气泡、麦位特效时，直接读 resource_group.items。
送礼
地址：POST /api/v1/rooms/gift/send
参数：
| 参数 | 必填 | 说明 |
|---|---|---|
room_id |
是 | 房间 ID |
command_id |
是 | 客户端本次送礼幂等 ID |
target_type |
否 | 默认 user |
target_user_id |
否 | 单收礼用户 ID |
target_user_ids |
否 | 多收礼用户 ID |
gift_id |
是 | 礼物 ID |
gift_count |
是 | 礼物数量 |
pool_id |
否 | 幸运礼物奖池 ID |
返回值：
| 字段 | 说明 |
|---|---|
result |
命令提交结果 |
billing_receipt_id |
钱包扣费回执 |
room_heat |
最新房间热度 |
gift_rank |
最新房间礼物榜 |
rocket |
送礼后的火箭状态，字段同 state |
lucky_gift |
本次送礼聚合幸运礼物结果 |
lucky_gifts |
多目标送礼时每个目标的幸运礼物结果 |
后台配置
地址：GET /v1/admin/activity/room-rocket/config
参数：无
返回值：
| 字段 | 说明 |
|---|---|
enabled |
是否开启 |
fuelSource |
固定为 heat_value |
launchDelayMs |
点火后延迟发射毫秒 |
broadcastEnabled |
是否发区域或全局飘屏 |
broadcastScope |
region、global、none |
rewardStackPolicy |
allow_stack 或 priority_only |
levels |
5 级配置 |
giftFuelRules |
礼物燃料规则 |
地址：PUT /v1/admin/activity/room-rocket/config
参数：
| 参数 | 必填 | 说明 |
|---|---|---|
enabled |
是 | 是否开启 |
fuelSource |
是 | 固定传 heat_value |
launchDelayMs |
是 | 点火后延迟发射毫秒 |
broadcastEnabled |
是 | 是否发飘屏 |
broadcastScope |
是 | region、global、none |
broadcastDelayMs |
是 | 保留字段，当前点火后立即入 outbox |
rewardStackPolicy |
是 | allow_stack 或 priority_only |
levels |
是 | 必须 5 级 |
levels[].fuelThreshold |
是 | 等级阈值 |
levels[].coverUrl |
否 | 小封面图 |
levels[].animationUrl |
否 | 常态动效 |
levels[].launchAnimationUrl |
否 | 发射动效 |
levels[].launchedImageUrl |
否 | 发射后图 |
levels[].inRoomRewards |
否 | 在房奖励池 |
levels[].top1Rewards |
否 | 贡献第一奖励池 |
levels[].igniterRewards |
否 | 点火人奖励池 |
giftFuelRules[].giftId |
否 | 指定礼物 ID |
giftFuelRules[].giftTypeCode |
否 | 指定礼物类型 |
giftFuelRules[].multiplierPpm |
否 | 燃料倍率，1 倍为 1000000 |
giftFuelRules[].fixedFuel |
否 | 固定燃料 |
giftFuelRules[].excluded |
否 | 是否排除该礼物 |
返回值：同获取后台配置。
房间 IM
来源：腾讯云 IM 房间群。
基础字段：
| 字段 | 说明 |
|---|---|
TIMCustomElem.Ext |
room_system_message |
event_type |
事件类型 |
room_id |
房间 ID |
event_id |
消息 ID |
occurred_at_ms |
服务端 UTC 毫秒 |
room_rocket_fuel_changed
用途：刷新当前等级进度。
字段：
| 字段 | 说明 |
|---|---|
rocket_id |
当前累计火箭 ID |
level |
当前累计等级 |
added_fuel |
本次理论燃料 |
effective_added_fuel |
本次实际计入燃料 |
overflow_fuel |
本次作废燃料 |
current_fuel |
当前等级燃料 |
fuel_threshold |
当前等级阈值 |
status |
charging 或本次满阈值时的 ignited |
gift_id |
礼物 ID |
gift_count |
礼物数量 |
room_rocket_ignited
用途：当前等级满阈值，加入待发射队列；客户端立即把下一等级作为当前进度。
字段：
| 字段 | 说明 |
|---|---|
rocket_id |
待发射火箭 ID |
level |
待发射等级 |
rocket_level |
同 level |
room_short_id |
房间短号 |
rocket_cover_url |
小封面图 |
current_fuel |
满阈值燃料 |
fuel_threshold |
满阈值 |
ignited_at_ms |
点火时间 |
launch_at_ms |
预计发射时间 |
reset_at_ms |
UTC 日重置时间 |
top1_user_id |
点火时贡献第一 |
igniter_user_id |
点火人 |
room_rocket_launched
用途：火箭已到点发射，客户端播放发射表现。
字段：
| 字段 | 说明 |
|---|---|
rocket_id |
已发射火箭 ID |
level |
已发射等级 |
next_level |
当前正在累计等级 |
launched_at_ms |
发射时间 |
top1_user_id |
贡献第一 |
igniter_user_id |
点火人 |
rewards_json |
奖励摘要 |
区域或全局飘屏 IM
来源：腾讯云 IM 区域群或全局群。
基础字段：
| 字段 | 说明 |
|---|---|
TIMCustomElem.Ext |
im_broadcast |
TIMCustomElem.Desc |
room_rocket |
消息体：
| 字段 | 说明 |
|---|---|
broadcast_type |
room_rocket |
scope |
region 或 global |
room_id |
房间 ID |
room_short_id |
房间短号 |
rocket_id |
待发射火箭 ID |
rocket_level |
火箭等级 |
rocket_cover_url |
小封面图 |
launch_at_ms |
预计发射时间 |
igniter.user_id |
点火人用户 ID |
igniter.short_id |
点火人短 ID |
igniter.nickname |
点火人昵称 |
igniter.avatar |
点火人头像 |
奖励房间 IM
来源：腾讯云 IM 房间群。
基础字段：
| 字段 | 说明 |
|---|---|
TIMCustomElem.Ext |
im_broadcast |
TIMCustomElem.Desc |
room_rocket_reward_granted |
消息体：
| 字段 | 说明 |
|---|---|
broadcast_type |
room_rocket_reward_granted |
scope |
room |
room_id |
房间 ID |
rocket_id |
已发射火箭 ID |
rocket_level |
已发射等级 |
rewards |
本次所有获得奖励的人 |
rewards[].reward_role |
in_room、top1、igniter |
rewards[].user.user_id |
用户 ID |
rewards[].user.short_id |
用户短 ID |
rewards[].user.nickname |
用户昵称 |
rewards[].user.avatar |
用户头像 |
rewards[].resource_group_id |
资源组 ID |
rewards[].display_name |
奖励展示名 |
rewards[].icon_url |
奖励图标 |
rewards[].grant_id |
发奖回执 |
rewards[].status |
发奖状态 |
奖励 IM 用于通知本次哪些人中奖。top1 和点火人命中后会发完整配置池，同一用户可能同时收到多条 top1、igniter 和 1 条在房随机奖励。需要渲染金币数量、奖励天数、聊天气泡或麦位特效素材时，收到 IM 后调用 GET /api/v1/rooms/{room_id}/rocket，读取 state.last_rewards[].resource_group。
客户端处理
- 进房先调
GET /api/v1/rooms/{room_id}/rocket。 - 送礼成功优先用返回的
rocket刷新状态。 - 收到
room_rocket_fuel_changed刷新进度。 - 收到
room_rocket_ignited把该火箭加入待发射队列，并显示下一等级当前进度。 - 收到
room_rocket_launched播放发射表现。 - 收到
room_rocket_reward_granted展示本次所有中奖人和奖励。 - 如果 IM 丢失或乱序，用 GET 接口兜底。
- 不要用普通
room_gift_sent自行推算火箭燃料。
高频和延迟处理
- 送礼只同步写 Room Cell 状态和 room outbox，不同步请求腾讯 IM。
- 房间进度 IM 走 room outbox 补偿投递，失败会重试。
- 点火后延迟发射通过 RocketMQ delayed wakeup 唤醒；到点后 room-service 重新校验
rocket_id、level、launch_at_ms、UTC 重置边界。 - 奖励 IM 一次性包含所有中奖人，避免按用户逐条发 IM。