每個擴充功能都必須有文件來指導使用者該擴充功能的用途以及如何使用它。
最低要求的文件是這組三個 Markdown 文件:
-
PREINSTALL.md
-
POSTINSTALL.md
-
CHANGELOG.md
此外,您還應該考慮生產:
- 擴充公共儲存庫的
README
文件。 - 在您自己的網站上發布並在
PREINSTALL.md
中連結的較長形式的教程、指南和參考。
要了解一些最佳實踐以及常見的措辭和結構,我們建議您查看官方 Firebase 擴充功能提供的文件。
創建自述文件
您的擴充目錄可以選擇包含自述文件。請注意, firebase ext:dev:init
指令不會自動為您產生一個。
不過,Firebase CLI 確實支援以下便利命令來自動產生README
文件,其中包含從extension.yaml
文件和PREINSTALL.md
文件中提取的內容:
firebase ext:info ./path/to/extension --markdown > README.md
官方 Firebase 擴充功能的所有自述文件都是使用此命令產生的。
新增安裝訊息
編寫或產生自述文件後,請向其中新增安裝資訊。您可以使用以下程式碼片段作為模板:
--- ## 🧩 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
) - 任何計費影響的簡要描述(從樣板文字開始)
該內容在哪裡向用戶顯示?
- 在Extensions.dev的擴充頁面上。
- 您的擴充功能的原始碼儲存庫(在擴充目錄內)
- 作為擴充自述文件的一部分(如果您使用 Firebase CLI
)--markdown > README.md
標誌
PREINSTALL
檔案無法存取擴充的參數值,因此您不應期望參數引用以實際值呈現。
有哪些最佳實務?
- 如果可能的話,將
PREINSTALL
檔案的完整內容保留在一頁以內 - 提供最終用戶在安裝擴充功能之前絕對需要了解的詳細信息
- 將詳細說明放在
POSTINSTALL
文件或其他補充文件中 - 簡要提及您是否提供其他工具或腳本來支援擴展
我們建議盡可能使用以下樣板文本,只要適用於您的擴充功能即可。我們提供了一些範例,但最重要的一點是確保列出所有 Google 和非 Google 計費服務。
您可以使用以下資源找到正確的產品定價詳細資訊:
對於所有擴充程序,請包含此部分以幫助您的用戶了解計費影響:
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 控制台中(在已安裝擴充功能的詳細資訊卡中)
- 確保透過在實際專案中安裝擴充功能來檢查
POSTINSTALL
內容的顯示。
- 確保透過在實際專案中安裝擴充功能來檢查
您的擴充功能的原始碼儲存庫(在擴充目錄內)
POSTINSTALL
檔案可以存取擴充的參數值和幾個與函數相關的變數。當POSTINSTALL
內容顯示在 Firebase 控制台中時,將顯示實際值而不是參數或變數參考。以下詳細了解如何在POSTINSTALL
檔案中引用參數和變數。
有哪些最佳實務?
- 保持
POSTINSTALL
文件的完整內容簡潔但具有描述性。 - 使用標題對內容進行劃分,以分解不同的任務或概念。
- 考慮在您的網站(範例)或擴充儲存庫中的補充 Markdown 文件(範例)中發布特定工作流程或任務的詳細說明。
- 參考參數和功能相關變量,以便使用者在指令上下文中看到其配置值
引用參數和變數
安裝後,Firebase 控制台會顯示擴充的POSTINSTALL
檔案的內容。如果您在POSTINSTALL
檔案中引用參數和與函數相關的變數(請參閱下表),則控制台會使用已安裝實例的實際值填入這些參考。
使用以下語法存取POSTINSTALL
檔案中配置的參數值:${param: PARAMETER_NAME }
您也可以僅在POSTINSTALL
檔案中引用以下與函數相關的變數。 Firebase 支援這些變量,以便您可以更輕鬆地在安裝後為使用者提供指導。它們只能在POSTINSTALL
檔案中使用,因為這些變數的值只有在安裝後才可用。
在此表中, function-name是extension.yaml
內函數資源物件中name
欄位的值。
函數相關變數參考 | 描述 | 變數值(擴充安裝後由 Firebase 自動填入) |
---|---|---|
${function: function-name .location} | ||
功能部署位置 | 範例值:us-central1 | |
${function: function-name .name} | ||
最終部署的函數的名稱,其中包括擴展的實例 ID | 通用格式: 範例值: | |
${function: function-name .url} (僅適用於 HTTP 函數) | ||
最終部署函數的 URL,客戶端程式碼可以向其發出 HTTP 請求 | 通用格式: 範例值: |
我們建議盡可能使用以下樣板文本,只要適用於您的擴充功能即可。
對於所有擴展,請包含以下部分以幫助您的用戶監控其安裝的擴展:
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 驗證使用者時,您的擴充功能都會建立一個新的 Cloud Firestore 文件。您可以透過在控制台中手動新增的身份驗證使用者來指示使用者測試已安裝的擴充實例。然後,他們可以觀察在控制台的 Cloud Firestore 部分中建立的新文件。
新增客戶端程式碼
如果適用,您還可以指導使用者如何新增客戶端程式碼來觸發您的擴充。您應該引導使用者查看他們需要使用的 API 的官方文件。您還可以包含範例應用程式或編譯的客戶端範例,以協助您的使用者將擴充功能整合到他們的應用程式中(有關範例,請參閱分散式計數器擴充功能)。
為了讓您的使用者可以觸發 HTTP 請求觸發的函數(以及擴充),您需要向他們提供已部署函數的名稱或其URL 。
最終部署的函數的名稱與您在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}`**.
寫入 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 僅顯示使用者完成升級時將生效的變更。
- 您的擴充功能的原始碼儲存庫(在擴充目錄內)。