Skip to main content

Integrity Monitoring

Obtaining Play Integrity State​

You can always retrieve the configured Play Integrity settings with the following:

approov playintegrity -get

This will generate output such as the following:

KeyID: d4dd9548372f47cad0f464a0c1ae96d2fd5c54df
CloudProjectNumber: 733523093046
RequireAppCert: on
RequireAppIntegrity: PLAY_RECOGNIZED
RequireDeviceIntegrity: MEETS_DEVICE_INTEGRITY
RateLimit: unlimited
RecheckPeriod: never

It shows if Play Integrity integration has been enabled and the integrity verdicts that are required. It will also show the private key ID being used for access to your Google Cloud account. It is not possible to obtain the private key again once it is set. It is held securely by the Approov cloud service.

Disabling Play Integrity​

The Play Integrity integration can be disabled using:

approov playintegrity -remove

You will need an admin or delegate role and confirmation to do this:

WARNING: this will have an immediate impact on your apps in production
ATTENTION: If you wish to continue then please type YES and return: YES
Play Integrity disabled

This will immediately stop any usage of Play Integrity by your apps. It will also prevent any further attestation rejections as a consequence of Play Integrity results.

Setting App Integrity Requirement​

You can specify the set of app integrity verdicts that are acceptable as follows:

approov playintegrity -setRequireAppIntegrity PLAY_RECOGNIZED

You will need an admin or delegate role and confirmation to do this:

WARNING: this will have an immediate impact on your apps in production
ATTENTION: If you wish to continue then please type YES and return: YES
Play Integrity app integrity required verdicts set

This causes the Approov attestation to be rejected unless the app integrity is determined as PLAY_RECOGNIZED. Changes impact apps that have previously performed a Play Integrity attestation, as well as for new Play Integrity attestations. Note that you may specify multiple acceptable verdicts separated by |, but you should surround the parameter in double quotes for it to be accepted as single parameter.

You can clear any required verdicts by using this command, so that any verdict is considered acceptable:

approov playintegrity -clearRequireAppIntegrity

Setting App Certificate Integrity​

The Play Integrity token may include an certificateSha256Digest field that provides the SHA256 hashes of the certificates used to sign the application. This claim might not be present if the device does not meet even basic integrity requirements. This is in contrast to the Approov app signature analysis which operates even if a device is rooted.

If you want Approov to use this information then enable it using:

approov playintegrity -setRequireAppCert on

You will need an admin or delegate role and confirmation to do this:

WARNING: this will have an immediate impact on your apps in production
ATTENTION: If you wish to continue then please type YES and return: YES
Play Integrity app certificate check state set

If this is enabled, and the valid signing certificates have been added to the Approov account using approov appsigncert, then a comparison is made as an additional check to ensure that the Play Integrity token is consistent with the identity of the calling app. This may cause failures if Play Integrity is not able to provide a certificate because it has not been evaluated. Changes impact apps that have previously performed a Play Integrity attestation, as well as for new Play Integrity attestations.

You can always disable this feature with:

approov playintegrity -setRequireAppCert off

Setting Device Integrity Requirement​

You can specify the set of device integrity verdicts that are acceptable as follows:

approov playintegrity -setRequireDeviceIntegrity MEETS_DEVICE_INTEGRITY

You will need an admin or delegate role and confirmation to do this:

WARNING: this will have an immediate impact on your apps in production
ATTENTION: If you wish to continue then please type YES and return: YES
Play Integrity app integrity required verdicts set

Changes to the device integrity policy impacts apps that have previously performed a Play Integrity attestation, as well as for new Play Integrity attestations. Note that you may specify multiple acceptable verdicts separated by |, but you should surround the parameter in double quotes for it to be accepted as single parameter.

You can also opt in (via the Google Play console) to receive additional labels in the integrity verdict. You could then upgrade the required verdict to MEETS_STRONG_INTEGRITY, for instance.

