KappS Base de conocimiento · Blog

Google Play Integrity API en 2026: guía paso a paso

Blog Guía

La Play Integrity API responde a una pregunta concreta y práctica para tu backend: ¿esta solicitud procede de la copia de mi app que distribuyó Google Play, en un dispositivo que es lo que dice ser? Tu servidor pide a Google un veredicto de integridad, recibe una carga firmada y decide —en el servidor, nunca en el cliente— hasta qué punto confiar en la interacción. Es la forma estándar de frenar compilaciones manipuladas, clientes automatizados, emuladores y copias instaladas por sideload antes de que lleguen a la economía de tu juego, a los derechos de tus suscripciones o a tus ingresos por anuncios.

Esta guía sigue el orden en el que realmente vas a trabajar: habilitar la API, vincular un proyecto de Cloud, elegir entre una solicitud estándar y una clásica, preparar el proveedor de tokens, solicitar y descifrar un token, leer los campos del veredicto, gestionar la cuota y los códigos de error, e implantar la aplicación de políticas sin bloquear a los usuarios que pagan. Una regla recorre todo el proceso: la API te entrega señales para tus propias decisiones, y la única forma duradera de superar una comprobación de integridad es publicar una app genuina por el canal oficial.


1. Qué certifica la API y qué no

Por defecto se reciben tres familias de veredictos, y cada una responde a una pregunta distinta.

  • appIntegrity — ¿proviene esto de tu binario sin modificar? appRecognitionVerdict devuelve PLAY_RECOGNIZED cuando el paquete y el certificado coinciden con lo que distribuye Google Play, UNRECOGNIZED_VERSION cuando el certificado o el nombre del paquete no coinciden con los registros de Play, y UNEVALUATED cuando falta algún requisito previo.
  • deviceIntegrity — ¿es genuino el dispositivo? De forma predeterminada, deviceRecognitionVerdict puede contener MEETS_DEVICE_INTEGRITY: un dispositivo Android genuino y certificado, con prueba respaldada por hardware en Android 13 y versiones superiores de que el gestor de arranque está bloqueado y el software cargado es genuino. En un dispositivo que no cumple ninguna etiqueta, el campo simplemente se omite.
  • accountDetails: ¿tiene el usuario un derecho de uso? appLicensingVerdict devuelve LICENSED (instalada o actualizada desde Google Play), UNLICENSED o UNEVALUATED.

Hay dos puntos de disciplina que importan más que la lista de campos. Primero, Google afirma claramente que la API funciona mejor junto con otras señales, como parte de una estrategia global contra el abuso y no como tu único mecanismo: un veredicto es un dato más, y tratarlo como el único filtro genera tanto falsos positivos como elusiones fáciles. Segundo, son señales de riesgo, no juicios sobre tus usuarios: un aficionado con un dispositivo rooteado no es un delincuente, y la respuesta debe ser proporcional a lo que realmente está en juego en esa pantalla.

2. Paso 1: habilita la API y vincula un proyecto de Cloud

Cada app o SDK que llama a la API necesita un proyecto de Google Cloud, porque ahí es donde se monitoriza el uso y se gestiona la cuota.

  1. En Google Cloud Console, crea un proyecto nuevo o elige uno existente que quieras usar.
  2. Ve a APIs y servicios → Habilitar APIs y servicios, busca Play Integrity API y haz clic en Habilitar.
  3. Después, vincula ese proyecto a tu app. En Play Console, abre tu app, ve a Protegido con Play, busca Play Integrity API y elige Empezar.

La vinculación es el paso que desbloquea todo lo demás. Un proyecto habilitado en Cloud pero no vinculado en Play Console —o en Play SDK Console para los SDK— no es elegible para las opciones de configuración adicionales ni para un aumento de cuota. El flujo de vinculación habilitará la API por ti si te saltaste el paso en la consola, así que cualquiera de los dos órdenes funciona; saltarte la vinculación, no.

El descifrado requiere una credencial que tu app nunca debe llevar. Crea una cuenta de servicio dentro del proyecto de Cloud vinculado y llama al endpoint de decodificación desde tu servidor con el ámbito playintegrity. El cliente solicita tokens; solo el servidor los abre.

3. Paso 2 — elige una solicitud estándar o clásica

Hay dos estilos de solicitud, y elegir el correcto desde el principio te ahorra una reescritura posterior.

  • Las solicitudes estándar son la opción predeterminada para las apps en Google Play. Funcionan en Android 5.0 (nivel de API 21) y versiones posteriores, y se construyen con dos llamadas: prepara el proveedor de tokens de integridad con antelación y luego solicita un token cuando realmente lo necesites.
  • Las solicitudes clásicas existen para los casos que las solicitudes estándar no cubren, en particular las apps distribuidas exclusivamente fuera de Google Play y los SDK. Estructuralmente, una solicitud clásica es una sola llamada que toma un nonce que tú generas, y las apps que no se distribuyen en Play también deben pasar su número de proyecto de Cloud con setCloudProjectNumber(). Las apps en Play se vinculan a través de la consola y no lo establecen en la solicitud.

