Integrowanie interfejsu Play Integrity na PC z aplikacją

Play Integrity na PC pomaga sprawdzić, czy zdarzenia w grze i żądania serwera pochodzą z oryginalnej instancji Gier Google Play na PC na oryginalnym komputerze. Dzięki wykrywaniu potencjalnie ryzykownych urządzeń i nieznanych emulatorów serwer backendu gry może reagować, podejmując odpowiednie działania zapobiegające oszustwom, nieautoryzowanemu dostępowi, nieuczciwemu ruchowi i nadużyciom.

Wymagania wstępne

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

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

Zdecyduj, kiedy będziesz wywoływać Play Integrity na PC, aby uzyskać ocenę integralności środowiska. Możesz na przykład poprosić o ocenę, 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:

• Zbierać odpowiedzi bez podejmowania żadnych działań egzekwujących i analizować dane wewnętrznie, aby sprawdzić, czy są one przydatnym sygnałem nadużycia.
• Zbierać odpowiedzi i implementować logikę na serwerze backendu, aby umożliwić urządzeniom, które przejdą testy integralności, normalne granie w Twoją grę, a jednocześnie utrudniać lub odmawiać dostępu do ruchu pochodzącego z podejrzanych środowisk.
• Zbierać odpowiedzi i implementować logikę na serwerze backendu, aby łączyć graczy na urządzeniach, które przejdą testy integralności, a także łączyć ruch pochodzący z podejrzanych środowisk.

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

Przygotowanie Play Integrity na PC

Przygotuj (lub „rozgrzej”) Play Integrity na PC, co pozwoli Google Play inteligentnie buforować częściowe informacje o atestach na urządzeniu, aby zmniejszyć opóźnienie na ścieżce krytycznej, gdy poprosisz o ocenę integralności. Możesz to zrobić asynchronicznie zaraz po otwarciu gry, aby w razie potrzeby móc wysyłać żądania integralności na żądanie.

void PrepareIntegrityToken(
  const PrepareIntegrityTokenParams & params,
  PrepareIntegrityTokenContinuation continuation
)

W przypadku powodzenia wywołanie będzie kontynuowane z wartością PrepareIntegrityTokenResultValue zawierającą RequestTokenData, która powinna być używana do żądania tokena integralności. Te dane powinny być buforowane w pamięci i ponownie używane przez cały czas trwania sesji aplikacji w przypadku wywołań RequestIntegrityToken.

Wywołanie PrepareIntegrityToken powinno być wykonywane tylko wtedy, gdy aplikacja stwierdzi, że konieczne jest całkowite ponowne sprawdzenie oceny integralności.

Poniżej znajdziesz fragment kodu pokazujący, jak należy wywołać działanie PrepareIntegrityToken:

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 naruszone. Za każdym razem, gdy gra wysyła żądanie serwera, które chcesz sprawdzić, możesz poprosić o token integralności, a następnie wysłać go do serwera backendu gry w celu odszyfrowania i weryfikacji.

Gdy sprawdzasz działanie użytkownika w aplikacji za pomocą Play Integrity API na PC, możesz użyć pola RequestIntegrityTokenParams::request_hash , aby zapobiec atakom polegającym na naruszeniu integralności. Możesz na przykład chcieć zgłosić wynik gracza do serwera backendu gry, a serwer chce sprawdzić, czy wynik nie został naruszony przez serwer proxy. Play Integrity na PC może zwrócić wartość ustawioną w tym polu w podpisanej odpowiedzi dotyczącej integralności. Bez 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, gdy poprosisz o ocenę integralności:

• Oblicz skrót wszystkich odpowiednich parametrów żądania (np. SHA256 stabilnej serializacji żądania) na podstawie działania użytkownika lub żądania serwera.
• Ustaw pole RequestIntegrityTokenParams::request_hash na skrót.

Poniżej znajdziesz 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 poprosisz o ocenę integralności, Play Integrity API zwróci 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. Przeczytaj odpowiedź JSON.

Wynikowy ładunek to token w postaci zwykłego tekstu, który zawiera oceny integralności i szczegóły oraz informacje podane 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 zdekodowanego tokena integralności zawiera informacje o żądaniu, w tym informacje podane przez dewelopera w polu requestHash.

Pola requestHash i packageName powinny być zgodne z polami oryginalnego żądania. 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łanie podjąć na podstawie oceny integralności

Pole deviceIntegrity może zawierać jedną wartość: deviceRecognitionVerdict. Możesz użyć tej wartości, aby określić, czy Twoja gra działa na komputerze, który przechodzi testy integralności Play (czyli czy otrzymujesz odpowiedź MEETS_PC_INTEGRITY). Pole accountDetails zawiera jedną wartość: appLicensingVerdict. Możesz użyć tej wartości, aby określić, czy użytkownik uzyskał licencję z Google Play. Serwer backendu gry może zbierać te informacje i używać ich do określania, jakie działanie powinna podjąć gra, np. zezwolić na wykonanie zdarzenia w grze lub odmówić dostępu do ryzykownego 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 PC, w którym nie wykryto żadnych naruszeń 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 używa naruszonej wersji Usług Google na komputerze), 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. Oznacza to, że użytkownik 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, m.in.:

• 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ługuj kody błędów

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

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 za pomocą strategii wykładniczego wycofywania.

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

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

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

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

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

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

2. Utwórz zgłoszenie tutaj i podaj, która grupa dyskusyjna Google ma otrzymywać jaką odpowiedź interfejsu API. Każda grupa jest przypisana do otrzymywania jednej z tych opcji:

   	Ocena licencji pozytywna	Ocena licencji negatywna	Nie można sprawdzić dopasowania licencji
   Integralność urządzenia pozytywna	ALLOWLIST_CONFIG_MEETS_PC_INTEGRITY_LICENSED	ALLOWLIST_CONFIG_MEETS_PC_INTEGRITY_UNLICENSED	ALLOWLIST_CONFIG_MEETS_PC_INTEGRITY_LICENSING_UNEVALUATED
   Integralność urządzenia negatywna	Nie dotyczy	Nie dotyczy	ALLOWLIST_CONFIG_NO_PC_INTEGRITY_LICENSING_UNEVALUATED

   Jeśli ocena integralności urządzenia jest negatywna, ocena licencji zawsze będzie miała wartość UNEVALUATED.

3. Gdy prośba zostanie przetworzona, a użytkownicy testowi znajdą się na liście dozwolonych, aby otrzymywać predefiniowane oceny integralności na potrzeby testowania, otrzymasz powiadomienie.