1. Antes de começar

Uma extensão do Firebase executa uma tarefa específica ou um conjunto de tarefas em resposta a solicitações HTTP ou acionamento de eventos de outros produtos do Firebase e do Google, como o Firebase Cloud Messaging, o Cloud Firestore ou o Pub/Sub.

O que você vai criar

Neste codelab, você vai criar uma extensão do Firebase para geohashing. Depois de implantada, a extensão converte as coordenadas X e Y em geohashes em resposta a eventos do Firestore ou por meio de invocações de função que podem ser chamadas. Isso pode ser usado como uma alternativa para implementar a biblioteca do Geofire em todas as plataformas de destino para armazenar dados, economizando tempo.

O que você aprenderá

• Como transformar um código do Cloud Functions em uma extensão distribuível do Firebase
• Como configurar um arquivo extension.yaml
• Como armazenar strings sensíveis (chaves de API) em uma extensão
• Como permitir que os desenvolvedores da extensão a configurem de acordo com as necessidades deles
• Como testar e implantar a extensão

O que é necessário

• CLI do Firebase (instalação e login)
• Uma Conta do Google, como uma conta do Gmail
• Node.js e npm
• Seu ambiente de desenvolvimento favorito

2. Começar a configuração

Buscar o código

Tudo o que você precisa para esta extensão está em um repositório do GitHub. Para começar, copie e abra o código no ambiente de desenvolvimento de sua preferência.

file_downloadDownload do código-fonte

1. Descompacte o arquivo ZIP transferido por download.
2. Para instalar as dependências necessárias, abra o terminal no diretório functions e execute o comando npm install.

Configurar o Firebase

Este codelab incentiva o uso de emuladores do Firebase. Se você quiser testar o desenvolvimento de extensões com um projeto real do Firebase, consulte Criar um projeto do Firebase. Este codelab usa o Cloud Functions. Se você estiver usando um projeto real do Firebase em vez dos emuladores, será necessário fazer upgrade para o plano de preços Blaze.

Quer pular para a próxima etapa?

Você pode fazer o download de uma versão concluída do codelab. Se você ficar preso no caminho ou quiser saber como é uma extensão concluída, confira a ramificação codelab-end do repositório do GitHub ou faça o download do arquivo ZIP completo.

file_downloadDownload do codelab concluído

3. Revisar o código

• Abra o arquivo index.ts do arquivo ZIP. Ele contém duas declarações do Cloud Functions.

O que essas funções fazem?

Essas funções de demonstração são usadas para geohashing. Eles pegam um par de coordenadas e o transformam em um formato otimizado para consultas geográficas no Firestore. As funções simulam o uso de uma chamada de API para que você aprenda mais sobre o processamento de tipos de dados sensíveis em extensões. Para mais informações, consulte a documentação sobre como executar consultas geográficas em dados no Firestore.

Constantes de função

As constantes são declaradas no início, na parte de cima do arquivo index.ts. Algumas dessas constantes são referenciadas nos acionadores definidos da extensão.

index.ts

import {firestore} from "firebase-functions";
import {initializeApp} from "firebase-admin/app";
import {GeoHashService, ResultStatusCode} from "./fake-geohash-service";
import {onCall} from "firebase-functions/v1/https";
import {fieldValueExists} from "./utils";

const documentPath = "users/{uid}";
const xField = "xv";
const yField = "yv";
const apiKey = "1234567890";
const outputField = "hash";

initializeApp();

const service = new GeoHashService(apiKey);

Gatilho do Firestore

A primeira função no arquivo index.ts fica assim:

index.ts

