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

O suporte ao App Check com o SDK do Navigation para iOS será lançado nos próximos dias. Se você ainda não encontrar esse recurso no console do Firebase, verifique novamente em alguns dias.

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 o App Attest. 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.

Importante:o App Check não bloqueia o tráfego não autorizado por padrão. Você precisa ativar a aplicação manualmente 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 do Navigation para iOS: 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 do Navigation para iOS de fontes maliciosas ou não autorizadas. Isso beneficia você diretamente, protegendo seu projeto contra fraudes 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. A ativação do 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 indicadores 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 iOS 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 para 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 indicadores silenciosos. Isso significa que, embora os usuários ainda possam relatar e votar, é menos provável que os relatórios deles fiquem 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 iOS 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.

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 do Navigation e do 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: os provedores de atestado recomendados, DeviceCheck ou App Attest, estão sujeitos a cotas e limitações definidas pela Apple.
• 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 iOS versão 11.0 ou mais recente instalado.
• O ID do pacote do app.
• O ID da equipe na guia "Membership" do console de desenvolvedor da Apple.
• Se você planeja usar o DeviceCheck, o arquivo de chave privada e o ID da chave.
• 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 aplicativo

Siga as instruções na documentação do desenvolvedor do Firebase para adicionar o Firebase ao seu app. Adicione o arquivo GoogleService-Info.plist, não modificado, ao nível raiz do projeto.

No arquivo AppDelegate, importe os seguintes módulos:

Swift

import FirebaseCore
import FirebaseAppCheck
import GoogleNavigation

Objective-C

@import FirebaseCore;
@import FirebaseAppCheck;
@import GoogleNavigation;

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. Essas 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.

1. Siga as instruções do Firebase para adicionar a biblioteca do App Check:
   • Instruções do App Attest.
   • Instruções do DeviceCheck.
2. Inicialize o App Check no AppDelegate:
   • Se você estiver usando o App Attest, crie uma implementação de AppCheckProviderFactory e registre-a antes de chamar FirebaseApp.configure():

     Swift

     class YourAppCheckProviderFactory: NSObject, AppCheckProviderFactory {
         func createProvider(with app: FirebaseApp) -> AppCheckProvider? {
             return AppAttestProvider(app: app)
         }
     }
     // In application(_:didFinishLaunchingWithOptions:)
     let providerFactory = YourAppCheckProviderFactory()
     AppCheck.setAppCheckProviderFactory(providerFactory)
     FirebaseApp.configure()

     Objective-C

     #import <FirebaseCore/FirebaseCore.h>
     #import <FirebaseAppCheck/FirebaseAppCheck.h>
     
     @interface YourAppCheckProviderFactory : NSObject <FIRAppCheckProviderFactory>
     @end
     
     @implementation YourAppCheckProviderFactory
     - (nullable id<FIRAppCheckProvider>)createProviderWithApp:(FIRApp *)app {
         return [[FIRAppAttestProvider alloc] initWithApp:app];
     }
     @end
     
     // In application:didFinishLaunchingWithOptions:
     YourAppCheckProviderFactory *providerFactory = [[YourAppCheckProviderFactory alloc] init];
     [FIRAppCheck setAppCheckProviderFactory:providerFactory];
     [FIRApp configure];

   • Se você estiver usando o DeviceCheck, defina a fábrica usando o seguinte:

     Swift

     AppCheck.setAppCheckProviderFactory(DeviceCheckProviderFactory())

     Objective-C

     FIRDeviceCheckProviderFactory *providerFactory = [[FIRDeviceCheckProviderFactory alloc] init];
     [FIRAppCheck setAppCheckProviderFactory:providerFactory];

Etapa 3: adicionar o provedor de token

Observação:se o app também usar outros SDKs da Plataforma Google Maps que oferecem suporte ao App Check (como o SDK do Places), você poderá usar a mesma configuração do Firebase App Check, mas precisará implementar e registrar a interface do provedor de token específica para cada SDK.

