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