Интегрируйте Play Integrity для ПК в свое приложение

Play Integrity для ПК помогает убедиться, что игровые события и запросы к серверу исходят от подлинного экземпляра Google Play Games для ПК на подлинном ПК-устройстве. Обнаруживая потенциально опасные устройства и неизвестные эмуляторы, внутренний сервер вашей игры может предпринять соответствующие меры для предотвращения читерства, несанкционированного доступа, мошеннического трафика и злоупотреблений.

Предварительные условия

• Завершите настройку SDK .
• Ознакомьтесь с мерами безопасности Integrity API.
• Прочитайте и изучите условия обслуживания Integrity API и информацию об обработке данных .
• В консоли Google Cloud Console создайте облачный проект или выберите существующий облачный проект, который вы хотите использовать с Play Integrity для ПК. Перейдите в раздел API и службы и включите API Google Play Integrity .
• Если вы планируете совершать более 10 тыс. запросов Play Integrity для ПК в день, вам следует подать заявку на увеличение вашего дневного максимума.

Шаг 1: Решите, как вы будете использовать Play Integrity для ПК в своей игре

Решите, когда вы будете вызывать Play Integrity для ПК для получения вердикта о целостности среды. Например, вы можете запрашивать вердикт при запуске игры, при входе игрока в систему или при присоединении к многопользовательской игре. Затем решите, как вы будете обрабатывать различные ответы о целостности. Например:

• Соберите ответ без каких-либо принудительных действий и проанализируйте данные внутри компании, чтобы понять, является ли это полезным сигналом о злоупотреблении.
• Соберите ответ и реализуйте логику на своем внутреннем сервере, чтобы позволить устройствам, прошедшим проверку целостности, нормально играть в вашу игру, одновременно блокируя или запрещая доступ к трафику, поступающему из подозрительных сред.
• Собирайте ответы и реализуйте логику на своем сервере, чтобы сопоставлять игроков на устройствах, которые прошли проверку целостности, а также сопоставлять трафик, поступающий из подозрительных сред.

Шаг 2: Запросите токены целостности в вашей игре

Разминка Play Integrity для ПК

Подготовьте (или «разогрейте») функцию Play Integrity для ПК, которая позволяет Google Play интеллектуально кэшировать частичную информацию об аттестации на устройстве, чтобы уменьшить задержку на критическом пути при запросе вердикта о целостности. Вы можете сделать это асинхронно, сразу после запуска игры, чтобы иметь возможность отправлять запросы на проверку целостности по мере необходимости.

void PrepareIntegrityToken(
  const PrepareIntegrityTokenParams & params,
  PrepareIntegrityTokenContinuation continuation
)

В случае успешного выполнения будет вызвано продолжение с PrepareIntegrityTokenResultValue , содержащим RequestTokenData , который следует использовать для запроса токена целостности. Эти данные следует кэшировать в памяти и использовать повторно в течение сеанса приложения для вызовов RequestIntegrityToken .

Только в том случае, если ваше приложение определит, что необходимо полностью пересмотреть вердикт о целостности, следует выполнить вызов PrepareIntegrityToken .

Ниже представлен фрагмент кода, показывающий, как должно вызываться действие 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();
}

Запросите свой токен целостности

Токены целостности — это механизм, позволяющий вашей игре проверить, не взломано ли устройство. Каждый раз, когда ваша игра отправляет серверный запрос, подлинность которого вы хотите проверить, вы можете запросить токен целостности и отправить его на внутренний сервер игры для расшифровки и проверки.

При проверке действий пользователя в вашем приложении с помощью Play Integrity API для ПК вы можете использовать поле RequestIntegrityTokenParams::request_hash для защиты от атак с подменой данных. Например, вы можете передать счёт игрока на внутренний сервер игры, и ваш сервер захочет убедиться, что этот счёт не был подменён прокси-сервером. Play Integrity для ПК может вернуть значение, заданное в этом поле, в подписанном ответе проверки целостности. Без requestHash токен целостности будет привязан только к устройству, но не к конкретному запросу, что создаёт возможность атаки.

void RequestIntegrityToken(
  const RequestIntegrityTokenParams & params,
  RequestIntegrityTokenContinuation continuation
)

Чтобы снизить вероятность атаки, когда вы запрашиваете вердикт о целостности:

• Вычислите дайджест всех соответствующих параметров запроса (например, SHA256 стабильной сериализации запроса) из действия пользователя или запроса сервера, который происходит.
• Установите поле RequestIntegrityTokenParams::request_hash в соответствии с дайджестом.

Ниже представлен фрагмент кода, показывающий, как можно вызвать действие 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();
}

Шаг 3: Расшифруйте и проверьте токены целостности на внутреннем сервере вашей игры.

Расшифровать токен целостности

После запроса вердикта целостности API Play Integrity предоставляет зашифрованный токен ответа. Чтобы получить вердикт целостности устройства, необходимо расшифровать токен целостности на серверах Google:

1. Создайте учетную запись службы в проекте Google Cloud, связанную с вашим приложением.

2. На сервере вашего приложения извлеките токен доступа из учетных данных вашей службы, используя область playintegrity, и выполните следующий запрос:

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

3. Прочитайте ответ JSON.

Полученная полезная нагрузка представляет собой простой текстовый токен, содержащий вердикты и подробности о целостности, а также информацию, предоставленную разработчиком. Расшифрованный токен целостности выглядит следующим образом:

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

Проверьте токен целостности

Поле requestDetails декодированного токена целостности содержит информацию о запросе, включая предоставленную разработчиком информацию в requestHash .

Поля requestHash и packageName должны совпадать с полями исходного запроса. Поэтому проверьте часть requestDetails полезной нагрузки JSON, убедившись, что поля requestPackageName и requestHash соответствуют значениям, отправленным в исходном запросе, как показано в следующем фрагменте кода:

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.

Шаг 4: Решите, какие действия предпринять на основе вердикта о добросовестности.

Поле deviceIntegrity может содержать одно значение — deviceRecognitionVerdict . Это значение можно использовать, чтобы определить, запущена ли ваша игра на компьютере, прошедшем проверку целостности Play (что соответствует ответу MEETS_PC_INTEGRITY ). Внутренний сервер вашей игры может собирать эту информацию и использовать её для определения того, какие действия должна предпринять игра, например, разрешить продолжение игрового события или запретить доступ к опасному трафику.

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

deviceRecognitionVerdict может иметь следующие значения:

MEETS_PC_INTEGRITY

Игра запущена на реальном ПК, где несанкционированного доступа к устройству не обнаружено.

Пусто (пустое значение)

Игра запущена на устройстве, имеющем признаки атаки (например, перехват API) или взлома системы (например, устройство, на котором запущена измененная версия Google Desktop Services), или приложение не запущено на физическом устройстве (например, эмулятор, не прошедший проверки целостности Google Play).

Шаг 5: Обработка кодов ошибок

Если ваша игра отправляет запрос Play Integrity for PC и вызов не выполняется, игра получает код ошибки. Эти ошибки могут возникать по разным причинам, например, из-за проблем со средой, таких как плохое сетевое соединение, проблемы с интеграцией API, а также вредоносная активность и активные атаки.

Повторяемые коды ошибок

Причиной этих ошибок иногда являются переходные условия, поэтому следует повторить вызов, используя стратегию экспоненциальной задержки.

Дополнительные рекомендации по стратегиям повторных попыток см. здесь.

Коды ошибок, не подлежащие повторному выполнению

Автоматические повторные попытки вряд ли помогут в таких случаях. Однако ручная попытка может помочь, если пользователь устранит причину, вызвавшую проблему.