ページにカスタムアクションボタンを表示

アドオン、拡張機能、またはサードパーティのサイトでホストされる追加のインターフェースを構築できます。 各アクションは、ユーザーがOwncastページでボタンを押すと読み込まれ、表示される単一のURLまたはカスタムHTMLです。

Plugin action buttons require Owncast v0.3.0

Plugins can also contribute action buttons alongside the ones you register by hand. See the plugin manifest documentation.

例

この機能の例として、以下のようなものが考えられます：

1. あなたが作ったチャットベースのゲーム用のリーダーボード、またはストリームで遊んでいる外部ゲーム。
2. 選択されたときにあなたのストリームオーバーレイで楽しいアニメーションを実行するアクションのリスト。
3. 最近の投票と結果を表示するあなたの投票チャットボットとの統合。
4. 寄付を受け取るためのチップジャー。
5. Markdownで表現できるよりも fancy でインタラクティブなスケジュール。

制限事項

1. 外部アクションを介して埋め込まれたURLは、SSLをサポートし、httpsプロトコルを持つサーバーでホストされる必要があります。 安全でないURLはサポートされていません。
2. これらのURLはiframe内での表示をサポートする必要があります。 これは、X-FRAME-OPTIONSとCSPがブロックされてはいけないことを意味します。 ブロックされている場合、URLを新しいタブで読み込むことに制限され、その経験はあまり良くありません。
3. 制御していないURLを使用することを試みることはできますが、リモートサーバーにかけられた制限により、これらの多くが機能しないことがよくあります。 その例として、PayPalまたはGoogleのURLを単純に投げ込むことが挙げられます。

アクションを登録する方法

1. 管理者に訪問し、「統合」項目の下で「外部アクション」ページに移動します。
2. アクションを追加します。
3. このアクションのURLまたはカスタムHTMLを設定します。 URLはHTTPSの宛先であり、リストされているベストプラクティスに従っている必要があります。
4. このアクションを起動するボタンに表示される名前、オプションの説明（アクションを提示するモーダルに表示されます）、ボタンのためのオプションのアイコンのURL、オプションのボタンの色を付与します。
5. 本当に制御していないURLを登録したい場合、しかしそれがデフォルト機能でうまくいかない場合、「外部で開く」を選択して、新しいタブでブラウザーが開くようにできます。 これは最適ではありませんが、オプションです。

Query parameters passed to URL actions

When a viewer opens a URL action, Owncast appends query parameters to your URL:

• instance is always appended and holds the URL of the Owncast page the viewer is on. Useful if you host one action for multiple servers.
• username and userId are appended only when the viewer has a chat user. username is the display name, which is not unique. userId is a stable identifier for that chat user.

These parameters are conveniences, not authenticated identity. Anyone can open your URL with any values, so never grant access or make privileged API calls based on them. Use them to pre-fill forms and label sessions.

The iframe sandbox

A URL action loads inside a modal in an iframe with sandbox="allow-same-origin allow-scripts allow-popups allow-forms". Your page can run scripts, submit forms, and open popups, but it cannot navigate the top-level Owncast page or trigger downloads.

There is no postMessage bridge. An embedded action cannot close or resize the modal, and it has no way to call back into Owncast. Treat the action as a self-contained page.

ベストプラクティス

1. このアクションのUIは、ほとんどナビゲーションを行わないか、全く行わない必要があります。 単に任意のページを表示する方法として扱われるべきではありません。
2. UIを小さなウィンドウで表示し、あまりスクロールを必要としないように設計し、モバイルや小さなディスプレイに対応します。
3. あなたのURLのサーバーが、X-FRAME-OPTIONSまたはCSPを介してOwncastサーバーからのコンテンツの読み込みを許可していることを確認します。
4. The query parameters Owncast appends tell you which server and which chat user opened the action. Use them to pre-fill forms, and remember they can be faked, so never treat them as proof of identity.
5. \<style>タグを介してカスタムスタイリングを含むHTMLアクションでは、ページ内の他の要素と衝突しないようなできるだけ特定的なセレクタを持つようにしてください。
6. \<form>要素を直接埋め込むHTMLアクションでは、送信ページを新しいタブで開くためにtarget="_blank"を設定することが理にかないます。 その方が、視聴者はフォームを提出するときにストリームを停止する必要がありません。