接入前先准备四项内容

红鲸 Web SDK 适合将会议入会界面嵌入已有网站或 Web 业务系统。集成方引入红鲸服务提供的 JavaScript 文件，准备一个页面容器，再通过 window.meeting.join(options) 发起入会。

项目禁止匿名入会时，还需要由业务服务端提供用户 Token，不应在前端硬编码。Web SDK 提供已有会议界面和入会流程；需要完全自定义 Android 会议界面时，应使用 Android 无 UI SDK。

如何引入 Web SDK

4.2.0 及以后版本使用以下脚本路径。

<script src="https://meeting.example.com:8443/connect/static/js/sdk.4.0.0.bundle.js"></script>

meeting.example.com 是示例域名。实际项目需要替换为已部署的红鲸会议服务地址。

如何准备会议容器

<div id="redwhale-meeting" style="width:100%;height:100vh"></div>

容器必须有可用的宽度和高度。如果容器的高度为 0，会议界面已加载但用户无法看到。

如何手动启动入会页面

<script>
  const meetingContainer = document.getElementById('redwhale-meeting');

  window.meeting.join({
    serverUrl: 'https://meeting.example.com:8443',
    el: meetingContainer,
    roomId: '${ROOM_ID}',
    meetingType: 'video',
    isMicrophoneEnabled: true,
    isCameraEnabled: true,
    autoJoin: 0
  });
</script>

autoJoin: 0 会显示入会页面，由用户确认姓名、设备和会议凭据后入会。

Web SDK 常用入会参数

快速开始页只保留首次入会所需参数，完整参数请查看“入会参数参考”。

什么时候可以自动入会

只有在业务系统已经完成用户身份校验，并且能够安全提供会议 ID、用户名和入会凭据时，才应该使用自动入会。不要把固定密码或长期 Token 写入前端 JavaScript。

window.meeting.join({
  serverUrl: 'https://meeting.example.com:8443',
  el: meetingContainer,
  roomId: '${ROOM_ID}',
  userName: '演示用户',
  password: '${MEETING_PASSWORD}',
  autoJoin: 1,
  meetingType: 'video'
});

如何处理连接成功和失败

window.meeting.join({
  serverUrl: 'https://meeting.example.com:8443',
  el: meetingContainer,
  roomId: '${ROOM_ID}',
  connectSuccess: (data) => {
    console.log('会议连接已建立');
    // 在这里初始化项目所需的会议事件监听。
  },
  connectFail: (error) => {
    console.error('会议连接失败', error);
    // 不要将 Token、密码或完整请求头写入日志。
  }
});

如何验证 Web SDK 接入结果

1. 页面能够成功加载 Web SDK 脚本。
2. window.meeting 存在，并且 window.meeting.join 是可调用方法。
3. 页面能显示会议入会界面。
4. 浏览器能够正常申请摄像头和麦克风权限。
5. 使用有效会议 ID 可以加入会议。
6. 连接失败时，页面能给出明确提示，不会泄露凭据。

常见问题

页面已加载但会议界面不可见

先检查会议容器是否有可用高度，再检查 SDK 脚本是否加载成功、el 是否指向正确的 DOM 元素。

浏览器无法打开摄像头或麦克风

检查页面是否使用 HTTPS，浏览器是否已授权设备访问，以及设备是否被其他程序占用。

能否把 Token 直接写在网页代码中

不应在可公开读取的前端源码中硬编码长期 Token。项目应由后端根据已验证的用户身份提供有效期和使用范围受限的入会凭据。

下一步

• 查看 Server API 调用准备
• 申请开发资料

Web SDK 加载完成后会挂载全局对象 window.meeting。调用 window.meeting.join(options) 可以显示加入会议界面，或使用会议参数自动入会。

基本调用

window.meeting.join({
  serverUrl: 'https://meeting.example.com:8443',
  el: document.getElementById('meeting'),
  roomId: '会议号',
  meetingType: 'video',
  isMicrophoneEnabled: true,
  isCameraEnabled: false
})

基础参数

4.1.0 及以后版本不支持使用密文密码入会。网页中不要保存长期有效的登录 Token 或其他服务端凭据。

音视频与功能参数

自动入会

4.2.0 及以后版本支持 autoJoin。设置为 1 时，需要同时传入 roomId、password 和 userName。

window.meeting.join({
  serverUrl: 'https://meeting.example.com:8443',
  el: document.getElementById('meeting'),
  roomId: '会议号',
  password: '会议密码',
  userName: '参会人名称',
  autoJoin: 1
})

回调参数

window.meeting.join({
  ...options,
  connectSuccess: ({ room, participants }) => {
    console.log('会议连接成功', room, participants)
  },
  connectFail: (error) => {
    console.error('会议连接失败', error)
  },
  endCallback: () => {
    console.log('已离开或结束会议')
  }
})

其他控制参数

参数检查

• roomId 来自实际会议，不在公开代码中写入真实会议号。
• serverUrl 与脚本地址使用同一个项目环境。
• 跨域部署时已配置允许的页面来源。
• 自动入会参数齐全，密码和 Token 不写入日志。
• 使用前检查当前服务端版本是否支持相应选项。

4.3.1 及以后版本可以通过 connectSuccess 取得 room、本地参会人和远端参会人，进而监听成员及媒体轨道事件。

取得房间与参会人

const options = {
  serverUrl: 'https://meeting.example.com:8443',
  el: document.getElementById('meeting'),
  roomId: '会议号',
  connectSuccess: (data) => {
    const room = data.room
    const localParticipant = room.localParticipant
    const participants = data.participants || []

    console.log(localParticipant.name)
    console.log(localParticipant.identity)
  }
}

