发送礼物

描述

调用此接口触发弹幕游戏内的送礼事件，会在弹幕游戏客户端产生相应的效果。

接口原型

• 请求方法：POST
• 请求地址：https://mini-game-api.zego.im/?Action=SendDanmakuGifts
• 传输协议：HTTPS
• 调用频率限制：20 次/秒（以房间为维度）

请求参数

以下请求参数列表仅列出了接口请求参数，公共参数列表请参考 调用方式 - 公共请求参数。

GiftList 参数说明：

GiftInfo 参数说明：

UserInfo 参数说明：

GiftId、Value 和 Num 的传入说明

Num（游戏效果份数）与 GiftID（礼物）和 Value（每份效果所需礼物份数）有关，且受具体游戏规则影响，详情请联系 ZEGO 技术支持。

例如：游戏 A 规定：

• “火箭”（礼物）的 GiftId 为 g1。
• 一次性发送 10 个 “火箭”，即可在游戏中召唤一个“小兵”（效果）。
• 一次性发送 66 个“火箭”，即可在游戏中召唤一个“大将”（效果）。

游戏过程中可能有以下几种情况：

• 当观众希望送出 20 个“火箭”在游戏中出两个小兵，则此时传入的 GiftInfo 数值为：

  Untitled

  "GiftInfo": {
      "GiftId": "g1",
      "Value": 10,
      "Num": 2
  }
  

  1

  Copied!

• 当观众希望送出 66 个火箭在游戏中出一个大将，则此时传入的数值为：

  Untitled

  "GiftInfo": {
      "GiftId": "g1",
      "Value": 66,
      "Num": 1
  }
  

  1

  Copied!

• 若开发者的数值与 ZEGO 技术支持约定的不符，则此时会返回错误信息，因为与约定的游戏规则不符。

  Untitled

  "GiftInfo": {
      "GiftId": "g1",
      "Value":30, // 30 不等于 10 或 66
      "Num": 1
  }
  

  1

  Copied!

请求示例

• 请求 URL

  Untitled

  https://mini-game-api.zego.im/?Action=SendDanmakuGifts
  &<公共请求参数>
  

  1

  Copied!

• 请求消息体

  Untitled

  {
    "RoomId": "room123",
    "MiniGameId": "TinyLoveWar",
    "GiftList": [
      {
        "UserInfo": {
          "UserId": "user1",
          "Nickname": "test1",
          "Avatar": "http://",
          "Sex": 1
        },
        "GiftInfo": {
          "GiftId": "g1",
          "Value": 5,
          "Num": 2
        },
        "Timestamp": 12312312,
        "ReceiverId":"anchor111",
        "MsgId":"445623452643416236"
      }
    ]
  }
  

  1

  Copied!

响应参数

送礼失败分为两种情况：

• 错误码 code != 0，则全部礼物赠送失败，MsgId 不会被记录，可直接重试，无需重新生成 MsgId。
• 错误码 code == 0，则礼物请求全部消费成功；但可能存在部分礼物赠送成功、部分礼物赠送失败，具体礼物是否成功以及失败原因见响应体中 Result 参数。若需对赠送失败的礼物重新赠送，则需重新生成 MsgId。

响应示例

{
    "Code": 0,
    "Message": "succeed",
    "RequestId": "abcd123",
    "Data": {
        "Results": [
          {
            "Result": 0,
            "Msg": "success",
            "MsgId":"445623452643416236"
          }
        ]
    }
}

返回码

以下仅列出了接口业务逻辑相关的返回码，完整返回码请参考 全局返回码。

Result 处理结果码