Crie documentação do usuário para sua extensão

Cada extensão deve ter documentação que ensine aos usuários o que a extensão faz e como usá-la.

A documentação mínima necessária é este conjunto de três arquivos markdown:

• PREINSTALL.md
• POSTINSTALL.md
• CHANGELOG.md

Além disso, você também deve considerar produzir:

• Um arquivo README para o repositório público da extensão.
• Tutoriais, guias e referências mais longos publicados em seu próprio site e vinculados em seu PREINSTALL.md .

Para aprender algumas práticas recomendadas e frases e estruturas comuns, recomendamos revisar os arquivos disponíveis com as extensões oficiais do Firebase .

Criando um README

Seu diretório de extensão pode conter opcionalmente um README. Observe que o comando firebase ext:dev:init não gera um automaticamente para você.

A CLI do Firebase, no entanto, oferece suporte ao seguinte comando de conveniência para gerar automaticamente um arquivo README contendo conteúdo extraído de seu arquivo extension.yaml e de seu arquivo PREINSTALL.md :

firebase ext:info ./path/to/extension --markdown > README.md

Todos os arquivos README das extensões oficiais do Firebase são gerados usando este comando.

Adicione informações de instalação

Depois de escrever ou gerar um README, adicione informações de instalação a ele. Você pode usar o seguinte snippet como modelo:

---

## 🧩 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)

---

Escrevendo um arquivo PREINSTALL

O arquivo PREINSTALL é a visão geral da sua extensão, um tipo de página de “marketing”.

Qual conteúdo está neste arquivo?

• Descrição abrangente da funcionalidade da sua extensão
• Lista de pré-requisitos, como configuração de banco de dados ou acesso a um serviço que não é do Google ( exemplo )
• Breve descrição de quaisquer tarefas de pré-instalação e suas instruções
• Breve descrição de quaisquer tarefas pós-instalação ( exemplo ) (instruções detalhadas estão em POSTINSTALL )
• Breve descrição de quaisquer implicações de faturamento (comece com texto padrão )

Onde esse conteúdo é exibido para o usuário?

Pré-instalar conteúdo no console do Firebase

• Na página da extensão em extensions.dev .
• Seu repositório de código-fonte para sua extensão (dentro do diretório de extensão)
• Como parte do README da extensão (se você usar a Firebase CLI --markdown > README.md )

Os arquivos PREINSTALL não podem acessar os valores dos parâmetros da extensão, portanto, você não deve esperar que as referências dos parâmetros sejam renderizadas com valores reais.

Quais são algumas das melhores práticas?

• Mantenha o conteúdo completo do arquivo PREINSTALL em menos de uma página , se possível
• Fornece o nível de detalhe que um usuário final precisa saber antes de instalar a extensão
• Coloque instruções detalhadas no arquivo POSTINSTALL ou em outros arquivos suplementares
• Mencione brevemente se você fornece outras ferramentas ou scripts para oferecer suporte à extensão

Texto padrão útil PREINSTALL

Recomendamos usar o máximo possível do texto padrão a seguir, conforme aplicável à sua extensão. Fornecemos alguns exemplos, mas o ponto mais importante é garantir que todos os serviços cobrados do Google e de terceiros sejam listados.

Você pode usar os seguintes recursos para encontrar os detalhes corretos de preços do produto:

• Lista de preços de produtos do Google Cloud
• Visão geral de preços do Firebase

Para todas as extensões, inclua esta seção para ajudar seus usuários a entender as implicações de faturamento:

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

Escrevendo um arquivo POSTINSTALL

O arquivo POSTINSTALL é a página de instruções detalhadas de pós-instalação da sua extensão.

Qual conteúdo está neste arquivo?

• Instruções detalhadas para quaisquer tarefas pós-instalação necessárias , como configurar regras de segurança do Firebase ou adicionar código do lado do cliente ( exemplo )
• Instruções genéricas sobre como testar imediatamente a extensão instalada (por exemplo, "vá para o console e faça isto")
• Informações básicas sobre como acionar a extensão, especialmente para extensões acionadas por solicitação HTTP
• Breves instruções sobre como monitorar a extensão instalada (comece com texto padrão )

Onde esse conteúdo é exibido para o usuário?

Conteúdo pós-instalação no console do Firebase

• No Console do Firebase, depois que um usuário instala sua extensão (no cartão de detalhes da extensão instalada)

  • Certifique-se de revisar a exibição do conteúdo do POSTINSTALL instalando sua extensão em um projeto real .

• Seu repositório de código-fonte para sua extensão (dentro do diretório de extensão)

Os arquivos POSTINSTALL podem acessar os valores dos parâmetros e diversas variáveis ​​relacionadas à função para a extensão. Quando o conteúdo POSTINSTALL é exibido no console do Firebase, os valores reais são exibidos em vez das referências de parâmetros ou variáveis. Saiba mais abaixo sobre como fazer referência a parâmetros e variáveis ​​em seu arquivo POSTINSTALL .

Quais são algumas das melhores práticas?

• Mantenha o conteúdo completo do arquivo POSTINSTALL conciso, mas descritivo.
• Divida o conteúdo usando títulos para separar tarefas ou conceitos distintos.
• Considere publicar instruções detalhadas para um fluxo de trabalho ou tarefa específica em seu site ( exemplo ) ou em arquivos markdown complementares no repositório de extensão ( exemplo ).
• Parâmetros de referência e variáveis ​​relacionadas à função para que o usuário veja seus valores configurados no contexto das instruções

Referenciando parâmetros e variáveis

Após a instalação, o console do Firebase exibe o conteúdo do arquivo POSTINSTALL da extensão. Se você fizer referência a parâmetros e variáveis ​​relacionadas à função (consulte a tabela abaixo) em seu arquivo POSTINSTALL , o console preencherá essas referências com os valores reais da instância instalada.