You can clear any required verdicts by using this command, so that any verdict is considered acceptable:

approov playintegrity -clearRequireDeviceIntegrity

Setting App Licensing Requirement​

You can specify the set of app licensing verdicts that are acceptable as follows:

approov playintegrity -setRequireAppLicensing LICENSED

You will need an admin or delegate role and confirmation to do this:

WARNING: this will have an immediate impact on your apps in production
ATTENTION: If you wish to continue then please type YES and return: YES
Play Integrity app licensing required verdicts set

Changes to the app licensing policy impacts apps that have previously performed a Play Integrity attestation, as well as for new Play Integrity attestations. Note that you may specify multiple acceptable verdicts separated by |, but you should surround the parameter in double quotes for it to be accepted as single parameter.

You can clear any required verdicts by using this command, so that any verdict is considered acceptable:

approov playintegrity -clearRequireAppLicensing

Rate Limiting Play Integrity Attestations​

Performing a Play Integrity attestation causes the device to call a Google API. The standard API usage tier provides a maximum of 10,000 requests per day across all apps using the same Google cloud project ID.

Approov will only perform a Play Integrity attestation the first time an app is launched after installation (or after adding the Play Integrity credentials, if there is already an installed base of app users). The Play Integrity verdicts are persisted to avoid having to use Play Integrity more frequently. Thus if your typical increase in new users for your app is less than 10,000 per day you can use the standard usage tier. If you expect higher traffic than this then you must request a raised usage tier from Google. The Approov integration already takes the appropriate measures to minimize the usage of the Play Integrity service.

If you exceed your quota then some devices will not be able to perform a Play Integrity attestation. This is not a problem (unless you are using the require-playintegrity option flag) as the Play Integrity attestation will be performed the next time the app is restarted and connects to the Approov service. This should help smooth the consumption of your quota. It is only problematic if you are continually exceeding your quota on a day-to-day basis.

Note there is also a attestation renewal feature which allows you to force a new Play Integrity attestation after a period, and this will increase your usage depending upon the size of your app user base.

It is also possible to constrain the number of Play Integrity attestations performed from your account using:

approov playintegrity -setRateLimit 400

You will need an admin or delegate role and confirmation to do this:

WARNING: this will have an immediate impact on your apps in production
ATTENTION: If you wish to continue then please type YES and return: YES
Play Integrity rate limit set

The value provided is the maximum number of attestations per hour. The value 400 roughly corresponds to the maximum hourly amount for 10,000 requests per day, the default limit. If an app needs to make a Play Integrity attestation and the limit for the hour is exceeded then it is delayed until the next time the app is started, when there is some available quota. Note that if you are using the require-playintegrity option flag then this will cause the app attestation to be rejected.

You can always reset the maximum rate to be unlimited with:

approov playintegrity -setRateLimit unlimited

Controlling Play Integrity Attestation Renewals​

By default, an app only performs a Play Integrity attestation when it is launched for the first time. The integrity verdicts are then securely held for the device by Approov. This approach avoids the high latency and usage overhead caused by using Play Integrity on every Approov token fetch. You can, however, opt to reattest using Play Integrity when the app uses the Approov service again when the prior Play Integrity attestation is more than a certain number of hours old. Use the command:

approov playintegrity -setRecheckPeriod 720

You will need an admin or delegate role and confirmation to do this:

WARNING: this will have an immediate impact on your apps in production
ATTENTION: If you wish to continue then please type YES and return: YES
Play Integrity recheck period set

The value provided is the number of hours before a recheck is needed. The value of 720 corresponds to the approximate number of hours in a month, so this requires a new Play Integrity attestation for each app instance every month. You need to consider how the additional Play Integrity attestations might impact your API usage tier.

Note that a given launch of an app will only ever make a single Play Integrity attestation, so if the app is not relaunched within the recheck period then the re-attestation will be delayed until it is.

You can always remove the recheck period with:

approov playintegrity -setRecheckPeriod never