Evitar abusos da API Gemini com o Firebase App Check

Quando você chama uma API diretamente de um app para dispositivos móveis ou da Web, ela fica vulnerável a abuso por clientes não autorizados. Se você quiser chamar o Gemini API diretamente do seu app para dispositivos móveis ou da Web, ajude a protegê-lo contra abusos usando Firebase AI Logic e aplicando Firebase App Check. Quando você aplica o App Check, ele só permite solicitações recebidas que foram verificadas como sendo do seu app e/ou de um dispositivo não adulterado.

Ir para as instruções de configuração

O Firebase AI Logic oferece um gateway de proxy que permite a integração com o Firebase App Check e protege o Gemini API quando ele é chamado diretamente pelos seus apps para dispositivos móveis e da Web. Quando App Check é aplicado a Firebase AI Logic, ele ajuda a proteger o Gemini Developer API e o Agent Platform Gemini API (formerly Vertex AI).

O App Check para Firebase AI Logic também oferece suporte à proteção contra repetição, o que significa que um token App Check só pode ser usado uma vez.


Resumo geral de como o App Check funciona

Com o App Check, os dispositivos que executam seu app usam um app ou provedor de atestado de dispositivos que verifica um ou ambos os itens a seguir:

  • As solicitações vêm do seu app autêntico
  • As solicitações vêm de um dispositivo autêntico que não foi comprometido

Esse atestado é anexado a todas as solicitações que o app faz usando um SDK Firebase AI Logic. Quando o App Check é aplicado, as solicitações de clientes sem um atestado válido são recusadas, assim como qualquer solicitação originada de um app ou plataforma que você não autorizou.

Ao configurar o App Check, considere adicionar a proteção contra repetição, que faz com que os tokens do App Check sejam de uso único. Essa opção oferece proteção aprimorada além da proteção básica e permite definir um nível adequado de proteção para seu app e casos de uso.

Encontre informações detalhadas sobre App Check na documentação, incluindo descrições de provedores de atestado e cotas e limites aplicáveis.

Configurar App Check

As instruções a seguir são otimizadas para configurar a aplicação de Firebase App Check para Firebase AI Logic.

Etapa 1: aplicar App Check

A partir do início de julho de 2026, durante o fluxo de trabalho de configuração guiada no console Firebase, o Firebase vai aplicar automaticamente o Firebase App Check para Firebase AI Logic e ajudar a proteger o Gemini API.

No entanto, se você já tiver configurado o Firebase AI Logic no seu projeto do Firebase antes do início de julho de 2026 (ou se o App Check não for aplicado por algum outro motivo), poderá fazer isso App Check seguindo as instruções abaixo.

  1. Verifique se App Check já está sendo aplicado para Firebase AI Logic.

    1. No console do Firebase, acesse a guia Segurança > App Check > APIs.

    2. Encontre a linha de Firebase AI Logic. Se aparecer Unenforced, continue com o restante destas instruções.

  2. Clique na linha de Firebase AI Logic para ver os gráficos de métricas. Abaixo desses gráficos, clique em Configurar.

  3. Na primeira tela da caixa de diálogo (Proteção básica), selecione Aplicada e clique em Continuar.

  4. Na próxima tela (Proteção contra repetição), selecione Desativada e clique em Continuar.

  5. Na tela final, revise as considerações para aplicar App Check e verifique se você está pronto para isso App Check. Se estiver tudo certo, clique em Continuar.

    Você não precisa registrar seus apps se quiser apenas aplicar App Check e usar apenas o provedor de depuração com Firebase AI Logic em um app de pré-produção. No entanto, quando você estiver pronto para lançar o app para usuários finais, será necessário registrar os apps como parte da configuração de um provedor de atestado de produção (como o App Attest, o Play Integrity ou reCAPTCHA Enterprise).

Etapa 2: configurar o provedor de depuração para desenvolvimento local

Para desenvolvimento local, é possível configurar o provedor de depuração App Check e manter App Check aplicado para Firebase AI Logic.

Swift

