Overview of the Play Integrity API

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 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

By accessing or using the Play Integrity API, you agree to the Play Core Software Development Kit Terms of Service. Please read and understand all applicable terms and policies before accessing the API.

Prerequisites

To integrate the Play Integrity API into your app, do the following:

Security considerations

Although the Play Integrity API enhances security and protects against tampering, it provides the most value for your app when you follow each of the best practices listed in this section.

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

Primarily, you should call the API to protect high-value, non-recurring actions that are an integral part of your user experience, such as logging in to a service or joining a multiplayer server.

On average, one call per active user per day is reasonable, although a user performing multiple high-value actions in a day might warrant multiple calls.

Generate nonces carefully

Nonces should be unique and impossible for an attacker to predict.

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 and remove these details from your APK/repository.

Send multiple decisions from your server to your app

Rather than sending a single pass/fail response from the server back to the app, it's better to send a number of decision outcomes and signals that are 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 and how your server responds can be tailored 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 a flaky 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.

High-level API usage

Figure 1. Sequence diagram that shows the high-level design of the Play Integrity API.

At a high level, your app or game uses the Play Integrity API as follows:

  1. Your app's server-side backend generates and sends a unique nonce to the client-side logic. The remaining steps refer to this logic as your “app.”
  2. Your app calls the Play Integrity API, passing in the nonce.
  3. Your app receives a signed and encrypted verdict from the Play Integrity API.
  4. Your app passes the signed and encrypted verdict to your app's backend.
  5. Your app's backend sends the verdict to Play's server. Play's server decrypts and verifies the verdict, passing the results to your app's backend.
  6. Your app's backend decides how to proceed, based on the signals contained in the token payload.
  7. Your app's backend sends the decision outcomes to your app.

API usage tiers

Requests to the API are subject to a maximum per app per day, as determined by the calling app's assigned usage tier. The following table presents the different tiers:

Table 1. Play Integrity API usage 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:

  1. Log into the Play Console.
  2. Select an app that uses the Play Integrity API.
  3. In the Release section of the left menu, go to Setup > App integrity.
  4. On the Integrity API tab, Within the API setting section, look for the API usage tier property. This property's value shows the API usage tier.

Change your usage tier

To request to change your app’s usage tier, contact developer support in the Play Console.