Add Play Integrity API

The Play Integrity API for PC helps you check that interactions and server requests are coming from a genuine PC device. By detecting potentially risky and fraudulent interactions, your app's backend server can respond with appropriate actions to prevent attacks and reduce abuse.

The API returns verdicts that help you detect potential threats, including:

• Risky devices and environments: The deviceIntegrity verdict helps you determine whether your app is running on a genuine PC device or a genuine instance of Google Play Games for PC.

Integrate with the API

To integrate the Play Integrity API for PC into your app, you need to first do the initial setup in Google Cloud Console. After that, you need to follow the following steps for each integrity check:

1. Prepare your integrity token
2. Request your integrity token
3. Request token data

Initial Setup in Google Cloud Console

Every app or SDK calling the Play Integrity API needs to make use of a Google Cloud project to authenticate their calls and monitor their API usage. 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.

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

Step 1: Prepare your integrity token

void PrepareIntegrityToken(
  const PrepareIntegrityTokenParams & params,
  PrepareIntegrityTokenContinuation continuation
)

Before requesting an integrity token (see RequestIntegrityToken), you must prepare (or "warm up") the Play Integrity API. This allows Google Play to intelligently cache partial attestation information on the device in order to decrease the latency on the critical path when you make a request for an integrity verdict.

On success, the continuation will be called with a PrepareIntegrityTokenResultValue containing a RequestTokenData that should be used to request an integrity token. This data should be cached in-memory and reused for the duration of the application's session for calls to RequestIntegrityToken. Only if your application determines that it is necessary to entirely re-evaluate the integrity verdict should a call to PrepareIntegrityToken be made.

Step 2: Request your integrity token

void RequestIntegrityToken(
  const RequestIntegrityTokenParams & params,
  RequestIntegrityTokenContinuation continuation
)

Integrity tokens are a mechanism for your application to verify the device is not tampered with. For example, your backend server can use the integrity token to verify:

• Genuine device: Determine whether your application is running on a genuine device that contains a genuine instance of Google Play Games for PC and not tampered with.

When you're checking a user action in your app with the Play Integrity API for PC, you can use the RequestIntegrityTokenParams::request_hash field to mitigate against tampering attacks. For example, a game may want to report the player's score to the game's backend server, and your server wants to verify this score has not been tampered with by a proxy server. The Play Integrity API returns the value you set in this field, inside the signed integrity response. Without the requestHash, the integrity token will be bound only to the device, but not to the specific request, which opens up the possibility of attack.

To mitigate this when you request an integrity verdict:

• Compute a digest of all relevant request parameters (e.g. SHA256 of a stable request serialization) from the user action or server request that is happening.
• Set the RequestIntegrityTokenParams::request_hash field to the digest.

Step 3: Request token data

After you request an integrity verdict, the Play Integrity API provides an encrypted response token. To obtain the device integrity verdicts, you must decrypt the integrity token on Google's servers. To do so, complete these steps:

1. Create a service account within the Google Cloud project that's linked to your app.

2. On your app's server, fetch the access token from your service account credentials using the playintegrity scope, and make the following request:

   playintegrity.googleapis.com/v1/<var>PACKAGE_NAME</var>:decodePcIntegrityToken -d \
    '{ "integrity_token": "<var>INTEGRITY_TOKEN</var>" }'
   

3. Read the JSON response.

The resulting payload is a plain-text token that contains integrity verdicts and details alongside developer-provided information. The token format is as follows:

{
  "requestDetails": { ... },
  "deviceIntegrity": { ... },
}

You must first check that the values in the requestDetails field match those of the original request before checking each integrity verdict. The following sections describe each field in more detail.

Request details field

The requestDetails field contains information about the request, including developer-provided information in the requestHash for standard requests and the nonce for classic requests.

"requestDetails": {
  // Application package name this attestation was requested for.
  // Note that this field might be spoofed in the middle of the request.
  "requestPackageName": "com.package.name",
  // The timestamp when the integrity token was requested.
  "requestTime": "1675655009345"
  // Request hash provided by the developer.
  "requestHash": "aGVsbG8gd29scmQgdGhlcmU",
}

These values should match those of the original request. Therefore, verify the requestDetails part of the JSON payload by making sure that the requestPackageName and requestHash match what was sent in the original request.

Device integrity field

The deviceIntegrity field can contain a single value, deviceRecognitionVerdict, that has one or more labels representing how well a device can enforce app integrity. If a device does not meet the criteria of any labels, then the deviceIntegrity field omits deviceRecognitionVerdict.

"deviceIntegrity": {
  "deviceRecognitionVerdict": ["MEETS_PC_INTEGRITY"]
}

By default, deviceRecognitionVerdict can contain the following:

MEETS_PC_INTEGRITY

Returns a verdict if the app is running on a genuine PC environment, where no on-device tampering was detected.

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

Usage Limits

Play Integrity API Usage Limits

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 with the following instructions if your app needs to handle an increased number of users.

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.

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

Quota increases are automatically applied to both the client call to generate integrity tokens and the server call to decrypt and verify integrity tokens.

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.

Request an integrity verdict at an appropriate moment

You should make API requests as close as possible to the time of the action or server request that you want to defend.

Make your API requests hard to replicate

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.

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.

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.

Show actionable error messages

When possible, provide useful error messages to the user and let them know what they can do to fix it.

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.

Terms of service and data safety

By accessing or using the Play Integrity API for PC, you agree to the Play Integrity API Terms of Service. 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.