Опубликуйте свое расширение

На этой странице объясняется, как опубликовать расширение в Extensions Hub.

Прежде чем начать

Чтобы опубликовать расширение, сначала вам необходимо зарегистрироваться в качестве издателя расширений .

Проверяемые источники

Все расширения, опубликованные на Extensions Hub, должны иметь публично проверяемый источник. Вместо того, чтобы загружать исходный код расширения напрямую на Extensions Hub, вы указываете местоположение источника, а Extension Hub загрузит его и построит оттуда.

В настоящее время это означает размещение исходного кода вашего расширения в публичном репозитории GitHub.

Загрузка из проверяемого источника имеет несколько преимуществ:

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

Рекомендуемый цикл разработки

Инструменты разработки Firebase Extensions поддерживают загрузку предварительных версий ваших расширений, что упрощает тестирование ваших расширений и процесса установки расширений в той же среде, в которой они в конечном итоге будут выпущены.

Эта возможность делает возможным следующий цикл разработки:

  1. Разрабатывайте и быстро совершенствуйте свое расширение с помощью Firebase Emulator Suite .

  2. Протестируйте свое расширение в реальном проекте, установив его из локального источника:

    firebase ext:install /path/to/extension
firebase deploy --only extensions

  3. Загрузите предварительную версию в Extensions Hub (см. ниже). Распространите ссылку на установку для более широкого тестирования и повторяйте процесс, загружая больше предварительных версий по мере необходимости.

  4. Загрузите финальную, стабильную версию в Extensions Hub (см. ниже) и отправьте ее на проверку. Если расширение пройдет проверку, оно будет опубликовано в Extension Hub.

  5. Увеличьте номер версии в extension.yaml и повторите этот цикл для следующей версии вашего расширения.

Загрузить новое расширение

Чтобы загрузить расширение в первый раз:

  1. Необязательно : отправьте свой код в публичный репозиторий GitHub.

  2. Запустите команду Firebase CLI ext:dev:upload :

    GitHub 

    firebase ext:dev:upload your_publisher_id/your_extension_id

    Местный источник 

    cd /path/to/extension
firebase ext:dev:upload your_publisher_id/your_extension_id --local

    При вызове команды вы указываете следующее:

    • Идентификатор издателя, который вы зарегистрировали .

    • Строка идентификатора, которая будет идентифицировать расширение. Называйте расширения в следующем формате: firebase-product - description-of-tasks-performed . Например: firestore-bigquery-export

    Команда запросит у вас дополнительную информацию:

    • Если вы загружаете с GitHub:

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

        При первой загрузке нового расширения репозиторий будет зарегистрирован как канонический источник вашего расширения.

      • Каталог в репозитории, содержащий ваше расширение.

      • Ссылка Git на коммит, из которого вы хотите построить исходный код версии расширения. Это может быть хэш коммита, тег или имя ветки.

    • Стадия выпуска загружаемой вами версии.

      Стадии alpha , beta и rc (release candidate) предназначены для загрузки предварительных версий для установки тестировщиками. Используйте одну из этих стадий для первоначальной загрузки нового расширения.

      stable этап используется для публичных релизов, публикуемых на Extensions Hub. Загрузка stable релиза автоматически инициирует проверку, и, если она пройдет, расширение будет опубликовано.

    Обратите внимание, что вы не указываете номер версии — это значение берется из файла extension.yaml . Когда вы загружаете предварительную версию расширения, номер этапа и загрузки добавляется к версии. Например, если extension.yaml указывает версию 1.0.1 и вы загружаете релиз-кандидат, это приведет к версии 1.0.1-rc.0 ; загрузка другого релиз-кандидата той же версии автоматически увеличит счетчик, что приведет к 1.0.1-rc.1 и т. д.

Теперь, когда вы загрузили предварительную версию расширения, вы можете поделиться ею с другими для тестирования. Пользователи могут установить ваше расширение одним из двух способов:

  • С помощью консоли : пользователи могут установить расширение, щелкнув ссылку в следующем формате:

    https://console.firebase.google.com/project/_/extensions/install?ref=your_publisher_id/your_extension_id@version

    Вы можете поделиться прямой ссылкой со своими тестерами.

  • С помощью CLI : пользователи могут установить расширение, передав строку идентификатора расширения команде ext:install :

    firebase ext:install your_publisher_id/your_extension_id@version \
    --project=destination_project_id

Загрузить обновленную версию

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

Чтобы загрузить обновление:

  1. Необязательно : зафиксируйте свой код в публичном репозитории Git.

  2. Запустите команду Firebase CLI ext:dev:upload :

    GitHub 

    firebase ext:dev:upload your_publisher_id/your_extension_id

    На этот раз вам не будет предложено указать репозиторий GitHub или корневой каталог расширения, поскольку они уже настроены для вашего расширения. Если с тех пор вы рефакторили структуру репозитория или перешли на новый репозиторий, вы можете изменить их с помощью аргументов команды --root и --repo .

    Местный источник 

    cd /path/to/extension
firebase ext:dev:upload your_publisher_id/your_extension_id --local

Отправить расширение для публикации

