本指南介绍如何使用 Cloudflare RealtimeKit Core SDK 在会议中注册、激活和渲染插件。
插件是运行在会议内部的交互式实时应用程序,例如共享白板或文档查看器。当参与者激活某个插件时,它会对会话中的每个人都变为活动状态。
会议插件对象可通过 meeting.plugins 获取。它提供两个 Plugin 对象集合:
all:本地参与者可用的每个插件。active:当前在会话中运行的插件。
// All plugins available to you
const allPlugins = meeting.plugins.all.toArray();
// Plugins currently active in the session
const activePlugins = meeting.plugins.active.toArray();
// Get a single plugin by its id
const plugin = meeting.plugins.all.get(pluginId);使用 useRealtimeKitSelector hook 响应式地读取插件。该 hook 仅在您的组件树包裹在 RealtimeKitProvider 中时才起作用。
import { useRealtimeKitSelector } from "@cloudflare/realtimekit-react";
const allPlugins = useRealtimeKitSelector((m) => m.plugins.all.toArray());
const activePlugins = useRealtimeKitSelector((m) => m.plugins.active.toArray());// All plugins available to you
val allPlugins = meeting.plugins.all
// Plugins currently active in the session
val activePlugins = meeting.plugins.active
// Get a single plugin by its id
val plugin = meeting.plugins.all.firstOrNull { it.id == pluginId }// All plugins available to you
let allPlugins = meeting.plugins.all
// Plugins currently active in the session
let activePlugins = meeting.plugins.active
// Get a single plugin by its id
let plugin = meeting.plugins.all.first { $0.id == pluginId }使用 useRealtimeKitSelector hook 响应式地读取插件。
import { useRealtimeKitSelector } from "@cloudflare/realtimekit-react-native";
const allPlugins = useRealtimeKitSelector((m) => m.plugins.all.toArray());
const activePlugins = useRealtimeKitSelector((m) => m.plugins.active.toArray());
// Get a single plugin by its namespaced id
const plugin = useRealtimeKitSelector((m) => m.plugins.all.get(pluginId));在初始化 SDK 时,您需要注册会话中可用的插件。每个配置提供了 RealtimeKit 用来列出该插件的元数据以及它加载的位置。
将插件配置数组作为 defaults.plugins 传入。每个配置提供了 RealtimeKit 用来列出该插件的元数据以及它渲染的 component。
RealtimeKitClient.init({
authToken: "<auth_token>",
defaults: {
plugins: [
{
// User-provided unique id. The SDK prefixes it with
// `{meetingId}:` to create the namespaced `plugin.id`.
id: "whiteboard",
// Display name shown in the plugins panel
name: "Whiteboard",
// Icon URL or data URI shown next to the name
icon: "https://example.com/whiteboard.png",
// Per-plugin permissions for the local participant
permissions: {
canActivate: true,
canDeactivate: true,
},
// The element rendered when the plugin is active
component: document.createElement("my-whiteboard"),
},
],
},
});component 是一个 HTMLElement。rtk-plugin-main 组件将其投影到会议布局中,因此应用样式会继续生效。
每个插件配置都接受以下字段:
| 字段 | 描述 | 类型 | 是否必填 |
|---|---|---|---|
id |
插件的唯一标识符。SDK 会为其加上前缀 {meetingId}: 以形成 plugin.id。 |
string |
是 |
name |
插件面板中显示的显示名称。 | string |
是 |
icon |
显示在名称旁边的图标 URL 或数据 URI。 | string |
是 |
permissions |
控制本地参与者是否可以激活或停用该插件。 | { canActivate: boolean; canDeactivate: boolean } |
是 |
component |
插件处于活动状态时渲染的元素。 | HTMLElement |
是 |
调用 initMeeting 时,将插件配置作为 defaults.plugins 传入。在 React Native 中,component 应该是一个带有 src 属性的对象,其中包含要渲染的 URL —— 您可以在 WebView 中加载它,或使用 UI Kit 来自动处理渲染。
const [meeting, initMeeting] = useRealtimeKitClient();
await initMeeting({
authToken: "<auth_token>",
defaults: {
plugins: [
{
// User-provided unique id. The SDK prefixes it with
// `{meetingId}:` to create the namespaced `plugin.id`.
id: "whiteboard",
// Display name shown in the plugins panel
name: "Whiteboard",
// Icon URL shown next to the name
icon: "https://example.com/whiteboard.png",
// Per-plugin permissions for the local participant
permissions: {
canActivate: true,
canDeactivate: true,
},
// URL to render when the plugin is active.
// Pass an object with a src property: { src: string }.
component: { src: "https://example.com/whiteboard/" },
},
],
},
});每个插件配置都接受以下字段:
| 字段 | 描述 | 类型 | 是否必填 |
|---|---|---|---|
id |
插件的唯一标识符。SDK 会为其加上前缀 {meetingId}: 以形成 plugin.id。 |
string |
是 |
name |
插件面板中显示的显示名称。 | string |
是 |
icon |
显示在名称旁边的图标 URL。 | string |
是 |
permissions |
控制本地参与者是否可以激活或停用该插件。 | { canActivate: boolean; canDeactivate: boolean } |
是 |
component |
插件处于活动状态时用于渲染的带有 src URL 的对象。 |
{ src: string } |
是 |
将 RtkClientPluginConfig 对象列表作为 plugins 传递给 RtkMeetingInfo。当你渲染插件时,SDK 会将每个插件的 url 加载到 WebView 中。
val meetingInfo = RtkMeetingInfo(
authToken = "<auth_token>",
plugins = listOf(
RtkClientPluginConfig(
// User-provided unique id. The SDK prefixes it with
// `{meetingId}:` to create the namespaced `plugin.id`.
id = "whiteboard",
// Display name shown in the plugins list
name = "Whiteboard",
// Icon URL shown next to the name
icon = "https://example.com/whiteboard.png",
// URL loaded into the plugin WebView when the plugin is active
url = "https://example.com/whiteboard/",
// Per-plugin permissions for the local participant
permissions = RtkClientPluginPermissions(
canActivate = true,
canDeactivate = true,
),
),
),
)每个插件配置都接受以下字段:
| 字段 | 描述 | 类型 | 是否必填 |
|---|---|---|---|
id |
插件的唯一标识符。SDK 会为其加上前缀 {meetingId}: 以形成 plugin.id。 |
String |
是 |
name |
插件列表中显示的显示名称。 | String |
是 |
icon |
显示在名称旁边的图标 URL。 | String |
是 |
url |
插件处于活动状态时加载到插件 WebView 中的 URL。必须使用 https://。 |
String |
是 |
permissions |
控制本地参与者是否可以激活或停用该插件。 | RtkClientPluginPermissions |
是 |
将 RtkClientPluginConfig 对象数组作为 plugins 传递给 RtkMeetingInfo。当你渲染插件时,SDK 会将每个插件的 url 加载到 WebView 中。
let meetingInfo = RtkMeetingInfo(
authToken: "<auth_token>",
plugins: [
RtkClientPluginConfig(
// User-provided unique id. The SDK prefixes it with
// `{meetingId}:` to create the namespaced `plugin.id`.
id: "whiteboard",
// Display name shown in the plugins list
name: "Whiteboard",
// Icon URL shown next to the name
icon: "https://example.com/whiteboard.png",
// URL loaded into the plugin WebView when the plugin is active
url: "https://example.com/whiteboard/",
// Per-plugin permissions for the local participant
permissions: RtkClientPluginPermissions(
canActivate: true,
canDeactivate: true
)
)
]
)每个插件配置都接受以下字段:
| 字段 | 描述 | 类型 | 是否必填 |
|---|---|---|---|
id |
插件的唯一标识符。SDK 会为其加上前缀 {meetingId}: 以形成 plugin.id。 |
String |
是 |
name |
插件列表中显示的显示名称。 | String |
是 |
icon |
显示在名称旁边的图标 URL。 | String |
是 |
url |
插件处于活动状态时加载到插件 WebView 中的 URL。必须使用 https://。 |
String |
是 |
permissions |
控制本地参与者是否可以激活或停用该插件。 | RtkClientPluginPermissions |
是 |
激活操作位于 Plugin 对象上。调用 activate() 会为会话中的每个参与者启用该插件,而 deactivate() 会为每个人停用它。这两种方法都遵循插件的 permissions。
const plugin = meeting.plugins.all.get(pluginId);
// Activate for all participants
await plugin.activate();
// Deactivate for all participants
await plugin.deactivate();const plugins = useRealtimeKitSelector((m) => m.plugins);
const plugin = plugins.all.get(pluginId);
// Activate for all participants
await plugin.activate();
// Deactivate for all participants
await plugin.deactivate();val plugin = meeting.plugins.all.firstOrNull { it.id == pluginId } ?: return
// Activate for all participants
plugin.activate()
// Deactivate for all participants
plugin.deactivate()guard let plugin = meeting.plugins.all.first(where: { $0.id == pluginId }) else { return }
// Activate for all participants
plugin.activate()
// Deactivate for all participants
plugin.deactivate()Plugin 对象代表单个插件。您可以从 meeting.plugins 中的任意集合获取它。
| 属性 | 描述 | 类型 |
|---|---|---|
id |
命名空间插件 id,格式为 {meetingId}:{configId}。 |
string |
name |
插件的显示名称。 | string |
icon |
图标 URL 或数据 URI。 | string |
permissions |
本地参与者的激活权限。 | { canActivate: boolean; canDeactivate: boolean } |
component |
插件处于活动状态时渲染的元素。 | HTMLElement |
active |
插件当前是否正在运行。 | boolean |
enabledBy |
激活该插件的参与者 ID。 | string |
| 属性 | 描述 | 类型 |
|---|---|---|
id |
命名空间插件 id,格式为 {meetingId}:{configId}。 |
String |
name |
插件的显示名称。 | String |
icon |
图标 URL。 | String |
permissions |
本地参与者的激活权限。 | RtkClientPluginPermissions |
isActive |
插件当前是否正在运行。 | Boolean |
enabledBy |
激活该插件的参与者 ID。 | String? |
| 属性 | 描述 | 类型 |
|---|---|---|
id |
命名空间插件 id,格式为 {meetingId}:{configId}。 |
String |
name |
插件的显示名称。 | String |
icon |
图标 URL。 | String |
permissions |
本地参与者的激活权限。 | RtkClientPluginPermissions |
isActive |
插件当前是否正在运行。 | Bool |
enabledBy |
激活该插件的参与者 ID。 | String? |
| 属性 | 描述 | 类型 |
|---|---|---|
id |
命名空间插件 id,格式为 {meetingId}:{configId}。 |
string |
name |
插件的显示名称。 | string |
icon |
图标 URL。 | string |
permissions |
本地参与者的激活权限。 | { canActivate: boolean; canDeactivate: boolean } |
component |
注册时提供的对象。包含渲染层加载的 src URL。 |
{ src: string } |
active |
插件当前是否正在运行。 | boolean |
enabledBy |
激活该插件的参与者 ID。 | string |
Plugin 对象在状态更改时会触发事件。您可以监听单个插件,也可以在映射(map)上监听以接收其中每个插件的事件。
| 事件 | 描述 |
|---|---|
stateUpdate |
在激活或停用插件时触发。 |
enabled |
当插件对本地参与者变为活动状态时触发。 |
closed |
当插件对本地参与者被停用时触发。 |
ready |
当插件准备就绪可用时触发。 |
const plugin = meeting.plugins.all.get(pluginId);
plugin.on("stateUpdate", ({ active, pluginId }) => {
console.log(`Plugin ${pluginId} active:`, active);
});
// Listen for any plugin being added to or removed from the map
meeting.plugins.all.on("pluginAdded", (plugin) => {
console.log("Plugin added:", plugin.name);
});
meeting.plugins.all.on("pluginDeleted", (plugin) => {
console.log("Plugin removed:", plugin.name);
});注册 RtkPluginsEventListener 以接收插件事件。
| 回调 | 描述 |
|---|---|
onPluginActivated |
当为所有参与者激活插件时调用。 |
onPluginDeactivated |
当为所有参与者停用插件时调用。 |
onPluginMessage |
插件网页向应用发送消息时调用。请参阅与插件交换消息。 |
onPluginFileRequest |
当插件向应用请求文件时调用。 |
val pluginsEventListener = object : RtkPluginsEventListener {
override fun onPluginActivated(plugin: RtkPlugin) {
// A plugin became active for all participants
}
override fun onPluginDeactivated(plugin: RtkPlugin) {
// A plugin was deactivated for all participants
}
override fun onPluginMessage(plugin: RtkPlugin, eventName: String, data: Any?) {
// A plugin sent a message to the app
}
override fun onPluginFileRequest(plugin: RtkPlugin) {
// A plugin requested a file from the app
}
}
meeting.addPluginsEventListener(pluginsEventListener)
// Remove the listener when the owning screen is torn down
meeting.removePluginsEventListener(pluginsEventListener)遵守 RtkPluginsEventListener 协议并注册该监听器以接收插件事件。
| 回调 | 描述 |
|---|---|
onPluginActivated |
当为所有参与者激活插件时调用。 |
onPluginDeactivated |
当为所有参与者停用插件时调用。 |
onPluginMessage |
插件网页向应用发送消息时调用。请参阅与插件交换消息。 |
onPluginFileRequest |
当插件向应用请求文件时调用。 |
extension MeetingViewModel: RtkPluginsEventListener {
func onPluginActivated(plugin: RtkPlugin) {
// A plugin became active for all participants
}
func onPluginDeactivated(plugin: RtkPlugin) {
// A plugin was deactivated for all participants
}
func onPluginMessage(plugin: RtkPlugin, eventName: String, data: Any?) {
// A plugin sent a message to the app
}
func onPluginFileRequest(plugin: RtkPlugin) {
// A plugin requested a file from the app
}
}
meeting.addPluginsEventListener(pluginsEventListener: self)
// Remove the listener when the owning screen is torn down
meeting.removePluginsEventListener(pluginsEventListener: self)如果您使用 UI Kit,RealtimeKit 为插件提供了现成的组件:
rtk-plugins-toggle:用于打开和关闭插件侧边栏的控制栏按钮。rtk-plugins:可用插件列表,带有用于激活或停用每个插件的控件。rtk-plugin-main:在会议布局中渲染活动插件的component。
这些组件会读取 meeting.plugins 的内容,因此一旦您在初始化时注册了插件,它们就会自动反映插件的状态。
插件处于活动状态时,getPluginView() 返回托管它的 Android WebView。从插件事件监听器的 onPluginActivated 回调中将此视图添加到布局。
激活后首次调用 getPluginView() 会创建 WebView,并开始加载插件的 url。插件保持活动状态时,后续调用会返回同一视图。插件未激活时,该方法返回 null。插件停用时,SDK 会丢弃其 WebView,因此请从布局中移除该视图,并在插件重新激活后再次调用 getPluginView()。
// In your RtkPluginsEventListener
override fun onPluginActivated(plugin: RtkPlugin) {
runOnUiThread {
// Returns an Android WebView you can add to your layout
val pluginView = plugin.getPluginView() ?: return@runOnUiThread
pluginContainer.addView(pluginView)
}
}
override fun onPluginDeactivated(plugin: RtkPlugin) {
runOnUiThread {
// The SDK discards the WebView on deactivation
pluginContainer.removeAllViews()
}
}插件处于活动状态时,getPluginView() 返回托管它的 WKWebView。从插件事件监听器的 onPluginActivated 回调中将此视图添加到视图层次结构。
激活后首次调用 getPluginView() 会创建 WebView,并开始加载插件的 url。插件保持活动状态时,后续调用会返回同一视图。插件未激活时,该方法返回 nil。插件停用时,SDK 会丢弃其 WebView,因此请从视图层次结构中移除该视图,并在插件重新激活后再次调用 getPluginView()。
// In your RtkPluginsEventListener
func onPluginActivated(plugin: RtkPlugin) {
DispatchQueue.main.async {
// Returns a WKWebView you can add to your view hierarchy
guard let pluginView = plugin.getPluginView() else { return }
self.pluginContainer.addSubview(pluginView)
}
}
func onPluginDeactivated(plugin: RtkPlugin) {
DispatchQueue.main.async {
// The SDK discards the WebView on deactivation
self.pluginContainer.subviews.forEach { $0.removeFromSuperview() }
}
}React Native UI Kit 为插件提供了现成的组件:
RtkPluginsToggle:用于打开和关闭插件侧边栏的控制栏按钮。RtkPlugins:列出可用插件的面板,带有用于激活或停用每个插件的控件。RtkPluginMain:在WebView中渲染活动插件。
一旦在初始化时注册了插件,这些组件就会自动读取 meeting.plugins。如果您使用 RtkMeeting,插件 UI 无需任何额外设置即可包含在内。
在 Web 上,插件的 component 是在你自己的页面中运行的 HTMLElement,因此 RealtimeKit 不提供单独的消息传递 API。请使用 UI 框架提供的机制与插件交换数据,例如属性、特性、回调或 DOM 事件。
如果插件组件嵌入了 iframe,请使用 iframe.contentWindow.postMessage(message, targetOrigin) 向其发送消息,并使用 window 上的 message 事件监听器监听回复。始终将插件源作为 targetOrigin 传递,并在信任传入消息前检查 event.origin。
Android 和 iOS Core SDK 支持通过 sendData 和 onPluginMessage 在应用与插件之间传递消息。在 SDK 选择器中选择 Android 或 iOS 查看本节。
在 Android 和 iOS 上,插件是 SDK 加载到 WebView 中的网页。应用和页面通过 SDK 注入 WebView 的桥接交换消息。该桥接有两个相互独立的单向方向,不会将消息配对为请求和响应。
| 方向 | 应用 API | 消息 type |
插件页面 API |
|---|---|---|---|
| 应用 → 插件 | RtkPlugin.sendData(eventName, data) |
24 |
window.addEventListener("message", handler) |
| 插件 → 应用 | RtkPluginsEventListener.onPluginMessage(plugin, eventName, data) |
20 |
window.parent.postMessage(message, "*") |
每条消息都包含字符串事件名称和可选数据。事件名称由应用自行约定,SDK 不保留任何名称。数据必须与 JSON 兼容:null、字符串、数字、布尔值、列表以及键为字符串的映射。
消息只在同一设备上的应用和插件 WebView 之间传输,不会发送给其他参与者。要在参与者之间共享插件状态,请使用会议键值存储或消息广播。
桥接不会验证发送消息的页面。只注册你信任的插件 URL,并验证任一端收到的每条消息。
插件页面发送消息时,SDK 会在每个已注册的 RtkPluginsEventListener 上调用 onPluginMessage。请在监听插件事件中注册的监听器内实现它。插件必须处于活动状态,并且监听器必须在页面发送消息前注册。
override fun onPluginMessage(plugin: RtkPlugin, eventName: String, data: Any?) {
when (eventName) {
"ready" -> {
// The plugin page has loaded and is listening for messages
plugin.sendData("init", mapOf("theme" to "dark"))
}
"score.updated" -> {
val payload = data as? Map<*, *> ?: return
val score = payload["score"] as? Int ?: return
// Update your app with score
}
}
}SDK 将页面发送的 JSON data 转换为 Kotlin 值:
| JSON 值 | Kotlin 类型 |
|---|---|
| 对象 | Map<String, Any?> |
| 数组 | List<Any?> |
| 字符串 | String |
| 布尔值 | Boolean |
| 数字 | Int、Long 或 Double |
null 或省略 |
null |
func onPluginMessage(plugin: RtkPlugin, eventName: String, data: Any?) {
switch eventName {
case "ready":
// The plugin page has loaded and is listening for messages
plugin.sendData(eventName: "init", data: ["theme": "dark"])
case "score.updated":
guard let payload = data as? [String: Any],
let score = payload["score"] as? NSNumber else { return }
// Update your app with score
default:
break
}
}SDK 将页面发送的 JSON data 转换为 Foundation 值。使用 as? [String: Any] 转换对象,使用 as? [Any] 转换数组,使用 as? String 转换字符串,使用 as? NSNumber 转换数字或布尔值。如果页面发送 null 或省略 data,则 data 为 nil。
val error = plugin.sendData(
eventName = "init",
data = mapOf("theme" to "dark", "locale" to "en-US"),
)
if (error != null) {
// PluginError.NotActive: the plugin is not active
}if let error = plugin.sendData(eventName: "init", data: ["theme": "dark", "locale": "en-US"]) {
// PluginError.NotActive: the plugin is not active
print(error)
}如果插件未激活,sendData 返回 PluginError.NotActive。否则不返回错误,并异步传送消息。没有错误表示 SDK 接受了消息,并不表示页面已收到消息。以下情况下,SDK 会丢弃消息且不报告错误:
- 插件激活后尚未调用
getPluginView(),因此不存在 WebView。 - 页面尚未加载,或尚未注册其
message监听器。 data包含与 JSON 不兼容的值。
SDK 不会将消息排队,也不会确认传送。为避免在页面就绪前发送,请让页面在加载后发送 ready 事件,并只在 onPluginMessage 收到该事件后调用 sendData。本页示例采用此模式。
在插件页面中,监听 window 上的 message 事件。SDK 将每条消息作为具有以下结构的对象传送:
{
"type": 24,
"uuid": "",
"payload": {
"eventName": "init",
"data": { "theme": "dark", "locale": "en-US" }
}
}在页面 <head> 的内联脚本中注册监听器,使其在应用发送任何内容前安装:
<script>
window.addEventListener("message", (event) => {
const message = event.data;
// Ignore anything that is not a message from the app
if (!message || message.type !== 24 || !message.payload) return;
const { eventName, data } = message.payload;
if (eventName === "init") {
// Validate data before using it
document.body.dataset.theme = data?.theme ?? "light";
}
});
</script>event.data 已经是对象。不要对其调用 JSON.parse。
要向应用发送消息,请调用 window.parent.postMessage,并传入一个具有 type: 20 和 payload 对象的对象,其中后者包含字符串 eventName 和可选的 data。
每次页面开始加载时,SDK 都会替换 WebView 中的 window.parent.postMessage,但不会发出替换已就绪的信号。请在页面的 load 事件后发送第一条消息,而不是从页面解析期间运行的脚本发送。
function sendToApp(eventName, data) {
window.parent.postMessage({ type: 20, payload: { eventName, data } }, "*");
}
// Tell the app that the page is ready to receive messages
window.addEventListener("load", () => sendToApp("ready"));
// Send application events after the page has loaded
document.querySelector("#submit-score").addEventListener("click", () => {
sendToApp("score.updated", { score: 42 });
});SDK 会忽略 postMessage 的第二个参数。它不限制哪些源可以发送消息。应用不会接收使用不同 type、省略 payload 或在插件未激活时发送的消息。如果需要将回复与请求相关联,请在 data 中包含自己的标识符。