如何生成 Cloudflare API 令牌?
要使用 RealtimeKit API,你必须拥有一个 Cloudflare 帐户 ↗。
按照创建 API 令牌指南从 Cloudflare 控制面板 ↗创建令牌。配置权限时,选择 Realtime > Realtime Admin。根据使用场景配置其他访问策略和限制。
Cloudflare API 令牌用于验证对 Cloudflare API 的请求。仅在后端使用这些令牌。切勿向前端公开 API 令牌或与最终用户分享。
为什么 peer report 端点对每个 participant ID 都返回 404 错误?
peer report 端点需要的是 peer_id,而不是 participant_id。参与者加入会议时,RealtimeKit 会为其创建一个 peer。每次参与者重新加入或重新加载页面,RealtimeKit 都会创建一个新的 peer,并分配新的唯一 peer ID。
若要获取 peer 报告数据:
-
使用
include_peer_events=true调用获取会话参与者详情端点:/accounts/{account_id}/realtime/kit/{app_id}/sessions/{session_id}/participants/{participant_id}?include_peer_events=true响应中的
peer_events字段包含与该参与者关联的所有 peer ID。 -
使用
peer_events中的peer_id调用根据 peer ID 获取参与者数据端点:/accounts/{account_id}/realtime/kit/{app_id}/sessions/peer-report/{peer_id}此端点会返回该 peer 的通话统计信息。
向 peer report 端点传递 participant_id 会返回 404 响应,错误内容为 No peer event exists for id <given-id>。
如何为参与者生成身份验证令牌?
后端通过 Add Participant API 端点将用户添加为会议参与者,从而生成身份验证令牌。API 响应中包含该参与者的 token 字段。
你可以将此令牌发送给相应参与者的前端。令牌与该参与者及会议绑定,不能用于访问其他会议。
若先前令牌过期后需要新令牌,请使用 Refresh Participant Token端点。更多信息请参阅参与者令牌。
身份验证令牌的有效期是多久?
默认情况下,身份验证令牌是 JSON Web Token (JWT),自签发起有效期为 100 天。若要缩短有效期,请参阅令牌有效期和刷新。令牌包含 meetingId 和 participantId 字段,将其与特定会议中的特定参与者关联。令牌不能访问其他会议。若先前令牌过期后需要新令牌,请使用 Refresh Participant Token端点。更多信息请参阅参与者令牌。
我可以在身份验证令牌过期前刷新它吗?
可以。当前令牌过期前,你可以调用 Refresh Participant Token端点。刷新身份验证令牌会生成新令牌,但不会使现有令牌失效。每个令牌都会保持有效,并按各自的过期时间独立过期。
可以配置身份验证令牌的有效期吗?
可以。调用 Add Participant 或 Refresh Participant Token端点时,可以传入 not_before 和 expires_on 时间戳,设置令牌开始生效及过期的时间。有效期最长为 100 天。更多信息请参阅令牌有效期和刷新。
生成新的身份验证令牌会使之前的令牌失效吗?
不会。生成新令牌(包括通过刷新流程生成)不会使现有令牌失效。每个令牌都会保持有效,并按各自的过期时间独立过期。若要使特定令牌失效,请撤销该令牌。
删除参与者会撤销之前签发的所有令牌吗?
会。Delete Participant端点会立即撤销为该参与者在此会议中签发的所有令牌。如果存在活动会话,它还会将参与者从会话中移除。
参与者使用过期或已失效的身份验证令牌会怎样?
参与者无法加入会议。RealtimeKit UI 和 Core SDK 会报告令牌无效。
由于 RealtimeKit 会在参与者进入会议阶段前拒绝其加入,因此不会向其收费。
参与者的身份验证令牌过期时,如果其已在会议中,会发生什么?
参与者会保持连接。RealtimeKit 不会在令牌的 expires_on 时间到达时断开参与者。参与者会继续留在会议中,直到自行离开或被移除。
SDK 重新连接时会再次检查身份验证令牌吗?
会。网络中断后的任何套接字重连都会重复使用同一令牌。如果令牌已过期,RealtimeKit 会以 401 错误拒绝连接。
持有有效身份验证令牌的参与者可以加入未激活的会议吗?
不可以。即使身份验证令牌有效且未过期,参与者也不能加入状态为 INACTIVE 的会议。
SDK 会缓存参与者身份验证令牌吗?
不会。RealtimeKit SDK 不会缓存参与者身份验证令牌,也不会将其存储在浏览器或设备存储中。
我可以提前安排 RealtimeKit 会议吗?
RealtimeKit 没有内置的日程安排系统,但你可以在应用中基于它实现日程功能。 RealtimeKit 会议没有开始或结束时间,因此后端必须存储日程,并控制用户何时可以加入。 常见做法如下:
- 用户安排会议时,后端会在 RealtimeKit 中创建会议,并将会议
id与开始和结束时间一并存储。 - 用户尝试在应用中加入会议时,后端会检查当前时间是否处于允许的时间范围内。
- 如果检查通过,后端会将参与者添加到会议, 向前端返回参与者身份验证令牌,前端再将该令牌传给 RealtimeKit SDK,以便用户加入。
若要限制参与者可加入的时间,请将其身份验证令牌的 not_before 和 expires_on 设置为与日程相符。
如何阻止参与者在特定日期或时间之后加入会议?
到达指定时间后,调用 Update Meeting端点,将会议状态设为 INACTIVE。如果存在活动会话,该操作会移除会话中的所有参与者,并阻止参与者加入会议或启动新会话。
curl https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/realtime/kit/{APP_ID}/meetings/{MEETING_ID} \
--request PATCH \
--header "Authorization: Bearer <CLOUDFLARE_API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{ "status": "INACTIVE" }'若要控制单个参与者的访问权限,请改为设置其身份验证令牌的 expires_on。更多信息请参阅令牌有效期和刷新。
同一用户可以从多个设备或浏览器标签页加入吗?
可以。用户从不同设备或标签页加入同一会议时,一个参与者可以对应多个 peer。每个连接都会成为独立的 peer,但它们都关联到同一参与者。
如何阻止用户再次加入会议?
使用 Delete Participant API 端点,删除该用户在此会议中的参与者记录。删除参与者并停止为其签发新令牌后,该用户将无法再加入此会议。
同一参与者可以加入会议的多个会话吗?
可以。只要该参与者仍属于此会议且拥有有效的身份验证令牌,就可以在不同时间加入同一会议的多个实时会话。
每个会话都需要创建新的参与者吗?
通常不需要。一般情况下,为某位用户和某场会议创建一次参与者记录,然后在该会议的多个会话中重复使用即可。你可能需要定期刷新参与者的身份验证令牌,但无需重新创建参与者。
自定义参与者 ID 应使用什么值?
请使用自己系统中的稳定内部标识符,例如数字用户 ID 或 UUID。不要使用电子邮件地址、电话号码或其他个人身份信息等个人数据。
如何决定使用哪个 SDK?
RealtimeKit 支持所有主流 Web 和移动平台框架。
对于大多数使用场景,我们建议使用 UI Kits。
请注意:使用 UI Kit 时也会获得 Core SDK,可根据需要基于它构建其他功能。
更多信息请参阅 SDK 选择指南。
如何将最终用户的摄像头画质设置为 1080p?
初始化 RealtimeKit 时,可以设置摄像头画质的媒体配置。
媒体配置选项请参阅高级选项。
较高的摄像头画质会增加带宽使用量。如果最终用户的设备性能不足以处理多个 peer 的 1080p 视频,会议性能可能会受到影响。
如何为最终用户的摄像头视频设置自定义帧率?
初始化 RealtimeKit 时,可以设置摄像头的媒体配置。
媒体配置选项请参阅高级选项。
较高的视频帧率会增加带宽使用量。如果最终用户设备的带宽不足,会议中其他 peer 的视频画质可能会受到影响。群组通话中请将视频帧率设为较低值(例如 <= 30)。当前默认值根据 simulcast 层为 24/30 FPS。
为什么插入麦克风后没有自动选择它?
RealtimeKit SDK 会尝试自动选择麦克风,以提供最佳体验;它优先选择蓝牙设备,而不是有线设备。不过,如果设备在加入 RealtimeKit 会议前就已插入,并且设备标签中不含 bluetooth、headset 或 earphone,系统可能无法识别它。
我们支持自动选择标签包含 bluetooth、headset、earphone 或 microphone 的麦克风,以及标签包含 usb 或 wired 等字样的 USB 设备。部分常用设备(例如 AirPods 或 Airdopes)也受支持。虚拟设备不会自动选择。
如果自动选择失败,最终用户可以在会议中通过 Settings 按钮手动选择麦克风,SDK 会在后续会话中记住该选择。如果你认为某种设备很常用,请联系支持团队,申请为其提供原生自动选择支持。
如何为屏幕共享设置自定义帧率?
初始化 RealtimeKit 时,可以设置屏幕共享的媒体配置。
媒体配置选项请参阅高级选项。
较高的屏幕共享帧率会增加带宽使用量。如果最终用户设备的带宽不足,会议中其他 peer 的视频画质可能会受到影响。群组通话中请将屏幕共享帧率设为较低值(例如 <= 30)。大多数场景下,5 FPS(默认值)已足够。
我无法发送聊天消息
可能有多种原因。
首先,尝试在演示应用 ↗中加入示例会议。如果你在演示应用中也无法发送消息,请联系支持团队。如果可以发送,则问题出在集成方面。
若要排查集成问题,先确认用户是否成功加入会议。若用户已成功加入会议,请检查用户的预设是否具有发送消息的权限。如果使用自定义 UI,请检查 Core Chat API是否正常,以排除 Core SDK 问题。
如果问题仍未解决,请检查框架是否拦截了 UI。Material UI 等框架可能会使用 Drawer 组件中的焦点陷阱阻止输入焦点。通常可以通过某个 prop 关闭焦点陷阱。Material UI 提供了 disableEnforceFocus prop。
如果仍无法发送消息,请联系支持团队。
为什么会议标签页在后台或最小化时看不到 SDK 通知?不返回标签页也能看到通知吗?
浏览器不会在后台标签页或最小化窗口之外显示页内内容。RealtimeKit UI Kit 通知属于页内元素,因此遵循此浏览器行为。画中画是独立的浏览器功能,可以在浮动窗口中显示参与者视频,但不会显示通知。
主持人可能需要在查看其他标签页时,知道有人进入等候室、参与者加入会议或录制开始。若要在会议标签页外显示系统通知,请选择以下方案:
- 页面中的 Notifications API: 请求通知权限 ↗后,使用浏览器的 Notification() 构造函数 ↗。页面打开时可通过它通知用户。浏览器支持情况 ↗各不相同,而且该构造函数在大多数移动浏览器中不可用。
- Service Worker 通知: 配合 showNotification() ↗ 使用 service worker。此方案适用于更多浏览器,包括许多移动浏览器。会议页面必须将 SDK 事件传递给 worker。标签页关闭后,service worker 无法独自继续接收 SDK 事件。
- Web Push: 使用 service worker、Push API ↗ 和推送订阅。请将 VAPID 私钥保存在服务器上 ↗。即使会议标签页关闭,后端也能发送推送消息。
根据事件的可用位置选择通知触发条件。会议页面打开时,SDK 会提供参与者加入、离开、音频和视频事件、本地音频和视频事件以及聊天更新。若要由后端触发通知,请订阅 RealtimeKit Webhook,然后向客户端发送相关事件。Webhook 覆盖的事件较少,包括参与者加入和录制状态变更;它们不会提供单条聊天消息或进入等候室的事件。
录制中的水印图像显示异常
通过 Start Recording API 传入水印图像 URL 时,录制器会在 Cloudflare 容器中运行的浏览器里加载图像。如果图像显示异常,请检查以下事项:
- CORS 请求头: 图像 URL 必须在 HTTP 响应中返回正确的 CORS 请求头(例如
Access-Control-Allow-Origin: *)。如果缺少这些请求头,浏览器会阻止图像加载。 - 直接图像 URL: URL 必须直接指向图像文件(例如
https://example.com/logo.png),而不是嵌入图像的 HTML 页面。 - 不要重定向: URL 不得重定向到其他位置。录制器会直接获取该 URL,因此重定向可能导致图像加载失败。
网络限制出站流量时,需要将哪些域名和端口加入允许列表?
如果网络限制出站流量,请参阅网络允许列表,了解 RealtimeKit 集成所需的域名和端口。
如何检查网络和设备是否已准备好参加 RealtimeKit 会议?
前往 test.realtime.cloudflare.com ↗并运行会前测试。此测试会检查摄像头、麦克风和网络,并验证与 Cloudflare Realtime 端点的连接,让你在加入会议前确认网络或防火墙未阻止所需服务。所需域名和端口请参阅网络允许列表。
我可以在自己的网站中通过 iframe 使用 Cloudflare 托管的演示应用或示例吗?
我们强烈建议不要将 Cloudflare 托管的演示应用或示例嵌入你的网站,即使通过 URL 参数传递身份验证令牌也不建议。
请按照 UI Kit 设置指南在自己的网站中配置默认会议 UI,或在自己的域名下部署 RealtimeKit Web 示例 ↗。这两种方案的实现成本都很低,并能带来显著好处:
- 控制权: 你可以完全控制用户体验、结构和界面。
- 稳定性: 你的实现保持一致,不会突然改变,从而保护产品免受意外中断。
- 可靠性: 你可以控制升级的时间和方式,为用户提供稳定体验。
演示应用和示例应用可能随时更新,恕不另行通知。
音视频参与者分钟数和仅音频参与者分钟数如何计费?
RealtimeKit 按活跃参与者分钟数计费。参与者加入会议会话时开始计费,离开时停止。
主要计费规则:
- 未出席者不计费: 使用 Add Participant API添加参与者不会产生费用。如果参与者从未加入会议,RealtimeKit 不会对其收费。
- 按时长计费: RealtimeKit 按参与者处于活动会话中的实际时长(精确到秒)收费。即使参与者没有发送或接收音频或视频,仍会计费。
- 多个标签页分别计费: 如果某人使用同一身份验证令牌从多个浏览器标签页加入,RealtimeKit 会分别对每个标签页计费。RealtimeKit 控制面板会显示该参与者的累计时长。
有关会议和会话的区别,请参阅 RealtimeKit 概念。
例如:
- 如果两位参与者在下午 7:00 加入并于下午 7:30 离开,每人使用 30 分钟。RealtimeKit 会收取 60 个参与者分钟数。
- 如果一位参与者在下午 4:00 加入,另一位在下午 4:03 加入,两人都在下午 5:00 离开,则他们分别使用 60 和 57 分钟。RealtimeKit 会收取 117 个参与者分钟数。
- 如果一位参与者在下午 3:00 加入并于下午 3:27 离开,另一位在下午 3:05 加入并于下午 3:30 离开,则他们分别使用 27 和 25 分钟。RealtimeKit 会收取 52 个参与者分钟数。
- 如果预计有五位参与者,但只有两位加入,RealtimeKit 只会对加入的两位参与者计收参与者分钟数。
- 如果预计两位参与者在下午 2:00 加入预先创建的会议,但两人都没有加入,RealtimeKit 不会收取任何参与者分钟费用。
创建会议和参与者令牌不会产生费用。
合成录制导出如何计费?
对于合成录制,录制器会作为隐藏的虚拟参与者加入会议并录制其视图。更多信息请参阅录制指南。
最后一位参与者离开后,录制器会继续运行会议的 session_keep_alive_time_in_secs 时长。默认值为 60 秒,最大值为 600 秒。
RealtimeKit 不会对录制器收取参与者分钟费用,而是按录制时长收取导出分钟费用。当前费率请参阅 RealtimeKit 定价。
当 record_on_start 为 true 时:
- 如果两位参与者在下午 7:00 加入并于下午 7:30 离开,录制会在下午 7:00 开始。两位参与者离开后,录制器会按默认设置继续保持活动 60 秒。录制在下午 7:31 停止,因此 RealtimeKit 会收取 31 分钟的导出费用。
- 如果预计有五位参与者,但只有两位在下午 8:00 加入并于下午 8:20 离开,录制会按默认的保持活动时间持续到下午 8:21。RealtimeKit 会收取 21 分钟的导出费用。即使五位参与者都在相同时间加入和离开,费用仍为 21 分钟,因为参与者数量不会影响录制导出分钟数。
- 如果没有人加入预先创建的会议,录制不会开始。仅创建
record_on_start设为true的会议本身不会产生费用。
有人在活动会话期间开始录制时:
- 如果录制在下午 4:20 开始,最后一位参与者在下午 5:00 离开,则默认会在下午 5:01 停止。RealtimeKit 会收取 41 分钟的导出费用。
- 如果录制在下午 4:20 开始,并且有人在下午 5:00 调用
kickAll(),录制会立即停止。RealtimeKit 会收取 40 分钟的导出费用。 - 如果会议和录制在下午 4:20 开始,会议设置两分钟的保持活动时间,且所有参与者在下午 5:00 关闭标签页,录制会在下午 5:02 停止。RealtimeKit 会收取 42 分钟的导出费用。
保持活动时间有助于需要在短暂断连期间保留同一录制内容的工作流。例如,教育科技 (EdTech) 应用可能会在只有一位参与者的会议中录制限时的课后作业。如果参与者失去网络连接,并在保持活动时间到期前重新加入,录制器会继续同一录制。断连期间的录制内容会有空白间隔,但应用无需合并两段独立录制。
导出费用包含保持活动时间。若要避免这段额外时长,请调用 kickAll() 或踢出所有参与者 API,明确结束会话。