export const locationUpdate = firestore.document(documentPath)
  .onWrite((change) => {
    // item deleted
    if (change.after == null) {
      return 0;
    }
    // double check that both values exist for computation
    if (
      !fieldValueExists(change.after.data(), xField) ||
      !fieldValueExists(change.after.data(), yField)
    ) {
      return 0;
    }
    const x: number = change.after.data()![xField];
    const y: number = change.after.data()![yField];
    const hash = service.convertToHash(x, y);
    // This is to check whether the hash value has changed. If
    // it hasn't, you don't want to write to the document again as it
    // would create a recursive write loop.
    if (fieldValueExists(change.after.data(), outputField)
      && change.after.data()![outputField] == hash) {
      return 0;
    }
    return change.after.ref
      .update(
        {
          [outputField]: hash.hash,
        }
      );
  });

Essa função é um gatilho do Firestore. Quando um evento de gravação ocorre no banco de dados, a função reage a esse evento pesquisando um campo xv e um campo yv. Se ambos os campos existirem, ela vai calcular o geohash e gravar a saída em um local de saída de documento especificado. O documento de entrada é definido pela constante users/{uid}, o que significa que a função lê todos os documentos gravados na coleção users/ e processa um geohash para esses documentos. Em seguida, ele gera o hash em um campo de hash no mesmo documento.

Funções chamáveis

A próxima função no arquivo index.ts fica assim:

index.ts

export const callableHash = onCall((data, context) => {
  if (context.auth == undefined) {
    return {error: "Only authorized users are allowed to call this endpoint"};
  }
  const x = data[xField];
  const y = data[yField];
  if (x == undefined || y == undefined) {
    return {error: "Either x or y parameter was not declared"};
  }
  const result = service.convertToHash(x, y);
  if (result.status != ResultStatusCode.ok) {
    return {error: `Something went wrong ${result.message}`};
  }
  return {result: result.hash};
});

Observe a função onCall. Ele indica que essa função é uma função chamável, que pode ser chamada no código do aplicativo cliente. Essa função que pode ser chamada usa os parâmetros x e y e retorna um geohash. Embora essa função não seja chamada diretamente neste codelab, ela é incluída aqui como um exemplo de algo a ser configurado na extensão do Firebase.

4. Configurar um arquivo extension.yaml

Agora que você sabe o que o código do Cloud Functions na sua extensão faz, está tudo pronto para empacotar para distribuição. Cada extensão do Firebase vem com um arquivo extension.yaml que descreve o que ela faz e como se comporta.

Um arquivo extension.yaml requer alguns metadados iniciais sobre a extensão. Cada uma das etapas a seguir ajuda a entender o significado de todos os campos e por que eles são necessários.

1. Crie um arquivo extension.yaml no diretório raiz do projeto que você fez o download anteriormente. Comece adicionando o seguinte:

name: geohash-ext
version: 0.0.1
specVersion: v1beta  # Firebase Extensions specification version (do not edit)

O nome da extensão é usado como base do ID da instância dela. Os usuários podem instalar várias instâncias de uma extensão, cada uma com o próprio ID. Em seguida, o Firebase gera o nome das contas de serviço da extensão e dos recursos específicos dela usando esse ID de instância. O número de versão indica a versão da sua extensão. Ele precisa seguir o versionamento semântico e precisa ser atualizado sempre que você fizer mudanças na funcionalidade da extensão. A versão da especificação da extensão é usada para determinar qual especificação das extensões do Firebase seguir. Neste caso, v1beta é usado.

2. Adicione alguns detalhes fáceis de usar ao arquivo YAML:

...

displayName: Latitude and longitude to GeoHash converter
description: A converter for changing your Latitude and longitude coordinates to geohashes.

O nome de exibição é uma representação amigável do nome da sua extensão quando os desenvolvedores interagem com ela. A descrição fornece uma breve visão geral do que a extensão faz. Quando a extensão é implantada em extensions.dev, ela fica assim:

3. Especifique a licença do código na sua extensão.

...

license: Apache-2.0  # The license you want for the extension

4. Indique quem criou a extensão e se o faturamento é necessário para a instalação:

...

author:
  authorName: AUTHOR_NAME
  url: https://github.com/Firebase

