Selecione a plataforma: Android iOS JavaScript

Usar o App Check para proteger sua chave de API

O Firebase App Check protege as chamadas do seu app para a Plataforma Google Maps, bloqueando o tráfego que vem de fontes diferentes de apps legítimos. Para isso, ele verifica se há um token de um provedor de atestação, como o reCAPTCHA Enterprise. Integrar seus apps ao App Check ajuda a proteger contra solicitações maliciosas, para que você não receba cobranças por chamadas de API não autorizadas.

O App Check é ideal para mim?

O App Check é recomendado na maioria dos casos, mas não é necessário ou não tem suporte nas seguintes situações:

  • Apps particulares ou experimentais. Se o app não estiver acessível publicamente, o App Check não será necessário.
  • Se o app for usado apenas entre servidores, o App Check não será necessário. No entanto, se o servidor que se comunica com a GMP for usado por clientes públicos (como apps para dispositivos móveis), considere usar o App Check para proteger esse servidor em vez da GMP.

Visão geral das etapas de implementação

Em geral, estas são as etapas que você vai seguir para integrar o app ao App Check:

  1. Adicione o Firebase ao aplicativo.
  2. Adicione e inicialize a biblioteca do App Check.
  3. Adicione o provedor de token ao seu app.
  4. Inicialize as APIs Maps JS e App Check.
  5. Ative a depuração.
  6. Monitore as solicitações do app e decida sobre a aplicação.

Depois da integração com o App Check, você poderá conferir as métricas de tráfego do back-end no console do Firebase. Essas métricas fornecem um detalhamento das solicitações de acordo com a presença de um token válido do App Check. Consulte a documentação do Firebase App Check para mais informações.

Quando você tiver certeza de que a maioria das solicitações é de fontes legítimas e que os usuários atualizaram para a versão mais recente do seu app, que inclui a implementação do App Check, ative a aplicação obrigatória. Quando a aplicação estiver ativada, o App Check vai rejeitar todo o tráfego sem um token válido do App Check.

Considerações ao planejar uma integração do App Check

Confira alguns pontos a serem considerados ao planejar sua integração:

  • Um dos provedores de atestado que recomendamos, o reCAPTCHA Enterprise,cobra por mais de 10.000 avaliações por mês.

    O outro provedor de comprovação que recomendamos, o reCAPTCHA v3, tem uma cota. Depois disso, o tráfego não será avaliado.

    Você pode usar um provedor de atestado personalizado, embora esse seja um caso de uso avançado. Consulte a documentação do App Check para mais informações.

  • Os usuários do seu app vão notar alguma latência na inicialização. No entanto, depois disso, qualquer reatestação periódica vai ocorrer em segundo plano, e os usuários não vão mais notar latência. A latência exata na inicialização depende do provedor de atestado escolhido.

    O período em que o token do App Check é válido (o time to live, ou TTL) determina a frequência das reconfirmações. Essa duração pode ser configurada no console do Firebase. A reatestação ocorre quando aproximadamente metade do TTL expira. Para mais informações, consulte os documentos do Firebase do seu provedor de atestado.

Integrar seu app ao App Check

Pré-requisitos e requisitos

  • Um app com a versão semanal ou trimestral mais recente da API Maps JS e as bibliotecas principais carregadas.
  • Um projeto na nuvem com a API Maps JS ativada.
  • Você precisa ser o proprietário do app no console do Cloud.
  • Você vai precisar do ID do projeto do app no console do Cloud.

Etapa 1: adicionar o Firebase ao app

Siga as instruções na documentação para desenvolvedores do Firebase e adicione o Firebase ao seu app.

Etapa 2: adicionar a biblioteca do App Check e inicializar o App Check

O Firebase oferece instruções para cada provedor de atestado padrão. Estas instruções mostram como configurar um projeto do Firebase e adicionar a biblioteca do App Check ao seu app. Siga os exemplos de código fornecidos para inicializar o App Check.

Etapa 3: carregar as bibliotecas da API Maps JavaScript

  1. Carregue as bibliotecas principal e do Maps, conforme mostrado no snippet a seguir. Para mais informações e instruções, consulte a documentação da API Maps JavaScript. 

    async function init() {
  const {Settings} = await google.maps.importLibrary('core');
  const {Map} = await google.maps.importLibrary('maps');
}

Etapa 4: inicializar as APIs Maps e App Check

  1. Inicialize o App Check usando a configuração fornecida pelo Console do Firebase.
  2. Verifique se as solicitações para a API Maps JS estão acompanhadas de tokens do App Check: 
      import {initializeApp} from 'firebase/app';
  import {
    getToken,
    initializeAppCheck,
    ReCaptchaEnterpriseProvider,
  } from 'firebase/app-check';
    
  async function init() {
    const {Settings} = await google.maps.importLibrary('core');
    const {Map} = await google.maps.importLibrary('maps');
  
    const app = initializeApp({
      // Your firebase configuration object
    });
  
    // Pass your reCAPTCHA Enterprise site key to initializeAppCheck().
    const appCheck = initializeAppCheck(app, {
      provider: new ReCaptchaEnterpriseProvider(
        'abcdefghijklmnopqrstuvwxy-1234567890abcd',
      ),
  
      // Optional argument. If true, the SDK automatically refreshes App Check
      // tokens as needed.
      isTokenAutoRefreshEnabled: true,
    });
  
    Settings.getInstance().fetchAppCheckToken = () =>
        getToken(appCheck, /* forceRefresh = */ false);
  
    // Load a map
    map = new Map(document.getElementById("map"), {
      center: { lat: 37.4161493, lng: -122.0812166 },
      zoom: 8,
    });
  }

Etapa 5: ativar a depuração (opcional)

Se você quiser desenvolver e testar seu app localmente ou executá-lo em um ambiente de integração contínua (CI), crie um build de depuração do app que use um secret de depuração para receber tokens válidos do App Check. Isso permite que você evite usar provedores de atestado reais no build de depuração.

Para testar o app localmente:

  • Ative o provedor de depuração para fins de desenvolvimento.
  • Você vai receber um UUID4 aleatório gerado automaticamente (chamado de "token de depuração" na documentação do App Check) dos registros de depuração do SDK. Adicione esse token ao console do Firebase.
  • Para mais informações e instruções, consulte a documentação do App Check.

Para executar o app em um ambiente de CI:

  • Gere um UUID4 aleatório no console do Firebase.
  • Adicione o UUID4 como um token de depuração e copie-o em um repositório de secrets que os testes de CI vão acessar por execução de teste.
  • Para mais informações e instruções, consulte a documentação do App Check.

Etapa 6: monitorar as solicitações de apps e decidir sobre a aplicação

Antes de começar a aplicação, verifique se você não vai interromper os usuários legítimos do app. Para isso, acesse a tela de métricas do App Check para ver qual porcentagem do tráfego do app é verificada, desatualizada ou ilegítima. Quando a maior parte do tráfego estiver verificada, você poderá ativar a aplicação.

Consulte a documentação do Firebase App Check para mais informações e instruções.