Play Integrity API hinzufügen

Mit der Play Integrity API für PC können Sie prüfen, ob Interaktionen und Serveranfragen von einem echten PC stammen. Wenn potenziell riskante und betrügerische Interaktionen erkannt werden, kann der Backend-Server Ihrer App mit entsprechenden Maßnahmen darauf reagieren, um Angriffe und Missbrauch zu verhindern.

Die API gibt Ergebnisse zurück, mit denen Sie potenzielle Bedrohungen erkennen können, darunter:

• Risikobehaftete Geräte und Umgebungen:Mit dem deviceIntegrity-Ergebnis können Sie feststellen, ob Ihre App auf einem echten PC-Gerät oder einer echten Instanz von Google Play Spiele für PC ausgeführt wird.

In die API einbinden

Wenn Sie die Play Integrity API für PCs in Ihre App einbinden möchten, müssen Sie zuerst die Ersteinrichtung in der Google Cloud Console vornehmen. Danach müssen Sie für jede Integritätsprüfung die folgenden Schritte ausführen:

1. Integritätstoken vorbereiten
2. Integritätstoken anfordern
3. Token-Daten anfordern

Ersteinrichtung in der Google Cloud Console

Für jede App oder jedes SDK, das die Play Integrity API aufruft, muss ein Google Cloud-Projekt verwendet werden, um die Aufrufe zu authentifizieren und die API-Nutzung zu überwachen. Wenn Sie ein neues Cloud-Projekt erstellen möchten oder Ihre App ausschließlich außerhalb von Google Play vertrieben wird, können Sie Play Integrity API-Antworten über die Google Cloud Console aktivieren.

Erstellen Sie in der Google Cloud Console ein neues Cloud-Projekt oder wählen Sie ein vorhandenes Cloud-Projekt aus, das Sie mit der Play Integrity API für PC verwenden möchten. Rufen Sie APIs und Dienste auf. Wählen Sie APIs und Dienste aktivieren aus. Suchen Sie nach der Play Integrity API und aktivieren Sie sie. Sie können die Play Integrity API jetzt in Ihre App einbinden.

Schritt 1: Integritätstoken vorbereiten

void PrepareIntegrityToken(
  const PrepareIntegrityTokenParams & params,
  PrepareIntegrityTokenContinuation continuation
)

Bevor Sie ein Integritätstoken anfordern (siehe RequestIntegrityToken), müssen Sie die Play Integrity API vorbereiten („aufwärmen“). So kann Google Play Attestinformationen teilweise intelligent auf dem Gerät zwischenspeichern, um die Latenz auf dem kritischen Pfad zu verringern, wenn Sie ein Integritätsurteil anfordern.

Bei Erfolg wird die Fortsetzung mit einem PrepareIntegrityTokenResultValue aufgerufen, das ein RequestTokenData enthält, das zum Anfordern eines Integritätstokens verwendet werden sollte. Diese Daten sollten im Arbeitsspeicher zwischengespeichert und für die Dauer der Anwendungssitzung für Aufrufe von RequestIntegrityToken wiederverwendet werden. Ein Aufruf von PrepareIntegrityToken sollte nur erfolgen, wenn Ihre Anwendung feststellt, dass das Integritätsurteil vollständig neu bewertet werden muss.

Schritt 2: Integritätstoken anfordern

void RequestIntegrityToken(
  const RequestIntegrityTokenParams & params,
  RequestIntegrityTokenContinuation continuation
)

Integritätstokens sind ein Mechanismus, mit dem Ihre Anwendung überprüfen kann, ob das Gerät manipuliert wurde. Ihr Back-End-Server kann das Integritätstoken beispielsweise verwenden, um Folgendes zu überprüfen:

• Echtes Gerät: Prüfen Sie, ob Ihre Anwendung auf einem echten Gerät ausgeführt wird, das eine echte Instanz von Google Play Spiele für PC enthält und nicht manipuliert wurde.

Wenn Sie eine Nutzeraktion in Ihrer App mit der Play Integrity API für PC prüfen, können Sie das Feld RequestIntegrityTokenParams::request_hash verwenden, um Manipulationen zu verhindern. Beispielsweise möchte ein Spiel die Punktzahl des Spielers an den Backend-Server des Spiels senden und Ihr Server möchte überprüfen, ob diese Punktzahl nicht von einem Proxyserver manipuliert wurde. Die Play Integrity API gibt den Wert, den Sie in diesem Feld festlegen, in der signierten Integritätsantwort zurück. Ohne die requestHash ist das Integritätstoken nur an das Gerät gebunden, nicht an die jeweilige Anfrage. Das kann zu Angriffen führen.

So können Sie dieses Problem beim Anfordern eines Integritätsurteils vermeiden:

