Каждое расширение должно иметь документацию, которая учит пользователей тому, что делает расширение и как его использовать.
Минимальная необходимая документация — это набор из трех файлов уценки:
-
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
) - Краткое описание последствий для выставления счетов (начните с шаблонного текста ).
Где этот контент отображается пользователю?
- На странице расширения на Extensions.dev .
- Репозиторий исходного кода вашего расширения (внутри каталога расширений).
- Как часть README расширения (если вы используете интерфейс командной строки Firebase
)--markdown > README.md
Файлы PREINSTALL
не могут получить доступ к значениям параметров расширения, поэтому не следует ожидать, что ссылки на параметры будут отображаться с фактическими значениями.
Каковы некоторые лучшие практики?
- По возможности сохраняйте полное содержимое файла
PREINSTALL
на одной странице . - Обеспечьте уровень детализации, который абсолютно необходимо знать конечному пользователю перед установкой расширения.
- Поместите подробные инструкции в файл
POSTINSTALL
или другие дополнительные файлы. - Кратко укажите, предоставляете ли вы другие инструменты или сценарии для поддержки расширения.
Мы рекомендуем использовать как можно больше следующего шаблонного текста, применимого к вашему расширению. Мы предоставили несколько примеров, но наиболее важным моментом является обеспечение перечисления всех оплачиваемых услуг 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
должно быть кратким, но информативным. - Разделите контент, используя заголовки, чтобы разделить отдельные задачи или концепции.
- Рассмотрите возможность публикации подробных инструкций для конкретного рабочего процесса или задачи на своем веб-сайте ( пример ) или в дополнительных файлах уценки в репозитории расширений ( пример ).
- Ссылайтесь на параметры и переменные, связанные с функциями , чтобы пользователь видел их настроенные значения в контексте инструкций.
Ссылки на параметры и переменные
После установки консоль 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} | ||
Имя окончательно развернутой функции, включающее идентификатор экземпляра расширения. | Общий формат: Пример значения: | |
${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, особенно для первоначального тестирования вашего расширения. Например, предположим, что ваше расширение создает новый документ Cloud Firestore каждый раз, когда создается новый пользователь аутентификации Firebase. Вы можете поручить своим пользователям протестировать установленный экземпляр вашего расширения, вручную добавив нового пользователя аутентификации в консоли. Затем они смогут просмотреть новый документ, созданный в разделе консоли 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 и интерфейс командной строки отображают только те изменения, которые вступят в силу, если пользователь завершит обновление.
- Репозиторий исходного кода вашего расширения (внутри каталога расширения).