Play Integrity für PC in Ihre App einbinden

Mit Play Integrity für PC können Sie prüfen, ob Spielereignisse und Serveranfragen von einer echten Instanz von Google Play Games für PC auf einem echten PC stammen. Durch das Erkennen potenziell riskanter Geräte und unbekannter Emulatoren kann der Backend-Server Ihres Spiels mit geeigneten Aktionen reagieren, um Betrug, nicht autorisierten Zugriff, betrügerischen Traffic und Missbrauch zu verhindern.

Voraussetzungen

Richten Sie das SDK ein.
Lesen Sie die Sicherheitsüberlegungen zur Integrity API.
Lesen und verstehen Sie die Nutzungsbedingungen der Integrity API und Informationen zur Datenverarbeitung.
Erstellen Sie in der Google Cloud Console ein Cloud-Projekt oder wählen Sie ein vorhandenes Cloud-Projekt aus, das Sie mit Play Integrity für PC verwenden möchten. Rufen Sie APIs und Dienste auf und aktivieren Sie die Google Play Integrity API.
Wenn Sie mehr als 10.000 Anfragen pro Tag an Play Integrity für PC senden möchten, sollten Sie eine Erhöhung des Tageslimits beantragen.

Schritt 1: Festlegen, wie Sie Play Integrity für PC in Ihrem Spiel verwenden

Legen Sie fest, wann Sie Play Integrity für PC aufrufen, um ein Integritätsergebnis für die Umgebung zu erhalten. Sie können beispielsweise ein Ergebnis anfordern, wenn das Spiel geöffnet wird, wenn sich ein Spieler anmeldet oder wenn ein Spieler einem Multiplayer-Spiel beitritt. Legen Sie dann fest, wie Sie mit den verschiedenen Integritätsantworten umgehen. Zum Beispiel können Sie:

Die Antwort ohne Durchsetzungsmaßnahmen erfassen und die Daten intern analysieren, um festzustellen, ob sie ein nützliches Signal für Missbrauch sind.
Die Antwort erfassen und Logik auf Ihrem Backend-Server implementieren, damit Geräte, die die Integritätsprüfungen bestehen, Ihr Spiel normal spielen können. Gleichzeitig können Sie den Zugriff auf Traffic aus verdächtigen Umgebungen einschränken oder verweigern.
Die Antwort erfassen und Logik auf Ihrem Backend-Server implementieren, um Spieler auf Geräten, die die Integritätsprüfungen bestehen, zusammenzubringen und gleichzeitig Traffic aus verdächtigen Umgebungen zusammenzubringen.

Schritt 2: Integritäts-Tokens in Ihrem Spiel anfordern

Play Integrity für PC vorbereiten

Bereiten Sie Play Integrity für PC vor, damit Google Play teilweise Attestierungsinformationen intelligent auf dem Gerät im Cache speichern kann. So wird die Latenz auf dem kritischen Pfad verringert, wenn Sie ein Integritätsergebnis anfordern. Sie können dies asynchron tun, sobald Ihr Spiel geöffnet wird, damit Sie bei Bedarf Integritätsanfragen senden können.

void PrepareIntegrityToken(
  const PrepareIntegrityTokenParams & params,
  PrepareIntegrityTokenContinuation continuation
)

Bei Erfolg wird die Fortsetzung mit einem PrepareIntegrityTokenResultValue aufgerufen, das ein RequestTokenData enthält, das zum Anfordern eines Integritäts-Tokens verwendet werden sollte. Diese Daten sollten im Arbeitsspeicher zwischengespeichert und für die Dauer der Sitzung der Anwendung für Aufrufe von RequestIntegrityToken wiederverwendet werden.

Ein Aufruf von PrepareIntegrityToken sollte nur erfolgen, wenn Ihre Anwendung feststellt, dass das Integritätsergebnis vollständig neu bewertet werden muss.

Details
Parameter	`params`: Parameter mit einer Google Cloud-Projektnummer. `continuation`: Der asynchrone Callback, an den der Anbieter des Integritäts-Tokens zurückgegeben werden soll.

Ein Code-Snippet, das zeigt, wie die PrepareIntegrityToken Aktion aufgerufen werden sollte, finden Sie unten:

google::play::integrity::IntegrityClient client_;