billingRequired: true

A seção author é usada para informar aos usuários a quem entrar em contato caso tenham problemas com a extensão ou queiram mais informações sobre ela. billingRequired é um parâmetro obrigatório e precisa ser definido como true, já que todas as extensões dependem do Cloud Functions, que exige o plano Blaze.

Isso abrange o número mínimo de campos necessários no arquivo extension.yaml para identificar essa extensão. Para mais detalhes sobre outras informações de identificação que podem ser especificadas em uma extensão, consulte a documentação.

5. Converter o código do Cloud Functions em um recurso de extensões

Um recurso de extensão é um item que o Firebase cria no projeto durante a instalação de uma extensão. A extensão passa a ser proprietária desses recursos e tem uma conta de serviço específica que opera neles. Nesse projeto, esses recursos são funções do Cloud, que precisam ser definidas no arquivo extension.yaml porque a extensão não cria recursos automaticamente a partir do código na pasta de funções. Se as funções do Cloud não forem declaradas explicitamente como um recurso, elas não poderão ser implantadas quando a extensão for implantada.

Local de implantação definido pelo usuário

1. Permita que o usuário especifique o local em que quer implantar a extensão e decida se é melhor hospedar a extensão mais perto dos usuários finais ou do banco de dados. No arquivo extension.yaml, inclua a opção de escolher um local.

extension.yaml

Agora você está pronto para escrever a configuração do recurso de função.

2. No arquivo extension.yaml, crie um objeto de recurso para a função locationUpdate. Anexe o seguinte ao arquivo extension.yaml:

resources:
  - name: locationUpdate
    type: firebaseextensions.v1beta.function
    properties:
      eventTrigger:
        eventType: providers/cloud.firestore/eventTypes/document.write
        resource: projects/${PROJECT_ID}/databases/(default)/documents/users/{uid}

Você define o name como o nome da função definido no arquivo index.ts do projeto. Você especifica o type da função que está sendo implantada, que deve ser sempre firebaseextensions.v1beta.function, por enquanto. Em seguida, você define o properties dessa função. A primeira propriedade que você define é o eventTrigger associado a essa função. Para refletir o que a extensão oferece atualmente, use o eventType de providers/cloud.firestore/eventTypes/document.write, que está disponível na documentação Escrever funções do Cloud para sua extensão. Você define resource como o local dos documentos. Como seu objetivo atual é espelhar o que existe no código, o caminho do documento detecta users/{uid}, com o local do banco de dados padrão antes dele.

3. A extensão precisa de permissões de leitura e gravação para o banco de dados do Firestore. No final do arquivo extension.yaml, especifique os papéis do IAM aos quais a extensão precisa ter acesso para trabalhar com o banco de dados no projeto do Firebase do desenvolvedor.

roles:
  - role: datastore.user
    reason: Allows the extension to read / write to your Firestore instance.

O papel datastore.user vem da lista de papéis do IAM compatíveis com extensões. Como a extensão vai ler e gravar, o papel datastore.user é uma boa opção.

4. A função que pode ser chamada também precisa ser adicionada. No arquivo extension.yaml, crie um novo recurso na propriedade "resources". Estas propriedades são específicas para uma função que pode ser chamada:

  - name: callableHash
    type: firebaseextensions.v1beta.function
    properties:
      httpsTrigger: {}

Embora o recurso anterior tenha usado um eventTrigger, aqui você usa um httpsTrigger, que abrange funções chamáveis e HTTPS.

Verificação do código

Foi muita configuração para fazer com que o extension.yaml corresponda a tudo o que o código faz no arquivo index.ts. O arquivo extension.yaml concluído vai ficar assim:

extension.yaml

name: geohash-ext
version: 0.0.1
specVersion: v1beta  # Firebase Extensions specification version (do not edit)

displayName: Latitude and Longitude to GeoHash converter
description: A converter for changing your Latitude and Longitude coordinates to geohashes.

