Google Play Integrity API en 2026: guía paso a paso
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?
appRecognitionVerdictdevuelvePLAY_RECOGNIZEDcuando el paquete y el certificado coinciden con lo que distribuye Google Play,UNRECOGNIZED_VERSIONcuando el certificado o el nombre del paquete no coinciden con los registros de Play, yUNEVALUATEDcuando falta algún requisito previo. - deviceIntegrity — ¿es genuino el dispositivo? De forma predeterminada,
deviceRecognitionVerdictpuede contenerMEETS_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?
appLicensingVerdictdevuelveLICENSED(instalada o actualizada desde Google Play),UNLICENSEDoUNEVALUATED.
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.
- En Google Cloud Console, crea un proyecto nuevo o elige uno existente que quieras usar.
- Ve a APIs y servicios → Habilitar APIs y servicios, busca Play Integrity API y haz clic en Habilitar.
- 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
nonceque tú generas, y las apps que no se distribuyen en Play también deben pasar su número de proyecto de Cloud consetCloudProjectNumber(). 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:
requestPackageNamedebe coincidir con el nombre de tu paquete;requestHashdebe coincidir con el hash que enviaste;timestampMillisdebe 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.
- Confirma primero la app:
PLAY_RECOGNIZEDsignifica que el binario y el certificado son los que distribuye Play. - Después, fíjate en el dispositivo:
MEETS_DEVICE_INTEGRITYes el umbral predeterminado. Las etiquetas adicionales —MEETS_BASIC_INTEGRITY,MEETS_STRONG_INTEGRITYyMEETS_VIRTUAL_INTEGRITY— son opcionales y pertenecen a una estrategia por niveles, no a un primer lanzamiento. - Usa
accountDetailscuando los derechos de compra sean relevantes:UNLICENSEDsignifica 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. - Si activaste
environmentDetails, elappAccessRiskVerdictte indica si hay apps capaces de capturar la pantalla o dibujar superposiciones —su listaappsDetectedusa valores comoKNOWN_INSTALLED,UNKNOWN_INSTALLEDyUNKNOWN_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_RECOGNIZEDes 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.
Hemos recibido tu mensaje y responderemos en un plazo de 24 horas.
← Volver a editar