拡張機能のユーザー ドキュメントを作成する

どの拡張機能にも、その機能と使用方法をユーザーに知らせるためのドキュメントが必要です。

最低限必要なドキュメントは、次の 3 つのマークダウン ファイルのセットです。

• PREINSTALL.md
• POSTINSTALL.md
• CHANGELOG.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 this extension in your Firebase project](https://www.gstatic.com/mobilesdk/210513_mobilesdk/install-extension.png "Install this extension in your Firebase project")][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 コンソールのプリインストール コンテンツ

Firebase コンソール">

• 拡張機能のページの extensions.dev。
• 拡張機能のソースコード リポジトリ（拡張機能ディレクトリ内）
• 拡張機能の README の一部として（Firebase CLI の --markdown > README.md フラグを使用する場合）

PREINSTALL ファイルは拡張機能のパラメータ値にアクセスできないため、パラメータ参照が実際の値でレンダリングされることはありません。

ベスト プラクティス

• 可能であれば、PREINSTALL ファイルの内容全体を 1 ページ未満にまとめます
• エンドユーザーが拡張機能をインストールする前に必ず知っておくべき情報を詳細に提供します
• 詳細な手順は POSTINSTALL ファイルまたはその他の補助ファイルに記述します
• 拡張機能をサポートする他のツールやスクリプトを提供するかどうかを簡潔に説明します

わかりやすい PREINSTALL の定型文

拡張機能に適用される次の定型文をできるだけ多く使用することをおすすめします。いくつか例を提示しましたが、最も重要な点は、Google の課金サービスと Google 以外の課金サービスがすべて列挙されていることです。

プロダクトの料金の詳細については、次のリソースをご覧ください。

• Google Cloud プロダクトの料金リスト
• Firebase の料金の概要

ユーザーが請求による影響を理解できるように、すべての拡張機能にこのセクションを加えます。

Billing

This extension uses other Firebase or Google Cloud services which may have
  associated charges:

*   <list Google services / products that your extension uses>
*   <list Firebase services that your extension uses>
*   Cloud Secret Manager <if the extension uses secret params>
*   Cloud Functions

When you use Firebase Extensions, you're only charged for the underlying
resources that you use. A paid-tier billing plan is only required if the
extension uses a service that requires a paid-tier plan, for example calling to
a Google Cloud API or making outbound network requests to non-Google services.
All Firebase services offer a no-cost tier of usage.
[Learn more about Firebase billing.](https://firebase.google.com/pricing)

<Applicable info about billing implications for non-Google services, such as:>
Usage of this extension also requires you to have a <non-Google-service> account.
You are responsible for any associated costs with your usage of <non-Google-service>.

POSTINSTALL ファイルの作成

POSTINSTALL ファイルは、拡張機能のインストール後の手順について詳しく説明するページです。

このファイルの内容

• Firebase セキュリティ ルールの設定やクライアント側コードの追加など、インストール後の必須作業の詳細な手順（例）
• インストールされた拡張機能をすぐに試すための一般的な手順（「コンソールに移動して、これを行います」など）
• 拡張機能、特に HTTP リクエスト トリガー型拡張機能のトリガー方法に関する基本情報
• インストールされた拡張機能をモニタリングする方法の簡単な説明（定型文から始まる）

この内容が表示される場所

Firebase コンソール">

Firebase コンソールのインストール後のコンテンツ

Firebase コンソール">

• ユーザーが拡張機能をインストールした後の Firebase コンソール（インストールされた拡張機能の詳細カード）

  • 実際のプロジェクトに拡張機能をインストールして、POSTINSTALL コンテンツの表示を確認してください。

• 拡張機能のソースコード リポジトリ（拡張機能ディレクトリ内）

POSTINSTALL ファイルは、拡張機能のパラメータ値と複数の関数関連の変数にアクセスできます。Firebase コンソールに POSTINSTALL の内容が表示されると、パラメータや変数の参照ではなく実際の値が表示されます。詳しくは、POSTINSTALL ファイルでパラメータと変数を参照する方法をご覧ください。

ベスト プラクティス

• POSTINSTALL ファイルの内容全体は簡潔でありながら、わかりやすいものにします。
• 見出しを使って内容を分類し、タスクやコンセプトを分割します
• 特定のワークフローやタスクの詳細な手順は、ウェブサイト（例）や、拡張機能リポジトリ内の補足のマークダウン ファイル（例）で公開することを検討してください。
• パラメータと関数関連の変数を参照して、ユーザーが構成した値を手順に沿って確認できるようにします

パラメータと変数の参照

インストール後、Firebase コンソールに拡張機能の POSTINSTALL ファイルの内容が表示されます。パラメータと関数関連の変数（下の表を参照）を POSTINSTALL ファイルで参照すると、その参照に対応する、インストール済みインスタンスの実際の値がコンソールに表示されます。

ヒント: 値が長くなるもの（データベース パスや関数 URL など）は、文やセクションの末尾にあるパラメータまたは変数を参照してください。これにより、POSTINSTALL ファイルの内容が実際の値でレンダリングされたときに、Firebase コンソールで文が読みやすくなります。

POSTINSTALL ファイル内の構成済みパラメータ値にアクセスするには、次の構文を使用します。${param:PARAMETER_NAME}

また、次の関数関連の変数をPOSTINSTALL ファイル内でのみ参照することもできます。Firebase はこの変数をサポートしているため、インストール後の作業をユーザーにより簡単に提供できます。この変数の値はインストール後まで使用できないため、POSTINSTALL ファイルでのみ使用できます。

この表の function-name は、extension.yaml 内の関数のリソース オブジェクトの name フィールドの値です。

関数関連の変数のリファレンス	説明	変数値（拡張機能のインストール後に Firebase によって自動入力）
${function:function-name.location}
	関数のデプロイ先の場所	値の例: us-central1
${function:function-name.name}
	拡張機能のインスタンス ID が含まれる、最後にデプロイされた関数の名前	一般的な形式: ext-extension-instance-id-function-name 値の例: ext-my-awesome-extension-6m31-yourFunctionName
${function:function-name.url} （HTTP 関数にのみ適用）
	クライアント側コードによる HTTP リクエストの作成先である、最後にデプロイされた関数の URL	一般的な形式: https://deployment-location-project-id.cloudfunctions.net/name-of-final-deployed-function 値の例: https://us-central1-project-123.cloudfunctions.net/ext-my-awesome-extension-6m31-yourFunctionName

わかりやすい POSTINSTALL の定型文

拡張機能に適用される次の定型文をできるだけ多く使用することをおすすめします。

インストールされている拡張機能をユーザーが監視できるように、すべての拡張機能に、次のセクションを加えます。

Monitoring

As a best practice, you can
[monitor the activity](https://firebase.google.com/docs/extensions/manage-installed-extensions_community#monitor)
of your installed extension, including checks on its health, usage, and logs.

拡張機能をトリガーする方法の文書化

拡張機能のユーザー ドキュメントで、拡張機能をトリガーする方法をユーザーに説明する必要があります。説明は必要に応じて詳細に記述できますが、POSTINSTALL ファイルを作成するためのベスト プラクティスの記載を忘れないでください。説明については、下記から拡張機能に該当する項目をご覧ください。

バックグラウンド イベント トリガー型拡張機能

ユーザーは、関連するプロダクトに応じて、バックグラウンド イベントによってトリガーされる拡張機能をさまざまな方法でトリガーできます。

コンソールで直接変更する

特に拡張機能の初期テストでは、Firebase コンソールで拡張機能のトリガーを直接変更するようユーザーに指示できます。たとえば、新しい Firebase Authentication ユーザーが作成されるたびに、拡張機能によって新しい Cloud Firestore ドキュメントが作成されるとします。コンソールに新しい Authentication ユーザーを手動で追加することで、拡張機能のインストール済みインスタンスをテストするようユーザーに指示できます。作成された新しいドキュメントはコンソールの Cloud Firestore セクションで確認できます。

クライアント側コードを追加する

クライアント側コードを追加して拡張機能をトリガーする方法をユーザーに示すこともできます。ユーザーが使用する必要のある API の公式ドキュメントを紹介します。また、ユーザーが拡張機能をアプリに統合できるように、サンプルアプリやコンパイル済みクライアント サンプルについて記載することもできます（Distributed Counter 拡張機能などを参照）。

HTTP リクエストでトリガーされる拡張機能

ユーザーが HTTP リクエスト トリガー型関数（拡張機能）をトリガーできるようにするには、デプロイされた関数の名前またはその URL をユーザーに提供する必要があります。

最後にデプロイされた関数の名前は、extension.yaml 内の関数のリソース オブジェクトで指定した name とは異なります。プロジェクトに同じ拡張機能が複数インストールされる場合に対応するため、Firebase は関数名を ext-extension-instance-id-function-name という形式に変更します。

拡張機能の POSTINSTALL ファイルに次の定型文を加えることをおすすめします。インストール後、Firebase コンソールに POSTINSTALL ファイルの内容が表示され、参照にはインストール済みインスタンスに構成された実際の値が表示されます。たとえば、yourFunction という名前の関数を定義した場合は、次のように追加できます（該当する場合）。

• HTTP onRequest 関数の場合

  To trigger this extension, make a request to or visit the following URL:
  **`${function:yourFunction.url}`**.
  

• HTTP 呼び出し可能（onCall）関数の場合

  This extension is implemented as an HTTP callable function. To call it from your client app,
  follow the instructions in the
  [callable functions documentation](https://firebase.google.com/docs/functions/callable#call_the_function).
  The name of the function to call is **`${function:yourFunction.name}`**,
  and its region is **`${function:yourFunction.location}`**.
  

重要: ユーザーが HTTP リクエスト トリガー型拡張機能を使用するには、その拡張機能にデプロイされた関数を一般公開する必要があります。ユーザーに提供する詳しい手順については、上記の定型文のサンプルをご覧ください。

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 には、ユーザーがアップグレードを完了した場合に有効になる変更のみが表示されます。
• 拡張機能のソースコード リポジトリ（拡張機能のディレクトリ内）