Integra Play Integrity para PC en tu app

Play Integrity para PC te ayuda a verificar que los eventos del juego y las solicitudes del servidor provengan de una instancia original de Google Play Juegos para PC en un dispositivo para PC original. Cuando se detectan dispositivos potencialmente riesgosos y emuladores desconocidos, el servidor de backend de tu juego puede tomar las medidas adecuadas para evitar trampas, accesos no autorizados, tráfico fraudulento y abusos.

Requisitos previos

• Completa la configuración del SDK.
• Revisa las consideraciones de seguridad de la API de Integrity.
• Lee y comprende las Condiciones del Servicio y la información sobre el tratamiento de datos de la API de Integrity.
• En la consola de Google Cloud, crea un proyecto de Cloud o elige uno existente que desees usar con Play Integrity para PC. Navega a APIs y servicios y habilita la API de Google Play Integrity.
• Si prevés realizar más de 10,000 solicitudes a Play Integrity para PC por día, debes solicitar que se aumente tu máximo diario.

Paso 1: Decide cómo usarás Play Integrity para PC en tu juego

Decide cuándo llamarás a Play Integrity para PC para obtener un veredicto de integridad sobre el entorno. Por ejemplo, podrías solicitar un veredicto cuando se abra el juego, cuando un jugador acceda o cuando un jugador se una a un juego multijugador. Luego, decide cómo controlarás las diferentes respuestas de integridad. Por ejemplo, puedes hacer lo siguiente:

• Recopilamos la respuesta sin aplicar ninguna acción de cumplimiento y analizamos los datos de forma interna para comprender si son un indicador útil de abuso.
• Recopila la respuesta y, luego, implementa la lógica en tu servidor de backend para permitir que los dispositivos que aprueban los veredictos de integridad ejecuten tu juego con normalidad, mientras que desafía o deniega el acceso al tráfico que proviene de entornos sospechosos.
• Recopila la respuesta y, luego, implementa la lógica en tu backend para unir a los jugadores en dispositivos que pasen las verificaciones de integridad y unir el tráfico proveniente de entornos sospechosos.

Paso 2: Solicita tokens de integridad en tu juego

Prepara Play Integrity para PC

Prepara (o "precalienta") Play Integrity para PC, lo que permite que Google Play almacene en la caché del dispositivo la información de certificación parcial de forma inteligente para disminuir la latencia en la ruta de acceso crítica cuando solicitas un veredicto de integridad. Puedes hacerlo de forma asíncrona en cuanto se abra el juego para que puedas realizar solicitudes de integridad a pedido cuando lo necesites.

void PrepareIntegrityToken(
  const PrepareIntegrityTokenParams & params,
  PrepareIntegrityTokenContinuation continuation
)

Si la operación se realiza correctamente, se llamará a la continuación con un PrepareIntegrityTokenResultValue que contiene un RequestTokenData que se debe usar para solicitar un token de integridad. Estos datos deben almacenarse en caché en la memoria y reutilizarse durante la sesión de la aplicación para las llamadas a RequestIntegrityToken.

Solo si tu aplicación determina que es necesario volver a evaluar por completo el veredicto de integridad, se debe realizar una llamada a PrepareIntegrityToken.

A continuación, se proporciona un fragmento de código que muestra cómo se debe llamar a la acción 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();
}

Solicita tu token de integridad

Los tokens de integridad son un mecanismo para que tu juego verifique que el dispositivo no se haya alterado. Cada vez que tu juego realice una solicitud del servidor que quieras verificar si es original, puedes solicitar un token de integridad y, luego, enviarlo al servidor de backend de tu juego para su desencriptación y verificación.

Cuando verifiques una acción del usuario en tu app con la API de Play Integrity para PC, puedes usar el campo RequestIntegrityTokenParams::request_hash para mitigar los ataques de manipulación. Por ejemplo, es posible que quieras informar la puntuación del jugador al servidor de backend de tu juego, y que tu servidor quiera verificar que un servidor proxy no haya manipulado esta puntuación. Play Integrity para PC puede devolver el valor que estableces en este campo, dentro de la respuesta de integridad firmada. Sin el requestHash, el token de integridad se vinculará solo al dispositivo, pero no a la solicitud específica, lo que abre la posibilidad de un ataque.