Si tu app está en Google Play, la respuesta es standard. Recurre a classic cuando la distribución realmente ocurra fuera de Play, o cuando una integración concreta te lo impida.

4. Paso 3 — preparar el proveedor y luego solicitar el token

Una solicitud estándar se divide deliberadamente en dos para que la parte lenta nunca caiga en la ruta crítica del usuario.

Prepara, o precalienta, el proveedor de tokens de integridad. Llama a esto mucho antes de necesitar un veredicto; normalmente al iniciar la app, lo que funciona bien porque la llamada es asíncrona y no afecta al tiempo de arranque. El precalentamiento permite que Google Play almacene en caché información parcial de atestación en el dispositivo para que la solicitud posterior sea rápida; volver a prepararlo también es una forma más ligera de que el siguiente veredicto esté más actualizado. El propio proveedor puede caducar si se conserva demasiado tiempo, lo que se manifiesta como INTEGRITY_TOKEN_PROVIDER_INVALID; gestiónalo solicitando un proveedor nuevo en lugar de reintentar con el obsoleto.

Solicita un token de integridad cuando lo necesites. Cuando la app haga una llamada al servidor que quieras avalar, solicita un token y envíalo a tu backend. Adjunta un hash de solicitud: calcula un resumen —por ejemplo, SHA-256 de los parámetros estables— y pásalo, porque la API devuelve ese valor dentro de la respuesta firmada. Sin él, un token queda vinculado al dispositivo pero no a la solicitud concreta, que es justo el hueco que necesita un proxy para reutilizarlo en otra cosa.

Las solicitudes clásicas usan un nonce que tú proporcionas. Se pasa a Google tal cual, así que nunca incluyas datos personales o sensibles, y debe ser Base64 válido de una longitud aceptada; de lo contrario, recibirás NONCE_TOO_SHORT, NONCE_TOO_LONG o NONCE_IS_NOT_BASE64 en lugar de un veredicto.

5. Paso 4 — descifra y verifica en tu servidor

El token que llega a tu backend está cifrado y es inútil hasta que Google lo descifra. Con las credenciales de tu cuenta de servicio y el alcance playintegrity, tu servidor llama a:

POST https://playintegrity.googleapis.com/v1/PACKAGE_NAME:decodeIntegrityToken { "integrity_token": "INTEGRITY_TOKEN" }

Lo que devuelve es una carga JSON en texto plano. Antes de mirar un solo veredicto, valida los detalles de la solicitud, porque la carga solo tiene sentido si de verdad es la respuesta a tu solicitud:

  • requestPackageName debe coincidir con el nombre de tu paquete;
  • requestHash debe coincidir con el hash que enviaste;
  • timestampMillis debe ser reciente: compáralo con una ventana de vigencia (un intervalo permitido en milisegundos) y rechaza cualquier valor más antiguo, ya que un token caducado es candidato a reenvío.

Google Play también aplica protección automática contra la repetición, lo que impide que un token de integridad se reutilice muchas veces. Tómalo como una red de seguridad y no como un sustituto de tu propia comprobación de vigencia, y decodifica el token en el servidor en el momento de la acción en lugar de guardar uno en caché durante un día.

6. Leer el payload sin bloquear de más

La carga útil es JSON con requestDetails, appIntegrity, deviceIntegrity, accountDetails y, una vez que lo actives, environmentDetails. El orden de los campos no está garantizado, así que lee siempre por clave. Una escalera de decisión viable es la siguiente.

  1. Confirma primero la app: PLAY_RECOGNIZED significa que el binario y el certificado son los que distribuye Play.
  2. Después, fíjate en el dispositivo: MEETS_DEVICE_INTEGRITY es el umbral predeterminado. Las etiquetas adicionales —MEETS_BASIC_INTEGRITY, MEETS_STRONG_INTEGRITY y MEETS_VIRTUAL_INTEGRITY— son opcionales y pertenecen a una estrategia por niveles, no a un primer lanzamiento.
  3. Usa accountDetails cuando los derechos de compra sean relevantes: UNLICENSED significa que la cuenta no tiene derecho de Play, aunque en algunos dispositivos antiguos un derecho puede persistir tras la desinstalación, así que léelo como una señal y no como un hecho.
  4. Si activaste environmentDetails, el appAccessRiskVerdict te indica si hay apps capaces de capturar la pantalla o dibujar superposiciones —su lista appsDetected usa valores como KNOWN_INSTALLED, UNKNOWN_INSTALLED y UNKNOWN_CAPTURING— y el veredicto de Play Protect resume el estado de Play Protect del dispositivo.

