Use the Play Integrity API to detect risky interactions and fight abuse

You can use the Play Integrity API to protect your apps and games from risky interactions. By identifying these interactions, your app can respond appropriately to reduce the risk of attacks and abuse.

How it works

The Integrity API unifies Google Play anti-abuse features with a collection of integrity signals to help Android app and game developers detect potentially risky and fraudulent traffic. This traffic could come from modified versions of your app or game, untrustworthy devices, or other untrustworthy environments. By detecting this traffic, you can respond with appropriate action to reduce attacks and abuse such as fraud, cheating, and unauthorized access.

When a user performs an app or game-defined action, your server instructs the client-side code to invoke the Integrity API. The Google Play server returns an encrypted response with an integrity verdict about whether or not you can trust this device and its binary. Your app then forwards that response to your server for verification. Your server can decide what your app or game should do next. 

The API provides an integrity verdict in a response that includes the following information:

  • Application integrity: This tells you whether you’re interacting with your unmodified binary recognized by Google Play. 
  • Account details: This tells you whether the current user account is licensed, which means that the user acquired the app or game by installing or paying for it from Google Play.
  • Device integrity: This tells you whether your app is running on a genuine Android device with Google Play services. 

Tip: The Integrity API provides the most value for your app when you follow each of the recommended practices in the documentation on the Android Developers site.

Set up and manage the Play Integrity API

Enable the Integrity API for your app

Important: By accessing or using the Integrity API, you agree to the Play Integrity API Terms of Service.

To enable Integrity API responses for your app, you need to link a Google Cloud project in Play Console. To link your project:

  1. Open Play Console and go to the App integrity page (Release > Setup > App integrity).
  2. Click the Integrity API tab.
  3. Choose "Link existing project" and the project you want to link to, or "Create new project."
  4. Click Link project.

To start integrating the Integrity API into your app, you need to do the following:

  • For Java/Kotlin apps, install the latest available Android library for the Play Integrity API from Google’s Maven Repository.
  • For Unity games,  install the latest release of Google Play Plugins for Unity. All versions of 2019.x, 2020.x and newer are supported. If you use Unity 2018.x, install 2018.4 or newer. If you use Unity 2017.x, install 2017.4.40 or newer. Unity 5.x and older are not supported.
  • For Native apps and games, install the latest Play Core Native SDK.

Now you can follow these steps on the Android Developers site to start using the Play Integrity API in your app or game.

 

(Optional) Choose how your response encryption is managed

By default, Google manages your response encryption. However, you can choose to self-manage your response encryption if you prefer. 

Important: Switching your response encryption between managed by Google and self-managed requires code changes on your backend server.

To self-manage your response encryption:

  1. Open Play Console and go to the App integrity page (Release > Setup > App integrity).
  2. Click the Integrity API tab.
  3. Scroll to the "Settings" section.
  4. Next to "Response encryption," the status will be "Managed by Google" by default. Click Change.
  5. Choose "Manage and download my response encryption keys" and click Save changes. Google will generate response encryption keys for you to download and manage. You must update your backend server logic to use the keys to decrypt responses.
  6. Follow the on-screen instruction to generate a .pem file and upload the .pem file to download your API keys.
  7. An on-screen message will confirm that your response encryption management has been updated.
  8. Download your new response encryption keys and update your backend server to decrypt responses with them in production. Return to the Integrity API tab on the App Integrity page to enable Google Play to start using the new response encryption keys instead of the legacy keys. This change is immediate.

If you want to revert from self-managed to Google-managed:

  1. Open Play Console and go to the App integrity page (Release > Setup > App integrity).
  2. Click the Integrity API tab.
  3. Scroll to the "Settings" section.
  4. Next to "Response encryption," the status will be "Self-managed" because you have changed it in the past. Click Change.
  5. Choose "Let Google manage my response encryption (recommended)" and click Save changes. Google will generate and manage your response encryption keys. Your backend server will call Google Play’s server to decrypt responses.

(Optional) Configure Integrity API responses 

The following API responses are configured by default:

API response Label 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.

No labels (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).

Account details LICENSED

The user has an app entitlement. In other words, the user installed or bought your app on Google Play.

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 necessary requirement was missed. This could happen for several reasons, including the following:

  • The device is not trustworthy enough.
  • 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.

 

You can also opt-in to receive the following API responses:

API response 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 keystore. The device passes system integrity checks and meets Android compatibility requirements.

 

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

To edit your API responses:

  1. Open Play Console and go to the App integrity page (Release > Setup > App integrity).
  2. Click the Integrity API tab.
  3. Scroll to the "Responses" section.
  4. Click Edit.
  5. Select or deselect the checkboxes next to the API responses you want to change.
  6. Click Save changes.

Important: The changes to API responses take effect immediately after you save them, including when your app is in production. Before you change the set of API responses in your Play Console, make sure your server is prepared to accept those responses.

Monitor your Play Integrity API usage and change tier

Apps are subject to a maximum number of requests per day to the API based on their app’s usage tier. Apps in the Standard tier can make up to 10,000 requests per day to the Integrity API.

To view your app’s usage tier:

  1. Open Play Console and go to the App integrity page (Release > Setup > App integrity).
  2. Click the Integrity API tab.
  3. Scroll to the "Settings" section.
  4. View your usage tier.

To view the volume of requests your app makes daily, view your linked Cloud project in the Google Cloud Console.

To exceed 10,000 requests per day, you can request to change your app’s usage tier to the Raised tier. To be eligible for the Raised tier you must:

  • Confirm correct implementation of API logic including retries.
  • Publish your app on Google Play in addition to any other distribution channels.

To change your app’s usage tier, complete this form.

Test your Play Integrity API integration

You can set up a list of Gmail accounts to test your Integrity API integration. First, make sure your testers have access to your release:

To set up a test:

  1. Open Play Console and go to the App integrity page (Release > Setup > App integrity).
  2. Click the Integrity API tab.
  3. Scroll to the "Testing" section.
  4. Click Create new test.
  5. Select an email list or create a new one.
  6. Click Create test.

Set up device exclusion on Google Play

You can exclude devices from your app’s distribution on Google Play based on their Integrity API response to the Play Store. Excluded devices won’t be able to see or install your app on Google Play. Device exclusion does not prevent users from obtaining your app another way such as through another distribution channel or via sideloading.

Important: Device exclusion uses an Integrity API response received by the Play Store app, it is unrelated to the response received by your app once you’ve integrated the API. 

You have three Integrity API device exclusion options:

  • Don’t exclude: Doesn’t exclude any devices based on Integrity API.
  • Exclude only basic failures: Excludes untrustworthy devices that don’t meet basic integrity.
  • Exclude all device failures: Excludes untrustworthy devices that don’t meet device integrity.

Tip: You can find definitions for basic integrity and device integrity in the Play Integrity API documentation on the Android Developers site.

Here's how you change the device exclusion setting in Play Console:

  1. Open Play Console and go to the App integrity page (Release > Setup > App integrity).
  2. Click the Integrity API tab.
  3. Next to "Device exclusion," choose whether or not you want to exclude devices from your app’s distribution based on their Integrity API response. Excluded devices won’t be able to see or install your app on Google Play.
  4. Save your changes.

Important: This automatically updates your device catalog exclusion rules.

Related content

Was this helpful?
How can we improve it?

Need more help?

Sign in for additional support options to quickly solve your issue

Search
Clear search
Close search
Google apps
Main menu
Search Help Center
false
false
true
92637
false
false