Play Integrity API Explained

Fraudsters automate sign-ups, farm promotions, scrape APIs and abuse paid features using modified apps or emulators. Client-side checks are easy to bypass. The Play Integrity API moves the decision to your server, using signed verdicts from Google Play.

How it works

The verdicts

Client code (standard request)

class IntegrityClient(context: Context, private val cloudProjectNumber: Long) {
    private val manager = IntegrityManagerFactory.createStandard(context)
    private var provider: StandardIntegrityManager.StandardIntegrityTokenProvider? = null

    /** Call early (e.g. app start); preparation can take a few seconds. */
    suspend fun warmUp() {
        provider = manager.prepareIntegrityToken(
            StandardIntegrityManager.PrepareIntegrityTokenRequest.builder()
                .setCloudProjectNumber(cloudProjectNumber)
                .build()
        ).await()
    }

    /** requestHash binds the token to THIS action (e.g. SHA-256 of "redeem:$couponCode:$userId"). */
    suspend fun token(requestHash: String): String {
        val p = provider ?: run { warmUp(); provider!! }
        return p.request(
            StandardIntegrityManager.StandardIntegrityTokenRequest.builder()
                .setRequestHash(requestHash)
                .build()
        ).await().token()
    }
}

Server-side verification

1. Receive the token with the action payload.
2. Call Google's decodeIntegrityToken API using service-account credentials (server only).
3. Check that package name and request hash match this exact action, and that the timestamp is recent.
4. Evaluate the app, device and account verdicts against your risk policy.
5. Decide: allow, require step-up (OTP, CAPTCHA, review), rate-limit, or deny.

Designing a fair response policy

• Tier by risk: require integrity for redeeming money or high-value promotions, not for reading articles.
• Don't hard-block too eagerly: some legitimate users have older or uncertified devices. Prefer step-up or limited functionality.
• Handle API errors gracefully: network issues or outdated Play services shouldn't lock users out. Retry or fall back to other checks.
• Monitor verdict distributions to tune your thresholds.

With Firebase

If your backend is Firebase (Firestore, Functions, AI Logic), App Check with the Play Integrity provider applies integrity checks to Firebase requests for you. See Gemini API Integration for an example.

Use cases

Common mistakes

• Decoding or evaluating the verdict on the device.
• Not binding tokens to the request (missing request hash), which enables replay.
• Calling the API on every request. Use it for sensitive actions, within quota.
• Blocking all users on API errors.

Frequently asked questions

Conclusion

Play Integrity gives your server trustworthy signals about the app, device and account behind a request. Bind tokens to actions with request hashes, verify server-side, apply a graduated risk policy, and handle errors without punishing legitimate users.

Next step: review the threats it helps with in Common Android Security Vulnerabilities.