Создайте пользовательскую документацию для вашего расширения.

Каждое расширение должно иметь документацию, объясняющую пользователям, что делает расширение и как его использовать.

Минимальная требуемая документация — это набор из трех файлов разметки:

  • 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

Все файлы 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">

  • На странице расширения extensions.dev .
  • Репозиторий исходного кода для вашего расширения (внутри каталога расширения)
  • Как часть README расширения (если вы используете 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-запросами
  • Краткие инструкции по мониторингу установленного расширения (начните со стандартного текста )

Где этот контент отображается для пользователя?

Изображение содержимого после установки в <span class= Консоль Firebase">
Пост-установочный контент в консоли Firebase

Большое изображение содержимого после установки в <span class= Консоль Firebase">

  • В консоли Firebase после того, как пользователь установит ваше расширение (в карточке сведений об установленном расширении)

  • Репозиторий исходного кода для вашего расширения (внутри каталога расширения)

Файлы POSTINSTALL могут получать доступ к значениям параметров и нескольким переменным, связанным с функциями, для расширения. Когда содержимое POSTINSTALL отображается в консоли Firebase , отображаются фактические значения , а не ссылки на параметры или переменные. Узнайте больше ниже о том, как ссылаться на параметры и переменные в файле POSTINSTALL .

Каковы некоторые передовые практики?

  • Содержимое файла POSTINSTALL должно быть кратким, но описательным.
  • Разделите контент, используя заголовки, чтобы разбить отдельные задачи или концепции.
  • Рассмотрите возможность публикации подробных инструкций для конкретного рабочего процесса или задачи на вашем веб-сайте ( пример ) или в дополнительных файлах разметки в репозитории расширений ( пример ).
  • Справочные параметры и переменные, связанные с функциями, чтобы пользователь мог видеть их настроенные значения в контексте инструкций.

Ссылочные параметры и переменные

После установки консоль Firebase отображает содержимое файла POSTINSTALL расширения. Если вы ссылаетесь на параметры и переменные, связанные с функциями (см. таблицу ниже) в вашем файле POSTINSTALL , то консоль заполняет эти ссылки фактическими значениями для установленного экземпляра.

Доступ к настроенным значениям параметров в файле POSTINSTALL осуществляется с помощью следующего синтаксиса: ${param: PARAMETER_NAME }

Вы также можете ссылаться на следующие переменные, связанные с функциями, только в вашем файле POSTINSTALL . Firebase поддерживает эти переменные, чтобы вам было проще предоставлять рекомендации пользователям после установки. Они доступны для использования только в файле POSTINSTALL , поскольку значения для этих переменных доступны только после установки.

В этой таблице function-name — это значение поля name в объекте ресурса функции в extension.yaml .

Ссылка на функциональную переменную Описание Значение переменной (автоматически заполняется Firebase после установки расширения)
${function: function-name .location}
Место, где развернута функция Пример значения:
us-central1
${function: function-name .name}
Имя окончательно развернутой функции, включающее идентификатор экземпляра расширения

Обобщенный формат:
ext- extension-instance-id - function-name

Пример значения:
ext-my-awesome-extension-6m31-yourFunctionName

${function: function-name .url} (применимо только для HTTP-функций)
URL-адрес окончательно развернутой функции, к которой клиентский код может отправлять 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

Мы рекомендуем использовать как можно больше следующего шаблонного текста, применимого к вашему расширению.

Для всех расширений включите следующий раздел, чтобы помочь пользователям контролировать установленные расширения:

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 Authentication . Вы можете поручить своим пользователям протестировать установленный экземпляр вашего расширения, вручную добавив нового пользователя Authentication в консоль. Затем они смогут наблюдать за новым документом, созданным в разделе Cloud Firestore консоли.

Добавить клиентский код

Если применимо, вы также можете проинструктировать своих пользователей о том, как добавить клиентский код для запуска вашего расширения. Вам следует направить пользователей к официальной документации по API, которые им нужно будет использовать. Вы также можете включить примеры приложений или скомпилированные примеры клиентов, чтобы помочь вашим пользователям интегрировать расширение в свое приложение (см. пример расширения Distributed Counter ).

Чтобы ваши пользователи могли активировать функцию, активируемую HTTP-запросом (и, следовательно, расширение), вам необходимо предоставить им имя развернутой функции или ее URL-адрес .

Имя окончательно развернутой функции не совпадает с 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 отображают только те изменения, которые вступят в силу, если пользователь завершит обновление.
  • Репозиторий исходного кода вашего расширения (внутри каталога расширения).