license: Apache-2.0  # The license you want for the extension

author:
  authorName: Sparky
  url: https://github.com/Firebase

billingRequired: true

resources:
  - name: locationUpdate
    type: firebaseextensions.v1beta.function
    properties:
      eventTrigger:
        eventType: providers/cloud.firestore/eventTypes/document.write
        resource: projects/${PROJECT_ID}/databases/(default)/documents/users/{uid}
  - name: callableHash
    type: firebaseextensions.v1beta.function
    properties:
      httpsTrigger: {}

roles:
  - role: datastore.user
    reason: Allows the extension to read / write to your Firestore instance.

Verificação de status

Neste ponto, você já configurou as partes funcionais iniciais da extensão, então pode testá-la usando os emuladores do Firebase.

1. Chame npm run build na pasta de funções do projeto de extensões baixado, se ainda não tiver feito isso.
2. Crie um novo diretório no sistema host e conecte-o ao seu projeto do Firebase usando firebase init.

cd ..
mkdir sample-proj
cd sample-proj
firebase init --project=projectID-or-alias

    This command creates a `firebase.json` file in the directory. In the following steps, you push the configuration specified in this file to Firebase.

3. No mesmo diretório, execute firebase ext:install. Substitua /path/to/extension pelo caminho absoluto do diretório que contém o arquivo extension.yaml.

firebase ext:install /path/to/extension

    This command does two things:

• Ele solicita que você especifique a configuração da instância da extensão e cria um arquivo *.env que contém as informações de configuração da instância.
• Ele adiciona a instância da extensão à seção extensions do firebase.json. Ele funciona como um mapa de ID da instância para a versão da extensão.
• Como você está implantando o projeto localmente, pode especificar que gostaria de usar um arquivo local em vez do Secret Manager do Google Cloud.

4. Inicie os emuladores do Firebase com a nova configuração:

firebase emulators:start

5. Depois de executar emulators:start, navegue até a guia do Firestore na visualização da Web dos emuladores.
6. Adicione um documento à coleção users com um campo de número xv e um campo de número yv.

7. Se você conseguiu instalar a extensão, ela cria um novo campo chamado hash no documento.

Fazer uma limpeza para evitar conflitos

• Quando terminar o teste, desinstale a extensão. Você vai atualizar o código da extensão e não quer que ela entre em conflito com a extensão atual mais tarde.

As extensões permitem que várias versões da mesma extensão sejam instaladas de uma só vez. Ao desinstalar, você garante que não haja conflitos com uma extensão instalada anteriormente.

firebase ext:uninstall geohash-ext

A solução atual funciona, mas, como mencionado no início do projeto, há uma chave de API codificada para simular a comunicação com um serviço. Como você pode usar a chave de API do usuário final em vez da fornecida originalmente? Continue lendo para descobrir.

6. Tornar o usuário da extensão configurável

Neste ponto do codelab, você tem uma extensão configurada para uso com a configuração opinativa das funções que você já escreveu, mas e se o usuário quiser usar latitude e longitude em vez de y e x para os campos que indicam a localização em um plano cartesiano? Além disso, como fazer com que o usuário final forneça a própria chave de API, em vez de consumir a chave fornecida? Você pode exceder rapidamente a cota dessa API. Nesse caso, você configura e usa parâmetros.

Definir parâmetros básicos no arquivo extension.yaml

Comece convertendo os itens para os quais os desenvolvedores podem ter uma configuração personalizada. O primeiro seria os parâmetros XFIELD e YFIELD.

1. No arquivo extension.yaml, adicione o seguinte código, que usa os parâmetros de campo XFIELD e YFIELD. Esses parâmetros estão na propriedade YAML params definida anteriormente:

extension.yaml