• Berechnen Sie einen Digest aller relevanten Anfrageparameter (z.B. SHA256 einer stabilen Anfrage-Serialisierung) aus der Nutzeraktion oder Serveranfrage, die gerade stattfindet.
• Setzen Sie das Feld RequestIntegrityTokenParams::request_hash auf den Digest.

Schritt 3: Tokendaten anfordern

Nachdem Sie ein Integritätsergebnis angefordert haben, stellt die Play Integrity API ein verschlüsseltes Antworttoken bereit. Um die Ergebnisse zur Geräteintegrität zu erhalten, müssen Sie das Integritätstoken auf den Google-Servern entschlüsseln. Führen Sie dazu die folgenden Schritte aus:

1. Erstellen Sie ein Dienstkonto im Google Cloud-Projekt, das mit Ihrer App verknüpft ist.

2. Rufen Sie auf dem Server Ihrer App das Zugriffstoken mit dem Bereich „playintegrity“ aus den Anmeldedaten Ihres Dienstkontos ab und senden Sie die folgende Anfrage:

   playintegrity.googleapis.com/v1/<var>PACKAGE_NAME</var>:decodePcIntegrityToken -d \
    '{ "integrity_token": "<var>INTEGRITY_TOKEN</var>" }'
   

3. Lesen Sie die JSON-Antwort.

Die resultierende Nutzlast ist ein Nur-Text-Token, das Integritätsergebnisse und Details sowie vom Entwickler bereitgestellte Informationen enthält. Das Tokenformat sieht so aus:

{
  "requestDetails": { ... },
  "deviceIntegrity": { ... },
}

Bevor Sie die einzelnen Integritätsurteile prüfen, müssen Sie zuerst prüfen, ob die Werte im Feld requestDetails mit denen der ursprünglichen Anfrage übereinstimmen. In den folgenden Abschnitten werden die einzelnen Felder genauer beschrieben.

Feld „Anfragedetails“

Das Feld requestDetails enthält Informationen zur Anfrage, einschließlich der vom Entwickler bereitgestellten Informationen in requestHash für Standardanfragen und in nonce für klassische Anfragen.

"requestDetails": {
  // Application package name this attestation was requested for.
  // Note that this field might be spoofed in the middle of the request.
  "requestPackageName": "com.package.name",
  // The timestamp when the integrity token was requested.
  "requestTime": "1675655009345"
  // Request hash provided by the developer.
  "requestHash": "aGVsbG8gd29scmQgdGhlcmU",
}

Diese Werte sollten mit denen der ursprünglichen Anfrage übereinstimmen. Prüfen Sie daher den requestDetails-Teil der JSON-Nutzlast und achten Sie darauf, dass requestPackageName und requestHash mit den Werten übereinstimmen, die in der ursprünglichen Anfrage gesendet wurden.

Feld „Geräteintegrität“

Das Feld deviceIntegrity kann einen einzelnen Wert, deviceRecognitionVerdict, enthalten, der ein oder mehrere Labels hat, die angeben, wie gut ein Gerät die App-Integrität erzwingen kann. Wenn ein Gerät die Kriterien für keine Labels erfüllt, wird deviceRecognitionVerdict im Feld deviceIntegrity ausgelassen.

"deviceIntegrity": {
  "deviceRecognitionVerdict": ["MEETS_PC_INTEGRITY"]
}

Standardmäßig kann deviceRecognitionVerdict Folgendes enthalten:

MEETS_PC_INTEGRITY

Gibt ein Ergebnis zurück, wenn die App in einer echten PC-Umgebung ausgeführt wird, in der keine Manipulationen auf dem Gerät erkannt wurden.

Leer (leerer Wert)

Die App wird auf einem Gerät ausgeführt, das Anzeichen für Angriffe (z. B. API-Hooks) oder Systemmanipulationen (z. B. durch Rooting) aufweist oder die App wird nicht auf einem physischen Gerät ausgeführt (z. B. einem Emulator, der die Google Play-Integritätsprüfungen nicht besteht).

Grenzen der Verwendung

Nutzungslimits für die Play Integrity API

Für Ihre App gilt ein Tageslimit von 10.000 Anfragen pro App. Wenn Ihre App eine höhere Anzahl von Nutzern verarbeiten muss, können Sie eine Erhöhung dieses Tageslimits beantragen. Folgen Sie dazu der Anleitung unten.

Tageslimit für Anfragen erhöhen

Damit Sie eine Erhöhung des Tageslimits für Anfragen beantragen können, muss Ihre App zusätzlich zu allen anderen Vertriebskanälen auch bei Google Play verfügbar sein.

So beantragen Sie eine Erhöhung des Tageslimits für Anfragen:

1. Verknüpfen Sie das Google Cloud-Projekt, das Sie für die Play Integrity API verwenden, in der Play Console.
2. Prüfen Sie, ob Sie die API-Logik korrekt implementieren, einschließlich der empfohlenen Wiederholungsstrategie.
3. Kontingenterhöhung über dieses Formular beantragen