window.meeting.join(options)

读取本地设备状态

const microphoneEnabled = localParticipant.isMicrophoneEnabled
const cameraEnabled = localParticipant.isCameraEnabled

可以监听本地轨道的静音和恢复事件：

localParticipant.addListener('trackMuted', (track) => {
  console.log('轨道已静音', track)
})

localParticipant.addListener('trackUnmuted', (track) => {
  console.log('轨道已恢复', track)
})

渲染视频轨道

const renderTrack = (track) => {
  if (!track.videoTrack) return

  const video = document.createElement('video')
  video.autoplay = true
  video.playsInline = true
  track.videoTrack.attach(video)
  document.getElementById('remote-videos').appendChild(video)
}

页面销毁、成员离开或轨道取消发布时，应移除对应元素并注销监听，避免残留音视频播放和内存占用。

监听成员加入

room.addListener('participantConnected', (participant) => {
  console.log('用户加入', participant.name, participant.identity)

  participant.addListener('trackUnmuted', renderTrack)
  participant.addListener('trackMuted', renderTrack)
  participant.addListener('trackPublished', renderTrack)
  participant.addListener('trackUnpublished', renderTrack)
  participant.addListener('trackSubscriptionStatusChanged', renderTrack)
})

监听成员离开

room.addListener('participantDisconnected', (participant) => {
  console.log('用户离开', participant.name, participant.identity)

  participant.removeListener('trackMuted', renderTrack)
  participant.removeListener('trackUnmuted', renderTrack)
  participant.removeListener('trackPublished', renderTrack)
  participant.removeListener('trackUnpublished', renderTrack)
  participant.removeListener('trackSubscriptionStatusChanged', renderTrack)
})

监听房间断开

room.addListener('disconnected', () => {
  console.log('会议连接已断开')
})

为已有参会人注册事件

连接成功时，房间内可能已经存在其他参会人。除监听后续加入事件外，还应遍历 data.participants 注册轨道监听。

participants.forEach((participant) => {
  participant.addListener('trackUnmuted', renderTrack)
  participant.addListener('trackMuted', renderTrack)
  participant.addListener('trackPublished', renderTrack)
  participant.addListener('trackUnpublished', renderTrack)
  participant.addListener('trackSubscriptionStatusChanged', renderTrack)
})

事件处理建议

• 进入会议后先处理已有参会人，再监听新成员加入。
• 使用 identity 关联业务用户，不以显示名称作为唯一标识。
• 每个监听器保留函数引用，便于准确注销。
• 轨道取消发布、成员离开和房间断开时同步清理 UI。
• 自动播放受浏览器策略影响时，引导用户完成一次页面交互。

红鲸 Android SDK 为无 UI 开发组件，应用需要自行实现会议界面和交互。接入前先根据服务端版本选择兼容的 AAR，再完成 Gradle、依赖和权限配置。

如何选择 Android SDK 版本

SDK 与 Demo 不公开直接下载。申请时需要提供服务端版本、目标 CPU 架构、Android 构建环境和计划接入场景，以便核对兼容线和资料范围。

当前已发布的兼容线

如何添加 AAR

在项目根目录创建本地 SDK 模块，例如 rwsdk，将申请获得的 AAR 放入该目录。以下示例文件名需要替换为实际版本。

// settings.gradle
include ':rwsdk'

// app/build.gradle
dependencies {
    api project(path: ':rwsdk')
}

// rwsdk/build.gradle
configurations.maybeCreate("default")
artifacts.add("default", file("native-sdk-v4.2.0.04-server420.aar"))

Android 构建环境

宿主项目仍需结合自身依赖树检查版本冲突，尤其是 Kotlin、协程、WebRTC、CameraX、OkHttp 和 Dagger。

需要声明哪些权限

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />

除清单声明外，Android 6.0 及以上还需要在运行时申请摄像头和麦克风权限。只有在用户发起相应功能时申请权限，并处理拒绝和永久拒绝状态。

下一步

• 初始化 Android SDK 并加入会议
• 申请 Android AAR 与 Demo

红鲸 Android SDK 不提供固定会议界面。应用完成 SDK 初始化和身份验证后，可创建或加入会议，并围绕 Room 对象实现音视频、参与者和界面交互。

接入顺序

1. 获取与服务端兼容的 AAR 并完成依赖配置。
2. 配置会议主机地址并初始化 SDK。
3. 使用账号或会议凭据登录。
4. 创建会议或获取已有会议的连接信息。
5. 创建 Room 对象并连接媒体服务。
6. 订阅房间状态、参与者和音视频轨道，实现自定义 UI。

配置服务地址并初始化

serverHost 必须在 init 之前设置。示例地址需要替换为项目提供的实际 HTTPS 地址。

Rwrtc.serverHost = "https://meeting.example.com"
Rwrtc.init(applicationContext)

生产环境不要在源码中硬编码账号、密码、Token 或 SecretKey。

登录

grantType 使用 password 时按账号密码登录，使用 meeting 时按会议号和会议密码登录。

Rwrtc.login(
    loginName = loginName,
    verification = verification,
    grantType = "password",
    successCallback = {
        // 登录成功
    },
    errorCallback = { error ->
        error.printStackTrace()
    }
)

创建会议

Rwrtc.startMeeting(
    roomName = "项目沟通会",
    userId = "demo-user-001",
    userName = "演示用户",
    disableRecordMerge = false,
    successCallback = { roomInfo ->
        val roomId = roomInfo.roomId
    },
    errorCallback = { error ->
        error.printStackTrace()
    }
)

