Setup

This page explains how to set up your app or game to use the Play Integrity API. You need to enable responses from the API and then you need to integrate the API into your app and your app's backend server. Additional configuration options, testing features, and reporting becomes available once you link the Google Cloud project that you're using for the Play Integrity API in the Google Play Console.

Enable Play Integrity API responses

Every app or SDK calling the Play Integrity API needs to make use of a Google Cloud project to monitor API usage. Apps on Google Play can link a Cloud project in the Google Play Console to enable Play Integrity API responses. If you want to create a new Cloud project or your app is exclusively distributed outside Google Play, you can enable Play Integrity API responses from your Google Cloud Console.

Set up in Google Play Console (recommended)

By enabling Play Integrity API responses in the Google Play Console, you will gain access to additional configuration options, testing features, and API reporting. This option is only available to apps distributed on Google Play. Navigate to Release > App integrity. Under Play Integrity API select Link a Cloud project. Choose the Cloud project you want to link to your app and this will enable Play Integrity API responses. You can now integrate the Play Integrity API into your app.

Set up in Google Cloud Console

In your Google Cloud Console, create a new Cloud project or choose an existing Cloud project that you want to use with the Play Integrity API. Navigate to APIs and services. Select enable APIs and services. Search for Play Integrity API and then enable it. You can now integrate the Play Integrity API into your app.

Set up instructions for SDK providers

SDK providers must use their own Google Cloud project to call the Play Integrity API, so that API usage is attributed to the SDK and not to individual apps using the SDK. This means that apps that use your SDK don't have to individually set up the Play Integrity API. Your requests to Play Integrity API automatically count towards your SDK's API usage and not the app.

SDK developers have two options to set up Play Integrity API, the Google Play SDK Console or the Google Cloud Console.

By enabling Play Integrity API responses in the Google Play SDK Console, you gain access to additional configuration options. Navigate to SDK integrity and click Settings. Under Project configuration select Link a Cloud project. Choose the Cloud project you want to link to your SDK and this will enable Play Integrity API responses. You can now integrate the Play Integrity API into your SDK. Note that access to the Google Play SDK Console is subject to eligibility criteria.

Use Google Cloud Console

You can enable Play Integrity API responses from your Google Cloud Console. In your Google Cloud Console, create a new Cloud project or choose an existing Cloud project that you want to use with the Play Integrity API. Navigate to APIs and services. Select enable APIs and services. Search for Play Integrity API and then enable it. You can now integrate the Play Integrity API into your SDK.

Increase your SDK's daily Play Integrity API requests

SDK providers that want to increase their maximum daily requests should complete the quota request form. In the open comments section, specify that you are making an SDK request and include your Maven coordinates (groupId:artifactId) or a URL to your SDK.

Increase your daily Play Integrity API requests

Your app will be subject to a maximum of 10,000 total requests per app per day. You can request to increase this daily maximum if your app needs to handle an increased number of users by following the instructions below.

Increase your daily maximum number of requests

To be eligible for an increase in your daily maximum number of requests, your app must be available on Google Play in addition to any other distribution channels. Even with an increased daily maximum, you should continue to limit classic requests per user to infrequent, high-value actions to preserve user data and battery.

To request an increase in your daily maximum number of requests, do the following:

  1. Link the Google Cloud project that you're using for the Play Integrity API in the Play Console.
  2. Ensure that you are correctly implementing API logic including the recommended retry strategy.
  3. Request a quota increase using this form.

It can take up to a week to increase Play Integrity API quota, so we strongly recommend monitoring your Play Integrity API usage in your Google Play Console or in your Google Cloud Console, where you can also set up quota alerts, to avoid interruptions to your service.

Classic request quota increases will automatically be applied to both the client call to generate integrity tokens and the server call to decrypt and verify integrity tokens. Standard request quota increases are applied to the server call to decrypt and verify integrity tokens.

Integrate Play Integrity API into your app

To integrate the Play Integrity API into your app or SDK, do one of the following depending on your development environment:

Kotlin or Java

The latest Android library for the Play Integrity API is available from Google's Maven Repository. Add the following dependency to your app's build.gradle file:

implementation 'com.google.android.play:integrity:1.4.0'

Unity

Install Google Play Integrity Plugin for Unity 1.3.0 or higher. For instructions, see how to install Google packages for Unity.

  • All versions of 2019.x, 2020.x, and newer are supported.
  • If you use Unity 2018.x, version 2018.4 or newer are supported.
  • Unity 2017.x and older aren't supported.

Native

