Zapobieganie nadużyciom interfejsu Gemini API za pomocą funkcji Sprawdzanie aplikacji Firebase

Gdy wywołujesz interfejs API bezpośrednio z aplikacji mobilnej lub aplikacji internetowej, jest on narażony na nadużycia ze strony nieautoryzowanych klientów. Jeśli chcesz wywołać Gemini API bezpośrednio z aplikacji mobilnej lub internetowej, musisz chronić ją przed nadużyciami, używając Firebase AI Logic i wymuszając Firebase App Check. Jeśli wymusisz App Check, zezwolisz tylko na przychodzące żądania, które zostały zweryfikowane jako pochodzące z Twojej aplikacji lub z niezmienionego urządzenia.

Przejdź do instrukcji konfiguracji

Firebase AI Logic udostępnia bramę proxy, która umożliwia integrację z Gemini API i ochronę Firebase App Check, gdy jest ona wywoływana bezpośrednio przez aplikacje mobilne i internetowe. Gdy App Check jest egzekwowane w przypadku Firebase AI Logic, pomaga to chronić zarówno Gemini Developer API, jak i Agent Platform Gemini API (formerly Vertex AI).

App Check w przypadku Firebase AI Logic obsługuje też ochronę przed atakami typu replay, co oznacza, że token App Check może być użyty tylko raz.


Ogólne podsumowanie działania App Check

Dzięki App Check urządzenia, na których działa Twoja aplikacja, korzystają z usługi potwierdzania autentyczności aplikacji lub urządzenia, która weryfikuje co najmniej jeden z tych elementów:

  • Żądania pochodzą z autentycznej aplikacji.
  • żądania pochodzą z oryginalnego, niezmodyfikowanego urządzenia;

To zaświadczenie jest dołączane do każdego żądania wysyłanego przez aplikację za pomocą pakietu SDK Firebase AI Logic. Gdy App Check jest wymuszane, żądania od klientów bez prawidłowego zaświadczenia zostaną odrzucone. Dotyczy to też żądań pochodzących z aplikacji lub platform, które nie zostały przez Ciebie autoryzowane.

Podczas konfigurowania App Check rozważ dodanie ochrony przed atakami typu replay, która sprawia, że tokeny App Check są jednorazowe. Ta opcja zapewnia lepszą ochronę niż ochrona podstawowa i umożliwia ustawienie odpowiedniego poziomu ochrony aplikacji i przypadków użycia.

Szczegółowe informacje o App Check znajdziesz w dokumentacji, w tym opisy dostawców atestów oraz obowiązujące limity.

Skonfiguruj usługę App Check

Poniższe instrukcje są zoptymalizowane pod kątem konfigurowania Firebase App Checkegzekwowania zasad w przypadku Firebase AI Logic.

Krok 1. Wymuś App Check

Od początku lipca 2026 r. w trakcie procesu konfiguracji z przewodnikiem w  FirebasekonsoliFirebase App Check Firebase automatycznie będzie wymuszać Firebase AI Logic w przypadku Firebase App Check, aby chronić Gemini API.

Jeśli jednak Firebase AI Logic zostało już skonfigurowane w projekcie Firebase przed początkiem lipca 2026 roku (lub App Check nie jest egzekwowane z innego powodu), możesz samodzielnie wymusić App Check, postępując zgodnie z tymi instrukcjami.

  1. Sprawdź, czy App Check jest już wymuszane w przypadku Firebase AI Logic.

    1. W konsoli Firebase otwórz kartę Zabezpieczenia > Sprawdzanie aplikacji > Interfejsy API.

    2. Znajdź wiersz Firebase AI Logic. Jeśli wyświetla się Unenforced, wykonaj pozostałe instrukcje.

  2. Kliknij wiersz z symbolem Firebase AI Logic, aby wyświetlić wykresy danych. Pod tymi wykresami kliknij Skonfiguruj.

  3. Na pierwszym ekranie okna (Ochrona podstawowa) wybierz Wymuszona, a następnie kliknij Dalej.

  4. Na następnym ekranie (Ochrona przed powtórzeniem) wybierz Wyłączone, a potem kliknij Dalej.

  5. Na ostatnim ekranie zapoznaj się z kwestiami dotyczącymi egzekwowania App Check , aby upewnić się, że możesz to zrobić App Check. Gdy wszystko będzie gotowe, kliknij Dalej.

    Nie musisz rejestrować aplikacji, jeśli chcesz tylko wymuszać App Check i tylko używać dostawcy debugowania z Firebase AI Logic w aplikacji przedprodukcyjnej. Gdy jednak będziesz gotowy(-a) do udostępnienia aplikacji użytkownikom końcowym, musisz zarejestrować aplikacje w ramach konfigurowania dostawcy atestów produkcyjnych (np. App Attest, Play Integrity lub reCAPTCHA Enterprise).

