En esta página, se describe cómo interpretar el resultado del veredicto de integridad y trabajar con él. Ya sea que realices una solicitud estándar o clásica a la API, el veredicto de integridad se devuelve en el mismo formato con contenido similar. El veredicto de integridad comunica información sobre la validez de los dispositivos, las apps y las cuentas. El servidor de tu app puede usar la carga útil resultante en un veredicto verificado y desencriptado para determinar la mejor manera de proceder con una acción o una solicitud particulares en tu app.
Formato del resultado del veredicto de integridad
La carga útil es un archivo JSON de texto sin formato y contiene indicadores de integridad junto con información que proporciona el desarrollador.
La estructura general de la carga útil es la siguiente:
{ requestDetails: { ... } appIntegrity: { ... } deviceIntegrity: { ... } accountDetails: { ... } environmentDetails: { ... } }
Antes de verificar cada veredicto de integridad, debes comprobar que los valores del campo requestDetails
coincidan con los de la solicitud original. En las siguientes secciones, se describe cada campo con mayor detalle.
Campo de detalles de la solicitud
El campo requestDetails
contiene información sobre la solicitud, incluida la información proporcionada por el desarrollador en el requestHash
de las solicitudes estándar y en el nonce
de las solicitudes clásicas.
Para solicitudes estándar a la API:
requestDetails: { // Application package name this attestation was requested for. // Note that this field might be spoofed in the middle of the request. requestPackageName: "com.package.name" // Request hash provided by the developer. requestHash: "aGVsbG8gd29scmQgdGhlcmU" // The timestamp in milliseconds when the integrity token // was prepared (computed on the server). timestampMillis: "1675655009345" }
Estos valores 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:
Kotlin
val requestDetails = JSONObject(payload).getJSONObject("requestDetails") val requestPackageName = requestDetails.getString("requestPackageName") val requestHash = requestDetails.getString("requestHash") val timestampMillis = requestDetails.getLong("timestampMillis") val currentTimestampMillis = ... // Ensure the token is from your app. if (!requestPackageName.equals(expectedPackageName) // Ensure the token is for this specific request || !requestHash.equals(expectedRequestHash) // Ensure the freshness of the token. || currentTimestampMillis - timestampMillis > ALLOWED_WINDOW_MILLIS) { // The token is invalid! See below for further checks. ... }
Java
RequestDetails requestDetails = decodeIntegrityTokenResponse .getTokenPayloadExternal() .getRequestDetails(); String requestPackageName = requestDetails.getRequestPackageName(); String requestHash = requestDetails.getRequestHash(); long timestampMillis = requestDetails.getTimestampMillis(); long currentTimestampMillis = ...; // Ensure the token is from your app. if (!requestPackageName.equals(expectedPackageName) // Ensure the token is for this specific request. || !requestHash.equals(expectedRequestHash) // Ensure the freshness of the token. || currentTimestampMillis - timestampMillis > ALLOWED_WINDOW_MILLIS) { // The token is invalid! See below for further checks. ... }
Para solicitudes clásicas a la API:
requestDetails: { // Application package name this attestation was requested for. // Note that this field might be spoofed in the middle of the // request. requestPackageName: "com.package.name" // base64-encoded URL-safe no-wrap nonce provided by the developer. nonce: "aGVsbG8gd29scmQgdGhlcmU" // The timestamp in milliseconds when the request was made // (computed on the server). timestampMillis: "1617893780" }
Estos valores 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 nonce
coincidan con lo que se envió en la solicitud original, como se muestra en el siguiente fragmento de código:
Kotlin
val requestDetails = JSONObject(payload).getJSONObject("requestDetails") val requestPackageName = requestDetails.getString("requestPackageName") val nonce = requestDetails.getString("nonce") val timestampMillis = requestDetails.getLong("timestampMillis") val currentTimestampMillis = ... // Ensure the token is from your app. if (!requestPackageName.equals(expectedPackageName) // Ensure the token is for this specific request. See 'Generate a nonce' // section of the doc on how to store/compute the expected nonce. || !nonce.equals(expectedNonce) // Ensure the freshness of the token. || currentTimestampMillis - timestampMillis > ALLOWED_WINDOW_MILLIS) { // The token is invalid! See below for further checks. ... }
Java
JSONObject requestDetails = new JSONObject(payload).getJSONObject("requestDetails"); String requestPackageName = requestDetails.getString("requestPackageName"); String nonce = requestDetails.getString("nonce"); long timestampMillis = requestDetails.getLong("timestampMillis"); long currentTimestampMillis = ...; // Ensure the token is from your app. if (!requestPackageName.equals(expectedPackageName) // Ensure the token is for this specific request. See 'Generate a nonce' // section of the doc on how to store/compute the expected nonce. || !nonce.equals(expectedNonce) // Ensure the freshness of the token. || currentTimestampMillis - timestampMillis > ALLOWED_WINDOW_MILLIS) { // The token is invalid! See below for further checks. ... }
Campo de integridad de la aplicación
El campo appIntegrity
contiene información relacionada con el paquete.
appIntegrity: { // PLAY_RECOGNIZED, UNRECOGNIZED_VERSION, or UNEVALUATED. appRecognitionVerdict: "PLAY_RECOGNIZED" // The package name of the app. // This field is populated iff appRecognitionVerdict != UNEVALUATED. packageName: "com.package.name" // The sha256 digest of app certificates (base64-encoded URL-safe). // This field is populated iff appRecognitionVerdict != UNEVALUATED. certificateSha256Digest: ["6a6a1474b5cbbb2b1aa57e0bc3"] // The version of the app. // This field is populated iff appRecognitionVerdict != UNEVALUATED. versionCode: "42" }
appRecognitionVerdict
puede tener los siguientes valores:
PLAY_RECOGNIZED
- La app y el certificado coinciden con las versiones que distribuye Google Play.
UNRECOGNIZED_VERSION
- El certificado o el nombre del paquete no coinciden con los registros de Google Play.
UNEVALUATED
- No se evaluó la integridad de la aplicación. Se omitió un requisito necesario, por ejemplo, el dispositivo no es lo suficientemente confiable.
Para asegurarte de que el token haya sido generado por una app creada por ti, verifica que la integridad de la aplicación sea la esperada, como se muestra en el siguiente fragmento de código:
Kotlin
val appIntegrity = JSONObject(payload).getJSONObject("appIntegrity") val appRecognitionVerdict = appIntegrity.getString("appRecognitionVerdict") if (appRecognitionVerdict == "PLAY_RECOGNIZED") { // Looks good! }
Java
JSONObject appIntegrity = new JSONObject(payload).getJSONObject("appIntegrity"); String appRecognitionVerdict = appIntegrity.getString("appRecognitionVerdict"); if (appRecognitionVerdict.equals("PLAY_RECOGNIZED")) { // Looks good! }
También puedes verificar el nombre del paquete de la app, su versión y los certificados de forma manual.
Campo de integridad del dispositivo
El campo deviceIntegrity
puede contener un solo valor, deviceRecognitionVerdict
, que tenga una o más etiquetas que representen la capacidad de un dispositivo para aplicar de manera forzosa la integridad de la app. Si un dispositivo no cumple con los criterios de ninguna etiqueta, el campo deviceIntegrity
estará vacío.
deviceIntegrity: { // "MEETS_DEVICE_INTEGRITY" is one of several possible values. deviceRecognitionVerdict: ["MEETS_DEVICE_INTEGRITY"] }
De forma predeterminada, deviceRecognitionVerdict
puede contener lo siguiente:
MEETS_DEVICE_INTEGRITY
- La app se está ejecutando en un dispositivo con tecnología Android y los Servicios de Google Play. El dispositivo pasa las verificaciones de integridad del sistema y cumple con los requisitos de compatibilidad de Android.
- Vacío (un valor en blanco)
- La app se está ejecutando en un dispositivo que muestra indicios de ataque (como trampas de API) o de vulneración del sistema (como un dispositivo con permisos de administrador), o bien no se está ejecutando en un dispositivo físico (como un emulador que no pasa las verificaciones de integridad de Google Play).
Para asegurarte de que el token provenga de un dispositivo confiable, verifica que el deviceRecognitionVerdict
sea el esperado, como se muestra en el siguiente fragmento de código:
Kotlin
val deviceIntegrity = JSONObject(payload).getJSONObject("deviceIntegrity") val deviceRecognitionVerdict = if (deviceIntegrity.has("deviceRecognitionVerdict")) { deviceIntegrity.getJSONArray("deviceRecognitionVerdict").toString() } else { "" } if (deviceRecognitionVerdict.contains("MEETS_DEVICE_INTEGRITY")) { // Looks good! }
Java
JSONObject deviceIntegrity = new JSONObject(payload).getJSONObject("deviceIntegrity"); String deviceRecognitionVerdict = deviceIntegrity.has("deviceRecognitionVerdict") ? deviceIntegrity.getJSONArray("deviceRecognitionVerdict").toString() : ""; if (deviceRecognitionVerdict.contains("MEETS_DEVICE_INTEGRITY")) { // Looks good! }
Si tienes problemas con la integridad del dispositivo de prueba, asegúrate de que la ROM de fábrica esté instalada (por ejemplo, puedes restablecer el dispositivo) y de que el bootloader esté bloqueado. También puedes crear pruebas de la API de Play Integrity en tu Play Console.
Etiquetas de dispositivos condicionales
Si tu app se lanza en Google Play Juegos para PC, el deviceRecognitionVerdict
también puede contener la siguiente etiqueta:
MEETS_VIRTUAL_INTEGRITY
- La app se está ejecutando en un dispositivo con tecnología Android y los Servicios de Google Play. El emulador pasa las verificaciones de integridad del sistema y cumple con los requisitos principales de compatibilidad de Android.
Información opcional del dispositivo
Si aceptas recibir etiquetas adicionales en el veredicto de integridad, deviceRecognitionVerdict
puede tener las siguientes etiquetas adicionales:
MEETS_BASIC_INTEGRITY
- La app se está ejecutando en un dispositivo que pasa las verificaciones básicas de integridad del sistema. Es posible que el dispositivo no cumpla con los requisitos de compatibilidad de Android y que no esté aprobado para ejecutar los Servicios de Google Play. Por ejemplo, es posible que el dispositivo esté ejecutando una versión no reconocida de Android o que tenga un bootloader desbloqueado, o que el fabricante no haya certificado el dispositivo.
MEETS_STRONG_INTEGRITY
- La app se está ejecutando en un dispositivo Android con la tecnología de los Servicios de Google Play y tiene una garantía sólida de integridad del sistema, como una prueba de integridad de inicio con copia de seguridad en hardware. El dispositivo pasa las verificaciones de integridad del sistema y cumple con los requisitos de compatibilidad de Android.
Un solo dispositivo devolverá varias etiquetas de dispositivo en el veredicto de integridad del dispositivo si se cumple cada uno de los criterios de la etiqueta.
Actividad del dispositivo reciente (beta)
También puedes habilitar la actividad reciente del dispositivo, que te indica cuántas veces tu app solicitó un token de integridad en un dispositivo específico durante la última hora. Puedes usar la actividad reciente del dispositivo para proteger tu app de dispositivos hiperactivos inesperados que podrían indicar un ataque activo. Puedes decidir cuánto confiar en cada nivel reciente de la actividad del dispositivo según la cantidad de veces que esperas que tu app esté instalada en un dispositivo típico para solicitar un token de integridad cada hora.
Si aceptas recibir recentDeviceActivity
, el campo deviceIntegrity
tendrá dos valores:
deviceIntegrity: { deviceRecognitionVerdict: ["MEETS_DEVICE_INTEGRITY"] recentDeviceActivity: { // "LEVEL_2" is one of several possible values. deviceActivityLevel: "LEVEL_2" } }
Las definiciones de deviceActivityLevel
difieren entre modos y pueden tener uno de los siguientes valores:
Nivel de actividad reciente del dispositivo | Solicitud a la API estándar | Solicitud a la API clásica |
---|---|---|
LEVEL_1 (valor más bajo) |
La app solicitó 10 tokens de integridad o menos en este dispositivo en la última hora. | La app solicitó 5 tokens de integridad o menos en este dispositivo en la última hora. |
LEVEL_2 |
La app solicitó entre 11 y 25 tokens de integridad en este dispositivo en la última hora. | La app solicitó entre 6 y 15 tokens de integridad en este dispositivo en la última hora. |
LEVEL_3 |
La app solicitó entre 26 y 50 tokens de integridad en este dispositivo en la última hora. | La app solicitó entre 16 y 30 tokens de integridad en este dispositivo en la última hora. |
LEVEL_4 (valor más alto) |
La app solicitó más de 50 tokens de integridad en este dispositivo en la última hora. | La app solicitó más de 30 tokens de integridad en este dispositivo en la última hora. |
UNEVALUATED |
No se evaluó la actividad reciente del dispositivo.
Estos son algunos de los diversos motivos por los que podría suceder:
|
Campo de detalles de la cuenta
El campo accountDetails
contiene un solo valor, appLicensingVerdict
, que representa el estado de la licencia de la app o el del derecho de acceso a esta última.
accountDetails: { // This field can be LICENSED, UNLICENSED, or UNEVALUATED. appLicensingVerdict: "LICENSED" }
appLicensingVerdict
puede tener uno de los siguientes valores:
LICENSED
- El usuario tiene derechos de acceso a la app. En otras palabras, el usuario instaló o compró tu app en Google Play.
UNLICENSED
- El usuario no tiene derechos de acceso a la app. Esto sucede, por ejemplo, cuando el usuario transfiere tu app desde una fuente desconocida o no la adquiere en Google Play. Para solucionar el problema, puedes mostrarles el diálogo GET_LICENSED a los usuarios.
UNEVALUATED
No se evaluó la información de las licencias porque se omitió un requisito necesario.
Estos son algunos de los diversos motivos por los que podría suceder:
- El dispositivo no es lo suficientemente confiable.
- La versión de tu app instalada en el dispositivo es desconocida para Google Play.
- El usuario no accedió a Google Play.
Para verificar que el usuario tenga derechos de acceso a tu app, comprueba que el objeto appLicensingVerdict
sea el esperado, como se muestra en el siguiente fragmento de código:
Kotlin
val accountDetails = JSONObject(payload).getJSONObject("accountDetails") val appLicensingVerdict = accountDetails.getString("appLicensingVerdict") if (appLicensingVerdict == "LICENSED") { // Looks good! }
Java
JSONObject accountDetails = new JSONObject(payload).getJSONObject("accountDetails"); String appLicensingVerdict = accountDetails.getString("appLicensingVerdict"); if (appLicensingVerdict.equals("LICENSED")) { // Looks good! }
Campo de detalles del entorno
Si habilitaste el veredicto de Play Protect en Google Play Console, tu respuesta de la API incluirá el campo environmentDetails
. El campo environmentDetails
contiene un solo valor, playProtectVerdict
, que proporciona información sobre Google Play Protect en el dispositivo.
environmentDetails: { playProtectVerdict: "NO_ISSUES" }
playProtectVerdict
puede tener uno de los siguientes valores:
NO_ISSUES
- Play Protect está activado y no detectó ningún problema con las apps del dispositivo.
NO_DATA
- Play Protect está activado, pero aún no se realizó ningún análisis. Es posible que el dispositivo o la app de Play Store se hayan restablecido recientemente.
POSSIBLE_RISK
- Play Protect está desactivado.
MEDIUM_RISK
- Play Protect está activado y encontró apps potencialmente dañinas instaladas en el dispositivo.
HIGH_RISK
- Play Protect está activado y encontró apps peligrosas instaladas en el dispositivo.
UNEVALUATED
No se evaluó el veredicto de Play Protect.
Estos son algunos de los diversos motivos por los que podría suceder:
- El dispositivo no es lo suficientemente confiable.
- Solo para juegos: La cuenta de usuario no es
LICENSED
.
Guía para usar el veredicto de Play Protect
El servidor de backend de tu app puede decidir cómo actuar en función del veredicto según tu tolerancia al riesgo. A continuación, se incluyen algunas sugerencias y posibles acciones de los usuarios:
NO_ISSUES
- Play Protect está activado y no detectó ningún problema, por lo que no se requiere ninguna acción por parte del usuario.
POSSIBLE_RISK
yNO_DATA
- Cuando recibas estos veredictos, pídele al usuario que compruebe si Play Protect está activado y si realizó un análisis.
NO_DATA
debe aparecer solo en circunstancias excepcionales. MEDIUM_RISK
yHIGH_RISK
- Según tu tolerancia al riesgo, puedes pedirle al usuario que inicie Play Protect y realice acciones en las advertencias de Play Protect. Si el usuario no puede cumplir con estos requisitos, puedes bloquearlo de la acción del servidor.