メインコンテンツへスキップ

プラグインのクイックスタート

The quickest way to build a plugin is with the JavaScript or Python SDK. Pick a tab below and follow it through installation. To use Rust, TinyGo, AssemblyScript, Zig, or another compiled language instead, see Native WebAssembly.

前提条件​

  • 管理できるOwncastサーバー（バージョン0.3.0以上）。
  • @owncast/plugin-sdkツールチェーン用に、Node.js 18以上（node --versionで確認可能）。

1。 新しいプラグインを作成する​

プラグインの識別子はスラグです：小文字の文字、数字、ハイフンで構成され、文字で始まります。 これはディレクトリ名、出力ファイル名、およびURLプレフィックスとして使用されます。

create-owncast-pluginを使用してプロジェクトをスキャフォールドし、スラグを渡します：

npx create-owncast-plugin@latest my-plugin
cd my-plugin
npm install

これで次のものが得られました：

my-plugin/
├── package.json
├── plugin.manifest.json     display name, slug, version, permissions
├── README.md                how to build, test, package, and install it
├── INSTRUCTIONS.md          optional, rendered as a tab in the admin
├── AGENTS.md                notes for AI coding agents
├── .agents/                 a bundled skill for AI coding agents
├── src/
│   └── plugin.js            your code, with a sample handler
└── __tests__/
    └── plugin.test.js       a sample scenario test

npm installはnode_modules/も作成します。 これらのファイルは自動的には作成されませんが、icon.png（管理者プラグインリストに表示）、public/ディレクトリ（/plugins/my-plugin/で提供される静的ファイル）、およびassets/ディレクトリ（ホストがマニフェストフィールドにインラインで追加するファイル）を追加できます。

マニフェストには人間が読み取れる表示名（"name": "My Plugin"）とスラグ（"slug": "my-plugin"）が含まれています。 表示名は管理者がリストで見るものです。 スラグは標準の識別子です。 マニフェストリファレンスでルールを確認してください。

2。 コードを書く​

ハンドラはイベントに反応します。 SDKは、あなたが定義したハンドラからマニフェストのサブスクリプションリストを派生させるため、同期する必要があるものはありません。 これがエコーボットです：

src/plugin.jsを開きます：

const { definePlugin, owncast } = require('@owncast/plugin-sdk');

module.exports = definePlugin({
  onChatMessage(msg) {
    owncast.chat.send(`echo: ${msg.body}`);
  },
});

ハンドラリファレンスを参照して、フックできるすべてのもの、APIリファレンスでowncast.*メソッドを確認してください。

3。 プラグインをビルドする​

これはプロジェクトルートにmy-plugin.ocpkgを生成します。一つのファイルにマニフェスト、コンパイルされたプラグイン、およびpublic/とassets/の内容が含まれています。 .ocpkgは配布形式です。この一つのファイルが管理者に必要なすべてです。

npm run package

4。 テストを実行する​

各シナリオは、実際のプラグインランタイムを通じてイベントを発生させ、モックされた副作用が発生します。したがって、テストが合格すれば、製品環境でも同じ動作を意味します。 テストガイドで完全なデータモデルを確認してください。

npm test

5。 （オプション）ローカル開発サーバーに対して反復実行する​

プラグインはhttp://localhost:8080/plugins/my-plugin/でサーバーし、エンドポイントをcurlしたり、ブラウザで静的ページを開いたり、/_dev/ヘルパーエンドポイントを通じてイベントハンドラをトリガーしたりします（例：POST /_dev/chat）。 コードを変更した場合、開発サーバーを再起動してください。

npm run serve

6。 サーバーにインストールする​

Owncast管理者で、サイドバーのプラグインを開き、プラグインのアップロードをクリックします。 ビルドしたmy-plugin.ocpkgファイルを選択してください。 プラグインはすぐにリストに表示されます。 有効を切り替えてロードします。

管理者用のプラグインページ、要求された権限、状態、有効化トグルを持つインストールされたプラグインのリスト、アップロードプラグインと構成ボタン

あるいは、my-plugin.ocpkgをサーバーのdata/plugins/ディレクトリにコピーし、次のスキャンで検出させることができます：

scp my-plugin.ocpkg user@your-owncast-server:/path/to/owncast/data/plugins/

プラグインが権限を宣言する場合、管理者は有効化前にプラグインの詳細ページの権限タブでそれらを確認します。 最初の有効化は承認された権限セットをキャプチャします。 If you later ship an update that asks for more access, the already-approved version keeps running with its existing permissions while the update waits as pending until the admin re-approves.

プラグインの詳細ページの権限タブ、要求された各権限の平易な説明のリスト

次に読むべきこと​

問題が発生した場合​

  • プラグインが管理者リストに表示されません。 .ocpkgがdata/plugins/にあり、単にplugins/にないこと、ファイル名が.ocpkgで終わっていることを確認してください。 管理者のプラグインページには、次のスキャン間隔を待たないためのリフレッシュボタンがあります。
  • プラグインが表示されますが、有効になりません。 管理者のプラグイン詳細ビューを確認してください。 状態列には、マニフェストが無効であるか、プラグインのインスタンス化に失敗した場合、errorと表示されます。 メッセージをホバーするか、ローカルでテストを実行して、出荷前に同じ問題を捕まえてください。
  • プラグインは有効になっていますが、何も機能しません。 正しいハンドラ名（onChatMessage / on_chat_message、onMessageではない）を使用していること、マニフェストに一致する権限が含まれていることを確認してください。 A call without its permission never reaches Owncast: the denial is logged on the server and the call returns an empty or zero value, so watch the Owncast logs.
  • プラグインは自動的に無効になっています。 5回連続してエラーを発生させるフィルタが、残りのセッションの間無効にされます。 バグを修正し、再ビルド、再デプロイ、再有効化してください。

Improve this page

See something missing or incorrect? Edit this page and improve the documentation for everyone.

Contributors to this documentation
Gabe KangasGabe Kangas