Integrowanie interfejsu Play Integrity na PC z aplikacją

Play Integrity na PC pomaga sprawdzać, czy zdarzenia w grze i żądania serwera pochodzą z autentycznego wystąpienia Gier Google Play na PC na oryginalnym urządzeniu z PC. Dzięki wykrywaniu potencjalnie niebezpiecznych urządzeń i nieznanych emulatorów serwer backendu gry może reagować, podejmując odpowiednie działania zapobiegające oszukiwaniu, nieautoryzowanemu dostępowi, fałszywemu ruchowi i nadużyciom.

Wymagania wstępne

• Dokończ konfigurowanie pakietu SDK.
• Zapoznaj się z kwestiami bezpieczeństwa dotyczącymi interfejsu Integrity API.
• Przeczytaj i zrozum warunki korzystania z usługi interfejsu Integrity API oraz informacje o przetwarzaniu danych.
• W konsoli Google Cloud utwórz projekt Cloud lub wybierz istniejący projekt Cloud, którego chcesz używać z interfejsem Play Integrity na PC. Otwórz Interfejsy API i usługi i włącz interfejs Play Integrity API.
• Jeśli przewidujesz, że będziesz wysyłać ponad 10 tys. żądań dziennie do interfejsu Play Integrity API na PC, poproś o zwiększenie dziennego limitu.

Krok 1. Określ, w jaki sposób będziesz używać interfejsu Play Integrity na PC w swojej grze

Zdecyduj, kiedy wywołasz interfejs Play Integrity API na PC, aby uzyskać ocenę integralności środowiska. Możesz na przykład poprosić o werdykt, gdy gra zostanie otwarta, gdy gracz się zaloguje lub gdy dołączy do gry wieloosobowej. Następnie zdecyduj, jak będziesz obsługiwać różne odpowiedzi dotyczące integralności. Możesz na przykład:

• Zbieranie odpowiedzi bez podejmowania działań egzekwujących i analizowanie danych wewnętrznie, aby sprawdzić, czy są one przydatnym sygnałem nadużycia.
• Zbierz odpowiedź i zastosuj logikę na serwerze backendu, aby umożliwić urządzeniom, które przeszły weryfikację, normalne granie w Twoją grę, a jednocześnie utrudniać lub odmawiać dostępu do ruchu pochodzącego z podejrzanych środowisk.
• Zbierz odpowiedź i wdroż logikę na serwerze backendu, aby dopasowywać graczy na urządzeniach, które przeszły testy integralności, a także dopasowywać ruch pochodzący z podejrzanych środowisk.

Krok 2. Poproś o tokeny integralności w grze

Rozgrzewanie Play Integrity na PC

Przygotowanie (lub „rozgrzanie”) usługi Play Integrity na PC, co umożliwia Google Play inteligentne buforowanie częściowych informacji o atestach na urządzeniu w celu zmniejszenia opóźnienia na ścieżce krytycznej podczas wysyłania prośby o werdykt dotyczący integralności. Możesz to zrobić asynchronicznie od razu po otwarciu gry, aby w razie potrzeby wysyłać żądania dotyczące integralności.

void PrepareIntegrityToken(
  const PrepareIntegrityTokenParams & params,
  PrepareIntegrityTokenContinuation continuation
)

W przypadku powodzenia wywołana zostanie kontynuacja z wartością PrepareIntegrityTokenResultValue zawierającą element RequestTokenData, który powinien być używany do żądania tokena integralności. Te dane powinny być buforowane w pamięci i ponownie wykorzystywane przez cały czas trwania sesji aplikacji w przypadku wywołań funkcji RequestIntegrityToken.

Wywołanie funkcji PrepareIntegrityToken powinno nastąpić tylko wtedy, gdy aplikacja uzna, że konieczne jest ponowne sprawdzenie wyniku weryfikacji.

Fragment kodu pokazujący, jak należy wywołać działanie PrepareIntegrityToken, wygląda tak:

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();
}

Poproś o token integralności

Tokeny integralności to mechanizm, który umożliwia grze sprawdzenie, czy urządzenie nie zostało zmodyfikowane. Za każdym razem, gdy gra wysyła żądanie do serwera, które chcesz sprawdzić pod kątem autentyczności, możesz poprosić o token integralności, a następnie wysłać go do serwera backendu gry w celu odszyfrowania i zweryfikowania.

