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.
Use Google Play SDK Console (recommended)
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:
- Link the Google Cloud project that you're using for the Play Integrity API in the Play Console.
- Ensure that you are correctly implementing API logic including the recommended retry strategy.
- 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 updated your app from Google Play on their device. |
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:
|
|
| 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.
You can also opt in to device attributes, which tells you the Android SDK version of the Android OS running on the device. In the future, it may be extended with other device attributes.
| 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. | ||
| 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 | ||
| Recent device activity | 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:
|
||
| Device attributes | sdkVersion: 19, 20, ..., 35 |
The SDK version of the Android OS running on the device.
The number returned maps to
Build.VERSION_CODES. |
|
| Empty (a blank value) | The SDK version is not evaluated because a necessary
requirement was missed. In this case, the sdkVersion field is
unset; thus, the deviceAttributes field is empty.
This could happen because:
|
||
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:
|
|
| 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:
- Log into the Play Console.
- Select an app that uses the Play Integrity API.
- In the Release section of the left menu, go to App integrity.
- Next to Play Integrity API, click Settings.
- In the Classic requests section of the page, next to Response encryption, click Edit.
- In the window that appears, click Manage and download my response encryption keys.
- Follow the instructions to upload a public key.
- After the window shows that the upload was successful, click Save and your encrypted keys download automatically.
- Change your server logic so that you decrypt and verify integrity tokens locally, in your own secure server environment, using your response encryption keys.
- (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:
- Change your server logic so that you're solely decrypting and verifying on Google's servers.
- Log into the Play Console.
- Select an app that uses the Play Integrity API.
- In the Release section of the left menu, go to App integrity.
- Next to Play Integrity API, click Settings.
- In the Classic requests section of the page, next to Response encryption, click Edit.
- In the window that appears, click Let Google manage my response encryption (recommended).
- Click Save changes.