Publicar sua extensão

Nesta página, explicamos como você pode publicar uma extensão no Extensions Hub.

Antes de começar

Para publicar uma extensão, primeiro você precisa se registrar como um editor de extensões.

Fontes verificáveis

Todas as extensões publicadas no Extensions Hub precisam ter uma origem verificável publicamente. Em vez de fazer upload do código-fonte da extensão diretamente para o Hub de extensões, você especifica o local de origem, e o Hub de extensões faz o download e o cria neste local.

Atualmente, isso significa disponibilizar o código-fonte da extensão em um repositório público do GitHub.

Fazer upload de uma fonte verificável tem vários benefícios:

  • Os usuários podem inspecionar o código-fonte da revisão específica da extensão que será instalada.
  • É possível fazer o upload apenas do que você pretende enviar e não, por exemplo, de trabalho em andamento nem de arquivos órfãos restantes do desenvolvimento.

Ciclo de desenvolvimento recomendado

As ferramentas de desenvolvimento de Extensões do Firebase oferecem suporte ao upload de versões de pré-lançamento das suas extensões, o que facilita o teste das extensões e o processo de instalação no mesmo ambiente em que serão lançadas.

Esse recurso possibilita um ciclo de desenvolvimento como o seguinte:

  1. Desenvolva e itere rapidamente sua extensão usando o Pacote de emuladores do Firebase.

  2. Instale a extensão de uma fonte local para testá-la em um projeto real:

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

  3. Faça upload de uma versão de pré-lançamento no Extensions Hub (confira abaixo). Distribua o link de instalação para testes mais amplos e repita o upload fazendo o upload de mais versões de pré-lançamento conforme necessário.

  4. Faça upload da versão final estável no Extensions Hub (confira abaixo) e envie-a para revisão. Se a extensão for aprovada na revisão, ela será publicada no Extension Hub.

  5. Incremente o número da versão em extension.yaml e repita esse ciclo para a próxima versão da sua extensão.

Fazer upload de uma nova extensão

Para fazer o upload de uma extensão pela primeira vez:

  1. Opcional: confirme o código em um repositório público do GitHub.

  2. Execute o comando ext:dev:upload da CLI do Firebase:

    GitHub

    firebase ext:dev:upload your_publisher_id/your_extension_id

    Origem do local

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

    Na invocação do comando, especifique o seguinte:

    • O ID do editor que você registrou.

    • Uma string com o ID que identificará a extensão. Nomeie suas extensões com o seguinte formato: firebase-product-description-of-tasks-performed. Por exemplo: firestore-bigquery-export

    O comando solicitará mais informações:

    • Se estiver fazendo upload do GitHub:

      • O URL para o repositório da extensão no GitHub. Um repositório pode conter várias extensões, desde que cada extensão tenha uma raiz exclusiva.

        Ao fazer upload de uma nova extensão pela primeira vez, o repositório será registrado como a fonte canônica da sua extensão.

      • O diretório no repositório que contém a extensão.

      • A referência Git da confirmação a partir da qual você quer criar a origem da versão de sua extensão. Pode ser um hash de confirmação, uma tag ou um nome de ramificação.

    • O estágio de lançamento da versão que você está enviando.

      Os estágios alpha, beta e rc (candidato a lançamento) são para o upload de versões de pré-lançamento para instalação pelos testadores. Use um desses estágios para o upload inicial de uma nova extensão.

      O cenário stable é usado para que versões públicas sejam publicadas no Hub de extensões. O upload de uma versão stable iniciará automaticamente uma revisão e, se aprovada, publicará a extensão.

    Você não especifica um número de versão. Esse valor vem do arquivo extension.yaml. Quando você faz upload de uma versão de extensão de pré-lançamento, o estágio e o número de upload são anexados à versão. Por exemplo, se extension.yaml especificar a versão 1.0.1 e você fizer o upload de uma versão candidata a lançamento, isso resultará na versão 1.0.1-rc.0. Fazer upload de outra versão candidata a lançamento da mesma versão incrementará automaticamente a contagem, resultando em 1.0.1-rc.1 e assim por diante.

Agora que você fez upload de uma versão de pré-lançamento da extensão, ela pode ser compartilhada com outras pessoas para teste. Os usuários podem instalar sua extensão de duas maneiras:

  • Com o console: os usuários podem instalar a extensão clicando em um link com o seguinte formato:

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

    Você pode compartilhar o link direto com seus testadores.

  • Com a CLI: os usuários podem instalar a extensão transmitindo a string do ID de extensão para o comando ext:install:

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

Fazer upload de uma versão atualizada

Depois de fazer upload da primeira versão de uma extensão, você poderá fazer o upload de atualizações para corrigir problemas, adicionar recursos ou avançar o estágio de lançamento. Quando você faz upload de uma nova versão, os usuários que têm uma versão mais antiga da extensão são solicitados a fazer upgrade no Console do Firebase.

Siga estas instruções para fazer upload de uma atualização:

  1. Opcional: confirme o código em um repositório Git público.

  2. Execute o comando ext:dev:upload da CLI do Firebase:

    GitHub

    firebase ext:dev:upload your_publisher_id/your_extension_id

    Desta vez, não será preciso especificar o repositório do GitHub ou o diretório raiz da extensão, porque eles já foram configurados para a extensão. Se você tiver refatorado a estrutura do repositório ou migrado para um novo repositório, altere-os com os argumentos de comando --root e --repo.

    Origem do local

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