Es kann bis zu einer Woche dauern, bis das Play Integrity API-Kontingent erhöht wird. Wir empfehlen Ihnen daher dringend, die Nutzung der Play Integrity API in der Google Play Console oder in der Google Cloud Console im Blick zu behalten. Dort können Sie auch Kontingentbenachrichtigungen einrichten, um Unterbrechungen Ihres Dienstes zu vermeiden.

Kontingenterhöhungen werden automatisch sowohl auf den Clientaufruf zum Generieren von Integritätstokens als auch auf den Serveraufruf zum Entschlüsseln und Überprüfen von Integritätstokens angewendet.

Sicherheitsaspekte

Die Play Integrity API bringt für Ihre App den größten Nutzen, wenn Sie die folgenden Best Practices einhalten:

Strategie zur Verhinderung von Missbrauch

Im Rahmen deiner Strategie gegen Missbrauch solltest du die Play Integrity API am besten zusammen mit anderen Signalen verwenden. Verwenden Sie diese API in Verbindung mit anderen geeigneten Sicherheits-Best Practices für Ihre App. Standardmäßig kann Ihre App pro Tag insgesamt bis zu 10.000 Anfragen über alle Installationen hinweg stellen. Sie können eine Erhöhung des Tageslimits beantragen.

Telemetriedaten erfassen und Zielgruppe analysieren, bevor Sie Maßnahmen ergreifen

Bevor Sie das Verhalten Ihrer App basierend auf den Ergebnissen der Play Integrity API ändern, können Sie die aktuelle Situation bei Ihrer bestehenden Zielgruppe nachvollziehen, indem Sie die API ohne Erzwingung implementieren. Sobald Sie wissen, welche Ergebnisse Ihre aktuelle Installationsbasis liefert, können Sie die Auswirkungen von geplanten Maßnahmen schätzen und Ihre Strategie zur Missbrauchsbekämpfung entsprechend anpassen.

Integritätsprüfung zum richtigen Zeitpunkt anfordern

API-Anfragen sollten so nah wie möglich am Zeitpunkt der Aktion oder Serveranfrage gesendet werden, die Sie schützen möchten.

API-Anfragen schwer nachzubilden

API-Anfragen enthalten ein Feld namens „requestHash“, das zum Schutz vor Manipulationen und ähnlichen Angriffen verwendet wird. In dieses Feld sollten Sie einen Digest aller relevanten Werte aus der Anfrage Ihrer App einfügen. Folgen Sie der Anleitung zum Verwenden der Inhaltsbindung, um die Standardanfragen Ihrer App zu schützen.

Ergebnisse zur Integrität nicht im Cache speichern

Durch das Zwischenspeichern von Integritätsergebnissen erhöht sich das Risiko von Proxying. Bei dieser Art von Angriff verwendet ein böswilliger Akteur ein Ergebnis von einem vertrauenswürdigen Gerät für missbräuchliche Zwecke in einer anderen Umgebung.

Eine Reihe von Antworten von Ihrem Server an Ihre App senden

Es ist schwieriger, eine Reihe von Entscheidungsergebnissen zu replizieren, als für jede Antwort eine binäre Antwort (Zulassen / Ablehnen) vom Server an die App zu senden. Sie könnten beispielsweise eine Reihe von zusammenhängenden Antworten wie „Zulassen“, „Mit Einschränkungen zulassen“, „Mit Einschränkungen zulassen, nachdem das CAPTCHA abgeschlossen wurde“ und „Ablehnen“ verwenden.

Aktionsfähige Fehlermeldungen anzeigen

Falls möglich, solltest du Nutzern informative Fehlermeldungen zur Problembehebung bereitstellen.

Plan für unerwartete Probleme oder Ausfälle

Das Google Play-Status-Dashboard enthält Informationen zum Dienststatus der Play Integrity API sowie Informationen zu Unterbrechungen und Ausfällen. Sie sollten im Voraus planen, wie sich Ihr Backend-Server im unwahrscheinlichen Fall eines groß angelegten Ausfalls der Play Integrity API verhalten soll.

Nutzungsbedingungen und Datensicherheit

Wenn Sie auf die Play Integrity API für PC zugreifen oder sie verwenden, stimmen Sie den Nutzungsbedingungen der Play Integrity API zu. Lesen und verstehen Sie alle anwendbaren Nutzungsbedingungen und Richtlinien, bevor Sie auf die API zugreifen.

In Google Play gibt es einen Abschnitt zur Datensicherheit, in dem Entwickler die Praktiken ihrer Apps hinsichtlich Datenerhebung, -weitergabe und -sicherheit offenlegen können, um Nutzer auf dem Laufenden zu halten. Weitere Informationen dazu, wie die Play Integrity API Daten verarbeitet, finden Sie hier.