Install Play Core Native SDK 1.13.0 or higher. For instructions, see Play Core Native's development environment setup guide.

Configure API responses (optional)

The API response includes default verdicts returned in every request. If you set up your Play Integrity API integration in the Play Console, you can customize your API response.

Default responses

The following integrity verdicts are returned in the Play Integrity API response by default:

Response field Value Description
Device integrity MEETS_DEVICE_INTEGRITY The app is running on an Android device powered by Google Play services. The device passes system integrity checks and meets Android compatibility requirements.
Empty (a blank value) The app is running on a device that has signs of attack (such as API hooking) or system compromise (such as being rooted), or the app is not running on a physical device (such as an emulator that does not pass Google Play integrity checks).
Play account details LICENSED The user has an app entitlement. In other words, the user installed or bought your app on Google Play. The user keeps the app entitlement after uninstalling the app, so the user account will still be licensed if the user later obtains the same app another way.
UNLICENSED The user doesn't have an app entitlement. This happens when, for example, the user sideloads your app or doesn't acquire it from Google Play.
UNEVALUATED Licensing details were not evaluated because a requirement was missed. This could happen for several reasons, including the following:
  • The device is not trustworthy enough.
  • The user is not signed in to Google Play.
  • The version of your app installed on the device is unknown to Google Play.
Application integrity PLAY_RECOGNIZED The app and certificate match the versions distributed by Google Play.
UNRECOGNIZED_VERSION The certificate or package name does not match Google Play records.
UNEVALUATED Application integrity was not evaluated. A necessary requirement was missed, such as the device not being trustworthy enough.

Conditional responses

If you distribute to Google Play Games for PC, you will automatically be opted in to receive an additional label in the device integrity verdict:

Response field Label Description
Device integrity MEETS_VIRTUAL_INTEGRITY The app is running on an Android emulator powered by Google Play services. The emulator passes system integrity checks and meets core Android compatibility requirements.

Optional responses

If you set up your Play Integrity API integration in the Play Console or the Play SDK Console, you can opt in to receive information in your API response.

To make changes to your API responses, visit the Play Console and navigate to Release > App integrity. Under Responses, edit and save your changes.

Optional device information

Apps and SDKs can opt in to additional device labels in the device integrity verdict. 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. You can prepare your backend server to behave differently depending on the range of possible responses. For example, a device that returns three labels (MEETS_STRONG_INTEGRITY, MEETS_DEVICE_INTEGRITY, and MEETS_BASIC_INTEGRITY ) can be trusted more than a device that returns only one label (MEETS_BASIC_INTEGRITY).

You can also opt in to recent device activity. Recent device activity returns a level ranging from LEVEL_1 (low number of requests) to LEVEL_4 (high number of requests). For example, a device that returns a significantly higher activity level than is typical for your app might be attempting to generate a large number of integrity tokens for distribution to untrusted devices.

Response field Label Description
Device integrity MEETS_BASIC_INTEGRITY The app is running on a device that passes basic system integrity checks. The device may not meet Android compatibility requirements and may not be approved to run Google Play services. For example, the device may be running an unrecognized version of Android, may have an unlocked bootloader, or may not have been certified by the manufacturer.
MEETS_STRONG_INTEGRITY The app is running on an Android device powered by Google Play services and has a strong guarantee of system integrity such as a hardware-backed proof of boot integrity. The device passes system integrity checks and meets Android compatibility requirements.
Recent device activity Standard API integrity token requests on this device in the last hour per app Classic API integrity token requests on this device in the last hour per app
LEVEL_1 (lowest) 10 or fewer 5 or fewer
LEVEL_2 Between 11 and 25 Between 6 and 10
LEVEL_3 Between 26 and 50 Between 11 and 15
LEVEL_4 (highest) More than 50 More than 15
UNEVALUATED Recent device activity was not evaluated. This could happen because:
  • The device is not trustworthy enough.
  • The version of your app installed on the device is unknown to Google Play.
  • There were technical issues on the device.

Optional environment details

Apps can opt in to receive additional verdicts about the environment. App access risk lets you know whether other apps are running that could capture the screen, display overlays, or control the device. The Play Protect verdict lets you know whether Play Protect is enabled on the device and whether it has found known malware.

After you opt in to receive these verdicts, your API response will include the environment details field with the verdict:

