Usar o App Check para proteger o SDK do Navigation para Android

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 seus apps legítimos. Para isso, ele solicita uma avaliação da autenticidade do app ou do dispositivo a um provedor de atestado, como a Play Integrity. Ao integrar seu app ao App Check, você adiciona proteção contra solicitações maliciosas e não autorizadas, o que protege seu faturamento contra cobranças indevidas. O App Check também melhora significativamente os relatórios de interrupção em tempo real no ecossistema de apps de frota, beneficiando todos os motoristas que usam seu app. Para mais informações, consulte Relatórios de interrupção.

Importante:o App Check não bloqueia o tráfego não autorizado por padrão. É necessário ativar manualmente a aplicação depois de verificar as métricas do app (consulte a Etapa 6: monitorar as solicitações do app e decidir sobre a aplicação).

Por que usar o App Check?

O App Check protege duas áreas distintas do SDK de navegação para Android: a funcionalidade de navegação principal e os relatórios de interrupção.

Navegação

O App Check ajuda a bloquear as principais solicitações do SDK de navegação para Android de fontes maliciosas ou não autorizadas. Isso beneficia você diretamente, protegendo seu projeto contra fraudes de faturamento e esgotamento de cotas.

Denúncia de interrupção

O App Check é altamente recomendado se o app oferece suporte a recursos de votação e relatórios de interrupção em tempo real. Ao ativar o App Check, você garante que os motoristas recebam as rotas mais precisas, considerando todos os feedbacks em tempo real.

Por que o App Check é importante para os relatórios:

• Alto nível de confiança para interdições:eventos que afetam o trajeto, como interdições de vias, podem alterar significativamente o comportamento de rotas para todos os motoristas. Para proteger o mapa contra possíveis atos de vandalismo, spam ou alertas imprecisos, a infraestrutura de moderação do Google para interdições de vias depende de indicadores fortes de integridade do dispositivo e do app.
• Como o App Check valida os relatórios:os relatórios e votos dos usuários enviados pelo SDK do Navigation para Android incluem o token do App Check, que é usado pelo back-end do Google para validar a legitimidade do feedback, aumentando o nível de confiança e permitindo que ele seja avaliado quanto ao impacto no mapa ativo.
• O impacto de omitir o App Check:os relatórios enviados sem um token válido do App Check são avaliados em um modelo de menor confiança e podem ser processados apenas como indicadores silenciosos. Isso significa que, embora os usuários ainda possam enviar alertas e votar, é menos provável que os alertas deles apareçam no mapa ou afetem as rotas de outros motoristas, além de precisarem de mais validação.

O App Check é ideal para mim?

O App Check é recomendado na maioria dos casos, mas não é necessário ou não tem suporte nos seguintes cenários:

• Apps particulares ou experimentais:se o app não estiver acessível ao público, o App Check não será necessário.
• Dispositivos comprometidos:os provedores de atestado recomendados impedem que o SDK do Navigation para Android seja executado em dispositivos não confiáveis, como smartphones com acesso root ou jailbreak. Para oferecer suporte a esses dispositivos, implante um provedor de atestado personalizado.
• Dispositivos Android que não são GMS:os dispositivos Android precisam executar os Serviços do Google Mobile (GMS) para a Play Integrity. Se você planeja oferecer suporte a dispositivos Android que não são do GMS, implante um provedor de atestado personalizado.

Visão geral das etapas de implementação

Em geral, você vai seguir estas etapas para integrar seu app ao App Check:

1. Adicione o Firebase ao aplicativo.
2. Adicione a biblioteca do App Check e inicialize o App Check.
3. Adicione um provedor de token. Essa etapa invoca o provedor de atestado escolhido para verificar a integridade do dispositivo ou app.
4. Inicialize as APIs Navigation e App Check.
5. Ative a depuração. Isso é útil durante o desenvolvimento ou em ambientes de integração contínua (CI).
6. Monitore as solicitações do app antes de ativar a aplicação. Dessa forma, você aplica o App Check sem interromper os usuários.

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

