跳到主要内容

房间状态同步

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

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

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

开通服务​

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

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

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

  1. 如果已处于音视频通话页面，直接填写房间状态同步回调地址。

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

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

    • 配置后 15 分钟后生效。

配置完成后，您的 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 示例：

    HTTP
    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 示例：

    HTTP
    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 分钟后会继续发送回调请求。
最后于 更新