INTEGRITY Документация

← Cloudflare Realtime / realtime / realtimekit / core

Плагины

Это руководство объясняет, как регистрировать, активировать и отображать плагины во встрече с помощью Cloudflare RealtimeKit Core SDK.

Плагины представляют собой интерактивные приложения реального времени, которые работают внутри встречи, например общая доска или средство просмотра документов. Когда участник активирует плагин, он становится активным для всех в сессии.

Модуль Plugins

Объект плагинов встречи доступен по адресу meeting.plugins. Он предоставляет две коллекции Plugin объекты:

// 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 хук для реактивного чтения плагинов. Хук работает только тогда, когда дерево ваших компонентов обёрнуто в 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 хук для реактивного чтения плагинов.

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 true
name Отображаемое имя в панели плагинов. string true
icon URL-адрес значка или data URI, отображаемый рядом с именем. string true
permissions Определяет, может ли локальный участник активировать или деактивировать плагин. { canActivate: boolean; canDeactivate: boolean } true
component Элемент, отображаемый, когда плагин активен. HTMLElement true

Передайте конфигурации плагинов как defaults.plugins при вызове initMeeting. В 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 true
name Отображаемое имя в панели плагинов. string true
icon URL-адрес значка, отображаемый рядом с именем. string true
permissions Определяет, может ли локальный участник активировать или деактивировать плагин. { canActivate: boolean; canDeactivate: boolean } true
component Объект с src URL-адрес для отображения, когда плагин активен. { src: string } true

Передайте pluginConfigs список в RtkMeetingInfo. SDK загружает для каждого плагина url напрямую в WebView при активации плагина.

val meetingInfo = RtkMeetingInfo(
	authToken = "<auth_token>",
	pluginConfigs = 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 true
name Отображаемое имя в списке плагинов. String true
icon URL-адрес значка, отображаемый рядом с именем. String true
url URL-адрес, загружаемый в WebView плагина, когда плагин активен. String true
permissions Определяет, может ли локальный участник активировать или деактивировать плагин. RtkClientPluginPermissions true

Передайте pluginConfigs массив в RtkMeetingInfo. SDK загружает для каждого плагина url напрямую в WebView при активации плагина.

let meetingInfo = RtkMeetingInfo(
	authToken: "<auth_token>",
	pluginConfigs: [
		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 true
name Отображаемое имя в списке плагинов. String true
icon URL-адрес значка, отображаемый рядом с именем. String true
url URL-адрес, загружаемый в WebView плагина, когда плагин активен. String true
permissions Определяет, может ли локальный участник активировать или деактивировать плагин. RtkClientPluginPermissions true

Активация и деактивация плагина

Активация находится на 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

A Plugin объект представляет собой отдельный плагин. Вы получаете его из одной из коллекций в meeting.plugins.

Свойство Описание Тип
id Идентификатор плагина с пространством имён в формате {meetingId}:{configId}. string
name Отображаемое имя плагина. string
icon URL-адрес значка или data URI. string
permissions Разрешения на активацию для локального участника. { canActivate: boolean; canDeactivate: boolean }
component Элемент, отображаемый, когда плагин активен. HTMLElement
active Запущен ли плагин в данный момент. boolean
enabledBy ID участника, который активировал плагин. string
Свойство Описание Тип
id Идентификатор плагина с пространством имён в формате {meetingId}:{configId}. String
name Отображаемое имя плагина. String
icon URL-адрес значка. String
permissions Разрешения на активацию для локального участника. RtkClientPluginPermissions

Пока плагин активен, вызывайте getPluginView() чтобы получить Android WebView который его размещает, и sendData(eventName, data) чтобы передавать данные в этот WebView.

Свойство Описание Тип
id Идентификатор плагина с пространством имён в формате {meetingId}:{configId}. String
name Отображаемое имя плагина. String
icon URL-адрес значка. String
permissions Разрешения на активацию для локального участника. RtkClientPluginPermissions

Пока плагин активен, вызывайте getPluginView() чтобы получить WKWebView который его размещает, и sendData(eventName:data:) чтобы передавать данные в этот WebView.

Свойство Описание Тип
id Идентификатор плагина с пространством имён в формате {meetingId}:{configId}. string
name Отображаемое имя плагина. string
icon URL-адрес значка. string
permissions Разрешения на активацию для локального участника. { canActivate: boolean; canDeactivate: boolean }
component Объект, предоставленный при регистрации. Содержит src URL-адрес, который загружает ваш слой рендеринга. { src: string }
active Запущен ли плагин в данный момент. boolean
enabledBy ID участника, который активировал плагин. string

Прослушивайте события плагина

A Plugin объект генерирует события при изменении своего состояния. Вы можете подписаться на события одного плагина или на карту, чтобы получать события всех плагинов, которые она содержит.

Событие Описание
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 чтобы получать события плагина.

Callback Описание
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)

Соответствует RtkPluginsEventListener и зарегистрировать обработчик для получения событий плагина.

Callback Описание
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(self)

Отрисовка плагинов

Если вы используете UI Kit, RealtimeKit предоставляет готовые компоненты для плагинов:

Эти компоненты считывают данные из meeting.plugins, поэтому они автоматически отражают состояние плагина после того, как вы зарегистрируете свои плагины при инициализации.

Когда плагин активен, getPluginView() возвращает Android WebView который его размещает. Добавьте это представление в свой макет, чтобы отобразить плагин.

val plugin = meeting.plugins.active.firstOrNull() ?: return

// Returns an Android WebView you can add to your layout
val pluginView = plugin.getPluginView()

Когда плагин активен, getPluginView() возвращает WKWebView который его размещает. Добавьте это представление в иерархию представлений, чтобы отобразить плагин.

guard let plugin = meeting.plugins.active.first else { return }

// Returns a WKWebView you can add to your view hierarchy
let pluginView = plugin.getPluginView()

React Native UI Kit предоставляет готовые компоненты для плагинов:

Эти компоненты считывают данные из meeting.plugins автоматически после регистрации плагинов при инициализации. Если вы используете RtkMeeting, интерфейс плагина включается без какой-либо дополнительной настройки.