• Cotas do provedor de atestado:o provedor de atestado que recomendamos, o Play Integrity, tem um limite diário de chamadas para o nível de uso da API padrão. Para mais informações sobre os limites de chamadas, consulte a página Configuração na documentação para desenvolvedores da API Google Play Integrity.
• Latência de inicialização:na maioria das situações, os usuários não vão notar latência durante o uso regular, porque os tokens do App Check são armazenados em cache no dispositivo. O sistema atualiza automaticamente os tokens do App Check em segundo plano antes que eles expirem para manter o desempenho sem interrupções. No entanto, se não houver um token válido do App Check, os usuários do app vão notar alguma latência na inicialização. Por exemplo, essa latência ocorre durante inicializações a frio quando um token em cache está expirado ou ausente.
• TTL do token:o time to live (TTL) determina o tempo de validade do token do App Check antes que ele precise ser atualizado. É possível configurar essa duração de 30 minutos a 7 dias no console do Firebase. Uma duração de 1 hora é recomendada como um valor de referência seguro, mas o SDK tenta automaticamente fazer atualizações em segundo plano em aproximadamente metade da duração do TTL. Para instruções detalhadas sobre o console, consulte a documentação do App Check do Firebase.

Integrar seu app ao App Check

Pré-requisitos e requisitos

• Um app com o SDK de navegação para Android versão 7.9 ou mais recente instalado.
• A impressão digital do certificado SHA-256 do seu app.
• O nome do pacote do seu app.
• Você precisa ser o proprietário do app no console do Google Cloud.
• O ID do projeto do app no console do Google 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. Adicione o arquivo google-services.json ao diretório no nível do app do seu projeto.

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

Adicione a dependência do App Check ao arquivo build.gradle do seu app:

Groovy (build.gradle)

dependencies {
    // Import the Firebase BoM
    implementation platform('com.google.firebase:firebase-bom:34.17.0')
    // Add the dependency for the App Check library with Play Integrity
    implementation 'com.google.firebase:firebase-appcheck-playintegrity'
}

Inicialize o App Check na classe Application ou na atividade principal:

Java

import com.google.firebase.FirebaseApp;
import com.google.firebase.appcheck.FirebaseAppCheck;
import com.google.firebase.appcheck.playintegrity.PlayIntegrityAppCheckProviderFactory;

// Initialize Firebase App
FirebaseApp.initializeApp(/* context= */ this);

// Initialize App Check
FirebaseAppCheck firebaseAppCheck = FirebaseAppCheck.getInstance();
firebaseAppCheck.installAppCheckProviderFactory(
    PlayIntegrityAppCheckProviderFactory.getInstance());

Kotlin

import com.google.firebase.Firebase
import com.google.firebase.appcheck.appCheck
import com.google.firebase.appcheck.playintegrity.PlayIntegrityAppCheckProviderFactory
import com.google.firebase.initialize

// Initialize Firebase App
Firebase.initialize(context = this)

// Initialize App Check
Firebase.appCheck.installAppCheckProviderFactory(
    PlayIntegrityAppCheckProviderFactory.getInstance(),
)

Etapa 3: adicionar o provedor de token

Observação:se o app também usa outros SDKs da Plataforma Google Maps compatíveis com o App Check (como o SDK do Places), você pode usar a mesma configuração do Firebase App Check, mas precisa implementar e registrar a interface do provedor de tokens específica para cada SDK.

Crie uma implementação da interface MapsAppCheckTokenProvider. Esse provedor busca de forma assíncrona os tokens do Firebase App Check e os transmite para a pilha de rede do SDK de navegação para Android usando o MapsAppCheckTokenCallback:

Java

import com.google.android.gms.maps.MapsAppCheckTokenCallback;
import com.google.android.gms.maps.MapsAppCheckTokenProvider;
import com.google.firebase.appcheck.FirebaseAppCheck;

public class NavigationTokenProvider implements MapsAppCheckTokenProvider {
  @Override
  public void fetchToken(MapsAppCheckTokenCallback callback) {
    FirebaseAppCheck.getInstance()
        .getAppCheckToken(false) // forcingRefresh = false
        .addOnSuccessListener(
            tokenResult -> {
              String token = tokenResult.getToken();
              callback.onSuccess(token);
            })
        .addOnFailureListener(
            e -> {
              callback.onFailure();
            });
  }
}

Kotlin

