← Cloudflare Realtime / realtime / realtimekit / core

Pluginy

Tento návod vysvětluje, jak pomocí Cloudflare RealtimeKit Core SDK registrovat, aktivovat a vykreslovat pluginy ve schůzce.

Pluginy jsou interaktivní realtime aplikace, které běží uvnitř schůzky, například sdílená tabule nebo prohlížeč dokumentů. Jakmile účastník plugin aktivuje, stane se aktivním pro všechny v dané relaci.

Modul Plugins

Objekt pluginů schůzky je dostupný na meeting.plugins. Poskytuje dvě kolekce Plugin objekty:

all: každý plugin dostupný lokálnímu účastníkovi.
active: pluginy, které aktuálně běží v relaci.

// 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);

Použijte useRealtimeKitSelector hook pro reaktivní čtení pluginů. Hook funguje pouze tehdy, když je strom vašich komponent obalený v 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 }

Použijte useRealtimeKitSelector hook pro reaktivní čtení pluginů.

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));

Zaregistrujte plugin

Pluginy dostupné v relaci registrujete při inicializaci SDK. Každá konfigurace poskytuje metadata, která RealtimeKit používá k zobrazení pluginu v seznamu a k načtení jeho umístění.

Předejte pole konfigurací pluginů jako defaults.plugins. Každá konfigurace poskytuje metadata, která RealtimeKit používá k uvedení pluginu v seznamu a component se vykresluje.

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 je HTMLElement. rtk-plugin-main komponenta ji promítne do rozvržení schůzky, takže styly vaší aplikace budou nadále platit.

Každá konfigurace pluginu přijímá následující pole:

Pole	Popis	Typ	Povinné
`id`	Jedinečný identifikátor pluginu. SDK k němu přidává předponu `{meetingId}:` a vytvořit tak `plugin.id`.	`string`	true
`name`	Zobrazované jméno v panelu pluginů.	`string`	true
`icon`	URL ikony nebo datové URI zobrazené vedle jména.	`string`	true
`permissions`	Určuje, zda může lokální účastník aktivovat nebo deaktivovat plugin.	`{ canActivate: boolean; canDeactivate: boolean }`	true
`component`	Element vykreslený, když je plugin aktivní.	`HTMLElement`	true

Předejte konfigurace pluginů jako defaults.plugins při volání initMeeting. V React Native component by měl být objekt s src vlastnost obsahující URL k vykreslení. Tu můžete načíst do WebView nebo použijte UI Kit, který vykreslování zajistí automaticky.

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/" },
      },
    ],
  },
});

Každá konfigurace pluginu přijímá následující pole:

Pole	Popis	Typ	Povinné
`id`	Jedinečný identifikátor pluginu. SDK k němu přidává předponu `{meetingId}:` a vytvořit tak `plugin.id`.	`string`	true
`name`	Zobrazované jméno v panelu pluginů.	`string`	true
`icon`	URL ikony zobrazené vedle jména.	`string`	true
`permissions`	Určuje, zda může lokální účastník aktivovat nebo deaktivovat plugin.	`{ canActivate: boolean; canDeactivate: boolean }`	true
`component`	Objekt s `src` URL k vykreslení, když je plugin aktivní.	`{ src: string }`	true

Předejte pluginConfigs seznam na RtkMeetingInfo. SDK načte u každého pluginu url přímo do WebView, jakmile je plugin aktivován.

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,
			),
		),
	),
)

Každá konfigurace pluginu přijímá následující pole:

Pole	Popis	Typ	Povinné
`id`	Jedinečný identifikátor pluginu. SDK k němu přidává předponu `{meetingId}:` a vytvořit tak `plugin.id`.	`String`	true
`name`	Zobrazované jméno v seznamu pluginů.	`String`	true
`icon`	URL ikony zobrazené vedle jména.	`String`	true
`url`	URL adresa načtená do WebView pluginu, když je plugin aktivní.	`String`	true
`permissions`	Určuje, zda může lokální účastník aktivovat nebo deaktivovat plugin.	`RtkClientPluginPermissions`	true

Předejte pluginConfigs pole na RtkMeetingInfo. SDK načte u každého pluginu url přímo do WebView, jakmile je plugin aktivován.

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
			)
		)
	]
)

Každá konfigurace pluginu přijímá následující pole:

Pole	Popis	Typ	Povinné
`id`	Jedinečný identifikátor pluginu. SDK k němu přidává předponu `{meetingId}:` a vytvořit tak `plugin.id`.	`String`	true
`name`	Zobrazované jméno v seznamu pluginů.	`String`	true
`icon`	URL ikony zobrazené vedle jména.	`String`	true
`url`	URL adresa načtená do WebView pluginu, když je plugin aktivní.	`String`	true
`permissions`	Určuje, zda může lokální účastník aktivovat nebo deaktivovat plugin.	`RtkClientPluginPermissions`	true

Aktivace a deaktivace pluginu

Aktivace se nachází na Plugin. Volání activate() povolí plugin pro všechny účastníky relace a deactivate() ho deaktivuje pro všechny. Obě metody respektují nastavení 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()

Objekt Plugin

A Plugin představuje jeden plugin. Získáte jej z kterékoli kolekce v meeting.plugins.