加入会议

Rwrtc.joinMeeting(
    roomId = roomId,
    userId = "demo-user-001",
    userName = "演示用户",
    hidden = false,
    successCallback = { joinInfo ->
        val token = joinInfo.token
        val meetingUrl = joinInfo.meeturl
    },
    errorCallback = { error ->
        error.printStackTrace()
    }
)

创建并连接 Room

Room 是音视频通话的核心对象。使用 joinMeeting 返回的媒体服务地址和 Token 建立连接。

val room = Rwrtc.create(
    appContext = application,
    options = RoomOptions(
        adaptiveStream = true,
        dynacast = true,
        hidden = false
    )
)

lifecycleScope.launch {
    room.connect(
        url = meetingUrl,
        token = token
    )
}

离开并释放资源

离开页面或结束业务流程时，应断开房间并释放 SDK 资源，避免摄像头、麦克风或渲染对象继续占用。

room.disconnect()
room.release()

接入检查

• 服务端版本与 AAR 兼容线一致。
• 摄像头、麦克风和网络权限已正确处理。
• serverHost 使用项目实际地址并在初始化前赋值。
• Token 只在受控流程中传递，不写入日志。
• 页面退出时停止本地轨道、移除渲染器并释放 Room。

本页说明 SDK 初始化前的公共配置，以及问题定位时可启用的日志能力。日志中不得输出账号、密码、Token 或业务敏感数据。

初始化顺序

serverHost 必须在 init 之前设置。建议在 Application 初始化阶段完成一次配置。

Rwrtc.serverHost = "https://meeting.example.com"
Rwrtc.loggingLevel = LoggingLevel.OFF
Rwrtc.init(applicationContext)

控制日志级别

loggingLevel 控制 SDK 日志级别，默认关闭。问题诊断结束后应恢复为适合生产环境的级别。

Rwrtc.loggingLevel = LoggingLevel.VERBOSE

底层 WebRTC 日志信息量较大，只建议在定位媒体连接问题时短时启用。

Rwrtc.enableWebRTCLogging = true

启用文件日志

日志目录必须是宿主应用可写目录。应用应控制日志保留周期，并在对外提供日志前完成敏感信息检查。

Rwrtc.enableFileLogging(
    logDirPath = File(filesDir, "rwrtc-logs").absolutePath,
    loggingLevel = LoggingLevel.VERBOSE,
    maxRetainedFiles = 5
)

关闭 SDK 内置文件日志：

Rwrtc.disableFileLogging()

接入自定义日志器

需要接入应用已有日志体系时，可实现 ILogger 并赋值给 Rwrtc.logger。生产环境应对日志内容进行分级、脱敏和访问控制。

RK3588 H.264 兼容配置

仅在定制设备存在 H.264 硬件编码尺寸限制时使用，普通设备不需要设置。配置应在创建房间和发布视频轨道前完成。

Rwrtc.rk3588H264WorkaroundConfig = Rk3588H264WorkaroundConfig(
    maxWidth = 1920,
    maxHeight = 1080
)

可用限制字段包括 maxWidth、maxHeight、maxLongEdge 和 maxPixels；未设置的字段表示不限制。

上线检查

• serverHost 使用项目实际 HTTPS 地址。
• 生产环境未开启不必要的详细日志。
• 日志目录可写且已设置保留数量。
• 日志不记录 Token、密码和用户隐私数据。
• 设备兼容参数经过目标终端实测。

会议业务接口负责取得会议号、媒体服务地址和连接 Token；取得连接信息后，再使用 Room 建立实时音视频连接。

创建会议

Rwrtc.startMeeting(
    roomName = "项目沟通会",
    userId = userId,
    userName = userName,
    disableRecordMerge = false,
    successCallback = { roomInfo ->
        val roomId = roomInfo.roomId
    },
    errorCallback = { it.printStackTrace() }
)

disableRecordMerge 用于控制录制合成方式，具体配置应与项目交付方案保持一致。

加入会议

Rwrtc.joinMeeting(
    roomId = roomId,
    userId = userId,
    userName = userName,
    hidden = false,
    successCallback = { info ->
        val token = info.token
        val mediaUrl = info.meeturl
    },
    errorCallback = { it.printStackTrace() }
)

hidden 表示是否以隐藏身份入会。普通参会端通常设置为 false。

离开或结束会议

普通参会人离开会议时调用：

Rwrtc.leaveMeeting(roomId)

结束会议会影响房间内所有参会人，只应在主持人权限和业务确认完成后调用：

Rwrtc.endMeeting(roomId)

结束会议前应增加二次确认，并处理成功与失败回调。

检查录制能力

调用录制接口前先确认当前服务端是否支持录制。

Rwrtc.getMeetingCapability(
    successCallback = { capability ->
        val supported = capability.recordSupport
    },
    errorCallback = { it.printStackTrace() }
)

开始与停止云端录制

Rwrtc.startRecord(
    roomId = roomId,
    userId = userId,
    successCallback = { recordInfo ->
        val recordId = recordInfo.recordId
    },
    errorCallback = { it.printStackTrace() }
)

Rwrtc.stopRecord(
    roomId = roomId,
    userId = userId,
    successCallback = { /* 已停止 */ },
    errorCallback = { it.printStackTrace() }
)

只有具备相应权限的角色才能控制云端录制。应用界面应根据能力检查、用户角色和当前录制状态决定是否显示操作入口。

业务检查