Crie um arquivo chamado AppCheckTokenProvider (ou, se você estiver usando Objective-C, dois arquivos chamados AppCheckTokenProvider.h e AppCheckTokenProvider.m) no nível raiz do app.

Essa classe precisa estar em conformidade com o protocolo GMSAppCheckTokenProvider e implementar o método fetchAppCheckTokenWithCompletion.

Swift

import Foundation
import FirebaseAppCheck
import GoogleNavigation

class AppCheckTokenProvider: NSObject, GMSAppCheckTokenProvider {
    func fetchAppCheckToken(completion: @escaping (String?, Error?) -> Void) {
        AppCheck.appCheck().token(forcingRefresh: false) { token, error in
            if let error = error {
                print("App Check Error: \(error)")
                completion(nil, error)
                return
            }
            guard let token = token else {
                completion(nil, NSError(domain: "AppCheck", code: -1, userInfo: [NSLocalizedDescriptionKey: "Token is nil"]))
                return
            }
            print("App Check Token: \(token.token)")
            completion(token.token, nil)
        }
    }
}

Objective-C

// AppCheckTokenProvider.h
#import <Foundation/Foundation.h>
#import <GoogleNavigation/GoogleNavigation.h>

NS_ASSUME_NONNULL_BEGIN

@interface AppCheckTokenProvider : NSObject <GMSAppCheckTokenProvider>
@end

NS_ASSUME_NONNULL_END

// AppCheckTokenProvider.m
#import "AppCheckTokenProvider.h"
#import <FirebaseAppCheck/FirebaseAppCheck.h>

@implementation AppCheckTokenProvider
- (void)fetchAppCheckTokenWithCompletion:(void (^)(NSString * _Nullable token, NSError * _Nullable error))completion {
    [[FIRAppCheck appCheck] tokenForcingRefresh:NO
                                     completion:^(FIRAppCheckToken * _Nullable token, NSError * _Nullable error) {
        if (token) {
            completion(token.token, nil);
        } else {
            completion(nil, error);
        }
    }];
}
@end

Etapa 4: inicializar as APIs do Navigation e do App Check

Inicialize o SDK do Navigation para iOS (usando GMSServices) e registre a instância do provedor de token transmitindo o identificador de serviços opaco compartilhado para GMSServices:

Swift

// In application(_:didFinishLaunchingWithOptions:)
GMSServices.provideAPIKey("YOUR_API_KEY")

// Register your App Check token provider before initializing Navigation SDK for iOS
if let services = GMSServices.sharedServices() as? GMSServices {
    services.appCheckTokenProvider = AppCheckTokenProvider()
}

Objective-C

// In application:didFinishLaunchingWithOptions:
[GMSServices provideAPIKey:@"YOUR_API_KEY"];

// Register your App Check token provider before initializing Navigation SDK for iOS
((GMSServices *)[GMSServices sharedServices]).appCheckTokenProvider = [[AppCheckTokenProvider alloc] init];

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

Depois que o App Check for aplicado ao SDK do Navigation para iOS, os recursos do app que dependem do SDK do Navigation para iOS 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. Configure a fábrica do provedor de depuração no AppDelegate:

   Swift

   #if targetEnvironment(simulator)
   let providerFactory = AppCheckDebugProviderFactory()
   #else
   let providerFactory = YourAppCheckProviderFactory()
   #endif
   AppCheck.setAppCheckProviderFactory(providerFactory)

   Objective-C

   #if TARGET_OS_SIMULATOR
   id<FIRAppCheckProviderFactory> providerFactory = [[FIRAppCheckDebugProviderFactory alloc] init];
   #else
   id<FIRAppCheckProviderFactory> providerFactory = [[YourAppCheckProviderFactory alloc] init];
   #endif
   [FIRAppCheck setAppCheckProviderFactory:providerFactory];

2. Ative a geração de registros no projeto do Xcode, inicie o app e localize o token de depuração local no registro do console.
3. Copie e adicione esse token de depuração ao 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, falsificação e abuso de cota depende da ativação da aplicação no nível do projeto.

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 relação ao 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.