Krok 2. Skonfiguruj dostawcę debugowania na potrzeby lokalnego programowania

W przypadku lokalnego środowiska programistycznego możesz skonfigurować App Check dostawcę debugowania i nadal utrzymywać wymuszanie App Check w przypadku Firebase AI Logic.

Swift

Aby użyć dostawcy debugowania podczas interaktywnego uruchamiania aplikacji w symulatorze (np. podczas lokalnego tworzenia):

  1. W projekcie Xcode zaimportuj FirebaseAppCheck i zainicjuj App Check za pomocą fabryki dostawcy debugowania przed skonfigurowaniem 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. Uzyskaj token debugowania:

    1. Uruchom aplikację w symulatorze lub na urządzeniu testowym.

    2. Otwórz konsolę Xcode i poszukaj App Checktokena debugowania. Przykład:

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

    3. Skopiuj token (np. 123a4567-b89c-12d3-e456-789012345678).

  3. Zarejestruj token debugowania u dostawcy App Check:

    1. W konsoli Firebase otwórz Zabezpieczenia > Sprawdzanie aplikacji > karta Aplikacje.

    2. Znajdź aplikację, kliknij rozszerzone menu (), a następnie wybierz Zarządzaj tokenami debugowania.

    3. Postępuj zgodnie z instrukcjami wyświetlanymi na ekranie, aby zarejestrować token debugowania.

Szczegółowe informacje o dostawcy debugowania (w tym o tym, jak uzyskać nowy token debugowania) znajdziesz w oficjalnej dokumentacji App Check.

Kotlin

Oto jak używać dostawcy debugowania podczas interaktywnego uruchamiania aplikacji w emulatorze (np. podczas lokalnego programowania):

  1. W kompilacji do debugowania skonfiguruj App Check tak, aby używała fabryki dostawcy debugowania:

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

  2. Uzyskaj token debugowania:

    1. Uruchom aplikację w emulatorze lub na urządzeniu testowym.

    2. W logach poszukaj App Checktokena debugowania. Przykład:

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

    3. Skopiuj token (np. 123a4567-b89c-12d3-e456-789012345678).

  3. Zarejestruj token debugowania u dostawcy App Check:

    1. W konsoli Firebase otwórz Zabezpieczenia > Sprawdzanie aplikacji > karta Aplikacje.

    2. Znajdź aplikację, kliknij rozszerzone menu (), a następnie wybierz Zarządzaj tokenami debugowania.

    3. Postępuj zgodnie z instrukcjami wyświetlanymi na ekranie, aby zarejestrować token debugowania.

Szczegółowe informacje o dostawcy debugowania (w tym o tym, jak uzyskać nowy token debugowania) znajdziesz w oficjalnej dokumentacji App Check.

Java

Oto jak używać dostawcy debugowania podczas interaktywnego uruchamiania aplikacji w emulatorze (np. podczas lokalnego programowania):

  1. W kompilacji do debugowania skonfiguruj App Check tak, aby używała fabryki dostawcy debugowania:

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

  2. Uzyskaj token debugowania:

    1. Uruchom aplikację w emulatorze lub na urządzeniu testowym.

    2. W logach poszukaj App Checktokena debugowania. Przykład:

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

    3. Skopiuj token (np. 123a4567-b89c-12d3-e456-789012345678).

  3. Zarejestruj token debugowania u dostawcy App Check:

    1. W konsoli Firebase otwórz Zabezpieczenia > Sprawdzanie aplikacji > karta Aplikacje.

    2. Znajdź aplikację, kliknij rozszerzone menu (), a następnie wybierz Zarządzaj tokenami debugowania.

    3. Postępuj zgodnie z instrukcjami wyświetlanymi na ekranie, aby zarejestrować token debugowania.