Confira como usar o provedor de depuração enquanto executa seu app em um simulador de forma interativa (por exemplo, durante o desenvolvimento local):

  1. No projeto do Xcode, importe FirebaseAppCheck e inicialize App Check com a fábrica do provedor de depuração antes de configurar Firebase.

    import SwiftUI
import FirebaseCore
import FirebaseAppCheck

@main
struct YourApp: App {
  init() {
    let providerFactory = AppCheckDebugProviderFactory()
    AppCheck.setAppCheckProviderFactory(providerFactory)
    FirebaseApp.configure()
  }

  var body: some Scene {
    WindowGroup {
      NavigationView {
        ContentView()
      }
    }
  }
}

  2. Receba seu token de depuração:

    1. Inicie o app no simulador ou no dispositivo de teste.

    2. Abra o console do Xcode e procure o token de depuração App Check. Exemplo:

      <Warning> [AppCheckCore][I-GAC004001] App Check debug token: '123a4567-b89c-12d3-e456-789012345678'.

    3. Copie o token (por exemplo, 123a4567-b89c-12d3-e456-789012345678).

  3. Registre seu token de depuração com App Check:

    1. No console do Firebase, acesse a guia Segurança > App Check > Apps.

    2. Encontre seu app, clique no menu flutuante () e selecione Gerenciar tokens de depuração.

    3. Siga as instruções na tela para registrar seu token de depuração.

Para mais detalhes sobre o provedor de depuração, incluindo como receber um novo token de depuração, consulte a documentação oficial do App Check.

Kotlin

Confira como usar o provedor de depuração enquanto executa seu app em um emulador de forma interativa (por exemplo, durante o desenvolvimento local):

  1. No build de depuração, configure App Check para usar a fábrica do provedor de depuração:

    Firebase.initialize(context = this)
Firebase.appCheck.installAppCheckProviderFactory(
    DebugAppCheckProviderFactory.getInstance(),
)

  2. Receba seu token de depuração:

    1. Execute o app no emulador ou no dispositivo de teste.

    2. Procure o token de depuração App Check nos seus registros. Exemplo:

      D DebugAppCheckProvider: Enter this debug secret into the allow list
in the Firebase Console for your project: 123a4567-b89c-12d3-e456-789012345678

    3. Copie o token (por exemplo, 123a4567-b89c-12d3-e456-789012345678).

  3. Registre seu token de depuração com App Check:

    1. No console do Firebase, acesse a guia Segurança > App Check > Apps.

    2. Encontre seu app, clique no menu flutuante () e selecione Gerenciar tokens de depuração.

    3. Siga as instruções na tela para registrar seu token de depuração.

Para mais detalhes sobre o provedor de depuração, incluindo como receber um novo token de depuração, consulte a documentação oficial do App Check.

Java

Confira como usar o provedor de depuração enquanto executa seu app em um emulador de forma interativa (por exemplo, durante o desenvolvimento local):

  1. No build de depuração, configure App Check para usar a fábrica do provedor de depuração:

    FirebaseApp.initializeApp(/*context=*/ this);
FirebaseAppCheck firebaseAppCheck = FirebaseAppCheck.getInstance();
firebaseAppCheck.installAppCheckProviderFactory(
        DebugAppCheckProviderFactory.getInstance());

  2. Receba seu token de depuração:

    1. Execute o app no emulador ou no dispositivo de teste.

    2. Procure o token de depuração App Check nos seus registros. Exemplo:

      D DebugAppCheckProvider: Enter this debug secret into the allow list
in the Firebase Console for your project: 123a4567-b89c-12d3-e456-789012345678

    3. Copie o token (por exemplo, 123a4567-b89c-12d3-e456-789012345678).

  3. Registre seu token de depuração com App Check:

    1. No console do Firebase, acesse a guia Segurança > App Check > Apps.

    2. Encontre seu app, clique no menu flutuante () e selecione Gerenciar tokens de depuração.

    3. Siga as instruções na tela para registrar seu token de depuração.

Para mais detalhes sobre o provedor de depuração, incluindo como receber um novo token de depuração, consulte a documentação oficial do App Check.

Web

