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

每個擴充功能都必須提供說明文件,讓使用者瞭解擴充功能的功能和使用方式。

必要的最低限度文件為這組三個 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)
  • 簡要說明任何結帳影響 (開頭為固定文字)

這項內容向使用者顯示的位置為何?

<span class=Firebase 控制台">
Firebase 控制台預先安裝內容

在 <span class=Firebase 主控台">

  • extensions.dev 的擴充功能頁面上。
  • 擴充功能的原始碼存放區 (位於擴充功能目錄中)
  • 做為擴充功能的 README 的一部分 (如果您使用 Firebase CLI --markdown > README.md 標記)

PREINSTALL 檔案無法存取擴充功能的參數值,因此您不應預期參數參照會以實際值顯示。

最佳做法有哪些?

  • 盡可能將 PREINSTALL 檔案的完整內容保留在一頁內
  • 提供使用者在安裝擴充功能前,必須絕對瞭解的詳細資訊
  • POSTINSTALL 檔案或其他輔助檔案中放入詳細操作說明
  • 如果您提供其他工具或指令碼來支援擴充功能,請簡短提及

寫入 POSTINSTALL 檔案

POSTINSTALL 檔案是擴充功能的詳細安裝後說明頁面。

這個檔案包含哪些內容?

  • 任何必要安裝後作業的詳細操作說明,例如設定 Firebase 安全性規則或新增用戶端程式碼 (範例)
  • 如何立即試用已安裝的擴充功能的一般操作說明 (例如「前往控制台,然後執行以下操作」)
  • 如何觸發擴充功能的基本資訊,特別是針對HTTP 要求觸發的擴充功能
  • 簡短的操作說明,說明如何監控已安裝的擴充功能 (開頭為固定文字)

這項內容向使用者顯示的位置為何?

在 <span class=Firebase 控制台">
Firebase 控制台中的安裝後內容

在 <span class=Firebase 主控台">

  • 使用者安裝擴充功能後,在 Firebase 主控台的已安裝擴充功能詳細資料卡中

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

POSTINSTALL 檔案可存取擴充功能的參數值和多個與函式相關的變數。當 POSTINSTALL 內容顯示在 Firebase 主控台時,系統會顯示實際值,而非參數或變數參照。請參閱下文,進一步瞭解如何在 POSTINSTALL 檔案中參照參數和變數

最佳做法有哪些?

  • POSTINSTALL 檔案的完整內容應簡明扼要,但具描述性。
  • 使用標題將內容分成不同工作或概念。
  • 建議您在網站 (範例) 或擴充功能存放區中的補充 Markdown 檔案 (範例) 中,發布特定工作流程或工作的詳細操作說明。
  • 參照參數和函式相關變數,讓使用者在指示內容中看到已設定的值

參照參數和變數

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

使用下列語法存取 POSTINSTALL 檔案中已設定的參數值:${param:PARAMETER_NAME}

您也可以參照下列與函式相關的變數 (僅限在 POSTINSTALL 檔案中)。Firebase 支援這些變數,方便您在安裝完成後為使用者提供指引。這些變數的值只有在安裝後才會提供,因此只能在 POSTINSTALL 檔案中使用。

在這個表格中,function-nameextension.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 檔案的最佳做法。如要瞭解如何提供這些說明,請展開下方適用於擴充功能的部分。

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