google::play::integrity::PrepareIntegrityTokenResult
IntegrityInterface::PrepareIntegrityToken(int64_t cloud_project_number) {
  google::play::integrity::PrepareIntegrityTokenParams params;
  params.cloud_project_number = cloud_project_number;

  auto promise = std::make_shared<
      std::promise<google::play::integrity::PrepareIntegrityTokenResult>>();
  client_.PrepareIntegrityToken(
      params,
      [promise](
          google::play::integrity::PrepareIntegrityTokenResult result) {
        promise->set_value(std::move(result));
      });

  return promise->get_future().get();
}

Integritäts-Token anfordern

Integritäts-Tokens sind ein Mechanismus, mit dem Ihr Spiel prüfen kann, ob das Gerät manipuliert wurde. Wenn Ihr Spiel eine Serveranfrage sendet, die Sie auf Echtheit prüfen möchten, können Sie ein Integritäts-Token anfordern und es dann zur Entschlüsselung und Überprüfung an den Backend-Server Ihres Spiels senden.

Wenn Sie eine Nutzeraktion in Ihrer App mit der Play Integrity API für PC prüfen, können Sie das RequestIntegrityTokenParams::request_hash Feld verwenden, um Manipulationen zu verhindern. Beispielsweise möchten Sie die Punktzahl des Spielers an den Backend-Server Ihres Spiels senden und Ihr Server möchte prüfen, ob diese Punktzahl nicht von einem Proxyserver manipuliert wurde. Play Integrity für PC kann den Wert, den Sie in diesem Feld festgelegt haben, in der signierten Integritätsantwort zurückgeben. Ohne den requestHash ist das Integritäts-Token nur an das Gerät gebunden, nicht an die spezifische Anfrage, was die Möglichkeit für Angriffe eröffnet.

void RequestIntegrityToken(
  const RequestIntegrityTokenParams & params,
  RequestIntegrityTokenContinuation continuation
)

Um die Möglichkeit eines Angriffs zu verringern, gehen Sie beim Anfordern eines Integritätsergebnisses so vor:

Berechnen Sie einen Digest aller relevanten Anfrageparameter (z.B. SHA256 einer stabilen Anfrageserialisierung) aus der Nutzeraktion oder Serveranfrage.
Legen Sie das Feld RequestIntegrityTokenParams::request_hash auf den Digest fest.

Details
Parameter	`params`: Parameter mit den vorbereiteten RequestTokenData und dem Hash der Integritätsprüfungsanfrage. `continuation`: Der asynchrone Callback, an den die Daten zurückgegeben werden sollen.

Ein Code-Snippet, das zeigt, wie die RequestIntegrityToken Aktion aufgerufen werden kann, finden Sie unten:

absl::StatusOr<google::play::integrity::RequestIntegrityTokenResult>
IntegrityInterface::RequestIntegrityToken(
    const google::play::integrity::PrepareIntegrityTokenResult&
        prepare_integrity_token_result,
    const std::string& request_hash) {
  // Check if the prepare_integrity_token_result is OK
  if (!prepare_integrity_token_result.ok()) {
    return absl::FailedPreconditionError(
        absl::StrCat("PrepareIntegrityTokenResult is not OK. Error code: ",
                     prepare_integrity_token_result.error_code));
  }

  google::play::integrity::RequestIntegrityTokenParams params{
      .request_token_data =
          prepare_integrity_token_result.request_token_data,
      .request_hash = request_hash};

  auto promise = std::make_shared<std::promise<
      google::play::integrity::RequestIntegrityTokenResult>>();
  client_.RequestIntegrityToken(
      params,
      [promise](google::play::integrity::RequestIntegrityTokenResult result) {
        promise->set_value(std::move(result));
      });

  return promise->get_future().get();
}

Schritt 3: Integritäts-Tokens auf dem Backend-Server Ihres Spiels entschlüsseln und überprüfen

Integritäts-Token entschlüsseln

Nachdem Sie ein Integritätsergebnis angefordert haben, stellt die Play Integrity API ein verschlüsseltes Antwort-Token bereit. Um die Ergebnisse zur Geräteintegrität zu erhalten, müssen Sie das Integritäts-Token auf den Servern von Google entschlüsseln:

Erstellen Sie ein Dienstkonto im Google Cloud- Projekt, das mit Ihrer App verknüpft ist.
Rufen Sie auf dem Server Ihrer App das Zugriffstoken aus den Anmeldedaten Ihres Dienstkontos mit dem Bereich „playintegrity“ ab und senden Sie die folgende Anfrage:
```
playintegrity.googleapis.com/v1/<var>PACKAGE_NAME</var>:decodePcIntegrityToken -d \
 '{ "integrity_token": "<var>INTEGRITY_TOKEN</var>" }'
```
Lesen Sie die JSON-Antwort.