• 创建、加入、离开和结束会议分别处理成功与失败状态。
• 结束会议具有明确权限判断和二次确认。
• 录制按钮以服务端能力和用户角色为准。
• 不在日志、埋点或界面错误信息中暴露连接 Token。

Room 是实时音视频能力的核心对象。业务层应把创建、连接、状态监听、断开和资源释放作为一个完整生命周期管理。

创建 Room

val room = Rwrtc.create(
    appContext = application,
    options = RoomOptions(
        adaptiveStream = true,
        dynacast = true,
        hidden = false
    )
)

连接房间

url 和 token 来自加入会议接口。connect 是挂起方法，应在协程中调用并处理异常。

lifecycleScope.launch {
    try {
        room.connect(url = mediaUrl, token = token)
    } catch (error: Throwable) {
        error.printStackTrace()
    }
}

ConnectOptions 可控制自动订阅、ICE 服务器、RTC 配置，以及连接后是否立即发布音频或视频。未明确需要时不要随意覆盖协议相关参数。

监听连接状态

房间状态包括 CONNECTING、CONNECTED、RECONNECTING 和 DISCONNECTED。界面应根据状态显示连接中、重连中或已断开，而不是只依赖一次连接回调。

lifecycleScope.launch {
    room::state.flow.collect { state ->
        // 根据 state 更新界面
    }
}

读取房间数据

这些属性中的多项支持响应式数据流，界面应订阅变化，避免只读取初始化时的快照。

查找参会人

可使用 getParticipantBySid 或 getParticipantByIdentity 查找房间中的参会人。业务系统通常以 identity 对应用户 ID。

更新房间选项

room.setRoomOptions(options)

传入对象中的空值不会覆盖已有设置。运行中修改媒体参数前，应确认目标 SDK 版本支持对应能力。

断开与释放

room.disconnect()
room.release()

disconnect 用于断开当前连接；release 会释放 Room 持有的全部资源。调用 release 后不能再次连接，重新入会必须创建新的 Room。

生命周期建议

• 页面进入时创建或取得 Room，离开业务流程时断开连接。
• 停止本地媒体、移除渲染器后再释放 Room。
• 重连状态下保留必要提示，避免重复创建多个 Room。
• Activity 或 Fragment 销毁时取消对应协程和监听。

本页介绍本地摄像头、麦克风、屏幕共享和自定义视频输入。运行时更新能力需使用与服务端兼容的 SDK 版本。

摄像头与麦克风

room.setCameraEnabled(true)
room.setMicrophoneEnabled(true)

关闭时分别传入 false。摄像头默认使用设备原生采集器。

仅需要本地静音而不停止轨道时，可使用：

room.setSpeakerMute(true)
room.setMicrophoneMute(true)

本地扬声器静音仍会接收远端音频数据；麦克风静音仍可能保持音频数据传输。需要控制数据订阅或发布时，应使用轨道级能力。

启动屏幕共享

应用应先通过 Android MediaProjection 流程取得用户授权，再将授权结果交给 SDK。

room.setScreenShareEnabled(
    enabled = true,
    mediaProjectionPermissionResultData = permissionData
)

停止屏幕共享：

room.setScreenShareEnabled(false)

配置屏幕共享参数

在 Rwrtc.create 时通过 RoomOptions 分别设置采集参数和发布参数：

val options = RoomOptions(
    screenShareCaptureDefaults = LocalVideoTrackOptions(
        isScreencast = true,
        captureParams = VideoCaptureParameter(1280, 720, 15)
    ),
    screenSharePublishDefaults = VideoTrackPublishDefaults(
        videoEncoding = VideoEncoding(
            maxBitrate = 1_000_000,
            maxFps = 15
        ),
        simulcast = false,
        videoCodec = VideoCodec.H264.codecName
    )
)

采集尺寸表示完整屏幕缩放后的目标输出尺寸，不是只截取屏幕的一部分。摄像头和屏幕共享使用两套独立参数。

运行时更新参数

room.updateCameraCaptureSettings(
    VideoCaptureParameter(640, 480, 15)
)

room.updateCameraEncodingSettings(
    VideoEncoding(maxBitrate = 800_000, maxFps = 15)
)

屏幕共享对应使用 updateScreenShareCaptureSettings 和 updateScreenShareEncodingSettings。

采集宽高必须为正偶数，帧率应大于 0 且不超过 120。自定义视频源不支持运行时更新采集参数。更新结果应检查 VideoSettingsUpdateResult，实际生效的采集规格可能与请求值略有差异。

自定义视频输入

只有项目使用外部摄像设备或自行采集视频帧时，才需要启用自定义视频输入。普通手机和平板直接使用默认摄像头采集即可。

room.setCameraEnabled(true, Track.CapturerType.CUSTOM)

room.inputCustomVideoDat(
    CustomVideoData(yuv, width, height, rotation)
)

自定义视频帧的格式、尺寸、方向和发送节奏必须与集成约定一致。

常见失败原因

参会人对象用于驱动成员列表、发言状态、网络质量、麦克风、摄像头和屏幕共享界面。相关属性会随会议状态变化，应采用响应式方式更新 UI。

参会人主要属性

网络质量包括 EXCELLENT、GOOD、POOR、UNKNOWN 和 LOST。界面不应把未知状态直接显示为网络故障。

判断媒体状态

val cameraEnabled = participant.isCameraEnabled()
val microphoneEnabled = participant.isMicrophoneEnabled()
val screenShareEnabled = participant.isScreenShareEnabled()

取得指定来源的轨道：

