Android 设备完整性检测实战用 Play Integrity API Checker 快速验证设备安全状态【免费下载链接】play-integrity-checker-appGet info about your Device Integrity through the Play Intergrity API项目地址: https://gitcode.com/gh_mirrors/pl/play-integrity-checker-app每天都有大量应用在裸奔——没有完整性校验攻击者拿到一台 Root 过的手机就能随意伪造请求、篡改数据、作弊刷量。Play Integrity API Checker 是一款基于 Google Play Integrity API 的开源 Android 工具它把官方完整性验证封装成一个可直接运行的 App一键点击就能看到设备在基本完整性、设备完整性、强完整性和虚拟完整性四个维度上的真实判定并拿到服务器返回的原始 JSON 证据。这篇文章从零带你跑通它并讲清楚每一行关键逻辑背后的用意。一、这工具到底解决什么问题你可以把 Play Integrity API 想象成一张设备体检报告单Google 在云端核实这台手机是不是原厂系统、有没有被 Root、是不是跑在模拟器里然后把结论打包成一份带签名的 token。而 Play Integrity API Checker 就是那个体检科窗口——它负责发起检查、把 token 递交给配套的验证服务器最后把结论翻译成你能一眼看懂的通过/失败图标。对普通开发者来说最有价值的不是这个 App 本身而是它演示了一套完整的客户端接入范式nonce 生成、令牌请求、网络上报、JSON 解析、状态映射、错误码分流。想在自己的应用里接入 Play Integrity API 的人几乎可以把这份源码当模板用。二、五分钟跑起来环境要求与部署步骤动手之前先核对一下你的环境Android Studio较新版本即可JDK 17 或更高Android SDK最低支持 API 21覆盖绝大多数存量设备一台装有官方 Play Store 的真机部署分四步走跟着做就行第 1 步克隆仓库git clone https://gitcode.com/gh_mirrors/pl/play-integrity-checker-app cd play-integrity-checker-app第 2 步配置服务器地址在项目根目录创建local.properties写入你的后端地址API_URLhttps://your-server-url.com注意这个 App 本身不做令牌校验它把 token 通过 GET 请求发给你自建的 Play Integrity Checker Server/api/check?token...由服务器与 Google 交互并回传判定结果。所以你还得有一个配套的验证服务以及一个在 Play Console 里启用了 Play Integrity 的 Google Cloud 项目。第 3 步构建安装./gradlew assembleDebug把生成的 APK 装到手机点击主界面的 Check 按钮四盏状态灯就会亮起。第 4 步确认分发渠道这里有个容易踩的坑侧载安装的版本可能拿不到MEETS_BASIC_INTEGRITY和MEETS_STRONG_INTEGRITY两个判定必须通过 Play Store 正式分发并在 Play Console 里把对应的 integrity 等级开关打开。这也是项目 README 里专门用警告框标注的第一条注意事项。三、核心功能地图一眼看全功能点说明对应代码位置一键完整性检测点击按钮即发起完整验证流程MainActivity.java四等级结果展示基本/设备/强/虚拟完整性图标区分通过、失败、未知setIcons()方法原始 JSON 查看菜单栏可查看服务器返回的完整 JSON并一键复制dialog_response.xml布局错误码人性化20 余种IntegrityErrorCode映射为原因 解决建议getErrorReason()/getErrorSolution()关于与文档入口内置关于对话框、许可证列表、官方文档链接dialogs/目录深浅色主题适配支持夜间模式跟随系统主题values-night/themes.xml值得一提的是界面细节虚拟完整性在旧版 API 不可用时整组隐藏避免给用户展示无意义的状态结果图标用ic_pass/ic_fail/ic_unknown三种 drawable 区分语义清晰。四、实战拆解核心验证流程是怎么串起来的整个流程在MainActivity.java里是一条清晰的主线我们一段段看。4.1 随机数 nonce防重放的盐private String generateNonce() { int length 50; String nonce ; String allowed ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789; for (int i 0; i length; i) { nonce nonce.concat(String.valueOf(allowed.charAt( (int) Math.floor(Math.random() * allowed.length())))); } return nonce; }每次检测都生成一个全新的 50 位随机字符串作为 nonce它随 token 一起发给 Google。这样即使有人截获了历史 token也无法重放旧请求。Google 官方要求 nonce 至少 16 字节这里取了更宽松的 50 位属于宁多勿少的稳妥做法。4.2 令牌请求一句话触发官方 APIIntegrityManager integrityManager IntegrityManagerFactory.create(getApplicationContext()); TaskIntegrityTokenResponse task integrityManager.requestIntegrityToken( IntegrityTokenRequest.builder() .setNonce(nonce) .build()); task.addOnSuccessListener(response - sendTokenRequest(response.token()));拿到IntegrityTokenResponse后取出其中的 token 字符串交给下一步——网络上报。失败分支则区分IntegrityServiceException和其他异常前者走错误码翻译后者直接展示原始信息。4.3 服务器核对token 交给后端裁决Request request new Request.Builder() .get() .url(BuildConfig.API_URL /api/check?token token) .build(); client.newCall(request).enqueue(new Callback() { /* 异步回调 */ });这里用 OkHttp 异步请求不阻塞主线程。回调里先检查 HTTP 状态码再校验响应体是否为空最后把 JSON 字符串交给解析函数——每一层都做了防御性判断值得学习。4.4 结果映射把字符串变成红绿灯private Integer[] parseValues(String integrity) { return new Integer[]{ integrity.contains(MEETS_BASIC_INTEGRITY) ? 1 : 0, integrity.contains(MEETS_DEVICE_INTEGRITY) ? 1 : 0, integrity.contains(MEETS_STRONG_INTEGRITY) ? 1 : 0, integrity.contains(MEETS_VIRTUAL_INTEGRITY) ? 1 : -1 }; }服务器解包后的deviceRecognitionVerdict是一个包含若干个MEETS_*字段的字符串代码用contains逐一探测。四个维度分别映射为1 表示通过、0 表示未通过、-1 表示不可用只有虚拟完整性会出现 -1用于隐藏界面元素。五、三个典型应用场景代码之外的设计思考场景一金融类 App 的强校验如果你做的是银行、支付类应用安全底线通常是基础 设备 强三关全过才放行关键操作。参考项目里的parseValues思路你可以把判定收敛成一个布尔结果public boolean isHardenedEnvironment(Integer[] state) { return state[0] 1 state[1] 1 state[2] 1; }同时注意不要信任 App 端算出的结论。真正的裁决必须发生在你的服务器上客户端最多拿来做提示。场景二游戏防作弊游戏场景更关注模拟器和自动化工具。MEETS_VIRTUAL_INTEGRITY就是为此设计的——检测设备是否运行在虚拟化环境。项目里专门用Group控件在不支持时隐藏该行避免把未知误显示成失败这种对用户心智的保护很值得借鉴。场景三企业内部合规检查配合 MDM 或企业自建服务器可以做成周期性体检每次启动或登录时自动触发一次完整性请求把结果上报到管理后台形成设备安全台账。此时项目里的 JSON 查看 复制功能就派上用场了——方便调试和留档。六、避坑问答新手最容易卡住的五个点Q1为什么侧载安装后基本完整性和强完整性永远显示失败这是 Play Integrity 的分发策略决定的这两档判定只对通过 Play Store 安装且已关联 Google Cloud 项目的应用开放。侧载属于来路不明Google 直接给否定结论。解决方式就是走正式渠道分发。Q2API_NOT_AVAILABLE是什么情况设备上的 Google Play 服务版本过旧或不完整。解决办法是更新 Play Store 和 Play Services。项目把这类错误统一映射到建议更新的提示文案你可以照抄这套映射表。Q3TOO_MANY_REQUESTS频繁出现调用太频繁被限流了。官方按应用维度做配额实测时不要疯狂连点加个节流或冷却期。Q4为什么项目警告生产环境别这么实现README 里的警告很关键这个 App 把整个 JSON 结果发给客户端是为了展示和调试。生产应用应该让服务器只回传 yes/no并且把完整性校验和登录等操作绑定在一起否则逆向者可以绕过客户端直接打你的 API。Q5nonce 有什么讲究太短小于 16 字节会触发NONCE_TOO_SHORT太长会触发NONCE_TOO_LONG还得是 base64 安全的字符。项目里的 50 位随机串就是为规避这两个错误码准备的。七、进阶方向从跑起来到用得稳服务端加缓存对同一设备短时间内的重复请求做 5 分钟级缓存明显降低 Google 配额消耗。频率控制参考令牌桶算法把客户端请求压到合理水位避免触发限流。验证与业务绑定别让完整性检查成为孤立请求把它嵌进登录、支付、发帖等关键动作里一次请求同时完成鉴权与校验。结果审计把每次判定的原始 JSON 存日志方便事后排查为什么这台设备被拒。八、写在最后Play Integrity API Checker 的价值在于它把一条客户端 → 服务器 → Google的完整验证链路浓缩成了一个几百行代码的小工程。对新手它是理解 Play Integrity API 的最佳入门样本对老手它是一份可随时取用的接入骨架。照着本文跑通一次再对照源码看一遍MainActivity.java的每个分支你对设备完整性验证的理解会比读十篇文档都扎实。下一步建议先在自己手机上完成一次检测再到 Play Console 配置好 Cloud 项目最后把整套流程搬进你自己的应用——你会发现安全能力的门槛并没有想象中那么高。【免费下载链接】play-integrity-checker-appGet info about your Device Integrity through the Play Intergrity API项目地址: https://gitcode.com/gh_mirrors/pl/play-integrity-checker-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考