移动端云渲染开播弹幕玩法
本文介绍如何在移动端设备上使用云渲染开播弹幕玩法。
前提条件
主播在移动端开播弹幕玩法前，请确保：
- 一个有效的声网账号以及声网项目。请参考开通服务从声网控制台获得以下信息：
- App ID：声网随机生成的字符串，用于识别你的项目。
- 客户 ID 和密钥：调用弹幕玩法 RESTful API 所需的 Key 和 Secret。
- 临时 Token：Token 也称为动态密钥，用于在加入 RTC 频道时对用户鉴权。临时 Token 的有效期为 24 小时。在生产环境中，你需要参考使用 Token 鉴权在你的 App 服务端生成 Token。
- 已联系销售开通弹幕玩法服务。
- 你已在 App 中实现了基本的实时音视频功能，且 App 已获取相关设备的使用权限。请参考实现音视频互动。
实现流程
移动端云渲染开播弹幕玩法的流程如下图所示：
声网推荐你在阅读本节的同时在新标签页打开弹幕玩法服务端 API 专区以获得佳的快速开始体验：
- 详细的 API 参数说明、调用示例和调用注意事项
- 使用专区右侧的“Send API Request”功能快捷调用 RESTful API
- 一键生成和复制不同语言的 RESTful API 调用代码
获取云游戏
调用获取云游戏列表获取想开播的游戏编号 (game_id)，并联系销售授权该游戏。以 cURL 为例：
curl --location --request GET 'https://{domain}/v2/projects/{appid}/cloud-bullet-game/api/live-data/games?page_num=1&page_size=10' \
--header 'Accept: application/json' \
--header 'Authorization: agora token={Your_RTC_Token}' \
--header 'Content-Type: application/json'
之后使用 game_id 调用获取云游戏详情以获取游戏支持的礼物列表和弹幕指令等信息。以 cURL 为例：
curl --location --request GET 'https://{domain}/v2/projects/{appid}/cloud-bullet-game/api/live-data/games/pkzb' \
--header 'Accept: application/json' \
--header 'Authorization: agora token={Your_RTC_Token}' \
--header 'Content-Type: application/json'
完成礼物映射
每个弹幕玩法提供了不同价位的付费礼物，你需要分别做不同的礼物映射。
每个游戏的礼物列表，可以从获取云游戏详情获取。因礼物涉及计量计费，在礼物消息 (live_gift) 推送协议中，gift_id、gift_num、gfit_value，需要严格遵守礼物表中的对应关系。以胖可争霸为例，支持的礼物列表如下：
gift_id | gift_price | 礼物说明 |
|---|---|---|
| 1001 | 0.1 元 | 召唤大黄蜂 × 12 |
| 1002 | 5 元 | 召唤搬仓鼠 × 36 |
| 1003 | 10 元 | 召唤白猫警员 × 2 |
| 1004 | 20 元 | 召唤小墩墩 × 10 |
| 1005 | 29.9 元 | 召唤牛战士 × 76 |
| 1006 | 66.6 元 | 召唤精灵龙 × 2 |
-
映射
gift_id业务后台在把礼物 ID 在推送给声网前，需要映射成声网内建礼物 ID (
gift_id)，且礼物价格保持一致。你需要根据你的业务系统中的礼物价格，寻找游戏礼物列表中同样价格的礼物 ID。例如，当你的系统中有 0.1 元的礼物 ID 为custom_gift_id，当该礼物消息触发时，把custom_gift_id映射成1001。 -
计算
gift_value计算公式为
gift_value=gift_num×gift_price× 100。计算时，你需要需要把单位从元折算成分。 -
包装
payload参考推送直播间消息中的礼物
payload参数说明，将上面步骤获取的参数包装成payload，在后续直播间互动阶段发生送礼事件时，将正确的payload发送给声网云游戏服务平台。
开始直播
主播开启直播后，App 加入 RTC 频道并拉取游戏视频流，之后在业务后台（即 App 服务端）调用启动云游戏服务。以 cURL 为例：
curl --location --request POST 'https://{domain}/v2/projects/{appid}/cloud-bullet-game/api/live-data/games/{gameid}/mode/cloud/rooms/{roomid}:start' \
--header 'Accept: application/json' \
--header 'Authorization: agora token={Your_RTC_Token}' \
--header 'Content-Type: application/json' \
--data '{
"openid": "abcxxxxxxxxx321_testopenid",
"nickname": "Player",
"avatar_url": "http://127.0.0.1/xxxxx.jpg",
"rtc_config": {
"broadcast_uid": 2345,
"uid": 1234,
"token": "{Your_RTC_Token}",
"channel_name": "TESTCHANNEL",
"encryption": {
"mode": "AES_128_GCM2",
"secret": "encryptionKey",
"salt": "encryptionKdfSalt"
}
}
}'
推送直播间消息
根据直播间中获取到的礼物、评论和点赞消息，在业务后台调用推送直播间消息，将这些消息发送至声网云游戏服务平台。以 cURL 为例：
# 以推送礼物消息为例
curl --location --request POST 'https://{domain}/v2/projects/{appid}/bullet-game/api/live-data/games/{gameid}/rooms/${roomid}/msgType/live_gift:push' \
--header 'Accept: application/json' \
--header 'Authorization: agora token={Your_RTC_Token}' \
--header 'Content-Type: application/json' \
--data '[
{
"payload": {
"msg_id": "abcxxxxxxxxx321_12345678",
"openid": "abcxxxxxxxxx321_testopenid",
"gift_id": 10001,
"gift_num": 10,
"gift_value": 10000,
"avatar_url": "http://127.0.0.1/xxxxx.jpg",
"nickname": "Player",
"timestamp": 1699068964
},
}
]'
结束直播
主播下播后，调用关闭云游戏服务。以 cURL 为例：
curl --location --request POST 'https://{domain}/v2/projects/{appid}/cloud-bullet-game/api/live-data/games/{gameid}/mode/cloud/rooms/{roomid}:stop' \
--header 'Accept: application/json' \
--header 'Authorization: agora token={Your_RTC_Token}' \
--header 'Content-Type: application/json' \
--data '{
"openid": "abcxxxxxxxxx321_testopenid",
"taskid": "cloud_game_task_id"
}'
参考信息
开发注意事项
- 协议字段中的
msg_id，roomid和openid需要在声网侧保持全局唯一，建议格式为<appid>_xxxx的方式。对于msg_id，由于同一时间可能存在多用户发送消息，可以通过自增保持唯一性。 roomid在主播侧暴露存在安全风险，建议每次开播生成的room为不重复的随机值。- 启动云游戏服务调用超时异常处理：
- 网络访问接口超时时间需要设置为 5～10 秒
- 网络超时异常后，需要用同样的参数重试调用接口。