📚 课程目录第3章环境搭建与SDK引入

环境搭建与SDK引入：Android Studio配置、Gradle依赖声明、minSdkVersion要求、ProGuard规则调整

3.1 原理概述

Play Integrity API 是 Google 提供的设备端与服务器端联合验证服务，集成该 API 前必须正确配置 Android 项目的构建环境。核心依赖包含在 Google Play Services 的 play-services-integrity 模块中，该模块通过 Gradle 自动解析，并在运行时与 Google Play 服务框架通信。环境搭建的完整性直接影响后续 API 调用成功率、混淆后方法可访问性及最低兼容设备范围。

  关键前提：项目必须绑定并发布到 Google Play 管理中心，使用与发布证书匹配的 SHA-1 指纹注册应用。

3.2 环境搭建流程

确认 Android Studio 版本：推荐使用 Android Studio Hedgehog（2023.1.1）或更高版本，确保 Gradle 插件版本 ≥ 8.2。
创建或打开项目：最小目标 API 等级将限制依赖范围，需提前规划。
添加 Google Maven 仓库：在项目级 build.gradle 的 repositories 块中声明 google()。
声明依赖：在模块级 build.gradle 的 dependencies 块中引入 play-services-integrity。
设置 minSdkVersion：Play Integrity SDK 要求最低 API 级别为 19（Android 4.4），但建议 ≥ 23 以获取更完整的 Google Play 服务支持。
配置 ProGuard 规则：保留 API 类及回调接口，防止混淆移除。
同步项目：Gradle Sync 完成后检查依赖树验证版本。

版本锁定建议：显式指定 play-services-integrity:19.0.0 或更高版本，避免依赖传递导致的不兼容。

3.3 Gradle 依赖声明

模块级 build.gradle 中必须包含以下配置片段：

android {
    compileSdk 34
    defaultConfig {
        minSdkVersion 23
        targetSdkVersion 34
    }
}

dependencies {
    implementation 'com.google.android.gms:play-services-integrity:19.0.0'
}

若项目使用 Kotlin DSL（build.gradle.kts），等效声明为：

dependencies {
    implementation("com.google.android.gms:play-services-integrity:19.0.0")
}

3.4 minSdkVersion 要求与影响

minSdkVersion	Play Integrity 支持	推荐场景
19 – 22	有限支持（r1 旧版 API）	需兼容老旧设备，但无法使用标准 Integrity
23 – 30	完整支持	多数应用首选，享受完整验证能力
31+	完整支持 + 增强回退	新应用推荐，可获取更高安全等级

注意：若 minSdkVersion < 23，Google Play 服务框架可能脱机或版本过旧，导致 IntegrityService 连接失败。建议至少提升至 23。

3.5 ProGuard 规则调整

Play Integrity SDK 使用内部匿名类和回调，混淆后若不保留对应规则，运行时将抛出 ClassNotFoundException 或 MethodNotFoundException。在 proguard-rules.pro 中添加：

-keep class com.google.android.gms.integrity.** { *; }
-keepclassmembers class * implements com.google.android.gms.integrity.IntegrityService$IntegrityCallback {
    public void onIntegrityTokenResponse(com.google.android.gms.integrity.IntegrityTokenResponse);
    public void onIntegrityTokenError(com.google.android.gms.integrity.IntegrityErrorCode);
}
-keep class * extends com.google.android.gms.integrity.IntegrityService$IntegrityCallback { *; }

若使用 R8 全量模式（android.enableR8.fullMode=true），上述规则仍需保留，且需额外避免收缩：

-keep,allowshrinking class com.google.android.gms.integrity.**

3.6 调试与验证

Gradle 依赖树：运行 ./gradlew :app:dependencies --configuration releaseRuntimeClasspath 确认 play-services-integrity 版本正确。
测试 API 可用性：在 Application.onCreate() 中尝试获取 IntegrityService 实例，若无异常则环境就绪。
ProGuard 映射：构建 Release APK 后检查 build/outputs/mapping/release/mapping.txt，确认 Integrity 相关类未被混淆。

3.7 常见错误与解决方案

错误现象	根因	修复
Gradle Sync 失败：`Could not resolve com.google.android.gms:play-services-integrity:19.0.0`	未添加 Google Maven 仓库	在 project-level `build.gradle` 中添加 `google()` 并排在 `mavenCentral()` 之前
运行时 `IntegrityService API not available`	设备 Google Play 服务版本过旧或未安装	检查设备 Google Play 服务 ≥ 23.0.0；使用 `GooglePlayServicesUtil.isGooglePlayServicesAvailable()` 提示用户更新
混淆后 `NoSuchMethodError` 异常	ProGuard 规则遗漏或错误	确认规则中保留了 `IntegrityCallback` 接口及其所有方法

3.8 性能与稳定性优化

延迟初始化：将 IntegrityService 的获取推迟到首次需要验证时，避免冷启动阻塞。
依赖版本固定：使用 implementation 'com.google.android.gms:play-services-integrity:19.0.0' 而非 play-services-integrity:+，防止不可预期的版本升级。
多变体处理：Debug 与 Release 变体可使用不同 ProGuard 规则，确保测试时不会被混淆干扰调试。

3.9 扩展：多 Build Variant 配置

若项目存在多个风味（如 demo 与 full），可将 ProGuard 规则按变体拆分：

android {
    buildTypes {
        release {
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'),
                         'proguard-rules-release.pro'
        }
        debug {
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'),
                         'proguard-rules-debug.pro'
        }
    }
}

Debug 变体可跳过混淆，降低调试门槛；Release 变体必须严格保留 Integrity 相关类。

3.10 后期部署检查清单

✅ build.gradle 中 play-services-integrity 版本与 Google Play Service 版本匹配。
✅ minSdkVersion ≥ 23，并在 AndroidManifest.xml 中无冲突覆盖。
✅ ProGuard 规则已合并到最终混淆配置中，可通过 mapping.txt 二次确认。
✅ 在真实设备（非模拟器）上运行一次集成测试，验证 IntegrityService 可用。