Die resultierende Nutzlast ist ein Klartext-Token, das neben von Entwicklern bereitgestellten Informationen auch Integritätsergebnisse und Details enthält. Ein entschlüsseltes Integritäts-Token sieht so aus:

{
  "requestDetails": {
    "requestPackageName": "com.your.package.name",
    "requestTime": "2025-08-29T13:10:37.285Z",
    "requestHash": "your_request_hash_string"
  },
  "deviceIntegrity": {
    "deviceRecognitionVerdict": [
      "MEETS_PC_INTEGRITY"
    ]
  },
  "accountDetails": {
    "appLicensingVerdict": "LICENSED"
  }
}

Integritäts-Token überprüfen

Das Feld requestDetails des decodierten Integritäts-Tokens enthält Informationen zur Anfrage, einschließlich der vom Entwickler bereitgestellten Informationen im requestHash.

Die Felder requestHash und packageName sollten mit denen der ursprünglichen Anfrage übereinstimmen. Überprüfen Sie daher den Teil requestDetails der JSON-Nutzlast, indem Sie prüfen, ob requestPackageName und requestHash mit den in der ursprünglichen Anfrage gesendeten Werten übereinstimmen. Das folgende Code-Snippet zeigt, wie das geht:

const auto& request_details = json_payload["requestDetails"];

if (request_details.value("requestPackageName", "") != <YOUR_PACKAGE_NAME>) {
  // Don't trust the verdicts.
}

// Check for the existence of the request_hash.
// If you set a request hash in the request and it's not present, you shouldn't
// trust the verdicts.
if (!request_details.contains("requestHash")) {
    // Don't trust the verdicts.
}


// The requestHash from request_details needs to match the request hash your
// app provided.
if (request_details.value("requestHash", "") != <PROVIDED_REQUEST_HASH>) {
    // Don't trust the verdicts.
}

// You can read the rest of payload's fields.

Schritt 4: Auf Grundlage des Integritätsergebnisses Maßnahmen ergreifen

Das Feld deviceIntegrity kann einen einzelnen Wert enthalten: deviceRecognitionVerdict. Mit diesem Wert können Sie feststellen, ob Ihr Spiel auf einem PC ausgeführt wird, der die Play Integrity-Prüfungen besteht (MEETS_PC_INTEGRITY als Antwort). Das Feld accountDetails enthält einen einzelnen Wert: appLicensingVerdict. Mit diesem Wert können Sie feststellen, ob der Nutzer eine Lizenz von Google Play erhalten hat. Der Backend-Server Ihres Spiels kann diese Informationen erfassen und damit festlegen, welche Maßnahmen Ihr Spiel ergreifen soll, z. B. ein Spielereignis zulassen oder den Zugriff auf risikoreichen Traffic verweigern.

"deviceIntegrity": {
  "deviceRecognitionVerdict": ["MEETS_PC_INTEGRITY"]
}
"accountDetails": {
  "appLicensingVerdict": "LICENSED"
}

Ergebnisse zur Geräteintegrität

deviceRecognitionVerdict kann die folgenden Werte haben:

MEETS_PC_INTEGRITY: Das Spiel wird in einer echten PC-Umgebung ausgeführt, in der keine Manipulationen auf dem Gerät erkannt wurden.
Leer (ein leerer Wert): Das Spiel wird auf einem Gerät ausgeführt, das Anzeichen für Angriffe (z. B. API-Hooks) oder Systemmanipulationen (z. B. durch Ausführen einer manipulierten Version von Google Desktop Services) 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).

Ergebnisse zu den Kontodetails

appLicensingVerdict kann die folgenden Werte haben:

LICENSED

Der Nutzer hat eine App-Berechtigung. Er hat Ihre App also auf seinem Gerät bei Google Play installiert oder aktualisiert.

UNLICENSED

Der Nutzer hat keine App-Berechtigung. Dies ist beispielsweise der Fall, wenn der Nutzer die App per Sideload oder nicht bei Google Play heruntergeladen hat.

UNEVALUATED

Lizenzierungsdetails wurden nicht geprüft, da eine erforderliche Voraussetzung nicht erfüllt wurde. Das kann verschiedene Gründe haben, z. B.:

Das Gerät ist nicht vertrauenswürdig genug.
Die Version der aktuell auf dem Gerät installierten App ist Google Play nicht bekannt.
Der Nutzer ist nicht in Google Play angemeldet.

Schritt 5: Fehlercodes verarbeiten

