跳到主要内容

房间状态同步

「房间状态同步」是实时音视频产品提供的一项服务端回调服务，具体提供以下能力：

  • 将音视频房间状态变化按照指定的时间间隔通知您的 App 服务器。
  • 将呼叫双方、会议成员或直播房间中主播角色用户触发的事件通知您的 App 服务器。具体事件可参见下文的 event 字段（房间事件类型）。

注意

直播模式房间中观众角色的操作事件不会触发事件回调。

开通服务​

您可以前往音视频通话页面，配置房间状态同步回调地址。注意回调地址必须是公网可访问的 URL。具体步骤如下：

  1. 确认当前 App Key 已开通音视频服务。如果您拥有多个应用，注意先选择应用名称。每个应用都提供用于隔离生产和开发环境的两套独立 App Key / Secret。应用时，请注意选择正确的环境（开发 / 生产）。

    如果您尚未向融云申请应用上线，仅可使用开发环境。

  2. 如果已处于音视频通话页面，可下拉页面，找到服务配置，切换到基本设置，并填写房间状态同步回调地址。

    回调地址示例：http(s)://your.app.server/any-url-path

    如果需要选择版本，请选择 1.1 （1.0 版本已不再维护）。

    配置后 30 分钟后生效。

配置完成后，您的 App 内所有音视频房间的任何状态变更，均会通过 HTTP 请求，实时回调您的服务器，如：音视频房间的创建、销毁、用户（不含观众角色）的加入与退出、发布音频或视频资源。

回调方法​

POST：<your-receiving-server-url>

数据格式：application/json

回调地址 <your-receiving-server-url> 是您在控制台为当前 App Key 和服务所配置的回调接收地址。请务必配置可正常访问的回调接收地址。如果您的网络有 IP 访问限制，请务必配置 IP 白名单，否则无法正常接收服务端回调。

为了验证数据有效性并确保调用者为融云 Server，每个请求前添加数据签名。回调签名规则详见服务端回调。

回调正文参数​

该回调服务的 HTTP 请求正文数据格式为 application/json，包含具有以下结构的 JSON 对象：

名称类型说明
appKeyString当前在使用的 App Key。
roomIdString当前的音视频房间 ID，即客户端 SDK 加入/创建音视频房间时传入的房间 ID。
sessionIdString当前音视频房间的唯一标识，由音视频服务端生成。
userIdString当前事件的用户 ID。
eventNumber事件类型，与房间模式有关。详细说明请参见下文房间事件类型。
exitTypeNumber在 event 字段为 12 时，exitType 表示呼叫双方（主叫、被叫）、会议成员或主播退出房间的原因。

1：主动离开房间；
2：被踢出房间；
3：断网超时被移出房间（如果融云服务端在客户端用户离线后 1 分钟之内未收到客户端的心跳信令，则将该用户踢出房间）；
4：多端登陆时被踢。

在 event 字段不为 12 时，exitType 默认为 0。

timestampNumber当前事件发生的时间戳，从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数。
extraObject业务侧为当前房间设置的自定义房间属性。
dataObjectSDK 内部为当前房间设置的房间属性。
audienceArray仅在同步房间内瞬时状态信息时（event 字段为 1），回调中包含观众（audience）参数。

观众的用户 ID 列表，按照加入时间排序得前 500 名。
durationTimeNumberevent 字段为 12 时，durationTime 表示该会议成员或主播单次房间进出累计时长（毫秒）。

event 字段为 3 时，durationTime 表示房间总时长（毫秒）。
membersArray用户资源信息，即呼叫双方（主叫、被叫）、会议成员或主播发布的所有资源的信息。

event 字段为 1 时，members 包含全量用户资源信息列表。

event 字段为其他事件时，members 只包含对应事件中增量的用户资源信息。如 user1 资源发布，那 members 里的信息只有 user1 的资源信息。
members[i].userIdString用户 ID。
members[i].joinTimeNumber对应用户加入房间的时间戳，从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数。
members[i].dataObject用户发布的资源信息。
members[i].data.roleString一对一通话中的主叫、被叫身份，仅适用于使用音视频呼叫 SDK（CallLib SDK/CallPlus SDK/CallKit）发起的一对一通话。RC_CallInvter 表示用户身份为主叫。RC_CallInvitee 表示用户身份为被叫。
members[i].data.urisArray用户资源信息列表，详情见下面说明。
members[i].data.uris[i].mediaTypeNumber音视频资源的类型。0: 音频。1: 视频
members[i].data.uris[i].msidString音视频资源的 Stream ID。
members[i].data.uris[i].uriString音视频资源的全网唯一 URI。您不需要关心其字符串构成。
members[i].data.uris[i].tagString客户端在发布资源时指定的标签信息，用于标识不同的流。默认的音视频 Tag 为 RongCloudRTC。
members[i].data.uris[i].stateNumber音视频资源的状态。0: 关闭。1: 开启。
members[i].extraObject由客户端 SDK 为当前用户设置的人员属性。

event 字段（房间事件类型）​

