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

O Firebase App Check oferece proteção para chamadas do seu app para a Plataforma Google Maps, bloqueando o tráfego que vem de fontes diferentes dos seus apps legítimos. Para isso, ele solicita uma avaliação da autenticidade do app ou do dispositivo de 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, por sua vez, protege seu faturamento contra cobranças não autorizadas. O App Check também melhora significativamente os relatórios de interrupção em tempo real no ecossistema de apps da sua frota, beneficiando todos os motoristas que usam seu app. Para mais informações, consulte Relatórios de interrupção.

Por que usar o App Check?

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

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

Relatórios de interrupção

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

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

  • A alta barra de confiança para fechamentos:eventos que afetam a rota, como interdições de vias, podem alterar significativamente o comportamento de roteamento para todos os motoristas. Para proteger o mapa contra vandalismo, spam ou relatórios imprecisos, a infraestrutura de moderação do Google para interrupções de interdição de vias depende de sinais fortes de integridade do dispositivo e do app.
  • Como o App Check valida relatórios:os relatórios e votos de 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 em tempo real.
  • 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 confiança mais baixa e podem ser processados apenas como sinais silenciosos. Isso significa que, embora os usuários ainda possam relatar e votar, é menos provável que os relatórios deles sejam visíveis no mapa ou afetem as rotas de outros motoristas e exigirão validação adicional.

O App Check é adequado para mim?

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

  • Apps particulares ou experimentais:se o app não for acessível publicamente, 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 nã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 não GMS, implante um provedor de atestado personalizado.

Visão geral das etapas de implementação

Em alto nível, siga 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 de sua escolha para verificar a integridade do dispositivo ou do 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 recomendado, a Play Integrity, tem um limite de chamadas diárias para o nível de uso da API padrão. Para mais informações sobre limites de chamadas, consulte a página de configuração na documentação para desenvolvedores da Google Play Integrity.
  • Latência de inicialização:na maioria das situações, os usuários não vão ter latência durante o uso normal, 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 da expiração para manter a performance perfeita. No entanto, se um token válido do App Check não estiver presente, os usuários do app vão ter alguma latência na inicialização. Por exemplo, essa latência ocorre durante inicializações a frio quando um token armazenado em cache expira ou está ausente.
  • TTL do token:o tempo de vida (TTL) determina o período em que o token do App Check é válido antes de precisar 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 uma linha de base segura, mas o SDK tenta atualizações em segundo plano em aproximadamente metade da duração do TTL. Para instruções detalhadas do console, consulte a documentação do Firebase App Check.

Integrar seu app ao App Check

Pré-requisitos e requisitos

  • Um app com o SDK do Navigation 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 seu 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 seu google-services.json arquivo ao diretório de 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 do aplicativo 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

Crie uma implementação da interface MapsAppCheckTokenProvider. Esse provedor busca de forma assíncrona tokens do App Check do Firebase App Check e os transmite para a pilha de rede do SDK do Navigation 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 a 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 do Navigation para Android, os recursos do app que dependem do SDK do Navigation para Android 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, é necessário criar um build de depuração do 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 seu 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 adicionar um token de depuração local à 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

Antes de ativar a restrição, monitore as solicitações do app para garantir que você não vai interromper usuários legítimos.

  1. Acesse a tela de métricas do App Check no console do Firebase para conferir a porcentagem de tráfego verificado em comparação com o não verificado.
  2. Quando tiver certeza de que a maioria do tráfego é verificada e 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.
  3. Quando a aplicação estiver ativada, o App Check vai rejeitar todo o tráfego sem um token válido do App Check.