建立擴充功能的使用者說明文件

每個擴充功能都必須提供說明文件，向使用者說明擴充功能的作用和使用方式。

必要的最低限度文件為這組三個 Markdown 檔案：

• PREINSTALL.md
• POSTINSTALL.md
• CHANGELOG.md

此外，您也應考慮製作以下內容：

• 擴充功能公開存放區的 README 檔案。
• 在您自己的網站上發布較長篇幅的教學課程、指南和參考資料，並在 PREINSTALL.md 中連結這些內容。

如要瞭解一些最佳做法和常見的詞彙和結構，建議您查看官方 Firebase 擴充功能提供的檔案。

建立 README

擴充功能目錄可選擇包含 README。請注意，firebase ext:dev:init 指令不會自動產生一個。

不過，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 檔案的完整內容保留在一頁內
• 提供使用者在安裝擴充功能前，絕對需要知道的詳細資訊
• 在 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 檔案可存取擴充功能的參數值和多個與函式相關的變數。當 POSTINSTALL 內容顯示在 Firebase 主控台時，系統會顯示實際值，而非參數或變數參照。請參閱下文，進一步瞭解如何在 POSTINSTALL 檔案中參照參數和變數。

有哪些最佳做法？

• 盡量簡明 POSTINSTALL 檔案的完整內容。
• 使用標題將內容分成不同工作或概念。
• 建議您在網站 (範例) 或擴充功能存放區中的補充 Markdown 檔案 (範例) 中，發布特定工作流程或工作的詳細操作說明。
• 參照參數和函式相關變數，讓使用者在操作說明的背景中查看已設定的值

參照參數和變數

安裝完成後，Firebase 主控台會顯示擴充功能的 POSTINSTALL 檔案內容。如果您在 POSTINSTALL 檔案中參照參數和函式相關變數 (請參閱下表)，主控台會在這些參照中填入已安裝例項的實際值。

提示：如果值可能很長 (例如資料庫路徑或函式網址)，請在句子和段落結尾參照參數或變數。當 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}
	最終 deployed 函式的名稱，其中包含擴充功能的執行個體 ID	一般格式： ext-extension-instance-id-function-name 範例值： ext-my-awesome-extension-6m31-yourFunctionName
${function:function-name.url} (僅適用於 HTTP 函式)
	最終部署函式的網址，用戶端程式碼可向該網址提出 HTTP 要求	一般格式： 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 的官方說明文件。您也可以加入範例應用程式或已編譯的用戶端範例，協助使用者將擴充功能整合至應用程式 (請參閱分散式計數器擴充功能的範例)。

由 HTTP 要求觸發的擴充功能

為了讓使用者能夠觸發 HTTP 要求觸發的函式 (以及擴充功能)，您需要向他們提供已部署的函式名稱或網址。

最終部署函式的名稱與您在 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 格式。

以下範例摘錄自其中一個官方擴充功能：

## 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 只會顯示使用者完成升級後會生效的變更。
• 擴充功能的原始碼存放區 (位於擴充功能目錄中)。