Dos casos poco evidentes merecen atención en el diseño. Los emuladores que superan las comprobaciones de integridad del sistema y cumplen los requisitos básicos de compatibilidad de Android pueden recibir una etiqueta de dispositivo propia, así que "emulador" no significa automáticamente "atacante". Y un dispositivo que no cumple ninguna etiqueta omite el campo por completo, lo que significa que el código que da por hecho que la clave siempre está presente falla en lugar de cerrarse de forma segura.

7. Cuota, códigos de error y fallos seguros

De forma predeterminada, tu app puede hacer hasta 10.000 solicitudes al día entre todas las instalaciones. Ese techo llega antes de lo que los equipos esperan tras un lanzamiento, así que vigila el uso en el proyecto de Cloud vinculado y solicita un aumento mientras la tendencia aún te deje margen. Superarlo se manifiesta como TOO_MANY_REQUESTS (código de error -8), que debes absorber con retroceso exponencial en lugar de bloquear a los usuarios.

La gestión de errores es donde suelen fallar las integraciones. Trata estos como transitorios y reintenta con retroceso exponencial: NETWORK_ERROR (-3), TOO_MANY_REQUESTS (-8), GOOGLE_SERVER_UNAVAILABLE (-12) y CLIENT_TRANSIENT_ERROR (-18). Los demás son del entorno: no hay Play Store, no hay Play services, una versión de Play services desactualizada, una cuenta de Play ausente, un número de proyecto de Cloud que la API rechaza. La guía de Google para esos casos es tratar el resultado como si el cliente hubiera fallado las comprobaciones, sin dejar de mantener la interacción usable siempre que puedas razonablemente.

Trata los errores como una cuestión de política, no solo como una ruta de código. Bloquear a todos los que tienen un dispositivo inusual convierte una señal antialuso en un problema de retención; ignorar en silencio todos los fallos es el error opuesto. Decide según cada superficie —una tabla de clasificación puede ser permisiva, una recarga de monedero puede ser estricta— y deja la decisión por escrito para que el siguiente ingeniero herede el razonamiento.

Google también incluye diálogos de subsanación: flujos activados por la app y guiados por Google que ayudan a un usuario legítimo a resolver el problema de fondo, como instalar la compilación oficial desde Play o restablecer la conectividad, en lugar de dejarlo en un callejón sin salida. Y si necesitas detectar abusos reiterados del mismo hardware tras una aplicación de políticas, la función device recall (beta) está pensada para eso.

8. Implementarlo sin romper la experiencia de tus usuarios

Telemetría antes de la aplicación de políticas. Registra los veredictos y su distribución durante unas semanas antes de restringir nada, para que conozcas la proporción real de resultados UNEVALUATED y UNLICENSED en tu propia base de instalaciones y no en el blog de otra persona. Después aplica las restricciones por niveles: primero la etiqueta de dispositivo predeterminada, más adelante las etiquetas adicionales, y una superficie cada vez. Mantén al cliente capaz de distinguir "reintentar" de "no", y asegúrate de que la app se degrade con elegancia cuando la API simplemente no esté disponible: un usuario con una red inestable no debería perder el acceso al contenido que ya pagó.

9. Dónde encaja KappS

KappS ayuda a los desarrolladores a mantener las cuentas y las versiones en un estado que resiste el escrutinio de las plataformas: preparar y enviar material conforme, nunca eludir las comprobaciones. En la práctica, eso significa:

  • Higiene de versiones. Firmadas con Play App Signing, subidas por el canal oficial, con códigos de versión y certificados coherentes con los registros que reconoce Google Play: las condiciones bajo las cuales PLAY_RECOGNIZED es siquiera posible.
  • Preparación de la cuenta. Verificación de desarrollador, perfil de pagos y registros fiscales alineados con la identidad legal detrás de la cuenta, para que un lanzamiento no se detenga por una revisión ajena.
  • Revisión de la integración. Una segunda mirada a cómo el cliente solicita tokens, sobre qué decide el servidor y si el nivel de aplicación de políticas coincide con el riesgo del negocio.

No ofrecemos ni ofreceremos elusión de integridad, falsificación de veredictos ni herramientas que oculten a Play una compilación manipulada. Eso es precisamente lo que esta API existe para detectar, pone en riesgo la cuenta y no es un servicio que prestemos. La única forma duradera de superar una comprobación de integridad es ser genuino.

Fuentes (documentación oficial de Google): Play Integrity API — Descripción general; Configuración; Realizar una solicitud estándar; Realizar una solicitud clásica; Acerca de los veredictos de integridad; Usar el recuerdo del dispositivo; Gestionar códigos de error; Diálogos de subsanación (developer.android.com).

¿Gestionas cuentas de desarrollador a escala? Nosotros nos encargamos de la parte operativa.

Haz clic para elegir un archivo · clic derecho → Pegar, o pulsa Ctrl/⌘+V para pegar una captura de pantalla

También puedes arrastrar un archivo a este cuadro.

Respondemos al correo que nos proporciones. Tus datos se quedan con KappS.

✔ Enviado

Hemos recibido tu mensaje y responderemos en un plazo de 24 horas.


← Volver a editar