房间事件类型（event 字段）列表：

  • event 1：同步房间内瞬时的全量状态信息。同步周期默认为 120 秒，可以在 15 秒到 600 秒范围内选择。

  • event 2：房间创建。

  • event 3：房间销毁。

    • 音视频房间存在自动销毁机制。自动销毁时会触发该事件。自动销毁的触发时机与房间模式有关，详见音视频房间销毁机制。
    • 通过服务端 API 直接销毁房间，触发该事件。详见主动销毁房间。

  • event 4：房间属性有变更。

  • event 5：全部房间成员（非直播模式）或全部主播（直播模式）已离开房间。

    • 对于直播模式的房间，所有主播均已离开房间时触发 event 5。此时房间内如果仍有观众，则房间不会自动销毁。
    • 对于会议模式、呼叫模式的房间，房间内最后一位成员离开时触发 event 5。此时音视频房间已无任何人员，触发自动销毁。

  • event 11：成员加入。

  • event 12：成员退出。服务端同时会通知退出的具体原因，可参见上表中的 exitType 字段。

  • event 13：房间中人员属性有变更。

  • event 14：邀请连麦 PK。仅适用于直播模式的音视频房间。

  • event 15：取消连麦 PK。仅适用于直播模式的音视频房间。

  • event 16：接受邀请连麦 PK。仅适用于直播模式的音视频房间。

  • event 17：拒绝邀请连麦 PK。仅适用于直播模式的音视频房间。

  • event 18：结束连麦 PK。仅适用于直播模式的音视频房间。

  • event 20：数据或资源发生变动，如音视频流发布或取消、角色切换、修改自定义属性等。

  • event 22：用户离线。

    • 客户端 15 秒内没有发心跳包到融云服务端，则会被标记为离线用户，但此时该客户端用户依然在房间内；融云服务端会仅将用户离线的状态同步给 App 服务端，并不执行其他操作；

  • event 23：用户恢复在线状态。

    • 客户端用户被标记为离线后，如果用户重新加入房间，或在因断网超时被踢出房间之前恢复了心跳，此时服务端会标记用户为在线，并给 App server 同步该状态信息。

回调请求示例​

  • 事件类型（event）为 1 时的 Request 示例：

    POST /any-url-path HTTP/1.1
    Host: your.app.server
    Content-Type: application/json

    {
      "appKey":"appKey",
      "sessionId":"sessionId",
      "roomId":"roomId",
      "userId":"123",
      "event":1,
      "exitType":2,
      "timestamp":1586244141831,
      "extra":{
            "key":"value"
          },
      "data":{
        "key":"value"
      },
      "audience":[
        "1118445"
        ],
      "members":[
          {
            "userId":"123",
            "joinTime":1586244140932,
            "data":{
            "uris":[
            {
              "mediaType":0,
              "msid":"13811223344_h0fc_web_RongCloudRTC",
              "uri":"{\"clusterId\":\"rtc-data-dev-rtc40-15-bdcbj.rongcloud.net\",\"serverId\":\"172.24.151.15:9005\",\"resourceId\":\"13811223344_h0fc_web_RongCloudRTC_0\",\"connectionId\":\"AAY2NjM0NjMAFDEzODExMjIzMzQ0X2gwZmNfd2ViAAM0NDQA\",\"ssrc\":2750434140,\"serviceProvider\":\"awsnx\",\"userTimestamp\":1585043802893}",
              "tag":"RongCloudRTC",
              "state":1
            },
            {
              "mediaType":1,
              "msid":"13811223344_h0fc_web_RongCloudRTC",
              "uri":"{\"clusterId\":\"rtc-data-dev-rtc40-15-bdcbj.rongcloud.net\",\"serverId\":\"172.24.151.15:9005\",\"resourceId\":\"13811223344_h0fc_web_RongCloudRTC_1\",\"connectionId\":\"AAY2NjM0NjMAFDEzODExMjIzMzQ0X2gwZmNfd2ViAAM0NDQA\",\"ssrc\":1782111418,\"serviceProvider\":\"awsnx\",\"userTimestamp\":1585043802893}",
              "tag":"RongCloudRTC",
              "state":1
            }
          ]
        },
        "extra":{
          "key":"v"
          }
        }
      ]
    }

  • 事件类型（event）为 12 时的 Request 示例：

    POST /any-url-path HTTP/1.1
    Host: your.app.server
    Content-Type: application/json

    {
        "appKey":"appKey",
        "roomId":"5d959b9a-25c7-45bd-8a01-64107e2ce76d",
        "sessionId":"zUYTr6J6es9ggF3japy867",
        "userId":"d1830a0970729c2fb73bf4fc7563e220",
        "event":12,
        "exitType":1,
        "timestamp":1645495818536,
        "durationTime":54866
    }

响应回调请求​

注意

  • 只要有 HTTP 200 OK 成功响应，融云会认为状态已经同步。
  • 如果应答超时 5 秒，融云会再尝试推送 2 次，如果仍然失败，将不再同步此条状态。
  • 如短时间内有大面积超时，将暂时停止请求您的服务器，1 分钟后会继续发送回调请求。异常断网情况下的会延迟 5 分钟同步。
编辑此页
最后由 Gordon Zhu 于 更新