Szczegółowe informacje o dostawcy debugowania (w tym o tym, jak uzyskać nowy token debugowania) znajdziesz w oficjalnej dokumentacji App Check.

Web

Aby użyć dostawcy debugowania podczas interaktywnego uruchamiania aplikacji z localhost (np. podczas lokalnego programowania):

  1. W kompilacji do debugowania włącz tryb debugowania, ustawiając wartość self.FIREBASE_APPCHECK_DEBUG_TOKEN na true przed zainicjowaniem App Check. Przykład:

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

  2. Otwórz aplikację internetową lokalnie i uruchom narzędzia programisty w przeglądarce. W konsoli debugowania zobaczysz token debugowania:

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

  3. Zarejestruj token debugowania u dostawcy App Check:

    1. W konsoli Firebase otwórz Zabezpieczenia > Sprawdzanie aplikacji > karta Aplikacje.

    2. Znajdź aplikację, kliknij rozszerzone menu (), a następnie wybierz Zarządzaj tokenami debugowania.

    3. Postępuj zgodnie z instrukcjami wyświetlanymi na ekranie, aby zarejestrować token debugowania.

Szczegółowe informacje o dostawcy debugowania (w tym o tym, jak uzyskać nowy token debugowania) znajdziesz w oficjalnej dokumentacji App Check.

Dart

iOS+

Aby użyć dostawcy debugowania podczas interaktywnego uruchamiania aplikacji w symulatorze (np. podczas lokalnego tworzenia):

  1. Aktywuj App Check za pomocą dostawcy debugowania od razu po zainicjowaniu aplikacji w 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. Włącz logowanie debugowania w projekcie Xcode:

    1. Kliknij Product (Produkt) > Scheme (Schemat) > Edit scheme (Edytuj schemat).
    2. W menu po lewej stronie kliknij Run (Uruchom), a następnie wybierz kartę Arguments (Argumenty).
    3. W sekcji Arguments Passed on Launch (Argumenty przekazywane przy uruchamianiu) dodaj -FIRDebugEnabled.

  3. Uzyskaj token debugowania:

    1. Otwórz ios/Runner.xcworkspace w Xcode i uruchom aplikację w symulatorze lub na urządzeniu testowym.

    2. Otwórz konsolę Xcode i poszukaj App Checktokena debugowania. Przykład:

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

    3. Skopiuj token (np. 123a4567-b89c-12d3-e456-789012345678).

  4. Zarejestruj token debugowania u dostawcy App Check:

    1. W konsoli Firebase otwórz Zabezpieczenia > Sprawdzanie aplikacji > karta Aplikacje.

    2. Znajdź aplikację, kliknij rozszerzone menu (), a następnie wybierz Zarządzaj tokenami debugowania.

    3. Postępuj zgodnie z instrukcjami wyświetlanymi na ekranie, aby zarejestrować token debugowania.

Android

Oto jak używać dostawcy debugowania podczas interaktywnego uruchamiania aplikacji w emulatorze (np. podczas lokalnego programowania):

  1. Aktywuj App Check za pomocą dostawcy debugowania od razu po zainicjowaniu aplikacji w 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. Uzyskaj token debugowania:

    1. Uruchom aplikację w emulatorze lub na urządzeniu testowym.

    2. W logach poszukaj App Checktokena debugowania. Przykład:

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

    3. Skopiuj token (np. 123a4567-b89c-12d3-e456-789012345678).

  3. Zarejestruj token debugowania u dostawcy App Check:

    1. W konsoli Firebase otwórz Zabezpieczenia > Sprawdzanie aplikacji > karta Aplikacje.

    2. Znajdź aplikację, kliknij rozszerzone menu (), a następnie wybierz Zarządzaj tokenami debugowania.

    3. Postępuj zgodnie z instrukcjami wyświetlanymi na ekranie, aby zarejestrować token debugowania.

Sieć