import com.google.android.gms.maps.MapsAppCheckTokenCallback
import com.google.android.gms.maps.MapsAppCheckTokenProvider
import com.google.firebase.appcheck.FirebaseAppCheck

class NavigationTokenProvider : MapsAppCheckTokenProvider {
    override fun fetchToken(callback: MapsAppCheckTokenCallback) {
        FirebaseAppCheck.getInstance()
            .getAppCheckToken(false)
            .addOnSuccessListener { tokenResult ->
                callback.onSuccess(tokenResult.token)
            }
            .addOnFailureListener {
                callback.onFailure()
            }
    }
}

Etapa 4: inicializar as APIs Navigation e App Check

Inicialize o SDK do Navigation para Android e registre sua instância do provedor de token unificado usando MapsApiSettings.setAppCheckTokenProvider():

Java

import com.google.android.gms.maps.MapsApiSettings;

// Register your App Check token provider before initializing Navigation SDK for Android
MapsApiSettings.setAppCheckTokenProvider(context, new NavigationTokenProvider());

Kotlin

import com.google.android.gms.maps.MapsApiSettings

// Register your App Check token provider before initializing Navigation SDK for Android
MapsApiSettings.setAppCheckTokenProvider(context, NavigationTokenProvider())

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

Depois que o App Check for aplicado ao SDK de Navigation para Android, os recursos do app que dependem dele não serão executados em um simulador ou em um ambiente de integração contínua (CI), porque esses ambientes não se qualificam como dispositivos válidos. Para executar o app nesses ambientes durante o desenvolvimento e os testes, crie um build de depuração do seu app que use o provedor de depuração do App Check em vez de um provedor de atestado de produção.

1. Adicione a dependência do provedor de depuração ao arquivo build.gradle do app:

   Groovy (build.gradle)

   dependencies {
       implementation 'com.google.firebase:firebase-appcheck-debug'
   }

2. Configure o App Check para usar a fábrica do provedor de depuração nos builds de depuração:

   Java

   import com.google.firebase.appcheck.debug.DebugAppCheckProviderFactory;
   import com.google.firebase.appcheck.playintegrity.PlayIntegrityAppCheckProviderFactory;
   
   if (BuildConfig.DEBUG) {
       firebaseAppCheck.installAppCheckProviderFactory(
           DebugAppCheckProviderFactory.getInstance()
       );
   } else {
       firebaseAppCheck.installAppCheckProviderFactory(
           PlayIntegrityAppCheckProviderFactory.getInstance()
       );
   }

   Kotlin

   import com.google.firebase.Firebase
   import com.google.firebase.appcheck.appCheck
   import com.google.firebase.appcheck.debug.DebugAppCheckProviderFactory
   import com.google.firebase.appcheck.playintegrity.PlayIntegrityAppCheckProviderFactory
   
   if (BuildConfig.DEBUG) {
       Firebase.appCheck.installAppCheckProviderFactory(
           DebugAppCheckProviderFactory.getInstance(),
       )
   } else {
       Firebase.appCheck.installAppCheckProviderFactory(
           PlayIntegrityAppCheckProviderFactory.getInstance(),
       )
   }

3. Inicie o app em um emulador ou dispositivo de depuração. O App Check vai imprimir um token de depuração local na saída do logcat.
4. Copie e registre esse token de depuração no console do Firebase. Para mais detalhes, consulte a documentação do provedor de depuração do Firebase App Check.

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

Observação:a aplicação não é estritamente necessária para que os relatórios de interrupção em tempo real se beneficiem da verificação de integridade do dispositivo. No entanto, a proteção total contra fraude de faturamento, spoofing e abuso de cota depende da ativação da aplicação no nível do projeto.

Antes de ativar a aplicação obrigatória, monitore as solicitações do app para garantir que os usuários legítimos não sejam afetados.

1. Acesse a tela de métricas do App Check no console do Firebase para conferir a porcentagem de tráfego verificado e não verificado.
2. Quando tiver certeza de que a maior parte do tráfego foi verificada e que os usuários legítimos atualizaram para uma versão do app que contém a implementação do App Check, ative a aplicação obrigatória.
3. Quando a aplicação estiver ativada, o App Check vai rejeitar todo o tráfego sem um token válido.