Wenn Ihr Spiel eine Anfrage an Play Integrity für PC sendet und der Aufruf fehlschlägt, erhält Ihr Spiel einen Fehlercode. Diese Fehler können verschiedene Ursachen haben, z. B. Probleme mit der Umgebung wie eine schlechte Netzwerkverbindung, Probleme mit Ihrer API-Integration oder böswillige Aktivitäten und aktive Angriffe.

Wiederholbare Fehlercodes

Die Ursache dieser Fehler liegt manchmal in vorübergehenden Bedingungen. Daher sollten Sie den Aufruf mit einer exponentiellen Backoff-Strategie wiederholen.

IntegrityError	Fehlerbeschreibung	Fehlercode
`kNetworkError`	Problem mit der Netzwerkverbindung auf dem Gerät.	5
`kTooManyRequests`	Zu viele Anfragen vom Gerät.	6
`kClientTransientError`	Ein vorübergehendes Problem mit dem Client.	7

Weitere Empfehlungen zu Wiederholungsstrategien finden Sie hier.

Nicht wiederholbare Fehlercodes

Automatische Wiederholungen sind in diesen Fällen unwahrscheinlich hilfreich. Eine manuelle Wiederholung kann jedoch helfen, wenn der Nutzer die Bedingung behebt, die das Problem verursacht hat.

IntegrityError	Fehlerbeschreibung	Fehlercode	Empfohlene Aktion
`kError`	Schwerwiegender Fehler bei der SDK-Aktion.	1	Überprüfen Sie Ihre API-Implementierung, bevor Sie es noch einmal versuchen.
`kCloudProjectNumberIsInvalid`	Die Cloud-Projektnummer ist ungültig.	2	Prüfen Sie, ob Ihre Cloud-Projektnummer in der Google Cloud Console richtig konfiguriert ist und die Anfragen mit der richtigen Cloud-Projekt Nummer gesendet werden.
`kRequestHashTooLong`	Der Anfrage-Hash ist zu lang.	3	Die generierten Anfrage-Hashes sind zu lang. Sie dürfen nicht länger als 500 Zeichen sein.
`kNoValidPreparedTokenFound`	Vor dem Senden der Tokenanfrage ist kein vorbereitetes Token vorhanden.	4	Rufen Sie die Aktion [PrepareIntegrityToken][prepare-token] auf, bevor Sie den Aufruf [RequestIntegrityToken][request-integrity-token] senden.
`kSdkRuntimeUpdateRequired`	Für das Play for Native SDK ist ein Update erforderlich.	8	Prüfen Sie, ob der Google Play Services-Client auf dem Gerät auf dem neuesten Stand ist und Sie die aktuelle Version des Play for Native PC SDK verwenden.

Verschiedene Antworten der Play Integrity API in Ihrer App testen

Sie können Tests erstellen, um zu prüfen, wie die Play Integrity API mit Ihrer App interagiert.

Richten Sie eine Google-Gruppe (oder beliebig viele) mit den E-Mail-Adressen der Nutzer ein. Sie können die Integritätsergebnisse oder den Fehlercode auswählen, die diese Nutzer in Ihrer App von den Servern von Google Play erhalten sollen. So können Sie testen, wie Ihre App auf alle möglichen Antworten und Fehler reagiert.

Erstellen Sie hier ein Ticket und geben Sie an, welche Google-Gruppe welche API-Antwort erhält. Jeder Gruppe wird eine der folgenden Optionen zugewiesen:

	Lizenzierungsergebnis „Bestanden“	Lizenzierungsergebnis „Nicht bestanden“	Lizenzierungsergebnis kann nicht bewertet werden
Geräteintegrität „Bestanden“	`ALLOWLIST_CONFIG_MEETS_PC_INTEGRITY_LICENSED`	`ALLOWLIST_CONFIG_MEETS_PC_INTEGRITY_UNLICENSED`	`ALLOWLIST_CONFIG_MEETS_PC_INTEGRITY_LICENSING_UNEVALUATED`
Geräteintegrität „Nicht bestanden“	–	–	`ALLOWLIST_CONFIG_NO_PC_INTEGRITY_LICENSING_UNEVALUATED`

Wenn Sie das Ergebnis zur Geräteintegrität nicht bestehen, wird für das Lizenzierungsergebnis immer „UNEVALUATED“ zurückgegeben.

Sie werden benachrichtigt, sobald die Anfrage verarbeitet wurde und die Testnutzer auf der Zulassungsliste stehen, um die vordefinierten Integritätsergebnisse für Tests zu erhalten.