The Play Integrity API helps protect your apps and games from potentially risky and fraudulent interactions, such as cheating and unauthorized access, allowing you to respond with appropriate actions to prevent attacks and reduce abuse.
When your app or game is used on a device that runs Android 4.4 (API level 19) or higher, the Play Integrity API provides a signed and encrypted response that includes the following information:
- Genuine app binary: Determine whether you're interacting with your unmodified binary that Google Play recognizes.
- Genuine Play install: Determine whether the current user account is licensed, which means that the user installed or paid for your app or game on Google Play.
- Genuine Android device: This tells you whether your app is running on a genuine Android device powered by Google Play services.
Terms of service and data safety
By accessing or using the Play Integrity API, you agree to the Play Integrity API Terms of Service. Please read and understand all applicable terms and policies before accessing the API.
Google Play has a data safety section for developers to disclose their apps’ data collection, sharing, and security practices. To help you complete the data safety section requirements, see this information on how the Play Integrity API handles data.
Security considerations
Although the Play Integrity API enhances security and protects against tampering, it provides the most value for your app when you follow these recommended practices:
Have an anti-abuse strategy
The Play Integrity API works best when used alongside other signals as part of your overall anti-abuse strategy and not as your sole anti-abuse mechanism. Use this API in conjunction with other appropriate security best practices for your app.
Don't obtain the integrity token too frequently
Generating an integrity token uses time, data, and battery, and each app has a maximum number of calls it can make per day as defined by its usage tier. Therefore you should call the API to protect high-value, infrequent actions that are an integral part of your user experience, such as logging in to a service or joining a multiplayer server. You shouldn't call the API on high-frequency or low-value actions. For example, don't call it every time the app goes to the foreground nor every few minutes in the background. An app making too many API calls may be throttled to protect users from incorrect implementations.
Use the nonce field to further protect your app
The Play Integrity API offers a field called nonce, which can be used to
further protect your app against certain attacks, such as replay attacks, and
person-in-the-middle (PITM) tampering attacks. The Play Integrity API returns
the value you set in this field, inside the signed integrity response. Carefully
follow the guidance on how to generate
nonces to protect your app from attacks.
Use a secure server environment
Perform all decryption and validation within a secure server environment. If your client app exposes any security details, an attacker could extract those from your APK or repository, giving them valuable information about your app or game.
Send a range of responses from your server to your app
Rather than sending the same binary pass/fail response from the server back to the app every time, it's better to have a range of decision outcomes since this is harder to replicate. For example, you could use a series of related responses such as Allow, Allow with limits, Allow with limits after reCAPTCHA completion, and Deny.
Have a tiered enforcement strategy
In your Play Console, you can opt in to receive additional device labels making it possible to build an anti-abuse strategy with multiple tiers of enforcement. After you opt in to receive additional labels, the integrity response will include multiple labels for the same device if each of the label criteria are met. Thus, you can prepare your backend server to behave differently depending on the range of possible responses.
For example, a device that returns MEETS_BASIC_INTEGRITY,
MEETS_DEVICE_INTEGRITY, and MEETS_STRONG_INTEGRITY could be trusted more
than a device that returns only MEETS_BASIC_INTEGRITY. You can configure your
server's response accordingly. This can be combined with different actions on
whether the user account is LICENSED or UNLICENSED.
Retry with exponential backoff
Environmental conditions, such as an unstable Internet connection or an overloaded device, can cause device integrity checks to fail. This can lead to no labels being generated for a device that is otherwise trustworthy. To mitigate these scenarios, be sure to include a retry option with exponential backoff.
Show actionable error messages
When possible, provide useful error messages to the user and let them know what they can do to fix it such as retrying, enabling their Internet connection, or checking the Play Store app is up-to-date.
Have a plan for unexpected issues or outages
The Play status dashboard shows information about the service status of Play Integrity API along with information about any disruptions and outages. You can configure in advance how you want your backend server to function in the unlikely event of a large-scale Play Integrity API outage.
High-level API usage
Figure 1. Sequence diagram that shows the high-level design of the Play Integrity API.
When the user performs a high-value action in your app that you want to protect with an integrity check, complete the following steps:
- Your app's server-side backend generates and sends a unique value to the client-side logic. The remaining steps refer to this logic as your “app.”
- Your app creates the nonce from the unique value and the content of your high-value action. It then calls the Play Integrity API, passing in the nonce.
- Your app receives a signed and encrypted verdict from the Play Integrity API.
- Your app passes the signed and encrypted verdict to your app's backend.
- Your app's backend sends the verdict to a Google Play server. The Google Play server decrypts and verifies the verdict, returning the results to your app's backend.
- Your app's backend decides how to proceed, based on the signals contained in the token payload.
- Your app's backend sends the decision outcomes to your app.
API usage tiers
Requests to the API are subject to a maximum number per app per day, as determined by the calling app’s assigned usage tier. The following table presents the different tiers:
| Usage tier | Number of API calls allowed per day | How to qualify |
|---|---|---|
| Standard | Up to 10,000 | Available to apps using any distribution channel |
| Raised | Over 10,000 - limit subject to approval | Must correctly implement API logic including retries Available to apps using any distribution channel in addition to Google Play |
The same package name on Google Play and on other distribution channels counts as a single app in terms of API usage. You can use a single Google Cloud project ID for multiple apps with different package names. If you do, the apps are counted as a single app in terms of API usage.
View your usage tier
To help you assess how often to interact with the Play Integrity API, the Play Console shows your app's usage tier. To view this usage tier, do the following:
- Log into the Play Console.
- Select an app that uses the Play Integrity API.
- In the Release section of the left menu, go to Setup > App integrity.
- On the Integrity API tab, within the Settings section look for the Usage tier property. This property's value shows your app's usage tier.
Change your usage tier
To request to change your app's usage tier, complete this form. You should request to move to the raised usage tier if your app needs to handle an increased number of users but not to call the API more frequently per user. Even with a raised usage tier, your app should continue to limit API calls to infrequent, high-value actions.
Set up quota monitoring and alerting
Tier increase requests are normally processed in a couple of business days. To maintain a good user experience and avoid emergency situations, we recommend setting up monitoring and alerting of your app's API quota usage with Cloud Monitoring.