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

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

這組共有三個 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)
  • 任何帳單影響的簡短說明 (開頭為 樣板文字)

使用者會在哪裡看到這項內容?

「<span class=」中預先安裝內容的圖片Firebase 控制台">
Firebase 控制台中預先安裝內容

<span class= 中預先安裝內容的大型圖片Firebase 控制台">

PREINSTALL 檔案無法存取擴充功能的參數值,因此你 參數參照會實際顯示實際值。

有哪些最佳做法?

  • PREINSTALL 檔案的完整內容維持在一個頁面。 可以的話
  • 提供使用者絕對必要的資訊詳細程度 再安裝擴充功能
  • POSTINSTALL 檔案或其他檔案中加入詳細操作說明 補充檔案
  • 簡單提及,如果您提供其他工具或指令碼來支持 擴充功能

寫入 POSTINSTALL 檔案

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

這個檔案包含哪些內容?

  • 安裝後工作中必要的詳細操作說明。 例如設定 Firebase 安全性規則或新增用戶端程式碼 (範例)
  • 說明如何立即試用 已安裝的擴充功能 (例如:「前往控制台,然後執行此項目」)
  • 如何觸發擴充功能的基本資訊,尤其是 HTTP 要求觸發的擴充功能
  • 監控已安裝擴充功能的簡要指示 (開頭是 樣板文字)

使用者會在哪裡看到這項內容?

「<span class=」中安裝後內容的圖片Firebase 控制台">
Firebase 控制台中的安裝後內容

<span class=&quot; 中安裝後內容的大型圖片Firebase 控制台">

  • 使用者安裝擴充功能後,透過 Firebase 控制台開啟 (在 已安裝擴充功能的詳細資料資訊卡)

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

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

有哪些最佳做法?

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

參照參數和變數

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

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

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

在此表格中,function-namename 欄位 函式的資源物件,範圍為 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 檔案。 如要瞭解如何提供這些操作說明,請展開下方段落, 適用於額外資訊

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