params:
  - param: XFIELD
    label: The X Field Name
    description: >-
      The X Field is also known as the **longitude** value. What does
      your Firestore instance refer to as the X value or the longitude
      value. If no value is specified, the extension searches for
      field 'xv'.
    type: string
    validationRegex: ^\D([0-9a-zA-Z_.]{0,375})$
    validationErrorMessage: >-
      The field can only contain uppercase or lowercase letter, numbers,
      _, and . characters and must be less than 1500 bytes long. The field
      must also not start with a number.
    default: xv
    required: false
    immutable: false
    example: xv
  - param: YFIELD
    label: The Y Field Name
    description: >-
      The Y Field is also known as the **latitude** value. What does
      your Firestore instance refer to as the Y value or the latitude
      value. If no value is specified, the extension searches for
      field 'yv'.
    type: string
    validationRegex: ^\D([0-9a-zA-Z_.]{0,375})$
    validationErrorMessage: >-
      The field can only contain uppercase or lowercase letter, numbers,
      _, and . characters and must be less than 1500 bytes long. The field
      must also not start with a number.
    default: yv
    required: false
    immutable: false
    example: yv

• param nomeia o parâmetro de uma forma que seja visível para você, o produtor da extensão. Use esse valor mais tarde ao especificar os valores dos parâmetros.
• label é um identificador legível por humanos para que o desenvolvedor saiba o que o parâmetro faz.
• description fornece uma descrição detalhada do valor. Como ele oferece suporte a Markdown, é possível vincular a documentação extra ou destacar palavras que podem ser importantes para o desenvolvedor.
• type define o mecanismo de entrada para que um usuário defina o valor do parâmetro. Existem muitos tipos, incluindo string, select, multiSelect, selectResource e secret. Para saber mais sobre cada uma dessas opções, consulte a documentação.
• validationRegex restringe a entrada do desenvolvedor a um determinado valor de regex (no exemplo, ele se baseia nas diretrizes simples de nome de campo encontradas aqui). Se isso falhar...
• validationErrorMessage alerta o desenvolvedor sobre o valor de falha.
• Padrão é o valor que seria usado se o desenvolvedor não tivesse inserido nenhum texto.
• Obrigatório significa que o desenvolvedor não precisa inserir nenhum texto.
• Imutável permite que o desenvolvedor atualize essa extensão e mude esse valor. Nesse caso, o desenvolvedor precisa poder mudar os nomes dos campos conforme os requisitos mudam.
• O exemplo dá uma ideia de como uma entrada válida pode ser.

Foi muita informação.

2. Você tem mais três parâmetros para adicionar ao arquivo extension.yaml antes de adicionar um parâmetro especial.

  - param: INPUTPATH
    label: The input document to listen to for changes
    description: >-
      This is the document where you write an x and y value to. Once
      that document has received a value, it notifies the extension to
      calculate a geohash and store that in an output document in a certain
      field. This accepts function [wildcard parameters](https://firebase.google.com/docs/functions/firestore-events#wildcards-parameters)
    type: string
    validationRegex: ^[^/]+(/[^/]*/[^/]*)*/[^/]+$
    validationErrorMessage: >-
      This must point to a document path, not a collection path from the root
      of the database. It must also not start or end with a '/' character.
    required: true
    immutable: false
    example: users/{uid}
  - param: OUTPUTFIELD
    label: Geohash field
    description: >-
      This specifies the field in the output document to store the geohash in.
    type: string
    validationRegex: ^\D([0-9a-zA-Z_.]{0,375})$
    validationErrorMessage: >-
      The field can only contain uppercase or lowercase letter, numbers,
      _, and . characters and must be less than 1500 bytes long. The field
      must also not start with a number.
    required: false
    default: hash
    immutable: false
    example: hash

Definir parâmetros sensíveis

Agora, você precisa gerenciar a chave de API especificada pelo usuário. Essa é uma string sensível que não deve ser armazenada em texto simples na função. Em vez disso, armazene esse valor no Cloud Secret Manager. Esse é um local especial na nuvem que armazena segredos criptografados e impede que eles sejam vazados acidentalmente. Isso exige que o desenvolvedor pague pelo uso desse serviço, mas adiciona uma camada extra de segurança às chaves de API e limita as atividades fraudulentas. A documentação do usuário alerta o desenvolvedor de que é um serviço pago para que não haja surpresas no faturamento. No geral, o uso é semelhante aos outros recursos de string mencionados acima. A única diferença é o tipo, que é chamado de secret.

• No arquivo extension.yaml, adicione o seguinte código:

extension.yaml

  - param: APIKEY
    label: GeohashService API Key
    description: >-
      Your geohash service API Key. Since this is a demo, and not a real
      service, you can use : 1234567890.
    type: secret
    required: true
    immutable: false

Atualize os atributos resource para usar parâmetros

Como mencionado anteriormente, o recurso (e não a função) define como ele é observado. Portanto, o recurso locationUpdate precisa ser atualizado para usar o novo parâmetro.

• No arquivo extension.yaml, adicione o seguinte código:

extension.yaml

## Change from this
  - name: locationUpdate
    type: firebaseextensions.v1beta.function
    properties:
      eventTrigger:
        eventType: providers/cloud.firestore/eventTypes/document.write
        resource: projects/${PROJECT_ID}/databases/(default)/documents/users/{uid}]

