KappS Wissensdatenbank · Blog

Google Play Integrity API 2026: Schritt-für-Schritt-Anleitung

Blog Leitfaden

Die Play Integrity API beantwortet für Ihr Backend eine eng umrissene, praktische Frage: Stammt diese Anfrage von der Kopie meiner App, die Google Play ausgeliefert hat, auf einem Gerät, das auch das ist, was es vorgibt zu sein? Ihr Server fordert bei Google ein Integritätsurteil an, erhält eine signierte Nutzlast und entscheidet – auf dem Server, nie auf dem Client –, wie weit er der Interaktion vertrauen kann. Das ist der Standardweg, um manipulierte Builds, geskriptete Clients, Emulatoren und per Sideload installierte Kopien auszubremsen, bevor sie Ihre Spielökonomie, Ihre Abo-Ansprüche oder Ihren Werbeumsatz erreichen.

Dieser Leitfaden folgt der Reihenfolge, in der Sie tatsächlich arbeiten werden: API aktivieren, ein Cloud-Projekt verknüpfen, zwischen einer Standard- und einer klassischen Anfrage wählen, den Token-Provider vorwärmen, ein Token anfordern und entschlüsseln, die Verdict-Felder lesen, Quota- und Fehlercodes behandeln und die Durchsetzung ausrollen, ohne zahlende Nutzer auszusperren. Eine Regel zieht sich durch alles – die API liefert Ihnen Signale für Ihre eigenen Entscheidungen, und der einzige dauerhafte Weg, eine Integritätsprüfung zu bestehen, ist, eine echte App über den offiziellen Kanal zu veröffentlichen.


1. Was die API bestätigt und was nicht

Standardmäßig kommen drei Urteilsfamilien zurück, und jede beantwortet eine andere Frage.

  • appIntegrity — stammt das aus Ihrem unveränderten Binary? Das appRecognitionVerdict liefert PLAY_RECOGNIZED, wenn Paket und Zertifikat mit dem übereinstimmen, was Google Play verteilt, UNRECOGNIZED_VERSION, wenn Zertifikat oder Paketname nicht mit den Play-Datensätzen übereinstimmen, und UNEVALUATED, wenn eine Voraussetzung fehlt.
  • deviceIntegrity — ist das Gerät echt? Standardmäßig kann das deviceRecognitionVerdict den Wert MEETS_DEVICE_INTEGRITY enthalten: ein echtes, zertifiziertes Android-Gerät mit hardwaregestütztem Nachweis ab Android 13, dass der Bootloader gesperrt ist und die geladene Software echt ist. Bei einem Gerät, das kein Label erfüllt, wird das Feld einfach weggelassen.
  • accountDetails — verfügt der Nutzer über eine Berechtigung? Das appLicensingVerdict liefert LICENSED (aus Google Play installiert oder aktualisiert), UNLICENSED oder UNEVALUATED.

Zwei Punkte der Disziplin sind wichtiger als die Feldliste. Erstens stellt Google ausdrücklich fest, dass die API am besten zusammen mit anderen Signalen funktioniert, als Teil einer übergreifenden Anti-Missbrauchsstrategie und nicht als Ihr einziges Instrument — ein Urteil ist ein einzelner Input, und es als einziges Kriterium zu behandeln, erzeugt sowohl Fehlalarme als auch einfache Umgehungen. Zweitens sind dies Risikosignale, keine Urteile über Ihre Nutzer: Ein Hobbyist auf einem gerooteten Gerät ist kein Krimineller, und die Reaktion sollte dem angemessen sein, was auf diesem Bildschirm tatsächlich auf dem Spiel steht.

2. Schritt 1 — die API aktivieren und ein Cloud-Projekt verknüpfen

Jede App oder jedes SDK, das die API aufruft, benötigt ein Google Cloud-Projekt, denn dort wird die Nutzung überwacht und das Kontingent verwaltet.

  1. Erstellen Sie in der Google Cloud Console ein neues Projekt oder wählen Sie ein bestehendes aus, das Sie verwenden möchten.
  2. Gehen Sie zu APIs und Dienste → APIs und Dienste aktivieren, suchen Sie nach Play Integrity API und klicken Sie auf Aktivieren.
  3. Verknüpfen Sie dann dieses Projekt mit Ihrer App. Öffnen Sie in der Play Console Ihre App, gehen Sie zu Mit Play geschützt, finden Sie Play Integrity API und wählen Sie Jetzt starten.