val publication = participant.getTrackPublication(Track.Source.CAMERA)
val videoTrack = publication?.track as? VideoTrack

可用来源包括 CAMERA、MICROPHONE、SCREEN_SHARE 和 UNKNOWN。

初始化视频渲染器

room.initVideoRenderer(
    viewRenderer = renderer,
    rendererEvents = object : RendererCommon.RendererEvents {
        override fun onFirstFrameRendered() {
            // 首帧已显示
        }

        override fun onFrameResolutionChanged(
            width: Int,
            height: Int,
            rotation: Int
        ) {
            // 更新画面布局
        }
    }
)

将视频轨道添加到渲染器：

videoTrack?.addRenderer(renderer)

页面退出或轨道切换时移除：

videoTrack?.removeRenderer(renderer)

设置镜像与缩放

renderer.setMirror(true)
renderer.setScalingType(
    RendererCommon.ScalingType.SCALE_ASPECT_FIT
)

SCALE_ASPECT_FIT 显示完整画面，可能出现黑边；SCALE_ASPECT_FILL 填满区域，可能裁剪内容；SCALE_ASPECT_BALANCED 在两者之间平衡。

切换本地摄像头

localVideoTrack.switchCamera(CameraPosition.FRONT)

切换音频输出设备

val handler = room.audioHandler as AudioSwitchHandler
val devices = handler.availableAudioDevices
handler.selectDevice(devices[index])

设备列表可能随蓝牙耳机或有线耳机接入发生变化，界面应动态刷新，并处理目标设备已离线的情况。

房间消息适合传递会议内的轻量交互信息。重要业务状态仍应由业务服务端保存和校验，不应只依赖实时消息。

发送文本消息

lifecycleScope.launch {
    room.sendTextMessage("会议即将开始")
}

发送自定义消息

lifecycleScope.launch {
    room.sendCustomMessage(customPayload)
}

自定义消息建议使用带版本号的 JSON 结构，并限制消息大小。不要在消息中传递密码、Token 或不必要的个人信息。

{
  "version": 1,
  "type": "raise_hand",
  "data": {
    "raised": true
  }
}

订阅消息

lifecycleScope.launch {
    room.subscribeMessage { participant, type, body ->
        val sender = participant?.name ?: "server"
        // 根据 type 校验并处理 body
    }
}

自己发送的消息不会在该订阅回调中再次触发。应用应自行更新本地发送状态，并处理消息解析失败或未知版本。

监听房间事件

lifecycleScope.launch {
    room.events.collect { event ->
        when (event) {
            is RoomEvent.ParticipantIdentitiesChanged -> {
                // 批量补充参会人名称和角色
            }
            else -> Unit
        }
    }
}

ParticipantIdentitiesChanged 携带当前房间参会人的用户 ID 集合。可通过 Rwrtc.getParticipantByUserIds 获取姓名、角色等业务信息，再更新房间内的参会人对象。

批量成员变化的处理

大量成员短时间内进入或离开时，事件可能高频触发。建议在 300 毫秒左右的时间窗口内聚合用户 ID，再批量查询，减少重复请求。

pendingUserIds
    .debounce(300L)
    .filter { it.isNotEmpty() }
    .collect { userIds ->
        fetchParticipantDetails(userIds.toList())
        pendingUserIds.value = emptySet()
    }

消息设计建议

• 为自定义消息定义 version、type 和 data。
• 接收端先校验类型和版本，再解析具体字段。
• 对重复消息设计幂等处理。
• 重要操作由服务端授权，不能仅凭客户端消息执行。
• 页面销毁时取消消息和事件协程。

首次调用前先准备三项信息

调用红鲸 Server API 前，调用方需要获取项目的 API 基础地址和具有对应权限的 Bearer Token。调用方的服务器还必须能够访问红鲸会议管理服务。

公开文档不展示 Token 在管理后台的获取步骤。实际 API 地址、端口、Token 和权限范围由项目管理员或交付人员提供。

组成完整 API 地址

各个 API 页面只列出具体路径，完整地址由项目的协议、域名或 IP、端口和接口路径组成。

https://api.example.com/<API_PATH>

例如，创建会议的接口路径是：

/mgr/api/createMeeting

使用项目的实际 API 基础地址替换 https://api.example.com。如果项目使用非默认端口，基础地址需要包含端口。

填写 Authorization 请求头

每个需要鉴权的 Server API 请求都应携带 Authorization 请求头。

Authorization: Bearer ${ACCESS_TOKEN}
Content-Type: application/json

${ACCESS_TOKEN} 是占位符。不要把 Token 写入网页前端、公开代码库、URL 查询参数或可被普通用户读取的日志。

Token 必须与调用模块的权限一致。如果 Token 未获授权访问会议、预约、录制或组织人员模块，对应接口会调用失败。

使用 JSON 请求体

红鲸 Server API 的请求体使用 JSON。发送请求时，需要使用 Content-Type: application/json 和 UTF-8 字符编码。

{
  "roomName": "项目演示会议",
  "hostInfo": {
    "userName": "演示主持人",
    "openId": "demo-host-001"
  }
}

示例中的姓名和 ID 是虚构数据。生产请求应使用业务系统中的实际用户标识，并遵守项目的个人信息处理要求。

判断调用是否成功

调用方应同时检查 HTTP 状态码和 JSON Body 中的业务错误码。HTTP 2xx 表示请求已被服务器处理，但业务是否成功仍应以返回结构为准。

成功返回示例：

{
  "code": 200,
  "data": {
    "roomId": "${ROOM_ID}"
  },
  "msg": "success"
}

