どの拡張機能にも、その機能と使用方法をユーザーに知らせるためのドキュメントが必要です。
最低限必要なドキュメントは、次の 3 つのマークダウン ファイルのセットです。
PREINSTALL.mdPOSTINSTALL.mdCHANGELOG.md
さらに、以下のものを作成することも検討してください。
- 拡張機能の公開リポジトリの
READMEファイル。 - 独自のウェブサイト上で公開され、
PREINSTALL.mdにリンクされているチュートリアル、ガイド、リファレンス。
ベスト プラクティス、一般的なフレーズや構造については、公式の Firebase 拡張で利用できるファイルをご覧ください。
README の作成
拡張機能ディレクトリには、README を含めることができます。firebase ext:dev:init コマンドで README が自動的に生成されるわけではありません。
Firebase CLI では、extension.yaml ファイルと PREINSTALL.md ファイルから取得した内容を含む README ファイルを自動生成する次の便利なコマンドがサポートされています。
firebase ext:info ./path/to/extension --markdown > README.md
公式の Firebase 拡張のすべての README ファイルは、このコマンドを使用して作成されます。
インストール情報を追加する
README を作成または生成したら、そこにインストール情報を追加します。次のスニペットをテンプレートとして使用できます。
--- ## 🧩 Install this extension ### Console [][install-link] [install-link]: https://console.firebase.google.com/project/_/extensions/install?ref=publisher_id/extension_name ### Firebase CLI ```bash firebase ext:install publisher_id/extension_name --project=[your-project-id] ``` > Learn more about installing extensions in the Firebase Extensions documentation: > [console](https://firebase.google.com/docs/extensions/install-extensions?platform=console), > [CLI](https://firebase.google.com/docs/extensions/install-extensions?platform=cli) ---
PREINSTALL ファイルの作成
PREINSTALL ファイルには、「マーケティング」ページの一種である拡張機能の概要が記載されます。
このファイルの内容
- 拡張機能についてのまとめ
- データベースの設定や Google 以外のサービスへのアクセスなどの前提条件のリスト（例）
- インストールの事前準備とその手順に関する簡単な説明
- インストール後に必要な作業（例）に関する簡単な説明（詳細な手順は
POSTINSTALLをご覧ください） - 請求による影響の簡単な説明（定型文から始まる）
この内容が表示される場所
Firebase コンソール">
Firebase コンソール">
- 拡張機能のページの extensions.dev。
- 拡張機能のソースコード リポジトリ（拡張機能ディレクトリ内）
- 拡張機能の README の一部として（Firebase CLI の
--markdown > README.md
PREINSTALL ファイルは拡張機能のパラメータ値にアクセスできないため、パラメータ参照が実際の値でレンダリングされることはありません。
ベスト プラクティス
- 可能であれば、
PREINSTALLファイルの内容全体を 1 ページ未満にまとめます - エンドユーザーが拡張機能をインストールする前に必ず知っておくべき情報を詳細に提供します
- 詳細な手順は
POSTINSTALLファイルまたはその他の補助ファイルに記述します - 拡張機能をサポートする他のツールやスクリプトを提供するかどうかを簡潔に説明します
POSTINSTALL ファイルの作成
POSTINSTALL ファイルは、拡張機能のインストール後の手順について詳しく説明するページです。
このファイルの内容
- Firebase セキュリティ ルールの設定やクライアント側コードの追加など、インストール後の必須作業の詳細な手順（例）
- インストールされた拡張機能をすぐに試すための一般的な手順（「コンソールに移動して、これを行います」など）
- 拡張機能、特に HTTP リクエスト トリガー型拡張機能のトリガー方法に関する基本情報
- インストールされた拡張機能をモニタリングする方法の簡単な説明（定型文から始まる）
この内容が表示される場所
Firebase コンソール">
Firebase コンソール">
ユーザーが拡張機能をインストールした後の Firebase コンソール（インストールされた拡張機能の詳細カード）
- 実際のプロジェクトに拡張機能をインストールして、
POSTINSTALLコンテンツの表示を確認してください。
- 実際のプロジェクトに拡張機能をインストールして、
拡張機能のソースコード リポジトリ（拡張機能ディレクトリ内）
POSTINSTALL ファイルは、拡張機能のパラメータ値と複数の関数関連の変数にアクセスできます。Firebase コンソールに POSTINSTALL の内容が表示されると、パラメータや変数の参照ではなく実際の値が表示されます。詳しくは、POSTINSTALL ファイルでパラメータと変数を参照する方法をご覧ください。
ベスト プラクティス
POSTINSTALLファイルの内容全体は簡潔でありながら、わかりやすいものにします。- 見出しを使って内容を分類し、タスクやコンセプトを分割します
- 特定のワークフローやタスクの詳細な手順は、ウェブサイト（例）や、拡張機能リポジトリ内の補足のマークダウン ファイル（例）で公開することを検討してください。
- パラメータと関数関連の変数を参照して、ユーザーが構成した値を手順に沿って確認できるようにします
パラメータと変数の参照
インストール後、Firebase コンソールに拡張機能の POSTINSTALL ファイルの内容が表示されます。パラメータと関数関連の変数（下の表を参照）を POSTINSTALL ファイルで参照すると、その参照に対応する、インストール済みインスタンスの実際の値がコンソールに表示されます。
POSTINSTALL ファイル内の構成済みパラメータ値にアクセスするには、次の構文を使用します。${param:PARAMETER_NAME}
また、次の関数関連の変数をPOSTINSTALL ファイル内でのみ参照することもできます。Firebase はこの変数をサポートしているため、インストール後の作業をユーザーにより簡単に提供できます。この変数の値はインストール後まで使用できないため、POSTINSTALL ファイルでのみ使用できます。
この表の function-name は、extension.yaml 内の関数のリソース オブジェクトの name フィールドの値です。
| 関数関連の変数のリファレンス | 説明 | 変数値（拡張機能のインストール後に Firebase によって自動入力） |
|---|---|---|
${function:function-name.location}
|
||
| 関数のデプロイ先の場所 |
値の例:us-central1
|
|
${function:function-name.name}
|
||
| 拡張機能のインスタンス ID が含まれる、最後にデプロイされた関数の名前 |
一般的な形式:
値の例: |
|
${function:function-name.url}
（HTTP 関数にのみ適用）
|
||
| クライアント側コードによる HTTP リクエストの作成先である、最後にデプロイされた関数の URL |
一般的な形式:
値の例: |
|
拡張機能をトリガーする方法の文書化
拡張機能のユーザー ドキュメントで、拡張機能をトリガーする方法をユーザーに説明する必要があります。説明は必要に応じて詳細に記述できますが、POSTINSTALL ファイルを作成するためのベスト プラクティスの記載を忘れないでください。説明については、下記から拡張機能に該当する項目をご覧ください。
CHANGELOG ファイルの作成
このファイルの内容
すべての拡張機能には、公開した各拡張機能の新しいバージョンに含まれる変更が記載された CHANGELOG.md ファイルが必要です。各バージョンをレベル 2 のヘッダー（##）に配置します。それ以外の場合は、任意の Markdown 形式を使用できます。
次の例は、公式の拡張機能の 1 つからの抜粋です。
## Version 0.1.3 feature - Support deletion of directories (issue #148). ## Version 0.1.2 feature - Add a new param for recursively deleting subcollections in Cloud Firestore (issue #14). fixed - Fixed "cold start" errors experienced when the extension runs after a period of inactivity (issue #48). ## Version 0.1.1 Initial release of the _Delete User Data_ extension.
この内容が表示される場所
- Firebase コンソールと CLI で、ユーザーが拡張機能の新しいバージョンにアップグレードしたとき。Firebase コンソールと CLI には、ユーザーがアップグレードを完了した場合に有効になる変更のみが表示されます。
- 拡張機能のソースコード リポジトリ（拡張機能のディレクトリ内）