Когда вы будете готовы публично опубликовать свое расширение:

  1. Зафиксируйте свой код в публичном репозитории Git. (Требуется для публичных релизов.)

  2. Запустите команду Firebase CLI ext:dev:upload , указав в качестве стадии выпуска stable :

    firebase ext:dev:upload your_publisher_id/your_extension_id

  3. Если вы ранее опубликовали версию своего расширения, загрузка новой стабильной версии автоматически отправит расширение на проверку.

    Если вы загрузили первую стабильную версию расширения, найдите расширение на панели инструментов издателя и нажмите «Опубликовать в Extensions Hub» .

После отправки рассмотрение может занять несколько дней. Если расширение будет принято, оно будет опубликовано в Extensions Hub. Если оно будет отклонено, вы получите сообщение с объяснением причины; затем вы сможете устранить указанные проблемы и повторно отправить его на рассмотрение.

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

  • Вы тщательно протестировали свое расширение и процесс установки.
  • Ваша документация полная и корректная и хорошо отображается в консоли Firebase.
  • Имя и бренд вашего издателя четко и точно идентифицируют вас как издателя.
  • Название, описание и значок вашего расширения четко и точно отражают его назначение.
  • Вы применили полезные и точные теги.
  • Вы объявили в extension.yaml все используемые вами API Google и сторонних API, а также все типы событий, которые генерирует ваше расширение.
  • Вы запрашиваете доступ только к тем ролям, которые необходимы для функционирования расширения, и четко объяснили пользователям, зачем вам нужен такой доступ.
  • Ваши исходные файлы явно лицензированы в соответствии с условиями Apache-2.0 .

Управление загруженными и опубликованными расширениями

Перечислите загруженные вами расширения

Чтобы вывести список расширений, загруженных вами под вашим идентификатором издателя, выполните одно из следующих действий:

Панель инструментов издателя

Просмотрите их на панели инструментов издателя .

Firebase CLI

Выполните команду ext:dev:list :

firebase ext:dev:list your_publisher_id

Просмотр использования загруженных вами расширений

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

Панель инструментов издателя

Панель управления издателя содержит совокупные показатели использования для всех ваших расширений, а также индивидуальные показатели для каждого расширения.

Firebase CLI

Выполните команду ext:dev:usage : 

firebase ext:dev:usage your_publisher_id

Отменить поддержку версии расширения

В какой-то момент вам может понадобиться отменить поддержку старой версии вашего расширения. Например, если вы выпускаете новую версию, которая исправляет критическую ошибку или обновляет зависимость с важным обновлением безопасности, важно не допустить установки старой версии новыми пользователями и побудить существующих пользователей обновиться.

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

Панель инструментов издателя

  1. На панели инструментов издателя щелкните расширение, чтобы открыть представление сведений о нем.
  2. Выберите версию, которую вы хотите отменить.
  3. Нажмите Устаревшая версия .

Firebase CLI

Выполните команду ext:dev:deprecate : 

firebase ext:dev:deprecate your_publisher_id/your_extension_id versions \
    [--message "deprecation_message"]

Вы можете указать одну версию или диапазон версий. Примеры:

  • 1.0.2
  • 1.1.0-1.1.7
  • <1.2.0
  • 1.1.*

Устаревшие версии расширения не перечислены в Extensions Hub и не могут быть установлены. Пользователи, чьи проекты имеют установленную устаревшую версию, увидят сообщение, призывающее их обновиться; в то же время они могут использовать и перенастраивать расширение.

Если каждая версия расширения устарела, расширение считается устарелым и будет удалено из Extensions Hub. Загрузка новой версии устаревшего расширения автоматически инициирует проверку и после принятия снова опубликует ее в Extensions Hub.

Чтобы отменить устаревание, используйте панель управления издателя или выполните команду ext:dev:undeprecate Firebase CLI: 

firebase ext:dev:undeprecate your_publisher_id/your_extension_id versions

Приложение: Устранение ошибок сборки

Когда вы загружаете свое расширение, бэкэнд сначала создает ваш исходный код, используя следующий процесс:

  1. Клонирует ваш репозиторий GitHub и проверяет указанную исходную ссылку.

  2. Устанавливает зависимости NPM, запуская npm clean-install в каждом исходном каталоге функции, указанном в extension.yaml (см. sourceDirectory в ресурсах облачных функций ).

    Обратите внимание на следующее:

    • Каждый файл package.json должен иметь соответствующий файл package-lock.json . Для получения дополнительной информации см. npm-ci .

    • Скрипты после установки не будут запущены во время установки зависимостей. Если исходный код вашей сборки зависит от скриптов после установки, выполните рефакторинг перед загрузкой.

  3. Собирает ваш код, запуская npm run build в каждом исходном каталоге функции, указанном в extension.yaml .

В окончательном пакете расширения, который будет предоставлен для общего доступа, будет сохранен только корневой каталог вашего расширения.

Если при загрузке расширения возникают ошибки сборки, повторите описанные выше шаги сборки локально в новом каталоге до тех пор, пока не исчезнут ошибки, а затем повторите загрузку.