错误返回的字段结构应在正式 API 参考页统一展示。业务代码不应仅根据 msg 文字判断结果，应优先根据状态码和结构化错误码处理。

凭据保存要求

• Token 只保存在服务端或受控的密钥管理系统中。
• 不将 Token、密码、SecretKey 或完整 Authorization 请求头记录到普通应用日志。
• 不通过前端 JavaScript 直接调用需要高权限 Token 的管理 API。
• 为不同业务系统分配独立凭据，不在多个系统间共用一个高权限 Token。
• 定期更换凭据，并保留可追溯的调用记录。

超时和重试

调用方应为连接和读取设置明确超时，但不应对所有失败请求无条件重试。创建会议、修改人员或开始录制等操作可能改变服务端状态。重试前应先确认接口是否幂等，或者通过查询接口确认首次请求是否已经生效。

完成首次调用验证

1. 确认调用方服务器可以访问 API 基础地址。
2. 确认 TLS 证书有效，不通过关闭证书验证规避错误。
3. 使用权限范围最小的测试 Token。
4. 先调用查询类接口，确认鉴权、JSON 解析和返回结构。
5. 再调用创建或修改类接口。
6. 确认日志中没有凭据和个人信息。

常见问题

接口返回未授权时应该检查什么

检查 Authorization 格式、Token 是否过期、Token 是否属于当前项目，以及 Token 是否具有调用当前模块的权限。不要在工单或聊天中粘贴完整 Token。

HTTP 返回 2xx 是否一定表示业务成功

HTTP 2xx 表示服务器已接收并处理请求。调用方仍应检查 JSON Body 中的 code、data 和 msg，不应只根据 HTTP 状态码更新本地业务状态。

下一步

• 查看会议管理 API
• 查看预约会议 API
• 查看录制管理 API
• 查看组织与人员 API
• 查看事件订阅与回调

本页补充各业务接口共用的调用约定。具体路径、字段和权限以项目交付版本为准，应用不应根据示例推测未提供的接口。

调用方需要统一的四项规则

请求约定

• 使用项目实际提供的 HTTPS 服务地址。
• 请求和响应正文使用 JSON 时，设置 Content-Type: application/json。
• 身份凭据仅由受控服务端保存和使用，不应放在网页、移动端或公开代码仓库中。
• 为每次请求记录业务侧请求 ID，便于排查超时和重复提交。
• 不在日志、截图或工单中记录完整凭据，也不向外返回内部堆栈和服务器路径。

curl --request POST \
  --url 'https://meeting.example.com/api/example' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <access-token>' \
  --data '{"example":"value"}'

响应处理

调用方应同时检查 HTTP 状态、业务状态和响应正文，不要只以“收到 JSON”判断成功。

{
  "code": 0,
  "message": "success",
  "data": {}
}

字段名称可能因接口版本不同而变化，正式开发应以对应接口文档和实际返回为准。

超时、重试与幂等

• 查询类请求可在网络错误或服务暂时不可用时有限重试。
• 创建会议、开始录制等写操作重试前应确认是否具备幂等机制。
• 使用指数退避并设置最大重试次数，避免故障时持续放大请求量。
• 客户端超时不代表服务端一定未执行，应通过查询接口核对最终状态。

分页与批量数据

列表接口应按接口提供的分页字段迭代获取，不要假设单次请求返回全部数据。批量查询应限制单批数量，并记录未处理或失败的对象。

常见错误分类

本页说明快速会议的创建、修改和查询方式。请先完成 Server API 调用准备，并在请求头中传入项目获得的 Bearer Token。

接口一览

通用请求头

创建会议

POST /mgr/api/createMeeting

{
  "roomName": "项目沟通会",
  "hostInfo": {"openId": "demo-host-001", "userName": "演示主持人"},
  "password": "${MEETING_PASSWORD}"
}

成功后返回 roomId、password 等会议信息。请将会议号作为后续查询和修改的主要标识。

修改会议

POST /mgr/api/modifyMeeting

{
  "roomId": "${ROOM_ID}",
  "roomName": "项目沟通会（更新）",
  "hostInfo": {"openId": "demo-host-002", "userName": "演示主持人"}
}

查询会议详情

GET /mgr/api/getMeetingDetail?roomId=${ROOM_ID}&haveParticipant=true&range=all

返回信息包括会议名称、主持人、会议状态、实际开始/结束时间、会议类型、静音策略、录制状态和参与人列表。

查询会议状态

GET /mgr/api/getMeetingStatus?roomId=${ROOM_ID}

设置变声

POST /mgr/api/modifyVoiceChange

{"roomId":"${ROOM_ID}","voiceChange":1}

调试建议

• 生产环境不要记录 Bearer Token 和入会密码。
• openId 应使用业务系统中稳定、唯一且不可复用的标识。
• 对会议修改和变声等写操作保留审计日志。

预约会议用于将会议日程、主持人、参会人和静音策略写入红鲸会议系统。时间参数均使用 13 位毫秒时间戳。

使用前先确认三项规则

修改周期会议、结束时间、主持人或参会人时，应先明确操作针对整个预约还是具体会议实例，避免业务日程与会议状态不一致。

接口一览

创建或修改预约

创建使用 POST /mgr/api/bookingMeeting，修改使用 POST /mgr/api/modifyBooking。修改时需要传入 roomId。

