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

每項擴充功能都必須提供說明文件，教導使用者擴充功能的功能和使用方式。

最低限度的必要文件是下列三組 Markdown 檔案：

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

此外，您也應考慮製作：

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

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

建立 README

擴充功能目錄可以選擇性包含 README。請注意，firebase ext:dev:init 指令不會自動為您產生這個變數。

不過，Firebase CLI 支援下列便利指令，可自動產生 README 檔案，其中包含從 extension.yaml 檔案和 PREINSTALL.md 檔案擷取的內容：

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}
	最終部署函式的名稱，包括擴充功能的例項 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 官方文件。您也可以加入範例應用程式或編譯的用戶端範例，協助使用者將擴充功能整合至應用程式 (請參閱Distributed Counter 擴充功能的範例)。

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