房间状态同步
「房间状态同步」是实时音视频产品提供的一项服务端回调服务,具体提供以下能力:
- 将音视频房间状态变化按照指定的时间间隔通知您的 App 服务器。
- 将呼叫双方、会议成员或直播房间中主播角色用户触发的事件通知您的 App 服务器。具体事件可参见下文的 event 字段(房间事件类型)。
注意
直播模式房间中观众角色的操作事件不会触发事件回调。
开通服务
您可以前往音视频通话页面,配置房间状态同步回调地址。注意回调地址必须是公网可访问的 URL。具体步骤如下:
-
确认当前 App Key 已开通音视频服务。如果您拥有多个应用,注意先选择应用名称。每个应用都提供用于隔离生产和开发环境的两套独立 App Key / Secret。应用时,请注意选择正确的环境(开发 / 生产)。
如果您尚未向融云申请应用上线,仅可使用开发环境。
-
如果已处于音视频通话页面,可下拉页面,找到服务配置,切换到基本设置,并填写房间状态同步回调地址。
回调地址示例:
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 对象:
名称 | 类型 | 说明 |
---|---|---|
appKey | String | 当前在使用的 App Key。 |
roomId | String | 当前的音视频房间 ID,即客户端 SDK 加入/创建音视频房间时传入的房间 ID。 |
sessionId | String | 当前音视频房间的唯一标识,由音视频服务端生成。 |
userId | String | 当前事件的用户 ID。 |
event | Number | 事件类型,与房间模式有关。详细说明请参见下文房间事件类型。 |
exitType | Number | 在 event 字段为 12 时,exitType 表示呼叫双方(主叫、被叫)、会议成员或主播退出房间的原因。1:主动离开房间; 2:被踢出房间; 3:断网超时被移出房间(如果融云服务端在客户端用户离线后 1 分钟之内未收到客户端的心跳信令,则将该用户踢出房间); 4:多端登陆时被踢。 在 event 字段不为 12 时,exitType 默认为 0。 |
timestamp | Number | 当前事件发生的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数。 |
extra | Object | 业务侧为当前房间设置的自定义房间属性。 |
data | Object | SDK 内部为当前房间设置的房间属性。 |
audience | Array | 仅在同步房间内瞬时状态信息时(event 字段为 1),回调中包含观众(audience )参数。观众的用户 ID 列表,按照加入时间排序得前 500 名。 |
durationTime | Number | event 字段为 12 时,durationTime 表示该会议成员或主播单次房间进出 累计时长(毫秒)。event 字段为 3 时,durationTime 表示房间总时长(毫秒)。 |
members | Array | 用户资源信息,即呼叫双方(主叫、被叫)、会议成员或主播发布的所有资源的信息。event 字段为 1 时,members 包含全量用户资源信息列表。event 字段为其他事件时,members 只包含对应事件中增量的用户资源信息。如 user1 资源发布,那 members 里的信息只有 user1 的资源信息。 |
members[i].userId | String | 用户 ID。 |
members[i].joinTime | Number | 对应用户加入房间的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数。 |
members[i].data | Object | 用户发布的资源信息。 |
members[i].data.role | String | 一对一通话中的主叫、被叫身份,仅适用于使用音视频呼叫 SDK(CallLib SDK/CallPlus SDK/CallKit)发起的一对一通话。RC_CallInvter 表示用户身份为主叫。RC_CallInvitee 表示用户身份为被叫。 |
members[i].data.uris | Array | 用户资源信息列表,详情见下面说明。 |
members[i].data.uris[i].mediaType | Number | 音视频资源的类型。0: 音频。1: 视频 |
members[i].data.uris[i].msid | String | 音视频资源的 Stream ID。 |
members[i].data.uris[i].uri | String | 音视频资源的全网唯一 URI。您不需要关心其字符串构成。 |
members[i].data.uris[i].tag | String | 客户端在发布资源时指定的标签信息,用于标识不同的流。默认的音视频 Tag 为 RongCloudRTC 。 |
members[i].data.uris[i].state | Number | 音视频资源的状态。0: 关闭。1: 开启。 |
members[i].extra | Object | 由客户端 SDK 为当前用户设置的人员属性。 |
event 字段(房间事件类型)
房间事件类型(event
字段)列表:
-
event 1:同步房间内瞬时的全量状态信息。同步周期默认为 120 秒,可以在 15 秒到 600 秒范围内选择。
-
event 2:房间创建。
-
event 3:房间销毁。
-
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 分钟同步。