Veja como usar o provedor de depuração ao executar seu app em localhost de forma interativa (por exemplo, durante o desenvolvimento local):

  1. No build de depuração, ative o modo de depuração definindo self.FIREBASE_APPCHECK_DEBUG_TOKEN como true antes de inicializar App Check. Exemplo:

    self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
initializeAppCheck(app, { /* App Check options */ });

  2. Acesse seu app da Web localmente e abra as ferramentas para desenvolvedores do navegador. No console de depuração, você verá um token:

    AppCheck debug token: "123a4567-b89c-12d3-e456-789012345678".
You will need to safelist it in the Firebase console for it to work.

  3. Registre seu token de depuração com App Check:

    1. No console do Firebase, acesse a guia Segurança > App Check > Apps.

    2. Encontre seu app, clique no menu flutuante () e selecione Gerenciar tokens de depuração.

    3. Siga as instruções na tela para registrar seu token de depuração.

Para mais detalhes sobre o provedor de depuração, incluindo como receber um novo token de depuração, consulte a documentação oficial do App Check.

Dart

iOS+

Confira como usar o provedor de depuração enquanto executa seu app em um simulador de forma interativa (por exemplo, durante o desenvolvimento local):

  1. Ative o App Check com o provedor de depuração logo depois de inicializar o app do Firebase:

    import 'package:flutter/material.dart';
import 'package:firebase_core/firebase_core.dart';

// Import the firebase_app_check plugin
import 'package:firebase_app_check/firebase_app_check.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();
  await FirebaseAppCheck.instance.activate(
    // Set appleProvider to `AppleProvider.debug`
    appleProvider: AppleProvider.debug,
  );
  runApp(App());
}

  2. Ative a geração de registros de depuração no seu projeto do Xcode:

    1. Abra Produto > Esquema > Editar esquema.
    2. Selecione Executar no menu à esquerda e depois a guia Argumentos.
    3. Na seção Arguments Passed on Launch, adicione -FIRDebugEnabled.

  3. Receba seu token de depuração:

    1. Abra ios/Runner.xcworkspace com o Xcode e execute o app no simulador ou no dispositivo de teste.

    2. Abra o console do Xcode e procure o token de depuração App Check. Exemplo:

      <Warning> [AppCheckCore][I-GAC004001] App Check debug token: '123a4567-b89c-12d3-e456-789012345678'.

    3. Copie o token (por exemplo, 123a4567-b89c-12d3-e456-789012345678).

  4. Registre seu token de depuração com App Check:

    1. No console do Firebase, acesse a guia Segurança > App Check > Apps.

    2. Encontre seu app, clique no menu flutuante () e selecione Gerenciar tokens de depuração.

    3. Siga as instruções na tela para registrar seu token de depuração.

Android

Confira como usar o provedor de depuração enquanto executa seu app em um emulador de forma interativa (por exemplo, durante o desenvolvimento local):

  1. Ative o App Check com o provedor de depuração logo depois de inicializar o app do Firebase:

    import 'package:flutter/material.dart';
import 'package:firebase_core/firebase_core.dart';

// Import the firebase_app_check plugin
import 'package:firebase_app_check/firebase_app_check.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();
  await FirebaseAppCheck.instance.activate(
    // Set androidProvider to `AndroidProvider.debug`
    androidProvider: AndroidProvider.debug,
  );
  runApp(App());
}

  2. Receba seu token de depuração:

    1. Execute o app no emulador ou no dispositivo de teste.

    2. Procure o token de depuração App Check nos seus registros. Exemplo:

      D DebugAppCheckProvider: Enter this debug secret into the allow list
in the Firebase Console for your project: 123a4567-b89c-12d3-e456-789012345678

    3. Copie o token (por exemplo, 123a4567-b89c-12d3-e456-789012345678).

  3. Registre seu token de depuração com App Check:

    1. No console do Firebase, acesse a guia Segurança > App Check > Apps.

    2. Encontre seu app, clique no menu flutuante () e selecione Gerenciar tokens de depuração.

    3. Siga as instruções na tela para registrar seu token de depuração.

Web

