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

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

最低限必要なドキュメントは、次の 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 コンソールのプリインストール コンテンツ

<span class=Firebase コンソール">

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

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

ベスト プラクティス

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

POSTINSTALL ファイルの作成

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

このファイルの内容

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

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

インストール後のコンテンツが表示されている <span class=Firebase コンソール">
Firebase コンソールのインストール後のコンテンツ

インストール後のコンテンツの拡大画像(<span class=Firebase コンソール">

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

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

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 が含まれる、最後にデプロイされた関数の名前

一般的な形式:
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 ファイルを作成するためのベスト プラクティスの記載を忘れないでください。説明については、下記から拡張機能に該当する項目をご覧ください。

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