Aby użyć dostawcy debugowania podczas interaktywnego uruchamiania aplikacji z localhost (np. podczas lokalnego programowania):

  1. W pliku web/index.html włącz tryb debugowania, ustawiając wartość self.FIREBASE_APPCHECK_DEBUG_TOKEN na true:

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

  ...

</body>

  2. Uruchom aplikację internetową lokalnie i otwórz narzędzia programisty w przeglądarce. W konsoli debugowania zobaczysz token debugowania:

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

    Ten token jest przechowywany lokalnie w przeglądarce i będzie używany za każdym razem, gdy będziesz korzystać z aplikacji w tej samej przeglądarce na tym samym komputerze. Jeśli chcesz użyć tokena w innej przeglądarce lub na innym urządzeniu, ustaw self.FIREBASE_APPCHECK_DEBUG_TOKEN na ciąg tokena zamiast true.

  3. Zarejestruj token debugowania u dostawcy App Check:

    1. W konsoli Firebase otwórz Zabezpieczenia > Sprawdzanie aplikacji > karta Aplikacje.

    2. Znajdź aplikację, kliknij rozszerzone menu (), a następnie wybierz Zarządzaj tokenami debugowania.

    3. Postępuj zgodnie z instrukcjami wyświetlanymi na ekranie, aby zarejestrować token debugowania.

Szczegółowe informacje o dostawcy debugowania (w tym o tym, jak uzyskać nowy token debugowania) znajdziesz w oficjalnej dokumentacji App Check.

Unity

Oto jak używać dostawcy debugowania podczas interaktywnego uruchamiania aplikacji w emulatorze (np. podczas lokalnego programowania):

  1. W konsoli Firebase utwórz token debugowania:

    1. W konsoli Firebase otwórz Zabezpieczenia > Sprawdzanie aplikacji > karta Aplikacje.

    2. Znajdź aplikację, kliknij rozszerzone menu (), a następnie wybierz Zarządzaj tokenami debugowania.

    3. Aby utworzyć nowy token debugowania, postępuj zgodnie z instrukcjami wyświetlanymi na ekranie.

  2. W kodzie inicjowania aplikacji dodaj ten kod:

    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
}

Szczegółowe informacje o dostawcy debugowania (w tym o tym, jak uzyskać nowy token debugowania) znajdziesz w oficjalnej dokumentacji App Check.

Krok 3. Skonfiguruj App Check dla użytkowników i środowiska produkcyjnego

Gdy aplikacja będzie gotowa do udostępnienia użytkownikom, musisz ją zarejestrować i skonfigurować dostawcę atestu wersji produkcyjnej (np. App Attest, Play Integrity lub reCAPTCHA Enterprise).

  1. Wybierz dostawcę atestów produkcyjnych i postępuj zgodnie z instrukcjami wdrażania, które znajdziesz pod tymi linkami:

    Jeśli żaden z tych dostawców atestów nie spełnia Twoich potrzeb, możesz wdrożyć dostawcę niestandardowego, który korzysta z zewnętrznego dostawcy atestów lub własnych technik atestowania.

  2. (Zalecane) Zwiększ ochronę, dodając ochronę przed atakami typu replay, co oznacza, że token App Check może być użyty tylko raz.

Zwiększanie ochrony przez dodanie ochrony przed powtórzeniem

Zalecamy używanie najnowszych wersji pakietu SDK, aleaby korzystać z ochrony przed powtórzeniem, musisz używać co najmniej jednej z tych wersji:
Platformy Apple w wersji 12.2.0 lub nowszej | Android BoM w wersji 34.14.0 lub nowszej (App Check w wersji 19.1.0 lub nowszej) | Web w wersji 12.14.0 lub nowszej | Flutter w wersji 4.15.0 lub nowszej (App Check w wersji 4.10.0 lub nowszej) | Unity w wersji 13.12.0 lub nowszej

Domyślnie App Check używa tokenów sesji, które mają konfigurowalny czas życia (TTL) w zakresie od 30 minut do 7 dni. Te tokeny sesji są buforowane przez pakiet SDK App Check, wysyłane wraz z żądaniami z aplikacji i mogą być ponownie używane do momentu wygaśnięcia ich czasu życia. Używanie tokenów sesji jest uważane za podstawową ochronę.

