Google Play Integrity

🔐 Overview

What is Google Play Integrity and why it matters for internal applications

Google Play Integrity API helps you check that the interactions with your app are coming from your unmodified and official binary. This protects both you and your users from:

Piracy & Clones: Unauthorized copies of your app
Tampering: Modified versions of your app with malicious code
Device Attacks: Emulators, rooted devices, and other compromised environments
API Abuse: Automated scripts and bots abusing your backend

Supported Applications

Sarathi - com.rptpl.roadpilot
Fleet - com.rptpl.owner
Dhaba - com.rptpl.roadpilotdhaba
Mech - com.rptpl.roadpilotmech

⚙️ How It Works

The verification flow from app to server

// Step 1: App requests integrity token from Play Integrity API

App sends: app_id + hashing

↓

// Step 2: Play Integrity returns signed token

Token contains: app_recognition_verdict + device_integrity + account_details

↓

// Step 3: App sends token to your server

Request includes: metadata + integrity_token

↓

// Step 4: Server verifies token with Google

Server decrypts and validates token signature

↓

// Step 5: Server processes request if valid

Response: { success: true, data: {...} }

✓ App Recognition

Validates the app is from Google Play and matches your package name

✓ Device Integrity

Checks device hasn't been tampered with or rooted

✓ Account Details

Verifies the user's Google Account is linked correctly

🚀 Integration Setup

Step-by-step guide to integrate Play Integrity into your apps

Step 1: Google Cloud Setup

Go to Google Cloud Console
Create a new project (e.g., "sarathi-production") for each app
Enable the Play Integrity API
Create a service account with "Play Integrity API Verifier" role
Download the JSON key file
Upload to server: storage/google-credentials/sarathi-production.json

Step 2: Android Integration

                        
// build.gradle (app level)
dependencies {
    implementation 'com.google.android.play:integrity:1.1.0'
}

// Kotlin code
val integrityManager = IntegrityManagerFactory.create(applicationContext)
val tokenTask = integrityManager.requestIntegrityToken(IntegrityTokenRequest.builder()
    .build())
                        
                    

Step 3: Send Token to Your API

                        
tokenTask.addOnSuccessListener { token ->
    // Make API request with the token
    val metadata = JSONObject()
        .put("app_name", "sarathi")
        .put("integrity_token", token.token())

    // Call your API endpoint
}
                        
                    

Step 4: Server Configuration

Update .env.production with your project IDs:

                            
SARATHI_PROD_PROJECT_ID=your-project-id-here
FLEET_PROD_PROJECT_ID=your-project-id-here
DHABA_PROD_PROJECT_ID=your-project-id-here
MECH_PROD_PROJECT_ID=your-project-id-here
GOOGLE_PLAY_INTEGRITY_ENABLED=true
                            
                        

⚠️ Response Verdicts

Understanding the verdict values and what they mean

📱 App Recognition Verdicts

`PLAY_RECOGNIZED`	✓ Downloaded/installed from Google Play
`UNRECOGNIZED_VERSION`	⚠️ Legitimate but unrecognized version
`UNEVALUATED`	⚠️ Not enough data to evaluate
`FAKE`	✗ Unauthorized or modified app

🔧 Device Integrity Verdicts

`MEETS_STRONG_INTEGRITY`	✓ Certified Android device with Google Play Services
`MEETS_BASIC_INTEGRITY`	✓ Legitimate device (may be rooted/emulator)
`UNEVALUATED`	✗ Device integrity cannot be verified

ℹ️ Note: Our system accepts both MEETS_STRONG_INTEGRITY and MEETS_BASIC_INTEGRITY for legitimate use cases, while blocking UNEVALUATED and FAKE verdicts in production.

🌍 Environment Settings

How Play Integrity is configured across environments

Production

• Integrity: REQUIRED
• Strict enforcement
• Blocks all fake apps
• Logs all failures

Staging

• Integrity: OPTIONAL
• Logs warnings only
• Allows testing
• Development friendly

Local

• Integrity: DISABLED
• No checks
• Full access
• Development mode

🔧 Error Handling

Common errors and how to handle them

❌ Token Not Provided

Error: "Google Play Integrity token is required"

Solution: Ensure your Android app is properly requesting and sending the integrity token.

❌ Token Expired

Error: "Failed integrity verification - token too old"

Solution: Tokens expire after 5 minutes. Request a fresh token for each API call.

❌ Invalid Token

Error: "Invalid or expired integrity token"

Solution: Token signature validation failed. Ensure token hasn't been tampered with.

⚠️ Configuration Error

Error: "Google Play Integrity service not configured"

Solution: Check that service account files exist in storage/google-credentials/ for the app.

🧪 Testing

How to test Play Integrity integration

Testing in Staging

In staging environment, integrity checks are optional. You can test your integration without valid tokens to ensure other functionality works.

Test License Testing

Google Play Console allows you to add test accounts that bypass normal integrity checks for development purposes.

Production Testing

For production testing, use real devices and Google Play-signed APKs. ADB installs may fail integrity checks.

🛠️ Troubleshooting

Common issues and solutions

❓ Why are legitimate users being blocked?

Check if users are using sideloaded APKs, modified versions, or testing on emulators. Legitimate Play Store installs should pass.

❓ How do I debug which specific check failed?

Check server logs for detailed verdict information. Each failed token includes the reason (app_recognition_verdict, device_integrity_verdict).

❓ Can I allow specific rooted devices?

For production security, we block UNEVALUATED verdicts. If you need to allow rooted devices for testing, use the staging environment.

❓ What happens if Google Play Integrity API is down?

Our system treats API failures as verification failures. In staging, requests will still be allowed with a logged warning.