| **Warning:** This document is confidential and access is governed by your non-disclosure agreement with Google.
| **Note:** The features described on this page are only available to select Play partners.

## What is automatic protection?

Automatic integrity protection is a service from Google Play that protects your
apps and games against modification and unauthorized redistribution. If users
get your protected app from an unknown source, they'll be prompted to get it or
buy it from Google Play to receive ongoing updates.

When you turn on automatic integrity protection, Google Play adds runtime checks
to your app's code to prevent modification and redistribution, and then makes
those checks hard to remove with advanced anti-tamper protection. Based on
Google internal analysis, apps using Play integrity features see on average \~80%
lower unauthorized usage compared to unprotected apps.

## New: Customizable anti-tamper protection

We're evaluating a new feature that will enhance the protection of a
developer-selected set of Java and Kotlin methods. You will be able to identify
specific methods that you want to protect in your release and, when the release
is uploaded to Play, Play will prioritize enhanced protection for those methods.

By identifying methods for protection using our recommended practices, you can
get the dual benefit of more resilient protection and better control over the
performance impact of protections.

## Setup guide

This guide will take you through using customizable anti-tamper protection in
your app.

### Step 1: Add the automatic protection interface to your codebase

Add the following interface to your app or game.
**Note:** We intend to provide this interface through a Google Play supported Maven library in the future. Provide feedback and let us know what other improvements you would like to see.  

### Kotlin

```kotlin
package com.google.android.play.protections.annotations

/**
 * Describes that a method is a candidate for enhanced protection.
 *
 * <p>This annotation will be removed automatically from the dex code of your
 * bundle at the time when Google Play protects your bundle. Only use it as
 * a method level annotation. Any other usage (e.g. accessing the class
 * reflectively at runtime) is unsupported.
 */
@Retention(AnnotationRetention.RUNTIME)
@Target(AnnotationTarget.FUNCTION)
public annotation class PlayAutomaticIntegrityProtection() {}
```

### Java

```java
package com.google.android.play.protections.annotations;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Describes that a method is a candidate for enhanced protection.
 *
 * <p>This annotation will be removed automatically from the dex code of your
 * bundle at the time when Google Play protects your bundle. Only use it as
 * a method level annotation. Any other usage (e.g. accessing the class
 * reflectively at runtime) is unsupported.
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface PlayAutomaticIntegrityProtection {}
```

When using additional tooling to optimize your app it is important to configure
it in such a way that the annotation is not lost in that process. For example,
if you use a tool like ProGuard, you'd need a configuration file like the
following:  

    # Keep the annotation class and its members.
    -keep class com.google.android.play.protections.annotations.PlayAutomaticIntegrityProtection* { *; }

    # By default, ProGuard treats annotation attributes as optional, and removes
    # them in the obfuscation step. This rule will ensure they are kept.
    -keepattributes RuntimeVisibleAnnotations, AnnotationDefault

    # Keep any methods with the annotation, but allow them to be obfuscated.
    -keepclassmembers,allowobfuscation class * {
        @com.google.android.play.protections.annotations.PlayAutomaticIntegrityProtection *;
    }

### Step 2: Annotating methods for custom protection

Once you have the interface included in your app or game, you can add
protection to a method by annotating it:  

### Kotlin

```kotlin
import com.google.android.play.protections.annotations.PlayAutomaticIntegrityProtection

@PlayAutomaticIntegrityProtection()
fun myMethod() {
  ...
}
```

### Java

```java
import com.google.android.play.protections.annotations.PlayAutomaticIntegrityProtection;

@PlayAutomaticIntegrityProtection()
public void myMethod() {
  ...
}
```

In order to select the method or methods that will benefit from enhanced protection,
there are a few recommendations to follow. As a general criteria to not impact
your app or game performance, select **cold methods** rather than
**hot methods**.

For maximizing protections, select methods that:

- Are **critical** to the application. If these were removed the application would no longer function correctly.
- Are **not** executed in the **main/UI thread**.
- Run **more than once**, during the lifetime of the app, but don't run in a hot loop.
- Are **non-trivial**. Prefer methods containing more than 5 lines. Getters, setters, and constructors shouldn't be selected.
- Are **not** executed during **startup**, if possible.
- Are **newly introduced** or heavily refactored in the release.
- Are **not** abstract or interface methods.

A better selection of methods, will lead to stronger overall protection. If
each new release has a newly protected method, that version of the app or game
will be more resilient to attacks.

### Step 3: Testing

Once you have protected your app or game through the Play Console, it's
important that you test it thoroughly. In particular, ensure that the annotated
methods for enhanced protection are invoked during your testing so that you can
better assess any potential impact on the performance.

### Removing custom protection

If you no longer want to protect a specific method, you can remove the
`@PlayAutomaticIntegrityProtection()` annotation.

We do not recommend turning off the protection once your protected artifact has
been published to an
open track, since this could facilitate diff-based attacks.
When you're testing different artifacts with custom method protections turned on and
off, we recommend you do this in your internal testing track.

## Support and feedback

We would appreciate your feedback on this feature. You can contact your Google
Play partner manager anytime, you can use the
[integrity support form](https://support.google.com/googleplay/android-developer/contact/app_integrity), and you can also use the
[new issue tracker](https://issuetracker.google.com/issues/new?component=1434565) for automatic integrity protection.
Issues that you create will only be visible to you and to Google.