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 Spiele für PC auf einem echten PC stammen. Wenn der Backend-Server Ihres Spiels potenziell riskante Geräte und unbekannte Emulatoren erkennt, kann er mit entsprechenden Maßnahmen reagieren, um Betrug, nicht autorisierten Zugriff, betrügerischen Traffic und Missbrauch zu verhindern.

Voraussetzungen

• SDK einrichten
• Lesen Sie die Sicherheitsaspekte der Integrity API.
• Lesen Sie die Nutzungsbedingungen und die Informationen zur Datenverarbeitung für die Integrity API und machen Sie sich damit vertraut.
• 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 die Play Integrity API für PC-Spiele stellen möchten, sollten Sie eine Erhöhung des Tageslimits beantragen.

Schritt 1: Festlegen, wie Sie die Play Integrity API für PC in Ihrem Spiel verwenden möchten

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

• Erfassen Sie die Antwort ohne Durchsetzungsmaßnahmen und analysieren Sie die Daten intern, um festzustellen, ob sie ein nützliches Signal für Missbrauch sind.
• Erfassen Sie die Antwort und implementieren Sie Logik auf Ihrem Backend-Server, damit Geräte, die die Integritätsprüfung bestehen, Ihr Spiel normal spielen können. Gleichzeitig sollten Sie Zugriff auf Traffic aus verdächtigen Umgebungen anfechten oder verweigern.
• Erfassen Sie die Antwort und implementieren Sie Logik in Ihrem Backend, um Spieler auf Geräten, die die Integritätsprüfungen bestehen, zusammenzuführen und Traffic aus verdächtigen Umgebungen zusammenzuführen.

Schritt 2: Integritätstokens in Ihrem Spiel anfordern

Play Integrity für PC aufwärmen

Bereiten Sie Play Integrity für PC vor („Aufwärmen“), damit Google Play teilweise Attestierungsinformationen intelligent auf dem Gerät zwischenspeichern kann, um die Latenz auf dem kritischen Pfad zu verringern, wenn Sie eine Anfrage für ein Integritätsurteil stellen. Sie können dies asynchron ausführen, sobald Ihr Spiel geöffnet wird, damit Sie bei Bedarf On-Demand-Integritätsanfragen stellen 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ä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.

Ein Code-Snippet, das zeigt, wie die Aktion PrepareIntegrityToken aufgerufen werden sollte, ist unten zu sehen:

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ätstoken anfordern

Integritätstokens sind ein Mechanismus, mit dem Ihr Spiel überprüfen kann, ob das Gerät manipuliert wurde. Immer wenn Ihr Spiel eine Serveranfrage stellt, die Sie auf Echtheit prüfen möchten, können Sie ein Integritätstoken anfordern und es dann zum Entschlüsseln und Überprüfen 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 Feld RequestIntegrityTokenParams::request_hash verwenden, um Manipulationen zu verhindern. Beispielsweise möchten Sie möglicherweise die Punktzahl des Spielers an den Backend-Server Ihres Spiels senden und Ihr Server möchte überprüfen, ob diese Punktzahl nicht von einem Proxyserver manipuliert wurde. Play Integrity für PC kann den Wert, den Sie in diesem Feld festlegen, in der signierten Integritätsantwort zurückgeben. Ohne den requestHash ist das Integritätstoken nur an das Gerät gebunden, nicht an die spezifische Anfrage. Das eröffnet die Möglichkeit für Angriffe.

void RequestIntegrityToken(
  const RequestIntegrityTokenParams & params,
  RequestIntegrityTokenContinuation continuation
)

So verringern Sie die Wahrscheinlichkeit eines Angriffs, wenn Sie ein Integritätsergebnis anfordern:

• 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.

Ein Code-Snippet, das zeigt, wie die Aktion RequestIntegrityToken aufgerufen werden kann, ist unten zu sehen:

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ätstokens auf dem Backend-Server Ihres Spiels entschlüsseln und prüfen

Integritätstoken entschlüsseln

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 Servern von Google entschlüsseln:

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 Klartext-Token, das Integritätsergebnisse und Details sowie vom Entwickler bereitgestellte Informationen enthält. Ein entschlüsseltes Integritätstoken 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"
    ]
  },
}

Integritätstoken prüfen

Das Feld requestDetails des decodierten Integritätstokens enthält Informationen zur Anfrage, einschließlich der vom Entwickler bereitgestellten Informationen in requestHash.

Die Felder requestHash und packageName sollten mit denen der ursprünglichen Anfrage übereinstimmen. Prüfen Sie daher den requestDetails-Teil der JSON-Nutzlast, indem Sie sicherstellen, dass requestPackageName und requestHash mit dem übereinstimmen, was in der ursprünglichen Anfrage gesendet wurde, wie im folgenden Code-Snippet gezeigt:

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: Anhand des Integritätsurteils entscheiden, welche Maßnahmen ergriffen werden sollen

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 (eine MEETS_PC_INTEGRITY-Antwort). Der Backend-Server Ihres Spiels kann diese Informationen erfassen und damit festlegen, welche Maßnahmen Ihr Spiel ergreifen soll, z. B. ob ein Spielereignis fortgesetzt oder der Zugriff auf riskanten Traffic verweigert werden soll.

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

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 (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 eine manipulierte Version von Google Desktop Services) aufweist oder das Spiel wird nicht auf einem physischen Gerät ausgeführt (z. B. einem Emulator, der die Google Play-Integritätsprüfungen nicht besteht).

Schritt 5: Fehlercodes verarbeiten

Wenn Ihr Spiel eine Play Integrity for PC-Anfrage stellt und der Aufruf fehlschlägt, erhält Ihr Spiel einen Fehlercode. Diese Fehler können verschiedene Ursachen haben, z. B. Umweltprobleme wie eine schlechte Netzwerkverbindung, Probleme mit der API-Integration oder schädliche 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.

Weitere Empfehlungen zu Wiederholungsstrategien

Nicht wiederholbare Fehlercodes

Automatische Wiederholungen sind in diesen Fällen wahrscheinlich nicht hilfreich. Ein manueller Wiederholungsversuch kann jedoch hilfreich sein, wenn der Nutzer die Bedingung behebt, die das Problem verursacht hat.