Response field Value Description
App access risk verdict KNOWN_INSTALLED Apps are installed by Google Play or preloaded on the system partition by the device manufacturer.
KNOWN_CAPTURING Apps installed by Google Play or preloaded on the device are running that could be used to read or capture inputs and outputs of the requesting app, such as screen recording apps.
KNOWN_CONTROLLING Apps installed by Google Play or preloaded on the device are running that could be used to control the device and inputs and outputs of the requesting app, such as remote controlling apps.
KNOWN_OVERLAYS Apps installed by Google Play or preloaded on the device are running that might be displaying overlays on the requesting app.
UNKNOWN_INSTALLED Other apps are installed, which were not installed by Google Play or preloaded on the system partition by the device manufacturer.
UNKNOWN_CAPTURING Other apps are running (not installed by Play or preloaded on the device) that could be used to read or capture inputs and outputs of the requesting app, such as screen recording apps.
UNKNOWN_CONTROLLING Other apps are running (not installed by Play or preloaded on the device) that could be used to control the device and inputs and outputs of the requesting app, such as remote controlling apps.
UNKNOWN_OVERLAYS Other apps are running (not installed by Play or preloaded on the device) that might be displaying overlays on the requesting app.
EMPTY (a blank value) App access risk is not evaluated if a necessary requirement was missed. In this case the appAccessRiskVerdict field is empty. This could happen for several reasons, including the following:
  • The device is not trustworthy enough.
  • The device form factor is not a phone, tablet, or foldable.
  • The device is not running Android 6 (API level 23) or higher.
  • The version of your app installed on the device is unknown to Google Play.
  • The version of the Google Play Store on the device is outdated.
  • Games only: The user account does not have a Play license for the game.
  • A standard request was used with the verdictOptOut parameter.
  • A standard request was used with a Play Integrity API library version that doesn't yet support app access risk for standard requests.
Play Protect verdict NO_ISSUES Play Protect is turned on and did not find any app issues on the device.
NO_DATA Play Protect is turned on but no scan has been performed yet. The device or the Play Store app may have been recently reset.
POSSIBLE_RISK Play Protect is turned off.
MEDIUM_RISK Play Protect is turned on and has found potentially harmful apps installed on the device.
HIGH_RISK Play Protect is turned on and has found dangerous apps installed on the device.
UNEVALUATED The Play Protect verdict was not evaluated. A necessary requirement was missed, such as the device not being trustworthy enough.

Configure classic request settings (optional)

Skip this section if you only plan to make standard API requests.

When you make classic requests, by default, Google Play's servers manage the response encryption that your app uses when you interact with the Play Integrity API. While we recommend that you use this default option, you can also choose to manage and download your response encryption keys by following the instructions below.

Let Google manage your response encryption (default and recommended)

To protect your app's security, it's recommended that you allow Google to generate and manage your response encryption keys. Your backend server will call Google Play's server to decrypt responses.

Manage and download my response encryption keys

If you want to decrypt the integrity verdict locally within your own secure server environment, you can manage and download your response encryption keys. To manage and download your response encryption keys, you must use the Play Console, and your app must be available on Google Play in addition to any other distribution channels. Follow the instructions below to switch from Google-managed to self-managed response encryption keys.

Remember not to decrypt or verify the received token from within your client app, and never expose any decryption keys to the client app.

Before you change your response encryption management strategy in the Play Console, make sure your server is correctly configured to decrypt and verify integrity tokens on Google Play's servers to avoid disruption.

Switch between Google-managed and self-managed response encryption keys

If Google currently manages your response encryption, and you want to switch to manage and download your response encryption keys yourself, follow these steps:

  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 App integrity.
  4. Next to Play Integrity API, click Settings.
  5. In the Classic requests section of the page, next to Response encryption, click Edit.
  6. In the window that appears, click Manage and download my response encryption keys.
  7. Follow the instructions to upload a public key.
  8. After the window shows that the upload was successful, click Save and your encrypted keys download automatically.
  9. Change your server logic so that you decrypt and verify integrity tokens locally, in your own secure server environment, using your response encryption keys.
  10. (Optional) When you self-manage your response encryption keys, your app can still fall back to Google Play's server to decrypt and verify the response.

If you self-manage your response encryption keys, and you want to switch to have Google manage your response encryption, follow these steps:

  1. Change your server logic so that you're solely decrypting and verifying on Google's servers.
  2. Log into the Play Console.
  3. Select an app that uses the Play Integrity API.
  4. In the Release section of the left menu, go to App integrity.
  5. Next to Play Integrity API, click Settings.
  6. In the Classic requests section of the page, next to Response encryption, click Edit.
  7. In the window that appears, click Let Google manage my response encryption (recommended).
  8. Click Save changes.