Overview of the Play Integrity API

The Play Integrity API helps you check that interactions and server requests are coming from your genuine app binary running on a genuine Android device. By detecting potentially risky and fraudulent interactions, such as from tampered app versions and untrustworthy environments, your app’s backend server can respond with appropriate actions to prevent attacks and reduce abuse.

When your app or game is used on an Android device with the Google Play Store and powered by Google Play services, the Play Integrity API provides a response that helps you determine whether you're interacting with the following:

  • 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: Determine whether your app is running on a genuine Android device powered by Google Play services (or a genuine instance of Google Play Games for PC).

You can also choose to receive information about the environment in your Play Integrity API response, including:

  • Risk of app access: Determine whether apps are running that could be used to capture the screen, display overlays, or control the device.
  • Risk from known malware: Determine whether Google Play Protect is turned on and whether it has found risky or dangerous apps installed on the device.

Overview

When a user performs an action in your app, you can call the Play Integrity API to check that it happened in your genuine app binary, installed by Google Play, running on a genuine Android device. You can also opt-in to additional information in the response including the volume of requests a device had made recently and signals about the environment, including the app access risk verdict and the Play Protect verdict. If anything is wrong with the verdicts, then your app's backend server can decide what to do to defend against problems like abuse and fraud, misuse and cheating, unauthorized access, and attacks.

Play Integrity API Overview
flow

Security considerations

Play Integrity API 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. By default, your app can make up to 10,000 total requests per day across all installs. You can request to increase your daily maximum.

Gather telemetry and understand your audience before taking action

Before you change how your app behaves based on Play Integrity API verdicts, you can understand the current situation with your existing audience by implementing the API without enforcement. Once you know what verdicts your current install base is returning, you can estimate the impact of any enforcement you're planning and adjust your anti-abuse strategy accordingly.

Decide how you'll request integrity verdicts

Play Integrity API offers two options for requesting and receiving integrity verdicts. Whether you make standard requests, classic requests, or a combination of both types of request, the integrity verdict response will be returned in the same format.

Standard API requests are suitable for any app or game and can be made on demand to check that any user action or server request is genuine. Standard requests have the lowest latency (a few hundred milliseconds on average) and a high reliability of obtaining a usable verdict. Standard requests make use of smart on-device caching while delegating protection against certain types of attack to Google Play.

Classic API requests, the original way to request integrity verdicts, also continue to be available. Classic requests have higher latency (a few seconds on average) and you are responsible for mitigating the risk of certain types of attacks. Classic requests use more of the user's data and battery than standard requests because they initiate a fresh assessment and so they should be made infrequently as a one-off to check whether a highly sensitive or valuable action is genuine. If you are considering making a classic request and caching it to use later, then you should make a standard request instead to reduce the risk of attacks.

The following table highlights some key differences between the two types of requests:

Standard API request Classic API request
Minimum Android SDK version required Android 5.0 (API level 21) or higher Android 4.4 (API level 19) or higher
API warm up required ✔️ (a few seconds)
Typical request latency A few hundred milliseconds A few seconds
Potential request frequency Frequent (on-demand check for any action or request) Infrequent (one-off check for highest value actions or most sensitive requests)
Mitigate against replay and similar attacks Automatic mitigation by Google Play Use nonce field with server side logic

You can see a table with more differences in the classic request considerations.

Request an integrity verdict at an appropriate moment

You should request an app access risk verdict as close as possible to the time of the action or server request that you want to defend against being accessed, to prevent scammers from working around the integrity check performed by your app.

Make your API requests hard to replicate

Standard API requests have a field called requestHash that is used to protect against tampering and similar attacks. In this field, you should include a digest of all relevant values from your app's request. Follow the guidance on how to use content binding to protect your app's standard requests.

Classic API requests have a field called nonce (short for number once), that is used to protect against certain types of attacks, such as replay and tampering attacks. Follow the guidance on how to generate nonces to protect your app's classic requests.

Avoid caching integrity verdicts

Caching integrity verdicts increases the risk of proxying, which is an attack where a bad actor reuses a verdict from a good device for abusive purposes in another environment. Instead of caching responses, you can make a standard API request to get a verdict on demand.

Have a tiered enforcement strategy

The Play Integrity API's integrity verdict has a range of possible responses making it possible to build an anti-abuse strategy with multiple tiers of enforcement. You can do this by configuring your app's backend server to behave differently depending on each possible response or group of responses.

It's also possible to tier your enforcement strategy based on device trustworthiness by opting in to receive additional device labels in your API response from the Play Console. Each device will return all the labels whose criteria it satisfies. For example, after opting in to receive all the device labels, you could choose to trust a device that returns MEETS_STRONG_INTEGRITY, MEETS_DEVICE_INTEGRITY, and MEETS_BASIC_INTEGRITY more than a device that only returns MEETS_BASIC_INTEGRITY. You can respond differently from the server in each scenario.

Send a range of responses from your server to your app

Having a range of decision outcomes is harder to replicate than sending a binary Allow/Deny response from the server back to the app for each response. For example, you could use a series of related responses such as Allow, Allow with limits, Allow with limits after CAPTCHA completion, and Deny.

Detect large-scale abuse using recent device activity

Use the recent device activity feature in the Play Integrity API to find devices requesting large numbers of integrity tokens. High-volume-activity abusers commonly generate valid attestation results from real devices and provide them to bots to automate attacks on rooted devices and emulators. You can use the recent device activity level to check how many attestations were generated by your app on that device in the last hour.

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 that 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 should plan in advance how you want your backend server to function in the unlikely event of a large-scale Play Integrity API outage.

Consider end to end enterprise fraud solutions

Enterprise customers looking for a complete fraud and bot management solution can purchase reCAPTCHA Enterprise for mobile, which includes SDKs for Android that provide fraud risk scores to developers. reCAPTCHA Enterprise automatically includes Play Integrity API signals, and combines them with reCAPTCHA network and application signals for customers, providing a frictionless, invisible fraud management solution out of the box. It can also provide protection for Android apps where Play Integrity API is not available.

Challenge risky traffic when accessing high value or sensitive features

Identify high value or sensitive actions in your app or game to protect with the Play Integrity API instead of denying access outright. When possible, challenge risky traffic before allowing high-value actions to proceed. For example, when the app access risk indicates that an app is running that could capture the screen, ask the user to disable or uninstall apps that can capture the screen before allowing them to proceed to functionality that you want to protect.

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 keep your users informed. To help you complete your data form, see this information on how the Play Integrity API handles data.