Die Verknüpfung ist der Schritt, der alles andere freischaltet. Ein Projekt, das in Cloud aktiviert, aber nicht in der Play Console verknüpft ist – bzw. in der Play SDK Console für SDKs –, ist nicht für die zusätzlichen Konfigurationsoptionen oder eine Quotenerhöhung berechtigt. Der Verknüpfungsablauf aktiviert die API für Sie, wenn Sie den Console-Schritt übersprungen haben, sodass beide Reihenfolgen funktionieren; das Weglassen der Verknüpfung nicht.

Die Entschlüsselung erfordert eine Anmeldeinformation, die Ihre App niemals mitführen darf. Erstellen Sie ein Dienstkonto im verknüpften Cloud-Projekt und rufen Sie den Decode-Endpunkt von Ihrem Server mit dem Scope playintegrity auf. Der Client fordert Tokens an; nur der Server öffnet sie.

3. Schritt 2 — wählen Sie eine Standard- oder eine klassische Anfrage

Es gibt zwei Anfrage-Stile, und gleich den richtigen zu wählen erspart später eine Überarbeitung.

  • Standardanfragen sind die Standardwahl für Apps auf Google Play. Sie laufen auf Android 5.0 (API-Level 21) und höher und bestehen aus zwei Aufrufen: Bereiten Sie den Integrity-Token-Provider im Voraus vor und fordern Sie dann einen Token an, wenn Sie tatsächlich einen benötigen.
  • Classic-Anfragen gibt es für die Fälle, die Standardanfragen nicht abdecken – vor allem für Apps, die ausschließlich außerhalb von Google Play vertrieben werden, und für SDKs. Strukturell ist eine Classic-Anfrage ein einzelner Aufruf, der eine von Ihnen erzeugte Nonce entgegennimmt, und Apps, die nicht über Play vertrieben werden, müssen zusätzlich ihre Cloud-Projektnummer mit setCloudProjectNumber() übergeben. Apps auf Play werden über die Konsole verknüpft und setzen sie nicht in der Anfrage.

Wenn Ihre App auf Google Play läuft, ist standard die richtige Wahl. Greifen Sie zu classic, wenn die Distribution tatsächlich außerhalb von Play stattfindet oder eine bestimmte Integration Sie einschränkt.

4. Schritt 3 — den Anbieter aufwärmen, dann das Token anfordern

Eine Standardanfrage wird bewusst in zwei Teile geteilt, damit der langsame Teil nie auf dem kritischen Pfad des Nutzers landet.

Bereiten Sie den Integritäts-Token-Provider vor, oder wärmen Sie ihn auf. Rufen Sie dies deutlich vor dem Zeitpunkt auf, zu dem Sie ein Urteil benötigen – typischerweise beim App-Start, was gut funktioniert, weil der Aufruf asynchron ist und die Startzeit nicht beeinflusst. Das Aufwärmen lässt Google Play teilweise Attestierungsinformationen auf dem Gerät zwischenspeichern, sodass die spätere Anfrage schnell ist; ein erneutes Vorbereiten ist zudem ein leichterer Weg, das nächste Urteil aktueller zu machen. Der Provider selbst kann ablaufen, wenn er zu lange gehalten wird, was sich als INTEGRITY_TOKEN_PROVIDER_INVALID zeigt; behandeln Sie das, indem Sie einen frischen Provider anfordern, statt den veralteten erneut zu versuchen.

Fordern Sie bei Bedarf ein Integritäts-Token an. Wenn die App einen Serveraufruf macht, für den Sie bürgen möchten, fordern Sie ein Token an und senden Sie es an Ihr Backend. Hängen Sie einen Request-Hash an: Berechnen Sie einen Digest — zum Beispiel SHA-256 der stabilen Parameter — und übergeben Sie ihn, denn die API gibt diesen Wert in der signierten Antwort zurück. Ohne ihn ist ein Token an das Gerät gebunden, aber nicht an die konkrete Anfrage, und genau diese Lücke braucht ein Proxy, um es für etwas anderes wiederzuverwenden.

Klassische Anfragen verwenden stattdessen eine von Ihnen bereitgestellte Nonce. Sie wird unverändert an Google übergeben, legen Sie also niemals personenbezogene oder sensible Daten hinein, und sie muss gültiges Base64 in einer akzeptierten Länge sein – andernfalls erhalten Sie NONCE_TOO_SHORT, NONCE_TOO_LONG oder NONCE_IS_NOT_BASE64 statt eines Urteils.

5. Schritt 4 – Entschlüsseln und verifizieren Sie auf Ihrem Server

Das Token, das Ihr Backend erreicht, ist verschlüsselt und nutzlos, bis Google es entschlüsselt. Mit den Anmeldedaten Ihres Dienstkontos und dem playintegrity-Scope ruft Ihr Server auf:

POST https://playintegrity.googleapis.com/v1/PACKAGE_NAME:decodeIntegrityToken { "integrity_token": "INTEGRITY_TOKEN" }

Zurück kommt eine JSON-Nutzlast im Klartext. Bevor Sie sich auch nur ein einziges Urteil ansehen, validieren Sie die Anfragedetails, denn die Nutzlast ist nur aussagekräftig, wenn sie wirklich die Antwort auf Ihre Anfrage ist:

  • requestPackageName muss Ihrem Paketnamen entsprechen;
  • requestHash muss mit dem von Ihnen gesendeten Hash übereinstimmen;
  • timestampMillis muss aktuell sein — vergleichen Sie es mit einem Aktualitätsfenster (ein zulässiges Fenster in Millisekunden) und lehnen Sie alles Ältere ab, da ein veraltetes Token ein Kandidat für einen Replay-Angriff ist.

Google Play wendet außerdem automatischen Replay-Schutz an, der verhindert, dass ein Integritätstoken mehrfach wiederverwendet wird. Betrachten Sie das als Sicherheitsnetz und nicht als Ersatz für Ihre eigene Aktualitätsprüfung, und dekodieren Sie das Token serverseitig im Moment der Aktion, statt eines für einen Tag zwischenzuspeichern.

6. Die Payload lesen, ohne übermäßig zu blockieren

Die Payload ist JSON mit requestDetails, appIntegrity, deviceIntegrity, accountDetails und — sobald Sie sich anmelden — environmentDetails. Die Feldreihenfolge ist nicht garantiert, lesen Sie daher immer über den Schlüssel. Eine praktikable Entscheidungsleiter sieht so aus.

  1. Bestätigen Sie zuerst die App: PLAY_RECOGNIZED bedeutet, dass Binary und Zertifikat die von Play verteilten sind.
  2. Schauen Sie dann auf das Gerät: MEETS_DEVICE_INTEGRITY ist die Standardhürde. Die zusätzlichen Labels – MEETS_BASIC_INTEGRITY, MEETS_STRONG_INTEGRITY und MEETS_VIRTUAL_INTEGRITY – sind optional und gehören zu einer abgestuften Strategie, nicht zu einem ersten Release.
  3. Verwenden Sie accountDetails, wo Berechtigungen eine Rolle spielen: UNLICENSED bedeutet, dass das Konto keine Play-Berechtigung hat. Auf manchen älteren Geräten kann eine Berechtigung jedoch nach der Deinstallation bestehen bleiben – lesen Sie den Wert daher als Signal, nicht als Tatsache.
  4. Wenn Sie environmentDetails aktiviert haben, sagt Ihnen das appAccessRiskVerdict, ob Apps vorhanden sind, die den Bildschirm erfassen oder Overlays einblenden können – seine appsDetected-Liste verwendet Werte wie KNOWN_INSTALLED, UNKNOWN_INSTALLED und UNKNOWN_CAPTURING –, und das Play-Protect-Verdict fasst den Play-Protect-Status des Geräts zusammen.

Zwei nicht offensichtliche Fälle verdienen besondere Beachtung beim Design. Emulatoren, die Systemintegritätsprüfungen bestehen und die zentralen Android-Kompatibilitätsanforderungen erfüllen, können ein eigenes Geräte-Label erhalten, sodass „Emulator" nicht automatisch „Angreifer" bedeutet. Und ein Gerät, das kein Label erfüllt, lässt das Feld ganz weg, was bedeutet, dass Code, der davon ausgeht, dass der Schlüssel immer vorhanden ist, abstürzt, statt sicher zu scheitern.

7. Kontingent, Fehlercodes und sicheres Scheitern

Standardmäßig kann Ihre App bis zu 10.000 Anfragen pro Tag über alle Installationen hinweg stellen. Diese Obergrenze wird nach einem Launch schneller erreicht, als Teams erwarten – beobachten Sie die Nutzung im verknüpften Cloud-Projekt und beantragen Sie eine Erhöhung, solange die Trendlinie Ihnen noch Spielraum lässt. Wird sie überschritten, erscheint TOO_MANY_REQUESTS (Fehlercode -8), was Sie mit exponentiellem Backoff abfangen und nicht durch Blockieren von Nutzern.

Die Fehlerbehandlung ist der Punkt, an dem Integrationen meist schiefgehen. Behandeln Sie diese als vorübergehend und wiederholen Sie den Versuch mit Backoff: NETWORK_ERROR (-3), TOO_MANY_REQUESTS (-8), GOOGLE_SERVER_UNAVAILABLE (-12) und CLIENT_TRANSIENT_ERROR (-18). Andere sind umgebungsbedingt — kein Play Store, keine Play-Dienste, eine veraltete Version der Play-Dienste, ein fehlendes Play-Konto, eine Cloud-Projektnummer, die die API ablehnt. Die Empfehlung von Google lautet hier, das Ergebnis so zu behandeln, als hätte der Client die Prüfungen nicht bestanden, während Sie die Interaktion so weit wie vernünftigerweise möglich nutzbar halten.