Podczas sprawdzania działania użytkownika w aplikacji za pomocą interfejsu Play Integrity API na PC możesz użyć pola RequestIntegrityTokenParams::request_hash, aby zapobiec atakom polegającym na manipulowaniu danymi. Możesz na przykład chcieć przesłać wynik gracza na serwer backendu gry, a serwer może chcieć sprawdzić, czy wynik nie został zmodyfikowany przez serwer proxy. Usługa Play Integrity na PC może zwracać wartość ustawioną w tym polu w ramach podpisanej odpowiedzi dotyczącej integralności. Bez parametru requestHash token integralności będzie powiązany tylko z urządzeniem, a nie z konkretnym żądaniem, co stwarza możliwość ataku.

void RequestIntegrityToken(
  const RequestIntegrityTokenParams & params,
  RequestIntegrityTokenContinuation continuation
)

Aby zmniejszyć ryzyko ataku, podczas przesyłania prośby o ocenę integralności:

• Obliczanie skrótu wszystkich odpowiednich parametrów żądania (np. SHA256 stabilnej serializacji żądania) na podstawie działania użytkownika lub żądania serwera.
• W polu RequestIntegrityTokenParams::request_hash ustaw wartość skrótu.

Fragment kodu pokazujący, jak można wywołać działanie RequestIntegrityToken:

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();
}

Krok 3. Odszyfruj i zweryfikuj tokeny integralności na serwerze backendu gry

Odszyfrowywanie tokena integralności

Po wysłaniu żądania oceny integralności interfejs Play Integrity API dostarcza zaszyfrowany token odpowiedzi. Aby uzyskać oceny integralności urządzenia, musisz odszyfrować token integralności na serwerach Google:

1. Utwórz konto usługi w projekcie Google Cloud połączonym z Twoją aplikacją.

2. Na serwerze aplikacji pobierz token dostępu z danych logowania konta usługi za pomocą zakresu playintegrity i wyślij to żądanie:

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

3. Odczytaj odpowiedź JSON.

Wynikowy ładunek to token w formacie zwykłego tekstu, który zawiera wyniki weryfikacji integralności i szczegóły wraz z informacjami podanymi przez dewelopera. Odszyfrowany token integralności wygląda tak:

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

Weryfikowanie tokena integralności

Pole requestDetails w zdekodowanym tokenie integralności zawiera informacje o żądaniu, w tym informacje podane przez dewelopera w polu requestHash.

Pola requestHash i packageName powinny być zgodne z polami w pierwotnej prośbie. Dlatego sprawdź część requestDetails ładunku JSON, upewniając się, że requestPackageName i requestHash są zgodne z tym, co zostało wysłane w oryginalnym żądaniu, jak pokazano w tym fragmencie kodu:

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.

Krok 4. Zdecyduj, jakie działania podjąć na podstawie wyniku weryfikacji

Pole deviceIntegrity może zawierać jedną wartość: deviceRecognitionVerdict Za pomocą tej wartości możesz określić, czy gra działa na komputerze, który przeszedł testy integralności Play (odpowiedź MEETS_PC_INTEGRITY). Serwer backendu gry może zbierać te informacje i używać ich do określania, jakie działania powinna podjąć gra, np. zezwolić na kontynuowanie zdarzenia w grze lub odmówić dostępu w przypadku podejrzanego ruchu.

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

deviceRecognitionVerdict może mieć te wartości:

MEETS_PC_INTEGRITY

Gra działa w oryginalnym środowisku na PC, w którym nie wykryto żadnych manipulacji na urządzeniu.

Puste (pusta wartość)

Gra działa na urządzeniu, na którym pojawiły się oznaki ataku (np. punkt zaczepienia w interfejsie API) lub naruszenia systemu (np. urządzenie z zmodyfikowaną wersją Usług Google na komputery), albo aplikacja nie działa na urządzeniu fizycznym (tylko np. na emulatorze, który nie przeszedł testów integralności Google Play).

Krok 5. Obsługa kodów błędów

Jeśli gra wyśle żądanie do interfejsu Play Integrity API na PC i wywołanie się nie powiedzie, otrzyma kod błędu. Błędy te mogą wystąpić z różnych powodów, np. z powodu problemów środowiskowych, takich jak słabe połączenie sieciowe, problemów z integracją interfejsu API lub złośliwych działań i aktywnych ataków.

Kody błędów, które można ponowić

Przyczyną tych błędów są czasami przejściowe warunki, dlatego należy ponowić wywołanie, stosując strategię wzrastającego czasu do ponowienia.

Więcej rekomendacji dotyczących strategii ponawiania znajdziesz tutaj.

Kody błędów, których nie można ponowić

W takich przypadkach automatyczne ponawianie prób raczej nie pomoże. Jeśli jednak użytkownik rozwiąże problem, który spowodował błąd, ręczne ponowienie próby może pomóc.