Detect repeat abuse using device recall (beta)

This page describes how to use device recall to store and retrieve custom data with specific devices. You can reliably recall the custom data again later when your app is installed on the same device, even after the device is reset. This lets you detect and prevent a device from being re-used based on an action or behavior that you specify, while preserving user privacy.

How does device recall work?

Device recall gives apps the ability to store and recall custom data associated with a specific device in a way that preserves user privacy. The data is stored on Google's servers, allowing your app to reliably recall your custom data even after your app is reinstalled or the device is reset. For example, you could use the feature to recall devices where you found evidence of severe abuse, devices that already redeemed high-value items (such as a free trial), or devices that are being used repeatedly to create new accounts for abusive purposes. Device recall preserves user privacy because the requesting app can only recall the limited data that it associated with devices, without accessing any device or user identifiers. After you turn on device recall, you can do the following:

  • Read per-device data: You can read three custom values or bits for each device when you obtain an integrity verdict. You can define your own meaning to these values; for example, you can treat the values as three separate flags or you could combine them to represent eight custom labels.
  • Modify per-device data: After you obtain an integrity token, you can use that token to make a server-side call to Google Play's server to modify one or more of the values. You have up to 14 days to use the token. This lets you modify a value if, for example, abuse only becomes evident in the two week period after you first perform an integrity check. When you modify a value, the month and year when the modification was made is also stored.

Device recall prerequisites and considerations

Device recall may only be used to store and recall information to protect app security and to mitigate abuse, fraud, and unauthorized access. You may not use device recall to fingerprint or track individual users or devices and you may not use device recall to keep track of sensitive user or device characteristics like gender, age, or location data.

Device recall has the following prerequisites:

  • Device recall can be used on phones, tablets, foldables, TV, Auto, and Wear OS. On Wear, device recall is only available on devices that ship with Wear OS 5 or higher. Device recall is not supported on emulators.
  • Device recall requires recent versions of both Google Play Store and Google Play services to be installed and enabled on the device.
  • Device recall requires the user account to be Play licensed, otherwise the verdict will be unevaluated.

Device recall has the following timing considerations:

  • After you verify an integrity token, you have up to 14 days to use it to store custom device recall data.
  • Device recall includes timestamps so that you can consider recently modified data as higher priority than data that was modified a long time ago. Consider ignoring or resetting the data after a long enough time period to take into account that devices can change hands or be refurbished and resold.
  • The recall bits for a device will be stored for 3 years after the last read or write access.
  • If you need to delete all data associated with a device, your app can reset all three values on that device to false. This will automatically reset the time stamps.

For developers with multiple apps and developers transferring apps, device recall works as follows:

  • All the apps in your Google Play developer account have access to the same three values per device. In other words, if one of your apps modifies one of the values, then all of your apps will read the modified value when they're installed on the same device.
  • If an app is transferred from one developer account to another, device recall will reflect the new developer account's per-device data, not the old developer account's per-device data.

Turn on device recall

When you are ready, turn on device recall in the Play Console:

  1. Sign in to the Play Console.
  2. Select the app that will use device recall.
  3. In the Release section of the left menu, go to App integrity.
  4. Next to Play Integrity API, click Settings.
  5. In the Responses section of the page, click Change responses.
  6. Turn Device recall on.
  7. Click Save changes.

When you turn on or off device recall, any Play Integrity API test responses that you've set up in the Play Console will be deleted and you will need to create them again.

Read device recall values

Device recall works in both Play Integrity API classic and standard requests. In standard requests, device recall is refreshed in the warmup call. In other words, after you modify per-device data, you will need to perform another warm up to see the updated value. Once device recall is enabled, you will be able to read device recall values in your integrity verdicts.

Modify device recall values

You can modify device recall values by making a server-to-server API call similar to decoding the integrity verdict. Setting a bit to true will also update its write date (even if it was already true). Setting a bit to false will reset its write date to empty. Any bits that are unspecified in a request will remain unchanged. There is a small propagation delay between writing bits and being able to read them back in the verdict. This delay can be as long as 30 seconds, though it is generally much shorter. Device recall write requests should be less frequent than your integrity token requests. They are not counted in your integrity token request quota but are subject to non-public, defensive rate limits.

playintegrity.googleapis.com/v1/PACKAGE_NAME/deviceRecall:write -d \
'{
  "integrityToken": "INTEGRITY_TOKEN",
  "newValues": {
    "bitFirst": true,
    "bitThird": false
  }
}'
Previous
About integrity verdicts
Next
Handle error codes