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 API na PC w swojej grze

Zdecyduj, kiedy wywołać 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

Przygotuj (lub „rozgrzej”) interfejs Play Integrity na PC, który umożliwia Google Play inteligentne buforowanie częściowych informacji o atestach na urządzeniu, aby zmniejszyć opóźnienie 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();
}

Wysyłanie prośby 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;

Gdy wyślesz żądanie oceny integralności, interfejs Play Integrity API dostarczy 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"
    ]
  },
  "accountDetails": {
    "appLicensingVerdict": "LICENSED"
  }
}

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 Możesz użyć tej wartości, aby określić, czy gra działa na komputerze, który przeszedł testy integralności Play (czyli czy odpowiedź to MEETS_PC_INTEGRITY). Pole accountDetails zawiera jedną wartość: appLicensingVerdict. Za pomocą tej wartości możesz określić, czy użytkownik uzyskał licencję w Google Play. 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"]
}
"accountDetails": {
  "appLicensingVerdict": "LICENSED"
}

Oceny integralności urządzenia

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

Oceny szczegółów konta

appLicensingVerdict może mieć te wartości:

LICENSED

Użytkownik ma uprawnienia do korzystania z aplikacji. To znaczy, że zainstalował lub zaktualizował Twoją aplikację z Google Play na swoim urządzeniu.

UNLICENSED

Użytkownik nie ma uprawnień do korzystania z aplikacji. Może się tak zdarzyć, jeśli np. zainstaluje ją z innego urządzenia lub nie pozyska jej z Google Play.

UNEVALUATED

Szczegóły dotyczące licencji nie zostały określone, ponieważ pominięto niezbędny wymóg. Może się tak zdarzyć z kilku powodów. Oto niektóre z nich:

• Urządzenie nie jest wystarczająco zaufane.
• Google Play nie rozpoznaje wersji aplikacji zainstalowanej na urządzeniu.
• Użytkownik nie jest zalogowany w 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.

Testowanie różnych odpowiedzi interfejsu Play Integrity API w aplikacji

Możesz tworzyć testy, aby ocenić, jak interfejs Play Integrity API współdziała z Twoją aplikacją.

1. Skonfiguruj grupę dyskusyjną Google (lub dowolną liczbę grup) z adresami e-mail użytkowników. Możesz wybrać oceny integralności lub kod błędu, które użytkownicy powinni otrzymywać w aplikacji z serwerów Google Play. Dzięki temu możesz sprawdzić, jak aplikacja reaguje na wszystkie możliwe odpowiedzi i błędy.

2. Utwórz zgłoszenie i podaj, która grupa Google otrzyma którą odpowiedź interfejsu API. Każda grupa otrzymuje jedną z tych opcji:

   	Wynik weryfikacji licencji	Negatywna ocena licencji	Nie udało się sprawdzić stanu licencji
   Przejście weryfikacji integralności urządzenia	ALLOWLIST_CONFIG_MEETS_PC_INTEGRITY_LICENSED	ALLOWLIST_CONFIG_MEETS_PC_INTEGRITY_UNLICENSED	ALLOWLIST_CONFIG_MEETS_PC_INTEGRITY_LICENSING_UNEVALUATED
   Niepowodzenie testu integralności urządzenia	Nie dotyczy	Nie dotyczy	ALLOWLIST_CONFIG_NO_PC_INTEGRITY_LICENSING_UNEVALUATED

   Jeśli ocena integralności urządzenia zakończy się niepowodzeniem, ocena licencji zawsze zwróci wartość UNEVALUATED.

3. Gdy zgłoszenie zostanie przetworzone, a użytkownicy testowi zostaną dodani do listy dozwolonych, aby otrzymywać predefiniowane wyniki weryfikacji integralności na potrzeby testów, otrzymasz powiadomienie.