Możesz jednak zwiększyć ochronę poza ten poziom podstawowy, wymuszając ochronę przed powtórzeniem, która zamiast tego używa tokenów ograniczonego użytku. Gdy ochrona przed powtórzeniem jest wymuszana, dzieje się to:

  • App Check będzie blokować żądania wysyłane do Firebase AI Logic, które używają tokenów sesji. App Check zezwoli na żądanie Firebase AI Logic tylko wtedy, gdy będzie ono używać nowo wygenerowanego tokena o ograniczonym użyciu.

  • Po zweryfikowaniu tokenu o ograniczonym użyciu jest on wykorzystywany, aby można go było użyć tylko raz, co zapobiega atakom typu replay.

  • Pakiet SDK App Check generuje nowy token o ograniczonym użyciu dla każdego żądania. Pamiętaj, że ten proces może wpłynąć na Twoje żądania, dodając pewne opóźnienie i czasami koszt (w zależności od dostawcy atestów).

Konfigurowanie i egzekwowanie ochrony przed powtórzeniami

Kliknij Gemini API dostawcę, aby wyświetlić na tej stronie treści i kod dostawcy.

Aby skonfigurować i wymusić ochronę przed ponownym odtwarzaniem:

  1. Jeśli jeszcze tego nie zrobiono, skonfiguruj App Check, wykonując instrukcje podane wcześniej na tej stronie.

  2. Włącz korzystanie z tokenów o ograniczonym użyciu.

    Podczas tworzenia instancji w aplikacji ustaw parametr useLimitedUseAppCheckTokens na 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. Wymuszaj ochronę przed powtórzeniem.

    1. W kodzie aplikacji upewnij się, że masz włączone używanie tokenów o ograniczonym zakresie użycia (patrz poprzedni krok).

    2. W konsoli Firebase otwórz Zabezpieczenia > Sprawdzanie aplikacji.

    3. Rozwiń widok danych dla Firebase AI Logic.

    4. Sprawdź, czy podstawowa ochrona jest wymagana, a następnie kliknij Dalej.

    5. W przypadku ochrony przed powtórzeniem wybierz Nieegzekwowana (tylko monitorowanie) lub Egzekwowana.

      Aby zdecydować, kiedy wymusić ochronę przed powtórzeniem, weź pod uwagę te kwestie:

      • Monitorowanie żądań jest zalecane, jeśli znaczna liczba użytkowników korzysta ze starszych wersji aplikacji bez włączonych tokenów o ograniczonym użyciu. Jeśli natychmiast włączysz ochronę przed powtórzeniem, żądania od tych użytkowników będą blokowane.

      • Możesz monitorować wskaźnik Niezweryfikowany: ponownie użyty token, który określa liczbę żądań zawierających token użyty już w poprzednim żądaniu. Monitoruj ten wskaźnik w Firebasekonsoli (kliknij Zabezpieczenia > Sprawdzanie aplikacji > karta Interfejsy API).

        Jeśli znaczna część ostatnich żądań należy do tej kategorii, możesz uniknąć zakłóceń u użytkowników i poczekać z wymuszaniem ochrony przed powtórzeniami, aż więcej użytkowników zaktualizuje aplikację do wersji, która używa tokenów ograniczonego użytku.

Dowiedz się, jak Firebase AI Logic integruje się z App Check

Aby korzystać z Firebase AI Logicpakietów SDK, w projekcie w Firebase musi być włączony Firebase AI Logicinterfejs API (firebasevertexai.googleapis.com). Dzieje się tak, ponieważ żądania wysyłane przez pakiety SDK Firebase AI Logic są najpierw przesyłane na serwer Firebase AI Logic, który działa jako brama proxy, w której następuje weryfikacja Firebase App Check zanim żądanie zostanie przekazane do backendu wybranego dostawcy „Gemini API” i interfejsów API umożliwiających dostęp do modeli Gemini i Imagen.

Najczęstsze pytania i rozwiązywanie problemów

Znajdź dodatkowe najczęstsze pytania i odpowiedzi oraz informacje o rozwiązywaniu problemów lub kody błędów związane z Firebase AI Logic.