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 de fontes que não sejam apps legítimos. Para isso, ele verifica se há um token de um provedor de atestação, como o reCAPTCHA Enterprise. A integração dos seus apps com o 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 é compatível nos seguintes casos:

  • 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 para integrar seu 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 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 de integrar o App Check, você poderá ver as métricas de tráfego de back-end no console do Firebase. Essas métricas detalham as 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 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.

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

Confira alguns aspectos 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 atestado que recomendamos, o reCAPTCHA v3, tem uma cota. Depois que ela é atingida, o tráfego não é mais 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 de validade do token do App Check (o time to live, ou TTL) determina a frequência das novas atestações. Essa duração pode ser configurada no console do Firebase. A reatestação ocorre quando aproximadamente metade do TTL tiver decorrido. 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 para adicionar o Firebase ao seu app.

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

O Firebase fornece 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 JS

  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 o uso de 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 do app 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.