{
  "scheduleId": "schedule-demo-001",
  "roomName": "项目周会",
  "hostInfo": {"openId": "demo-host-001", "userName": "演示主持人"},
  "participantsInfo": [{"openId": "demo-user-001", "userName": "演示参会人"}],
  "startTime": 1793379600000,
  "stopTime": 1793383200000,
  "duration": 3600000,
  "repeatType": "none",
  "autoMute": "close",
  "allowAnonymous": false
}

创建成功后返回 roomId 和会议访问地址。

修改结束时间

POST /mgr/api/modifyBookingStopTime

取消预约

POST /mgr/api/cancelBooking

{"roomId":["${ROOM_ID_1}","${ROOM_ID_2}"]}

预约黑名单

添加使用 POST /mgr/api/blacklistAdd，删除使用 POST /mgr/api/blacklistDelete。

修改主持人

POST /mgr/api/modifyBookingHost

修改参会人

POST /mgr/api/modifyBookingMeetingUsers

查询预约列表

GET /mgr/api/getBookingList

实施注意事项

• 建议保存外部 scheduleId 与红鲸 roomId 的对应关系。
• 修改参会人和主持人前，校验 openId 是否已同步。
• 时间戳统一使用同一时区规则，避免日程偏移。
• 业务界面应明确展示开始时间、结束时间、重复规则和匿名入会设置。

录制管理 API 用于查询录制任务、下载录制文件，以及按用户启动或停止个人录制。个人录制需 v4.5.0 或更高版本。

接口一览

查询录制列表

GET /mgr/api/getRecordFileList?roomId=${ROOM_ID}&page=1&pageSize=10

下载录制文件

GET /mgr/api/downloadRecordFile/${RECORD_ID}

recordId 必须来自录制列表接口。下载链接应由服务端按权限发放，不要在公开页面或长时间有效的前端代码中暴露。

启动个人录制

POST /mgr/api/startPersonalRecord

{"roomId":"${ROOM_ID}","openId":"demo-user-001"}

停止个人录制

POST /mgr/api/stopPersonalRecord

请求参数与启动个人录制相同，并确保用户标识与启动时一致。

安全与合规建议

• 启动录制前，按组织制度完成告知、授权和留痕。
• 录制文件按项目要求设置访问权限、保留期和删除策略。
• 对查询、下载和录制开关操作记录审计日志。

组织与人员 API 用于将业务系统中的部门、用户和账号状态同步至红鲸。建议将 openId 作为跨系统稳定且唯一的人员标识。

接口一览

部门新增与修改

新增使用 POST /mgr/api/ou/department/add，修改使用 POST /mgr/api/ou/department/update。

{"name":"研发中心","id":"dept-demo-001","parentId":"dept-root","displayOrder":10}

部门删除与详情

• 删除：DELETE /mgr/api/ou/department/delete?id=${DEPARTMENT_ID}
• 详情：GET /mgr/api/ou/department/detail?id=${DEPARTMENT_ID}

删除部门前，先处理子部门和所属用户，避免产生无归属数据。

用户新增与修改

新增使用 POST /mgr/api/ou/user/add，修改使用 POST /mgr/api/ou/user/update。

{
  "name": "演示用户",
  "openId": "demo-user-001",
  "loginName": "demo.user",
  "password": "${INITIAL_PASSWORD}",
  "roleCode": 0,
  "deptIds": ["dept-demo-001"],
  "actived": true,
  "avatar": "https://example.com/avatar.png"
}

新增成功后返回红鲸会议管理系统中的用户 ID。

用户删除与详情

• 删除：DELETE /mgr/api/ou/user/delete?openId=${OPEN_ID}
• 详情：GET /mgr/api/ou/user/detail?openId=${OPEN_ID}

批量查询用户

POST /mgr/api/getUsersByOpenIds，v4.5.0 或更高版本。

{"openIds":["demo-user-001","demo-user-002"]}

同步策略建议

• 按“部门先于用户”的顺序同步，修改前查询目标是否存在。
• 优先将离职或停用用户设为未激活，再按数据保留制度处理删除。
• 保存每次同步的对象、结果和错误信息，但不记录明文密码。
• 批量同步时设置限速、重试和幂等逻辑。

红鲸可将会议状态和终端信令主动推送到业务系统。回调接收方必须使用 HTTPS、验证 Signature 请求头，并对重复事件实现幂等处理。

接入前必须完成四件事

1. 业务系统准备可由红鲸服务访问的 HTTPS 地址。
2. 由项目管理员配置回调地址和 SecretKey。
3. 接收方按约定计算 HMAC-SHA256 签名，并与 Signature 比较。
4. 接收方为重复推送设计幂等处理，并在验签通过后快速返回成功响应。

这四项没有完成时，不建议正式启用事件回调。耗时业务应先入队，再异步处理，避免回调超时。

SecretKey 属于敏感凭据，本页不公开它的获取步骤或实际值。

回调路由

上述路由为接收方的约定示例，实际路径应与项目配置保持一致。

Signature 签名验证

对请求的完整 URI（包含查询参数）使用 SecretKey 计算 HMAC-SHA256，将结果编码为小写十六进制字符串后，与请求头 Signature 进行常量时间比较。

signature = hex(HMAC-SHA256(secretKey, requestURIWithQuery))

验签失败时返回 401 并停止处理。不要在日志中输出 SecretKey 或完整签名调试信息。

会议事件类型

回调数据结构

{
  "eventType": "EventParticipantJoined",
  "callbackData": {
    "roomId": "${ROOM_ID}",
    "roomSid": "${ROOM_INSTANCE_ID}",
    "roomName": "项目沟通会",
    "roomType": "video",
    "status": 2,
    "startedTime": 1793379600000,
    "hostUser": {"id":"101","openId":"demo-host-001","userName":"演示主持人"},
    "changedParticipants": [
      {"id":"102","openId":"demo-user-001","userName":"演示参会人"}
    ]
  }
}