void RequestIntegrityToken(
  const RequestIntegrityTokenParams & params,
  RequestIntegrityTokenContinuation continuation
)

Para mitigar la posibilidad de un ataque, cuando solicites un veredicto de integridad, haz lo siguiente:

• Calcula un resumen de todos los parámetros de solicitud relevantes (p. ej., SHA256 de una serialización de solicitud estable) de la acción del usuario o la solicitud del servidor que está sucediendo.
• Establece el campo RequestIntegrityTokenParams::request_hash en el resumen.

A continuación, se proporciona un fragmento de código que muestra cómo se puede llamar a la acción 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();
}

Paso 3: A continuación, desencripta y verifica los tokens de integridad en el servidor de backend de tu juego

Cómo desencriptar un token de integridad

Después de solicitar un veredicto de integridad, la API de Play Integrity proporciona un token de respuesta encriptado. Para obtener los veredictos de integridad del dispositivo, debes desencriptar el token de integridad en los servidores de Google:

1. Crea una cuenta de servicio dentro del proyecto de Google Cloud que esté vinculado a tu app.

2. En el servidor de la app, recupera el token de acceso de las credenciales de la cuenta de servicio con el permiso playintegrity y realiza la siguiente solicitud:

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

3. Lee la respuesta JSON.

La carga útil resultante es un token de texto sin formato que contiene veredictos y detalles de integridad junto con la información proporcionada por el desarrollador. Un token de integridad desencriptado se ve de la siguiente manera:

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

Verifica el token de integridad

El campo requestDetails del token de integridad decodificado contiene información sobre la solicitud, incluida la información proporcionada por el desarrollador en el requestHash.

Los campos requestHash y packageName deben coincidir con los de la solicitud original. Por lo tanto, verifica la parte requestDetails de la carga útil de JSON asegurándote de que requestPackageName y requestHash coincidan con lo que se envió en la solicitud original, como se muestra en el siguiente fragmento de código:

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.

Paso 4: Decide qué acción tomar según el veredicto de integridad

El campo deviceIntegrity puede contener un solo valor, deviceRecognitionVerdict. Puedes usar este valor para determinar si tu juego se ejecuta en una PC que pasa las verificaciones de Play Integrity (que es una respuesta MEETS_PC_INTEGRITY). El servidor de backend de tu juego puede recopilar esta información y usarla para determinar qué acción debe realizar el juego, como permitir que continúe un evento del juego o denegar el acceso al tráfico riesgoso.

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

deviceRecognitionVerdict puede tener los siguientes valores:

MEETS_PC_INTEGRITY

El juego se ejecuta en un entorno de PC original, en el que no se detectó manipulación en el dispositivo.

Vacío (un valor en blanco)

El juego se está ejecutando en un dispositivo que tiene señales de ataque (como trampas de API) o de vulneración del sistema (como un dispositivo que ejecuta una versión alterada de los Servicios de escritorio de Google), o bien la app no se está ejecutando en un dispositivo físico (como un emulador que no pasa las verificaciones de integridad de Google Play).

Paso 5: Controla los códigos de error

Si tu juego realiza una solicitud de Play Integrity para PC y la llamada falla, recibirá un código de error. Estos errores pueden ocurrir por varios motivos, como problemas ambientales (por ejemplo, una mala conexión de red), problemas con la integración de la API o actividad maliciosa y ataques activos.

Códigos de error que se pueden reintentar

A veces, la causa de estos errores son condiciones transitorias, por lo que debes reintentar la llamada con una estrategia de retirada exponencial.

Consulta aquí para obtener más recomendaciones sobre las estrategias de reintento.

Códigos de error que no se pueden reintentar

Es poco probable que los reintentos automáticos sean de ayuda en estos casos. Sin embargo, un reintento manual puede ser útil si el usuario soluciona la condición que causó el problema.