## To this
  - name: locationUpdate
    type: firebaseextensions.v1beta.function
    properties:
      eventTrigger:
        eventType: providers/cloud.firestore/eventTypes/document.write
        resource: projects/${PROJECT_ID}/databases/(default)/documents/${INPUTPATH}

Confira o arquivo extension.yaml

• Revise o arquivo extension.yaml. O código será semelhante a este:

extension.yaml

name: geohash-ext
version: 0.0.1
specVersion: v1beta  # Firebase Extensions specification version (do not edit)

displayName: Latitude and Longitude to GeoHash converter
description: A converter for changing your Latitude and Longitude coordinates to geohashes.

license: Apache-2.0  # The license you want to use for the extension

author:
  authorName: Sparky
  url: https://github.com/Firebase

billingRequired: true

params:
  - param: XFIELD
    label: The X Field Name
    description: >-
      The X Field is also known as the **longitude** value. What does
      your Firestore instance refer to as the X value or the longitude
      value. If you don't provide a value for this field, the extension will use 'xv' as the default value.
    type: string
    validationRegex: ^\D([0-9a-zA-Z_.]{0,375})$
    validationErrorMessage: >-
      The field can only contain uppercase or lowercase letter, numbers,
      _, and . characters and must be less than 1500 bytes long. The field
      must also not start with a number.
    default: xv
    required: false
    immutable: false
    example: xv
  - param: YFIELD
    label: The Y Field Name
    description: >-
      The Y Field is also known as the **latitude** value. What does
      your Firestore instance refer to as the Y value or the latitude
      Value. If you don't provide a value for this field, the extension will use 'yv' as the default value.
    type: string
    validationRegex: ^\D([0-9a-zA-Z_.]{0,375})$
    validationErrorMessage: >-
      The field can only contain uppercase or lowercase letter, numbers,
      _, and . characters and must be less than 1500 bytes long. The field
      must also not start with a number.
    default: yv
    required: false
    immutable: false
    example: yv
  - param: INPUTPATH
    label: The input document to listen to for changes
    description: >-
      This is the document where you write an x and y value to. Once
      that document has been modified, it notifies the extension to
      compute a geohash and store that in an output document in a certain
      field. This accepts function [wildcard parameters](https://firebase.google.com/docs/functions/firestore-events#wildcards-parameters)
    type: string
    validationRegex: ^[^/]+(/[^/]*/[^/]*)*/[^/]+$
    validationErrorMessage: >-
      This must point to a document path, not a collection path from the root
      of the database. It must also not start or end with a '/' character.
    required: true
    immutable: false
    example: users/{uid}
  - param: OUTPUTFIELD
    label: Geohash field
    description: >-
      This specifies the field in the output document to store the geohash in.
    type: string
    validationRegex: ^\D([0-9a-zA-Z_.]{0,375})$
    validationErrorMessage: >-
      The field can only contain uppercase or lowercase letter, numbers,
      _, and . characters and must be less than 1500 bytes long. The field
      must also not start with a number.
    required: false
    default: hash
    immutable: false
    example: hash
  - param: APIKEY
    label: GeohashService API Key
    description: >-
      Your geohash service API Key. Since this is a demo, and not a real
      service, you can use : 1234567890.
    type: secret
    required: true
    immutable: false

resources:
  - name: locationUpdate
    type: firebaseextensions.v1beta.function
    properties:
      eventTrigger:
        eventType: providers/cloud.firestore/eventTypes/document.write
        resource: projects/${PROJECT_ID}/databases/(default)/documents/${INPUTPATH}
  - name: callableHash
    type: firebaseextensions.v1beta.function
    properties:
      httpsTrigger: {}

roles:
  - role: datastore.user
    reason: Allows the extension to read / write to your Firestore instance.

Acessar parâmetros no código

Agora que todos os parâmetros estão configurados no arquivo extension.yaml, adicione-os ao arquivo index.ts.

• No arquivo index.ts, substitua os valores padrão por process.env.PARAMETER_NAME, que busca os valores de parâmetro adequados e os preenche no código da função implantada no projeto do Firebase do desenvolvedor.

index.ts

// Replace this:
const documentPath = "users/{uid}";
const xField = "xv";
const yField = "yv";
const apiKey = "1234567890";
const outputField = "hash";

// with this:
const documentPath = process.env.INPUTPATH!; // this value is ignored since its read from the resource
const xField = process.env.XFIELD!;
const yField = process.env.YFIELD!;
const apiKey = process.env.APIKEY!;
const outputField = process.env.OUTPUTFIELD!;

Normalmente, você quer realizar verificações de valor nulo com os valores da variável de ambiente, mas, nesse caso, você confia que os valores do parâmetro foram copiados corretamente. Agora o código está configurado para funcionar com os parâmetros de extensão.

7. Criar documentação do usuário

Antes de testar o código em emuladores ou no marketplace de extensões do Firebase, a extensão precisa ser documentada para que os desenvolvedores saibam o que vão receber ao usá-la.

1. Comece criando o arquivo PREINSTALL.md, que é usado para descrever a funcionalidade, os pré-requisitos para instalação e as possíveis implicações de faturamento.

PREINSTALL.md

Use this extension to automatically convert documents with a latitude and
longitude to a geohash in your database. Additionally, this extension includes a callable function that allows users to make one-time calls
to convert an x,y coordinate into a geohash.

Geohashing is supported for latitudes between 90 and -90 and longitudes
between 180 and -180.

#### Third Party API Key

This extension uses a fictitious third-party API for calculating the
geohash. You need to supply your own API keys. (Since it's fictitious,
you can use 1234567890 as an API key).

#### Additional setup

Before installing this extension, make sure that you've [set up a Cloud
Firestore database](https://firebase.google.com/docs/firestore/quickstart) in your Firebase project.

After installing this extension, you'll need to:

- Update your client code to point to the callable geohash function if you
want to perform arbitrary geohashes.

Detailed information for these post-installation tasks are provided after
you install this extension.

#### Billing
To install an extension, your project must be on the [Blaze (pay as you
go) plan](https://firebase.google.com/pricing)

- This extension uses other Firebase and Google Cloud Platform services,
which have associated charges if you exceed the service's no-cost tier:
 - Cloud Firestore
 - Cloud Functions (Node.js 16+ runtime. [See
FAQs](https://firebase.google.com/support/faq#extensions-pricing))
 - [Cloud Secret Manager](https://cloud.google.com/secret-manager/pricing)