Behandeln Sie Fehler als Richtlinienfrage, nicht nur als Codepfad. Wenn Sie alle blockieren, deren Gerät ungewöhnlich aussieht, machen Sie aus einem Anti-Missbrauch-Signal ein Retention-Problem; jedes Scheitern stillschweigend zu ignorieren, ist der umgekehrte Fehler. Entscheiden Sie je Oberfläche – eine Bestenliste kann großzügig sein, ein Wallet-Top-up streng – und halten Sie die Entscheidung schriftlich fest, damit der nächste Entwickler die Begründung übernimmt.

Google liefert außerdem Remediation-Dialoge: app-ausgelöste, von Google geführte Abläufe, die einem legitimen Nutzer helfen, das zugrunde liegende Problem zu beheben, etwa indem er den offiziellen Build aus Play installiert oder die Verbindung wiederherstellt, statt ihn in einer Sackgasse zu lassen. Und wenn Sie nach einer Durchsetzungsmaßnahme wiederholten Missbrauch von derselben Hardware erkennen müssen, ist die Funktion Device Recall (Beta) genau dafür gemacht.

8. Ausrollen, ohne Ihre Nutzer zu verprellen

Telemetrie vor der Durchsetzung. Protokollieren Sie Urteile und ihre Verteilung einige Wochen, bevor Sie irgendetwas sperren, damit Sie den tatsächlichen Anteil von UNEVALUATED- und UNLICENSED-Ergebnissen in Ihrer eigenen Installationsbasis kennen und nicht aus dem Blogbeitrag von jemand anderem. Setzen Sie dann stufenweise durch: zuerst das Standard-Gerätelabel, weitere Labels später, und jeweils nur eine Oberfläche. Sorgen Sie dafür, dass der Client „erneut versuchen" von „nein" unterscheiden kann, und dass die App sauber degradiert, wenn die API schlicht nicht verfügbar ist – ein Nutzer in einem wackeligen Netz sollte den Zugang zu bereits bezahlten Inhalten nicht verlieren.

9. Wo KappS hineinpasst

KappS hilft Entwicklern, Konten und Releases in einem Zustand zu halten, der der Prüfung durch die Plattformen standhält — konforme Materialien vorbereiten und einreichen, niemals Prüfungen umgehen. In der Praxis bedeutet das:

  • Release-Hygiene. Mit Play App Signing signiert, über den offiziellen Kanal hochgeladen, Versionscodes und Zertifikate im Einklang mit den Aufzeichnungen, die Google Play erkennt – die Bedingungen, unter denen PLAY_RECOGNIZED überhaupt möglich ist.
  • Kontobereitschaft. Entwicklerprüfung, Zahlungsprofil und Steuerunterlagen im Einklang mit der rechtlichen Identität hinter dem Konto, damit ein Launch nicht durch eine unabhängige Prüfung ins Stocken gerät.
  • Integrationsprüfung. Ein zweiter Blick darauf, wie der Client Tokens anfordert, worauf der Server verzweigt und ob die Durchsetzungsstufe dem Geschäftsrisiko entspricht.

Wir bieten keine Integritätsumgehung, keine Verdict-Spoofing und keine Tools, die einen manipulierten Build vor Play verbergen — und wir werden es auch nicht tun. Genau das soll diese API erkennen, es gefährdet das Konto, und es ist keine Leistung, die wir erbringen. Der einzige dauerhafte Weg, eine Integritätsprüfung zu bestehen, ist, das echte Produkt zu sein.

Quellen (Google offizielle Dokumentation): Play Integrity API – Overview; Setup; Make a standard request; Make a classic request; About integrity verdicts; Use device recall; Handle error codes; Remediation dialogs (developer.android.com).

Sie verwalten Entwicklerkonten im großen Stil? Wir übernehmen die operative Seite.

Klicken Sie, um eine Datei auszuwählen · Rechtsklick → Einfügen oder Ctrl/⌘+V drücken, um einen Screenshot einzufügen

Sie können eine Datei auch auf dieses Feld ziehen.

Wir antworten an die von Ihnen angegebene E-Mail-Adresse. Ihre Daten bleiben bei KappS.

✔ Eingereicht

Wir haben Ihre Nachricht erhalten und antworten innerhalb von 24 Stunden.


← Zurück zum Bearbeiten