Whiteboard 插件是由 Cloudflare 托管和运营的协作白板。参与者可以在会议内的共享白板上共同绘图、书写和绘制示意图,并实时查看彼此的光标和姓名。
添加 Whiteboard 插件时使用与你自己的插件相同的插件 API 。无需部署或运营任何服务。
在共享白板上绘制形状、箭头、线条、手绘笔迹和文本。
实时查看每位参与者的光标和 RealtimeKit 显示名称。
稍后加入或重新连接,并继续使用当前白板。
将白板导出为图像。
每场会议只有一个白板。该白板在会议的所有会话中保持不变,因此会议再次开始时,参与者可以从上次离开的位置继续。详情请参阅白板数据 。
Whiteboard 插件不支持图像、框架、嵌入式 Web 内容或导入白板文件。尝试添加这些内容的参与者会看到不可用提示。
请阅读 Plugins 指南。本指南以该指南为基础。
获取参与者的身份验证令牌:将参与者添加到会议 时返回的 token。初始化 SDK 时传入的也是同一个令牌。
每位参与者都会从以下 URL 加载 Whiteboard 插件,并将身份验证令牌放在 # 后面的 URL 片段中:
https://whiteboard-v2.plugins.realtime.cloudflare.com/#authToken=<auth_token>
Whiteboard 插件会使用 RealtimeKit 验证令牌,然后打开该令牌所属会议的白板,并显示参与者的显示名称。无需传入会议 ID 或参与者姓名。
浏览器不会将 URL 片段发送给服务器,也不会将其包含在 Referer 标头中,因此请求日志不会记录令牌。插件加载后也会立即从地址栏中移除令牌。
使用片段,而非查询参数
请仅在 # 后传入身份验证令牌,不要将其作为查询参数传入,例如 ?authToken=。任何持有该令牌的人都可以以该参与者身份加入会议;浏览器会将查询参数发送给服务器,因此它们可能出现在日志中。插件不会使用查询参数中的令牌,而会显示 白板链接需要更新(Whiteboard link needs updating) 。
选择你的平台,查看每个步骤的代码。
Web Mobile
React Web Components Angular
创建一个加载插件 URL 的 iframe。请在初始化 SDK 之前创建一次,并在整个会议期间重复使用同一元素。
whiteboard-plugin.ts ts const WHITEBOARD_URL = "https://whiteboard-v2.plugins.realtime.cloudflare.com/" ;
function createWhiteboard ( authToken : string ) : HTMLIFrameElement {
const iframe = document. createElement ( "iframe" );
iframe.style.width = "100%" ;
iframe.style.height = "100%" ;
iframe.style.border = "none" ;
// Lets participants copy and paste on the board.
iframe.allow = "clipboard-read; clipboard-write" ;
// The plugin does not need your page's address.
iframe.referrerPolicy = "no-referrer" ;
iframe.src = `${ WHITEBOARD_URL }#authToken=${ encodeURIComponent ( authToken ) }` ;
return iframe;
}
const whiteboardElement = createWhiteboard ( "<auth_token>" ); 允许剪贴板访问
插件 iframe 必须设置 allow="clipboard-read; clipboard-write"。Whiteboard 插件与应用位于不同源,因此如果 iframe 未启用此权限,浏览器会阻止其中的 Clipboard API。若缺少此属性,白板的上下文菜单 Paste 将无法使用,且浏览器控制台会在每次复制或粘贴时显示权限策略错误。
请在 iframe 首次加载 src 之前设置 allow。浏览器会在框架加载时应用权限策略,因此之后再更改也不会生效,除非重新加载框架。
移动 SDK 会创建用于承载插件的 WebView,因此无需创建组件。下一步注册插件时,传入包含参与者身份验证令牌的插件 URL。
初始化 SDK 时注册 Whiteboard 插件。
说明
所有参与者所用平台上的插件 id 必须相同。只有使用相同 id 注册插件的参与者,其激活状态才会同步。
将步骤 1 中的 whiteboardElement 作为 component 传入。
RealtimeKitClient. init ({
authToken: "<auth_token>" ,
defaults: {
plugins: [
{
id: "whiteboard" ,
name: "Whiteboard" ,
icon: "https://example.com/whiteboard.png" ,
permissions: {
canActivate: true ,
canDeactivate: true ,
},
component: whiteboardElement,
},
],
},
}); val authToken = "<auth_token>"
val meetingInfo = RtkMeetingInfo (
authToken = authToken,
plugins = listOf (
RtkClientPluginConfig (
id = "whiteboard" ,
name = "Whiteboard" ,
icon = "https://example.com/whiteboard.png" ,
url = "https://whiteboard-v2.plugins.realtime.cloudflare.com/#authToken= $authToken " ,
permissions = RtkClientPluginPermissions (
canActivate = true ,
canDeactivate = true ,
),
),
),
) let authToken = "<auth_token>"
let meetingInfo = RtkMeetingInfo (
authToken : authToken,
plugins : [
RtkClientPluginConfig (
id : "whiteboard" ,
name : "Whiteboard" ,
icon : "https://example.com/whiteboard.png" ,
url : "https://whiteboard-v2.plugins.realtime.cloudflare.com/#authToken= \(authToken) " ,
permissions : RtkClientPluginPermissions (
canActivate : true ,
canDeactivate : true
)
)
]
) const authToken = "<auth_token>" ;
const [ meeting , initMeeting ] = useRealtimeKitClient ();
await initMeeting ({
authToken,
defaults: {
plugins: [
{
id: "whiteboard" ,
name: "Whiteboard" ,
icon: "https://example.com/whiteboard.png" ,
permissions: {
canActivate: true ,
canDeactivate: true ,
},
component: {
src: `https://whiteboard-v2.plugins.realtime.cloudflare.com/#authToken=${ authToken }` ,
},
},
],
},
});
有关每个配置字段的说明,请参阅注册插件 。
如果使用 UI Kit,Whiteboard 插件会显示在插件面板中,参与者可从面板中打开和关闭它。
如需通过自己的 UI 控制白板,请激活或停用插件。这两种操作都会应用于会话中的每位参与者。示例请参阅激活和停用插件 。
谁可以打开白板: 只有持有该会议有效身份验证令牌的参与者才能打开相应白板。令牌所属的会议决定打开哪个白板,因此参与者无法打开其他会议的白板。
谁可以编辑: 所有打开白板的参与者都可以编辑。预设不会控制白板编辑权限。
谁可以打开或关闭插件: 使用插件的 permissions 控制谁可以为会话激活或停用插件。
可嵌入的位置: Whiteboard 插件适用于任何域名,无需注册应用的源。
即使你将参与者从会议中移除,其身份验证令牌在过期前仍然有效,因此他们在此之前仍可打开白板。
为在同一会议的新会话开始时恢复白板,Cloudflare 会将该会议的所有白板内容存储在 Cloudflare 基础设施上。白板内容包括参与者添加的所有形状、线条、手绘笔迹和文本。
白板内容会无限期保留,会话结束时不会删除。
目前没有清除或删除白板的 API。
参与者光标和显示名称只会与当前打开白板的参与者共享,不会与白板内容一同存储。
白板内容
参与者可以在白板上输入任意文本,包括个人或敏感信息。你有责任管理参与者添加的内容,告知参与者白板内容会被存储,并遵守适用于你使用 Whiteboard 插件的法律或监管义务。你使用 Whiteboard 插件须遵守你与 Cloudflare 的协议。
有关其他 RealtimeKit 数据的保留期限,请参阅数据保留 。
Whiteboard 插件面向协作会议设计,不适用于大型广播活动。规划使用方式时,请注意以下限制:
白板参与者: 白板可同时连接的参与者数量有限。尝试加入已满白板的参与者无法连接,并会看到重新连接 按钮。对于网络研讨会等大规模活动,可让少数人编辑白板,再通过屏幕共享 与其他人分享。
白板大小: 每个白板都有最大大小限制。包含大量元素或超长手绘笔迹的白板可能达到上限。白板已满时,新变更不会保存,参与者会看到提示。
元素大小: 单个元素(例如特别长的连续手绘笔迹或大段文本)可能过大,无法分享。参与者会看到提示,且变更不会保存。
连接尝试: 短时间内来自同一网络的重复连接尝试会受到速率限制。参与者会看到 尝试次数过多(Too many attempts) ,一分钟后可重试。
白板无法加载时,插件会显示提示信息而不是白板。请使用以下表格解决这些提示和其他常见问题。