Veja como usar o provedor de depuração ao executar seu app em localhost de forma interativa (por exemplo, durante o desenvolvimento local):

  1. No arquivo web/index.html, ative o modo de depuração configurando self.FIREBASE_APPCHECK_DEBUG_TOKEN como true:

    <body>
  <script>
    self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
  </script>

  ...

</body>

  2. Execute seu app da Web localmente e abra as ferramentas para desenvolvedores do navegador. No console de depuração, você verá um token:

    AppCheck debug token: "123a4567-b89c-12d3-e456-789012345678".
You will need to safelist it in the Firebase console for it to work.

    Esse token é armazenado localmente no navegador e será usado sempre que você usar o app no mesmo navegador e na mesma máquina. Se você quiser usar o token em outro navegador ou em outra máquina, defina self.FIREBASE_APPCHECK_DEBUG_TOKEN como a string do token em vez de true.

  3. Registre seu token de depuração com App Check:

    1. No console do Firebase, acesse a guia Segurança > App Check > Apps.

    2. Encontre seu app, clique no menu flutuante () e selecione Gerenciar tokens de depuração.

    3. Siga as instruções na tela para registrar seu token de depuração.

Para mais detalhes sobre o provedor de depuração, incluindo como receber um novo token de depuração, consulte a documentação oficial do App Check.

Unity

Confira como usar o provedor de depuração enquanto executa seu app em um emulador de forma interativa (por exemplo, durante o desenvolvimento local):

  1. No console Firebase, crie um token de depuração:

    1. No console do Firebase, acesse a guia Segurança > App Check > Apps.

    2. Encontre seu app, clique no menu flutuante () e selecione Gerenciar tokens de depuração.

    3. Siga as instruções na tela para criar um novo token de depuração.

  2. No código de inicialização do app, adicione o seguinte:

    using Firebase.AppCheck;

void InitializeFirebase() {
  // Configure the Debug Provider factory with your debug token.
  DebugAppCheckProviderFactory.Instance.SetDebugToken("YOUR_DEBUG_TOKEN");

  // Set App Check to use the debug provider factory
  FirebaseAppCheck.SetAppCheckProviderFactory(
    DebugAppCheckProviderFactory.Instance);

  // Proceed to initialize Firebase as normal
}

Para mais detalhes sobre o provedor de depuração, incluindo como receber um novo token de depuração, consulte a documentação oficial do App Check.

Etapa 3: configurar o App Check para usuários finais e produção

Quando estiver tudo pronto para lançar o app para usuários finais, registre os apps e configure um provedor de atestação de produção (como o App Attest, a Play Integrity ou o reCAPTCHA Enterprise).

  1. Escolha um provedor de declaração de produção e siga as instruções de implementação nos links a seguir:

    Se nenhum desses provedores de atestado for suficiente para suas necessidades, você poderá implementar um provedor personalizado que use um provedor de atestado terceirizado ou suas próprias técnicas de atestado.

  2. (Recomendado) Melhore a proteção adicionando a proteção contra repetição, o que significa que um token App Check só pode ser usado uma vez.

Melhorar a proteção adicionando proteção contra repetição

Recomendamos usar as versões mais recentes do SDK, mas verifique se você está usando pelo menos uma destas versões para usar a proteção contra repetição:
plataformas da Apple v12.2.0+ | BoM do Android v34.14.0+ (App Check v19.1.0+) | Web v12.14.0+ | Flutter v4.15.0+ (App Check v4.10.0+) | Unity v13.12.0+

Por padrão, o App Check usa tokens de sessão, que têm uma vida útil (TTL) configurável entre 30 minutos e 7 dias. Esses tokens de sessão são armazenados em cache pelo SDK App Check, enviados com solicitações do seu app e podem ser reutilizados até que o TTL expire. O uso de tokens de sessão é considerado uma proteção básica.

No entanto, é possível reforçar a proteção além dessa proteção básica aplicando a proteção contra reprodução, que usa tokens de uso limitado. Quando a proteção contra repetição é aplicada, acontece o seguinte:

  • O App Check vai bloquear solicitações para Firebase AI Logic que usam tokens de sessão. Em vez disso, o App Check só permite uma solicitação para Firebase AI Logic se ela usar um token de uso limitado recém-criado.

  • Depois que o token de uso limitado é verificado, ele é consumido para que possa ser usado apenas uma vez, o que evita ataques de repetição.

  • O SDK App Check gera um novo token de uso limitado para cada solicitação. Esse processo pode afetar suas solicitações adicionando alguma latência e, às vezes, custos (dependendo do provedor de atestado).