Vlastnost	Popis	Typ
`id`	ID pluginu s oborem názvů ve tvaru `{meetingId}:{configId}`.	`string`
`name`	Zobrazované jméno pluginu.	`string`
`icon`	URL ikony nebo datové URI.	`string`
`permissions`	Oprávnění k aktivaci pro místního účastníka.	`{ canActivate: boolean; canDeactivate: boolean }`
`component`	Element vykreslený, když je plugin aktivní.	`HTMLElement`
`active`	Zda je plugin aktuálně spuštěný.	`boolean`
`enabledBy`	ID účastníka, který aktivoval plugin.	`string`

Vlastnost	Popis	Typ
`id`	ID pluginu s oborem názvů ve tvaru `{meetingId}:{configId}`.	`String`
`name`	Zobrazované jméno pluginu.	`String`
`icon`	URL ikony.	`String`
`permissions`	Oprávnění k aktivaci pro místního účastníka.	`RtkClientPluginPermissions`

Dokud je plugin aktivní, volejte getPluginView() a získat tak Android WebView která ji hostuje, a sendData(eventName, data) a odeslat tak data do daného WebView.

Vlastnost	Popis	Typ
`id`	ID pluginu s oborem názvů ve tvaru `{meetingId}:{configId}`.	`String`
`name`	Zobrazované jméno pluginu.	`String`
`icon`	URL ikony.	`String`
`permissions`	Oprávnění k aktivaci pro místního účastníka.	`RtkClientPluginPermissions`

Dokud je plugin aktivní, volejte getPluginView() a získat tak WKWebView která ji hostuje, a sendData(eventName:data:) a odeslat tak data do daného WebView.

Vlastnost	Popis	Typ
`id`	ID pluginu s oborem názvů ve tvaru `{meetingId}:{configId}`.	`string`
`name`	Zobrazované jméno pluginu.	`string`
`icon`	URL ikony.	`string`
`permissions`	Oprávnění k aktivaci pro místního účastníka.	`{ canActivate: boolean; canDeactivate: boolean }`
`component`	Objekt poskytnutý při registraci. Obsahuje `src` URL, kterou načítá vaše vykreslovací vrstva.	`{ src: string }`
`active`	Zda je plugin aktuálně spuštěný.	`boolean`
`enabledBy`	ID účastníka, který aktivoval plugin.	`string`

Naslouchejte událostem pluginu

A Plugin emituje události při změně svého stavu. Můžete naslouchat jednomu pluginu, nebo mapě a přijímat události pro každý plugin, který obsahuje.

Událost	Popis
`stateUpdate`	Emitováno, když se plugin aktivuje nebo deaktivuje.
`enabled`	Emitováno, když se plugin aktivuje pro místního účastníka.
`closed`	Emitováno, když se plugin deaktivuje pro místního účastníka.
`ready`	Emitováno, když je plugin připraven k použití.

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);
});

Zaregistrujte RtkPluginsEventListener a přijímat tak události pluginu.

Callback	Popis
`onPluginActivated`	Volá se, když je plugin aktivován pro všechny účastníky.
`onPluginDeactivated`	Volá se, když je plugin deaktivován pro všechny účastníky.
`onPluginMessage`	Volá se, když plugin odešle zprávu aplikaci.
`onPluginFileRequest`	Volá se, když plugin požaduje soubor od aplikace.

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)

Přizpůsobte se RtkPluginsEventListener a zaregistrujte listener pro příjem událostí pluginu.

Callback	Popis
`onPluginActivated`	Volá se, když je plugin aktivován pro všechny účastníky.
`onPluginDeactivated`	Volá se, když je plugin deaktivován pro všechny účastníky.
`onPluginMessage`	Volá se, když plugin odešle zprávu aplikaci.
`onPluginFileRequest`	Volá se, když plugin požaduje soubor od aplikace.

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)

Vykreslit pluginy

Pokud používáte UI Kit, RealtimeKit poskytuje předpřipravené komponenty pro pluginy:

rtk-plugins-toggle: tlačítko na ovládací liště, které otevírá a zavírá postranní panel s pluginy.
rtk-plugins: seznam dostupných pluginů s ovládacími prvky pro aktivaci nebo deaktivaci každého z nich.
rtk-plugin-main: vykresluje component aktivního pluginu v rozložení schůzky.

Tyto komponenty čtou z meeting.plugins, takže po zaregistrování pluginů při inicializaci automaticky odrážejí jejich stav.

Když je plugin aktivní, getPluginView() vrací Android WebView která jej hostuje. Přidejte toto zobrazení do svého layoutu, aby se plugin zobrazil.

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

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

Když je plugin aktivní, getPluginView() vrací WKWebView která jej hostuje. Přidejte toto zobrazení do hierarchie zobrazení, aby se plugin zobrazil.

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 poskytuje předpřipravené komponenty pro pluginy:

RtkPluginsToggle: tlačítko na ovládací liště, které otevírá a zavírá postranní panel s pluginy.
RtkPlugins: panel se seznamem dostupných pluginů a ovládacími prvky pro aktivaci nebo deaktivaci každého z nich.
RtkPluginMain: vykresluje aktivní plugin v WebView.

Tyto komponenty čtou z meeting.plugins automaticky poté, co jsou pluginy zaregistrovány při inicializaci. Pokud používáte RtkMeeting, je UI pluginu součástí bez jakéhokoli dalšího nastavování.