为扩展程序创建用户文档

每个扩展程序都必须提供一些文档来向用户说明扩展程序的用途和使用方法。

必须至少提供下面三个 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 文件可以访问该扩展程序的参数值和多个函数相关变量。当 Firebase 控制台中显示 POSTINSTALL 内容时，将显示实际值，而不是参数或变量引用。下文详细介绍了如何在 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 Callable (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 只会显示用户完成当前升级后生效的更新内容。
• 扩展程序的源代码库（在扩展程序目录中）。