Dica: para valores que podem ser longos (como um caminho de banco de dados ou URL de função), faça referência ao parâmetro ou variável no final das frases e seções. Essa prática recomendada facilita a leitura das frases no console do Firebase quando o conteúdo do arquivo POSTINSTALL é renderizado com valores reais.

Acesse os valores dos parâmetros configurados no arquivo POSTINSTALL usando a seguinte sintaxe: ${param: PARAMETER_NAME }

Você também pode fazer referência às seguintes variáveis ​​relacionadas à função apenas no arquivo POSTINSTALL . O Firebase oferece suporte a essas variáveis ​​para que você possa fornecer orientação mais facilmente aos usuários após a instalação. Elas só estão disponíveis para uso no arquivo POSTINSTALL porque os valores para essas variáveis ​​não estão disponíveis até depois da instalação.

Nesta tabela, function-name é o valor do campo name no objeto de recurso da função em extension.yaml .

Referência para variável relacionada à função	Descrição	Valor da variável (preenchido automaticamente pelo Firebase após a instalação da extensão)
${function: function-name .location}
	Local onde a função é implantada	Valor de exemplo: us-central1
${function: function-name .name}
	Nome da função implantada final, que inclui o ID da instância da extensão	Formato generalizado: ext- extension-instance-id - function-name Valor de exemplo: ext-my-awesome-extension-6m31-yourFunctionName
${function: function-name .url} (aplicável apenas para funções HTTP)
	URL da função final implantada , para a qual o código do cliente pode fazer solicitações HTTP	Formato generalizado: https:// deployment-location - project-id .cloudfunctions.net/ name-of-final-deployed-function Valor de exemplo: https://us-central1-project-123.cloudfunctions.net/ext-my-awesome-extension-6m31-yourFunctionName

Texto padrão útil POSTINSTALL

Recomendamos usar o máximo possível do texto padrão a seguir, conforme aplicável à sua extensão.

Para todas as extensões, inclua a seção a seguir para ajudar os usuários a monitorar as extensões instaladas:

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.

Documentando como acionar uma extensão

Na documentação do usuário da sua extensão, você precisa instruir seus usuários sobre como acionar sua extensão. Essas instruções podem ser tão detalhadas quanto você achar necessário, mas tenha em mente as práticas recomendadas para escrever um arquivo POSTINSTALL . Para obter orientação sobre como fornecer essas instruções, expanda a seção abaixo que se aplica à sua extensão.

Extensões acionadas por eventos em segundo plano

Seus usuários podem acionar uma extensão acionada por evento em segundo plano de várias maneiras, dependendo dos produtos envolvidos.

Faça alterações diretamente no console

Você pode instruir seus usuários a fazer alterações no acionamento de extensões diretamente no console do Firebase, especialmente para os testes iniciais da extensão. Por exemplo, digamos que sua extensão crie um novo documento do Cloud Firestore sempre que um novo usuário do Firebase Authentication for criado. Você pode instruir seus usuários a testar uma instância instalada de sua extensão adicionando manualmente um novo usuário de autenticação no console. Eles poderão então observar o novo documento criado na seção Cloud Firestore do console.

Adicione código do lado do cliente

Quando aplicável, você também pode instruir seus usuários sobre como adicionar código do lado do cliente para acionar sua extensão. Você deve direcionar os usuários à documentação oficial das APIs que eles precisarão usar. Você também pode incluir aplicativos de exemplo ou exemplos de clientes compilados para ajudar seus usuários a integrar a extensão em seus aplicativos (consulte a extensão Distributed Counter para ver um exemplo).

Extensões acionadas por solicitação HTTP

Para que seus usuários possam acionar uma função acionada por solicitação HTTP (e, portanto, a extensão), você precisa fornecer a eles o nome da função implantada ou seu URL .

O nome da função implantada final não é igual ao name especificado no objeto de recurso da função em extension.yaml . Para acomodar várias instalações da mesma extensão em um projeto, o Firebase renomeia a função neste formato: ext- extension-instance-id - function-name .

Os marcadores a seguir são sugestões de texto padrão para incluir no arquivo POSTINSTALL da sua extensão. Após a instalação, o console do Firebase exibe o conteúdo do arquivo POSTINSTALL e preenche essas referências com os valores reais configurados para a instância instalada. Por exemplo, se você definiu uma função chamada yourFunction , poderá incluir o seguinte (conforme aplicável):

• Para funções HTTP onRequest

  To trigger this extension, make a request to or visit the following URL:
  **`${function:yourFunction.url}`**.
  

• Para funções HTTP que podem ser chamadas ( 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}`**.
  

Importante: antes que seus usuários possam usar uma extensão acionada por solicitação HTTP, eles precisam tornar as funções implantadas para a extensão acessíveis publicamente. As instruções detalhadas a serem fornecidas aos usuários estão nos exemplos de texto padronizados acima.

Escrevendo um arquivo CHANGELOG

Qual conteúdo está neste arquivo?

Cada extensão deve ter um arquivo CHANGELOG.md que documente as alterações incluídas em cada nova versão de sua extensão publicada. Coloque cada versão sob um cabeçalho de nível 2 ( ## ); caso contrário, você pode usar qualquer formatação Markdown que desejar.

O exemplo a seguir é um trecho de uma das extensões oficiais:

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

Onde esse conteúdo é exibido para o usuário?

• No Console do Firebase e na CLI, quando os usuários fazem upgrade para novas versões da sua extensão. O Console do Firebase e a CLI exibem apenas as alterações que entrariam em vigor se o usuário concluísse o upgrade.
• O repositório de código-fonte da sua extensão (dentro do diretório de extensão).