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

每個擴充功能都必須提供說明文件，向使用者說明擴充功能內容 以及使用方式

這組共有三個 Markdown 檔案，其中至少包含必要及說明文件：

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

此外，您也應考慮製作：

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

如要瞭解一些最佳做法、常見的措辭與結構，建議你 檢閱 Cloud Storage 中 官方 Firebase 擴充功能。

建立 README

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

但 Firebase CLI 支援下列簡便指令， 自動產生 README 檔案，其中包含擷取自 extension.yaml 檔案和您的 PREINSTALL.md 檔案：

firebase ext:info ./path/to/extension --markdown > README.md

所有 README 檔案， 官方 Firebase 擴充功能 產生的輸出內容

新增安裝資訊

撰寫或產生 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 控制台中預先安裝內容

• 前往擴充功能的 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 控制台查看 (在 已安裝擴充功能的詳細資料資訊卡)

  • 請務必透過以下角色查看 POSTINSTALL 內容的顯示方式： 在實際的 專案

• 擴充功能的原始碼存放區 (位於擴充功能目錄中)

POSTINSTALL 檔案可以存取參數值和數個與函式相關的 變數的變數。POSTINSTALL 內容的顯示位置 Firebase 控制台會顯示實際值，而非參數 或變數參照進一步瞭解如何參照參數和 變數。POSTINSTALL

有哪些最佳做法？

• 盡量簡明 POSTINSTALL 檔案的完整內容。
• 利用標題區隔內容，藉此分段不同的工作或 概念。
• 建議您針對特定的 網站上的工作流程或工作 (範例) 或是在擴充功能存放區的補充 Markdown 檔案中 (範例)。
• 參考參數和函式相關 變數 這樣使用者就能在操作說明情境下看見已設定的值

參照參數和變數

安裝完成後，Firebase 控制台會顯示 擴充功能的 POSTINSTALL 檔案。如果您要參照參數和函式 變數 (請參閱下表)，然後是控制台POSTINSTALL 填入已安裝執行個體的「實際」值填入這些參照。

提示：適用於可能過長的值 (例如資料庫) 路徑或函式網址) 中，參照結尾處的參數或變數 語句和片段這項最佳做法可幫助使用者輕鬆閱讀句子 透過 Firebase 控制台取得 POSTINSTALL 檔案的內容 並以實際值轉譯

使用POSTINSTALL 以下語法：${param:PARAMETER_NAME}

您也可以在 僅限 POSTINSTALL 檔案。Firebase 支援這些變數，因此您可以 安裝後，使用者將能輕鬆獲得指引。因為 可在 POSTINSTALL 檔案中使用，因為這些變數的值 。

在此表格中，function-name 是 name 欄位 函式的資源物件。extension.yaml

函式相關變數的參考資料	說明	變數值 (安裝擴充功能後，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 函式)
	最終 deployed 函式的網址，用戶端程式碼可前往 發出 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 控制台，特別是用於擴充功能的初步測試。適用對象 舉例來說，假設您的擴充功能每次都會建立新的 Cloud Firestore 文件 建立新的 Firebase 驗證使用者。您可以指示使用者測試 手動新增驗證使用者，取得擴充功能的已安裝執行個體 。如此一來，他們就能觀察 控制台的「Cloud Firestore」區段

新增用戶端程式碼

在適用情況下，您也可以指示使用者如何新增用戶端程式碼 觸發額外資訊請將使用者導向官方說明文件 所需的 API 設定您也可以加入範例應用程式 彙整的用戶端範例，可協助您的使用者將擴充功能整合至自己的 應用程式 (請參閱 Distributed Counter 擴充功能 範例)。

HTTP 要求觸發的擴充功能

如此一來，您的使用者就能觸發 HTTP 要求觸發的函式 (以及 擴充功能，您需提供 deployed 函式的 name 或其狀態 網址：

最終部署的函式名稱與 name 你 extension.yaml 的函式資源物件中指定的。目的地： 可在專案中針對同一個擴充功能進行多次安裝：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}`**.
  

重要事項： 在使用者開始使用要求觸發的擴充功能之前， 而必須讓部署的擴充功能函式可公開存取。 欲為使用者提供的詳細操作說明，請參閱樣板文字 範例。

寫入 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 只會顯示 才會生效。
• 擴充功能的原始碼存放區 (位於擴充功能目錄中)。