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

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

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

• PREINSTALL.md
• POSTINSTALL.md
• CHANGELOG.md

Кроме того, вам также следует рассмотреть возможность производства:

• Файл README для общедоступного репозитория расширения.
• Подробные учебные пособия, руководства и ссылки опубликованы на вашем веб-сайте и связаны с вашим PREINSTALL.md .

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

Создание README

Каталог расширений может дополнительно содержать README. Обратите внимание, что команда firebase ext:dev:init не создает ее автоматически.

Однако интерфейс командной строки Firebase поддерживает следующую удобную команду для автоматического создания файла 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 )
• Краткое описание последствий для выставления счетов (начните с шаблонного текста ).

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

Предварительная установка контента в консоли Firebase

• На странице расширения на Extensions.dev .
• Репозиторий исходного кода вашего расширения (внутри каталога расширений).
• Как часть README расширения (если вы используете интерфейс командной строки Firebase --markdown > README.md )

Файлы PREINSTALL не могут получить доступ к значениям параметров расширения, поэтому не следует ожидать, что ссылки на параметры будут отображаться с фактическими значениями.

Каковы некоторые лучшие практики?

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

Полезный шаблонный текст PREINSTALL

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

  • Обязательно проверьте отображение содержимого POSTINSTALL , установив расширение в реальный проект .

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

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

Каковы некоторые лучшие практики?

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

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

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

Совет: Для значений, которые могут быть длинными (например, путь к базе данных или URL-адрес функции), ссылайтесь на параметр или переменную в конце предложений и разделов. Эта передовая практика упрощает чтение предложений в консоли Firebase, когда содержимое файла 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

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

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

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

Расширения, активируемые HTTP-запросом

Чтобы ваши пользователи могли запускать функцию, запускаемую 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}`**.
  

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