跳到主要内容

房间状态同步

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

  • 将音视频房间状态变化按照指定的时间间隔通知您的 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事件类型,与房间模式有关。详细说明请参见下文房间事件类型
exitTypeNumberevent 字段为 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 分钟同步。