プラグイン

このガイドでは、Cloudflare RealtimeKit Core SDK を使って、ミーティング内でプラグインを登録、有効化、描画する方法を説明します。

プラグインは、共有ホワイトボードやドキュメントビューアーなど、ミーティング内で動くインタラクティブなリアルタイムアプリケーションです。参加者がプラグインを有効にすると、セッション内の全員に対して有効になります。

Plugins モジュール

meeting.plugins で、ミーティングのプラグインオブジェクトを使えます。次の 2 つの 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 フックで、プラグインをリアクティブに読み取ります。このフックは、コンポーネントツリーが 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

initMeeting を呼ぶときに、プラグイン設定を defaults.plugins として渡します。React Native では、component は描画する URL を含む src プロパティを持つオブジェクトにしてください。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

RtkMeetingInfo に pluginConfigs リストを渡します。プラグインが有効になると、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`	プラグインが有効なときに、プラグインの WebView に読み込む URL です。	`String`	true
`permissions`	ローカル参加者がプラグインを有効化・無効化できるかを制御します。	`RtkClientPluginPermissions`	true

RtkMeetingInfo に pluginConfigs 配列を渡します。プラグインが有効になると、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`	プラグインが有効なときに、プラグインの WebView に読み込む URL です。	`String`	true
`permissions`	ローカル参加者がプラグインを有効化・無効化できるかを制御します。	`RtkClientPluginPermissions`	true

プラグインの有効化と無効化

有効化は Plugin オブジェクトで行います。activate() を呼ぶと、セッション内の全参加者に対してプラグインが有効になります。deactivate() を呼ぶと、全員に対して無効になります。どちらのメソッドも、プラグインの permissions に従います。

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

Plugin オブジェクト

Plugin オブジェクトは、1 つのプラグインを表します。meeting.plugins のいずれかのコレクションから取得します。

プロパティ	説明	型
`id`	`{meetingId}:{configId}` 形式の、名前空間付きプラグイン ID です。	`string`
`name`	プラグインの表示名です。	`string`
`icon`	アイコンの URL または data URI です。	`string`
`permissions`	ローカル参加者の有効化権限です。	`{ canActivate: boolean; canDeactivate: boolean }`
`component`	プラグインが有効なときに描画する要素です。	`HTMLElement`
`active`	プラグインが現在実行中かどうかです。	`boolean`
`enabledBy`	プラグインを有効にした参加者の ID です。	`string`

プロパティ	説明	型
`id`	`{meetingId}:{configId}` 形式の、名前空間付きプラグイン ID です。	`String`
`name`	プラグインの表示名です。	`String`
`icon`	アイコンの URL です。	`String`
`permissions`	ローカル参加者の有効化権限です。	`RtkClientPluginPermissions`

プラグインが有効なあいだは、getPluginView() を呼んでホストする Android WebView を取得し、sendData(eventName, data) でその WebView にデータを送れます。

プロパティ	説明	型
`id`	`{meetingId}:{configId}` 形式の、名前空間付きプラグイン ID です。	`String`
`name`	プラグインの表示名です。	`String`
`icon`	アイコンの URL です。	`String`
`permissions`	ローカル参加者の有効化権限です。	`RtkClientPluginPermissions`

プラグインが有効なあいだは、getPluginView() を呼んでホストする WKWebView を取得し、sendData(eventName:data:) でその WebView にデータを送れます。

プロパティ	説明	型
`id`	`{meetingId}:{configId}` 形式の、名前空間付きプラグイン ID です。	`string`
`name`	プラグインの表示名です。	`string`
`icon`	アイコンの URL です。	`string`
`permissions`	ローカル参加者の有効化権限です。	`{ canActivate: boolean; canDeactivate: boolean }`
`component`	登録時に渡したオブジェクトです。描画レイヤーが読み込む `src` URL を含みます。	`{ src: string }`
`active`	プラグインが現在実行中かどうかです。	`boolean`
`enabledBy`	プラグインを有効にした参加者の ID です。	`string`

プラグインイベントをリッスンする

Plugin オブジェクトは、状態が変わるとイベントを発行します。1 つのプラグインをリッスンするか、マップをリッスンして含まれるすべてのプラグインのイベントを受け取れます。

イベント	説明
`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)

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(self)

プラグインを描画する

プラグインが有効なとき、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()