Enviar uma extensão para publicação

Siga estas instruções quando estiver tudo pronto para lançar sua extensão publicamente:

  1. Confirme o código em um repositório Git público. Obrigatório para versões públicas.

  2. Execute o comando ext:dev:upload da CLI do Firebase, especificando stable como o estágio de lançamento:

    firebase ext:dev:upload your_publisher_id/your_extension_id

  3. Se você já tiver publicado uma versão da extensão, o upload de uma nova versão estável enviará a extensão automaticamente para revisão.

    Se você fez upload da primeira versão estável da extensão, localize a extensão no painel do editor e clique em Publicar no Hub de extensões.

Após o envio, a análise pode levar alguns dias. Se aceita, a extensão será publicada no Extensions Hub. Se rejeitada, você receberá uma mensagem explicando o motivo. Assim, você poderá resolver os problemas informados e reenviar para análise.

Para acelerar a análise e aumentar suas chances de passar na primeira tentativa, antes de enviar, verifique o seguinte:

  • Você testou por completo a extensão e o processo de instalação.
  • Sua documentação está completa e correta e é bem renderizada no Console do Firebase.
  • O nome e o branding do editor identificam você de maneira clara e precisa como editor.
  • O nome, a descrição e o ícone da extensão representam de maneira clara e precisa a finalidade dela.
  • Você aplicou tags úteis e precisas.
  • Você declarou em extension.yaml todas as APIs que você usa e que não são do Google, além de todos os tipos de evento emitidos pela extensão.
  • Você está pedindo acesso apenas aos papéis necessários para que a extensão funcione e você explicou claramente aos usuários por que precisa desse acesso.
  • Seus arquivos de origem estão claramente licenciados sob os termos de Apache-2.0.

Gerenciar extensões enviadas e publicadas

Listar suas extensões enviadas

Para listar as extensões enviadas com seu ID de editor, siga um destes procedimentos:

Painel do editor

Confira o conteúdo no painel do editor.

CLI do Firebase

Execute o comando ext:dev:list:

firebase ext:dev:list your_publisher_id

Conferir o uso das suas extensões enviadas

Para conferir o uso das extensões enviadas com seu ID de editor, siga um destes procedimentos:

Painel do editor

O painel do editor tem métricas de uso cumulativas para todas as suas extensões e métricas individuais para cada extensão.

CLI do Firebase

Execute o comando ext:dev:usage:

firebase ext:dev:usage your_publisher_id

Suspender o uso da versão de uma extensão

Em algum momento, convém suspender o uso de uma versão antiga da sua extensão. Por exemplo, se você lançar uma nova versão que corrige um bug crítico ou atualiza uma dependência com uma atualização de segurança importante, é importante evitar que novos usuários instalem uma versão antiga e incentivar os usuários existentes a fazer upgrade.

Para suspender o uso de uma versão de uma extensão, siga um destes procedimentos:

Painel do editor

  1. No painel do editor, clique na extensão para abrir os detalhes.
  2. Selecione a versão cujo uso você quer suspender.
  3. Clique em Suspender o uso da versão.

CLI do Firebase

Execute o comando ext:dev:deprecate:

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

Você pode especificar uma única versão ou um intervalo de versões. Exemplos:

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

As versões obsoletas de uma extensão não são listadas no Extensions Hub e não podem ser instaladas. Os usuários que têm projetos em uma versão obsoleta vão receber uma mensagem incentivando-os a fazer upgrade. Enquanto isso, eles vão poder usar e reconfigurar a extensão.

Se todas as versões de uma extensão forem descontinuadas, a extensão será considerada obsoleta e será removida do Extensions Hub. O upload de uma nova versão de uma extensão obsoleta iniciará automaticamente uma revisão e, após a aceitação, a publicará novamente no Extensions Hub.

Para reverter uma suspensão de uso, use o painel do editor ou execute o comando ext:dev:undeprecate da CLI do Firebase:

firebase ext:dev:undeprecate your_publisher_id/your_extension_id versions

Apêndice: como solucionar erros de versão

Quando você faz upload da extensão, o back-end primeiro cria o código-fonte usando o seguinte processo:

  1. Clona seu repositório do GitHub e verifica a referência especificada.

  2. Instala as dependências do NPM executando npm clean-install em cada diretório de origem da função especificado em extension.yaml. Consulte sourceDirectory em Recursos da função do Cloud.

    Observações:

    • Cada arquivo package.json precisa ter um arquivo package-lock.json correspondente. Para mais informações, consulte npm-ci.

    • Os scripts pós-instalação não serão executados durante a instalação da dependência. Se a versão do código-fonte depender de scripts pós-instalação, refatore-os antes de fazer upload.

  3. Cria seu código executando npm run build em todos os diretórios de origem da função especificados em extension.yaml.

Somente o diretório raiz da extensão será salvo no pacote de extensão final que será compartilhado.

Se você receber erros de build ao fazer upload da extensão, replique as etapas de compilação acima localmente em um novo diretório até que não haja erros e tente fazer o upload novamente.