Configurar e aplicar a proteção contra repetição

Clique no seu provedor de Gemini API para conferir o conteúdo e o código específicos do provedor nesta página.

Saiba como configurar e aplicar a proteção de repetição:

  1. Se você ainda não fez isso, configure o App Check seguindo as instruções anteriores nesta página.

  2. Ative o uso de tokens de uso limitado.

    No app, durante a instanciação, defina o parâmetro useLimitedUseAppCheckTokens como true:

    Swift 

    
// ...

// During instantiation, enable usage of limited-use tokens.
let ai = FirebaseAI.firebaseAI(
  backend: .googleAI(),
  useLimitedUseAppCheckTokens: true
)

// ...

    Kotlin 

    
// ...

// During instantiation, enable usage of limited-use tokens.
val ai = Firebase.ai(
  backend = GenerativeBackend.googleAI(),
  useLimitedUseAppCheckTokens = true
)

// ...

    Java 

    
// ...

// During instantiation, enable usage of limited-use tokens.
FirebaseAI ai = FirebaseAI.getInstance(
  /* backend: */ GenerativeBackend.googleAI(),
  /* useLimitedUseAppCheckTokens: */ true
);

// ...

    Web 

    
// ...

// During instantiation, enable usage of limited-use tokens.
const ai = getAI(firebaseApp, {
  backend: new GoogleAIBackend(),
  useLimitedUseAppCheckTokens: true
});

// ...

    Dart 

    
// ...

// During instantiation, enable usage of limited-use tokens
final ai = await FirebaseAI.googleAI(
  useLimitedUseAppCheckTokens: true,
);

// ...

    Unity 

    // ...

// During instantiation, enable usage of limited-use tokens
var ai = FirebaseAI.GetInstance(
  useLimitedUseAppCheckTokens: true
);

// ...

  3. Aplicar a proteção contra repetição.

    1. Na base de código do app, verifique se você ativou o uso de tokens de uso limitado (consulte a etapa anterior).

    2. No console do Firebase, acesse Segurança > App Check.

    3. Expanda a visualização de métricas para Firebase AI Logic.

    4. Verifique se a Proteção básica está Aplicada e clique em Continuar.

    5. Para proteção contra repetição, escolha Não aplicada (somente monitoramento) ou Aplicada.

      Considere o seguinte para decidir quando aplicar a proteção de repetição:

      • É recomendável monitorar suas solicitações se um número considerável de usuários estiver usando versões anteriores do app sem que os tokens de uso limitado estejam ativados. Se você aplicar a proteção contra repetição imediatamente, as solicitações desses usuários serão bloqueadas.

      • É possível monitorar especificamente a métrica Não verificado: token reutilizado, que é o número de solicitações com um token já usado em uma solicitação anterior. Monitore essa métrica no console do Firebase. Acesse a guia Segurança > App Check > APIs.

        Se uma parte significativa das solicitações recentes estiver nessa categoria, evite interromper os usuários e espere para aplicar a proteção contra repetição até que mais usuários tenham atualizado para uma versão do app que usa tokens de uso limitado.

Entenda como o Firebase AI Logic se integra ao App Check

Para usar os SDKs do Firebase AI Logic, a API Firebase AI Logic (firebasevertexai.googleapis.com) precisa estar ativada no seu projeto do Firebase. Isso acontece porque as solicitações feitas pelos SDKs do Firebase AI Logic são enviadas primeiro ao servidor do Firebase AI Logic, que atua como um gateway de proxy em que a verificação do Firebase App Check ocorre antes de a solicitação ser permitida para o back-end do provedor "Gemini API" escolhido e as APIs para acessar os modelos do Gemini e Imagen.

Perguntas frequentes e solução de problemas

Encontre mais perguntas frequentes e soluções de problemas ou códigos de erro relacionados a Firebase AI Logic.