会议结束原因

信令同步

可靠性要求

• 使用 roomSid + eventType + changedParticipants + 时间 等组合信息设计幂等键。
• 先快速验签和入队，再异步完成业务处理，避免回调超时。
• 对返回非 2xx、超时和重复推送设置监控和告警。
• 对未识别的 eventType 保留原始事件并安全忽略，避免影响已知事件。

排查时先确定问题发生在哪一层：页面或 App、业务接口、媒体连接、设备权限，还是服务端部署。每次只改变一个条件，并保留时间、用户、会议号、版本和错误信息。

无法访问服务地址

依次检查：

1. 终端能否解析项目域名。
2. HTTPS 证书是否有效，域名是否匹配。
3. TCP 8443 是否按项目网络范围开放。
4. 跨网络部署时 NAT、入口地址和回程路由是否正确。
5. 服务容器是否运行，系统时间是否准确。

不要通过长期关闭防火墙或 SELinux 解决访问问题，应根据日志增加最小必要规则。

无法加入会议

• 核对会议号、会议密码和用户身份信息。
• 确认会议仍然有效，未被结束或关闭。
• 确认 Web SDK 脚本、Android AAR 与服务端属于兼容版本。
• 检查加入会议接口是否返回媒体服务地址和 Token。
• 不要复用过期 Token，也不要把 Token 写入公开页面或日志。

已入会但没有声音

• 检查麦克风系统权限和浏览器授权。
• 检查是否调用了麦克风启用接口。
• 区分“麦克风轨道未发布”“轨道静音”和“本地扬声器静音”。
• 检查系统音频输出设备是否切换到蓝牙、有线耳机或其他设备。
• 检查远端音频轨道是否已订阅。

已入会但没有画面

• 检查摄像头权限以及是否被其他应用占用。
• 确认摄像头轨道已创建并发布。
• 检查远端轨道是否已订阅并添加到渲染器或视频元素。
• Web 页面检查视频元素是否支持自动播放和行内播放。
• Android 页面退出或重建后，应重新绑定有效轨道和渲染器。

屏幕共享无法开始

• Android 应先完成系统 MediaProjection 授权。
• Web 端需要在浏览器支持并允许的安全环境中发起共享。
• 检查 SDK 版本是否包含当前使用的屏幕共享参数。
• 确认共享轨道已发布，UDP 7882–7885 的媒体连接可用。
• 停止共享后清理旧轨道，再处理下一次共享请求。

画面卡顿或质量差

• 观察是否持续处于重连或网络质量较差状态。
• 检查 UDP 媒体端口是否被限制或发生不稳定 NAT 映射。
• 降低采集分辨率、帧率或编码码率后对比。
• 屏幕共享内容以文档为主时，可优先降低帧率；动态画面需要重新平衡清晰度和带宽。
• 不要高频连续修改运行时视频参数。

录制无法开始

• 先调用会议能力接口确认服务端支持录制。
• 确认当前用户具备录制控制权限。
• 检查会议是否已经在录制，避免重复启动。
• 核对服务端存储空间、录制目录和相关服务状态。
• 保留会议号、用户 ID、操作时间和错误响应用于排查。

Server API 调用失败

应保留哪些排查信息

• 客户端平台、操作系统、浏览器或 App 版本。
• Web SDK、Android SDK 和服务端版本。
• 问题发生时间、会议号和用户 ID；不要记录密码和完整 Token。
• 页面控制台、SDK 日志、接口响应和服务端日志中的关联请求 ID。
• 问题是否稳定复现，以及改变网络、设备或账号后的结果。

无法自行定位时，将上述信息整理后提交技术支持，不要只提供一张错误截图。

本页汇总当前公开文档中已经说明的版本变化。安装包、AAR 和 Demo 仍通过资料申请流程提供。

Android SDK 服务端兼容线

Android SDK 411 兼容线

Android SDK 420 兼容线

Web SDK 版本能力

Web SDK 脚本路径

4.2.0 及以后版本：

<script src="https://meeting.example.com:8443/connect/static/js/sdk.4.0.0.bundle.js"></script>

4.0.1 至 4.1.x 版本使用不带 /connect/ 的脚本路径。4.0.1 以前的项目可能使用带版本号的旧脚本文件，升级时应同步调整引用地址。

升级建议

• 先根据服务端版本选择对应兼容线，不跨兼容线直接替换 AAR。
• 在测试环境验证登录、入会、音视频、屏幕共享、录制和退出流程。
• 升级 Web SDK 时同时检查脚本路径和入会页面路径。
• 保留回滚所需的旧版本文件和配置。
• 完成兼容性测试后再进入生产环境。

可以申请哪些资料

• Docker 与 Docker Compose 离线安装文件。
• 红鲸音视频服务离线部署包。
• Android SDK AAR、Demo 和示例工程。
• 项目已授权的其他开发或部署资料。

申请时需要提供什么

• 单位和联系人信息。
• 需要的资料类型。
• 部署资料所需的 CPU 架构、Linux 版本和网络环境。
• 开发组件所需的服务端版本、目标平台和使用场景。

暂时无法确定的技术信息可以填写“待确认”，并在使用场景中说明计划完成的任务。

提交申请

红鲸收到表单后会核对版本、平台和资料范围，并通过约定渠道提供适用文件或进一步确认信息。

填写资料申请