Publique sua extensão

Esta página explica como você pode publicar uma extensão no Extensions Hub.

Antes de você começar

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

Fontes verificáveis

Todas as extensões publicadas no Extensions Hub devem ter uma fonte verificável publicamente. Em vez de fazer upload do código-fonte da extensão diretamente para o Extensions Hub, você especifica o local de origem e o Extension Hub fará o download e o criará a partir daí.

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

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

  • Os usuários podem inspecionar o código-fonte da revisão específica da extensão que será instalada.
  • Você pode garantir que carregará apenas o que pretende carregar e não, por exemplo, trabalho em andamento ou arquivos perdidos 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 de suas extensões, o que facilita o teste de suas extensões e o processo de instalação de extensões no mesmo ambiente em que elas serão lançadas.

Essa capacidade possibilita um ciclo de desenvolvimento como o seguinte:

  1. Desenvolva e itere rapidamente sua extensão usando o Firebase Emulator Suite .

  2. Teste sua extensão em um projeto real instalando-a a partir de uma fonte local:

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

  3. Carregue uma versão de pré-lançamento no Extensions Hub (veja abaixo). Distribua o link de instalação para testes mais amplos e itere carregando mais versões de pré-lançamento conforme necessário.

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

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

Carregar uma nova extensão

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

  1. Opcional : envie seu código para um repositório público do GitHub.

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

    GitHub

    firebase ext:dev:upload your_publisher_id/your_extension_id

    Fonte local

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

    Na invocação do comando, você especifica o seguinte:

    • O ID do editor que você registrou .

    • Uma string de 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á informações adicionais:

    • Se você estiver fazendo upload do GitHub:

      • A URL para o repositório da extensão no GitHub. Observe que um repositório pode conter múltiplas 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 sua extensão.

      • A referência Git do commit a partir do qual você deseja construir a fonte da versão da extensão. Pode ser um hash de commit, tag ou nome de branch.

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

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

      O estágio stable é usado para lançamentos públicos a serem publicados no Extensions Hub. O upload de uma versão stable iniciará automaticamente uma revisão e, se for aprovada, publicará a extensão.

    Observe que você não especifica um número de versão — esse valor vem do arquivo extension.yaml . Ao fazer 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 upload de um release candidate, isso resultará na versão 1.0.1-rc.0 ; carregar outro release candidate da mesma versão aumentaria automaticamente a contagem, resultando em 1.0.1-rc.1 e assim por diante.

Agora que carregou uma versão de pré-lançamento da extensão, você pode compartilhá-la 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 passando a string de ID da extensão para o comando ext:install :

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

Carregar uma versão atualizada

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

Para carregar uma atualização:

  1. Opcional : envie seu código para um repositório Git público.

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

    GitHub

    firebase ext:dev:upload your_publisher_id/your_extension_id

    Desta vez, você não será solicitado a especificar o repositório GitHub ou o diretório raiz da extensão, pois eles já foram configurados para sua extensão. Se você refatorou a estrutura do seu repositório ou migrou para um novo repositório, poderá alterá-los com os argumentos de comando --root e --repo .

    Fonte local

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

Envie uma extensão para publicação

Quando você estiver pronto para lançar publicamente sua extensão:

  1. Envie seu código para um repositório Git público. (Obrigatório para lançamentos públicos.)

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

    firebase ext:dev:upload your_publisher_id/your_extension_id

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

    Se você carregou a primeira versão estável da extensão, encontre-a no painel do editor e clique em Publicar no Extensions Hub .

Depois de enviada, a revisão pode levar alguns dias. Se aceita, a extensão será publicada no Extensions Hub. Se for rejeitado, você receberá uma mensagem explicando o motivo; você poderá então resolver os problemas relatados e reenviá-los para revisão.

Para agilizar a revisão e aumentar suas chances de aprovação na primeira tentativa, antes de enviar, verifique o seguinte:

  • Você testou exaustivamente sua extensão e o processo de instalação.
  • Sua documentação está completa e correta e funciona bem no console do Firebase.
  • O nome e a marca do editor identificam você de forma clara e precisa como editor.
  • O nome, a descrição e o ícone da sua extensão representam de forma clara e precisa a finalidade da sua extensão.
  • Você aplicou tags úteis e precisas.
  • Você declarou em extension.yaml todas as APIs do Google e de terceiros que você usa e todos os tipos de eventos que sua extensão emite.
  • Você está solicitando acesso apenas às funções necessárias para o funcionamento da extensão e explicou claramente aos usuários por que precisa desse acesso.
  • Seus arquivos de origem estão claramente licenciados sob os termos do Apache-2.0 .

Gerenciar extensões enviadas e publicadas

Liste suas extensões enviadas

Para listar as extensões que você enviou com seu ID de editor, siga um destes procedimentos:

Painel do editor

Visualize-os no painel do editor .

CLI do Firebase

Execute o comando ext:dev:list :

firebase ext:dev:list your_publisher_id

Ver o uso das extensões enviadas

Para visualizar o uso das extensões que você enviou com seu ID de editor, siga um destes procedimentos:

Painel do editor

O painel do editor possui 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

Descontinuar uma versão de uma extensão

Em algum momento, você pode querer descontinuar uma versão antiga da sua extensão. Por exemplo, se você lançar uma nova versão que corrija um bug crítico ou atualize uma dependência com uma atualização de segurança importante, é importante impedir que novos usuários instalem uma versão antiga e incentivar os usuários existentes a atualizarem.

Para descontinuar 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 a visualização de detalhes.
  2. Selecione a versão que você deseja descontinuar.
  3. Clique em Versão obsoleta .

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.*

Versões obsoletas de uma extensão não estão listadas no Extensions Hub e não podem ser instaladas. Os usuários cujos projetos possuem uma versão obsoleta instalada verão uma mensagem incentivando-os a atualizar; eles ainda podem usar e reconfigurar a extensão enquanto isso.

Se todas as versões de uma extensão forem obsoletas, 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 aceitação, a publicará no Extensions Hub novamente.

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: Solução de problemas de erros de compilação

Quando você carrega sua extensão, o back-end primeiro cria seu código-fonte usando o seguinte processo:

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

  2. Instala dependências do NPM executando npm clean-install em cada diretório de origem de função especificado em extension.yaml (consulte sourceDirectory em recursos do Cloud Function ).

    Observe o seguinte:

    • Cada arquivo package.json deve ter um arquivo package-lock.json correspondente. Para obter 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 construção do seu código-fonte depende de scripts pós-instalação, refatore-o antes de fazer upload.

  3. Constrói seu código executando npm run build em cada diretório de origem de função especificado em extension.yaml .

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

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