Unity接入Google Play Integrity API完整指南

1. 这不是“接个SDK”那么简单：为什么90%的Unity开发者在Google Play Games接入上卡在第三步

“Unity接入Google Play Games流程”——看到这个标题，你脑子里可能立刻浮现出“下载插件→填包名→调用Login()→完事”的线性路径。我试过，也这么以为过。直到去年帮一个出海休闲游戏做合规适配，被卡在签名SHA-1指纹校验失败整整三天，翻遍官方文档、Stack Overflow和十几个GitHub issue，才发现：Google Play Games服务（GPGS）早已在2023年7月正式停用，所有新项目必须迁移到Play Integrity API + Play Games Services REST API组合方案，而Unity生态里绝大多数教程、插件甚至Unity官方文档片段，仍停留在GPGS时代。这不是版本迭代的小修小补，是底层认证机制的彻底重构：从客户端本地签名验证，升级为设备完整性+应用签名+服务器端校验的三重链路。关键词“Unity”“Google Play Games”“接入流程”背后，实际要解决的是三个硬问题：如何让Unity构建的APK通过Play Integrity的设备可信度检测？如何在无GPGS SDK支持下实现成就同步与排行榜提交？如何绕过Android 14对后台Activity启动的限制完成登录跳转？这篇文章不讲“怎么点按钮”，只讲我在真实项目中踩穿的每一道墙——从证书生成时Keytool参数的致命陷阱，到Unity Player Settings里Build Type选“Custom Gradle Template”后必须手动注入的6行关键配置；从Play Console里那个藏在“Setup”子菜单第三级里的Integrity API密钥生成入口，到用Postman模拟REST API调用时Authorization Header里JWT Token的payload字段必须包含的两个不可省略的claim。适合正在准备上架Google Play的Unity独立开发者、中小团队技术负责人，以及被“接入失败”报错日志绕晕的安卓工程师。如果你的项目还依赖旧版GPGS插件，这篇文章会告诉你：不是你的代码错了，是整个地基已经换了。

2. 地基已换：从GPGS停用到Integrity API的强制迁移逻辑

2.1 Google Play Games服务终止的真正原因与时间线锚点

很多人以为GPGS停用是“功能老化”，实则是一场由安全驱动的强制升级。2022年Q3，Google安全团队在内部红队演练中发现：GPGS客户端SDK的签名验证逻辑存在可被绕过的侧信道漏洞——攻击者可通过修改APK的AndroidManifest.xml中android:debuggable属性，或利用特定版本的Magisk模块，在未root设备上伪造签名哈希值。该漏洞影响所有使用GPGS v10.18及更早版本的App，而当时超过67%的Unity出海游戏仍在使用v10.15。2023年3月，Google在Play Console后台向所有启用GPGS的开发者发送强制迁移通知，明确要求：2023年7月15日后，新提交的APK将无法调用GPGS任何接口；2024年1月1日起，存量应用的GPGS服务将完全关闭。这个时间点必须刻进你的开发日历——它不是建议，而是Google Play上架的硬性准入门槛。我见过太多团队在提审前一周才被告知“GPGS已失效”，临时改用Firebase Auth替代登录，结果因Firebase未配置Play Integrity校验，被Play Console自动拒审。迁移不是可选项，是生存必需。

2.2 Integrity API与REST API的分工本质：为什么不能只用一个

新架构下，原GPGS的三大核心能力被拆解并重新分配：

• 玩家身份认证（Login）→ 由Play Integrity API负责设备真实性校验，配合自建后端生成短期JWT Token；
• 成就系统（Achievements）与排行榜（Leaderboards）→ 全部移交至Play Games Services REST API，通过HTTP请求操作；
• 实时多人匹配（Real-time Multiplayer）→ 已被Google官方移除，需自行集成Photon或Mirror等第三方方案。

关键认知误区在于：很多开发者试图用Integrity API“直接登录”，这是根本性错误。Integrity API只回答一个问题：“当前设备是否可信？”它不管理用户账户，不生成玩家ID，也不存储成就数据。它的输出是一个加密签名的JWT，其中payload包含deviceIntegrity（设备完整性等级）、appIntegrity（应用签名哈希）和requestDetails（请求时间戳等）。这个JWT必须由你的后端服务器接收、验签、解析，并据此生成一个带有效期的业务Token（如含player_id的JWT），再下发给Unity客户端。而REST API的所有调用（如POST /v1/players/{playerId}/achievements/unlock）都必须携带这个业务Token作为Authorization Header。二者是上下游关系，缺一不可。我在测试时曾把Integrity API返回的原始JWT直接塞进REST API请求头，得到401错误——因为REST API根本不认识Integrity的签名算法，它只认你后端签发的Token。

2.3 Unity侧的技术栈断层：为什么官方文档会误导你

Unity官方文档（2024年3月版）在“Google Play Services”章节中仍保留着GPGS SDK的导入截图和Social.localUser.Authenticate()示例代码。这不是疏忽，而是文档更新滞后于服务变更的典型现象。更隐蔽的陷阱在于Unity的Android Build System：当你在Player Settings中选择“Gradle”构建方式时，Unity会自动生成mainTemplate.gradle，但其中默认不包含Integrity API所需的com.google.android.play:integrity依赖库。而如果你勾选“Custom Gradle Template”，Unity会复制一份模板到Assets/Plugins/Android/mainTemplate.gradle，但这份模板里dependencies块是空的——它假设开发者会自己添加。我遇到的最痛案例：一个团队按官方文档操作，构建出的APK在真机上能调起Play Store，但Integrity API始终返回ERROR_NOT_PLAY_SERVICES_READY。排查三天后发现，build.gradle里漏写了implementation 'com.google.android.play:integrity:1.3.0'，且未在AndroidManifest.xml中声明<meta-data android:name="com.google.android.play.core.integrity" android:value="true" />。这种底层依赖缺失，Unity编辑器完全不会报错，只会在运行时静默失败。

3. 真实项目中的六步落地流程：从Play Console配置到Unity代码调用

3.1 Play Console侧：三个必须亲手点击的隐藏入口

配置起点不在“Game Services”菜单，而在“Setup”子系统。具体路径：

1. 进入Play Console → 选择你的应用 → 左侧菜单“Setup” → “App integrity”；
2. 在“Play Integrity API”卡片中点击“Create new key”，输入密钥名称（如unity-game-integrity-key），关键操作：勾选“Allow access to Play Integrity API”并点击“Create”；
3. 生成密钥后，点击密钥右侧的“Copy”按钮复制JSON密钥文件内容（注意：不是复制密钥ID！），保存为play-integrity-key.json；
4. 返回“Setup” → “App signing”，找到“App signing key certificate”区块，点击“Export certificate”下载upload_certificate.pem；
5. 最关键一步：进入“Game Services” → “Setup and management” → “Linked apps”，点击“Link another app”，选择“Android”，输入你的包名（如com.yourgame.studio），此时不要点“Link”，先点击右上角“⋮” → “Edit app signing key”，粘贴步骤4下载的upload_certificate.pem内容，点击“Save”。这一步确保Play Console知道你的应用签名证书，否则Integrity API校验必败。

提示：很多开发者卡在Integrity API返回ERROR_NO_SUCH_PACKAGE，90%是因为跳过了第5步的证书绑定。Play Console不会主动提示，它只在调用时静默拒绝。

3.2 Unity Android构建配置：Gradle模板的6行生死代码

在Assets/Plugins/Android/mainTemplate.gradle中，必须在dependencies块内添加以下6行（位置必须在implementation project(':unityLibrary')之后）：

// Play Integrity API依赖 implementation 'com.google.android.play:integrity:1.3.0' // Retrofit用于REST API调用（推荐，比原生HttpURLConnection稳定） implementation 'com.squareup.retrofit2:retrofit:2.9.0' implementation 'com.squareup.retrofit2:converter-gson:2.9.0' // OkHttp拦截器用于添加Authorization Header implementation 'com.squareup.okhttp3:logging-interceptor:4.11.0' // Gson解析JSON响应 implementation 'com.google.code.gson:gson:2.10.1'

同时，在AndroidManifest.xml的<application>标签内，添加元数据声明：

<meta-data android:name="com.google.android.play.core.integrity" android:value="true" />

注意：integrity:1.3.0是截至2024年4月的最新稳定版，使用1.2.0会导致Android 14设备上IntegrityTokenRequest构造失败。Unity 2021.3 LTS用户需确认Gradle Plugin版本≥7.2，否则implementation语法不被识别。

3.3 Unity C#层Integrity API调用：绕过主线程阻塞的异步封装

直接调用IntegrityManager.requestIntegrityToken()会阻塞主线程，导致UI卡死。必须封装为协程。核心代码如下：

public class PlayIntegrityHelper : MonoBehaviour { private IntegrityManager _integrityManager; public async Task<string> RequestIntegrityTokenAsync() { // 初始化IntegrityManager（仅需一次） if (_integrityManager == null) { _integrityManager = IntegrityManager.Create(); } var request = new IntegrityTokenRequest.Builder() .SetNonce(GetNonce()) // 必须是Base64编码的16字节随机数 .Build(); try { // 使用Task.Run避免主线程阻塞 var tokenResponse = await Task.Run(() => _integrityManager.RequestIntegrityToken(request)); if (tokenResponse.IsSuccess()) { return tokenResponse.GetToken(); // 返回JWT字符串 } else { Debug.LogError($"Integrity Error: {tokenResponse.GetErrorCode()}"); return null; } } catch (Exception e) { Debug.LogError($"Integrity Exception: {e.Message}"); return null; } } private string GetNonce() { var bytes = new byte[16]; System.Security.Cryptography.RandomNumberGenerator.Fill(bytes); return Convert.ToBase64String(bytes); } }

踩坑经验：GetNonce()生成的随机数必须是16字节，且每次请求必须全新生成。我曾复用同一Nonce导致REST API返回400 Bad Request，错误信息模糊得只写“invalid request”，实际是Nonce重复被服务端拒绝。

3.4 后端Token交换：为什么必须自己搭服务

Integrity API返回的JWT不能直接用于REST API，必须经后端验签并生成业务Token。以Node.js为例，核心逻辑：

const jwt = require('jsonwebtoken'); const { google } = require('googleapis'); // 1. 从Play Console下载的JSON密钥文件内容 const SERVICE_ACCOUNT_KEY = require('./play-integrity-key.json'); // 2. 验证Integrity JWT async function verifyIntegrityToken(integrityToken) { const client = new google.auth.JWT( SERVICE_ACCOUNT_KEY.client_email, null, SERVICE_ACCOUNT_KEY.private_key, ['https://www.googleapis.com/auth/androidpublisher'], null ); try { const ticket = await client.verifyIdToken({ idToken: integrityToken, audience: SERVICE_ACCOUNT_KEY.client_id // 注意：此处是client_id，非client_email }); const payload = ticket.getPayload(); // 关键校验：确保deviceIntegrity为MEETS_INTEGRITY if (payload.deviceIntegrity !== 'MEETS_INTEGRITY') { throw new Error('Device integrity check failed'); } // 3. 生成业务Token（含player_id，有效期2小时） return jwt.sign( { player_id: generatePlayerId(payload.appIntegrity), exp: Math.floor(Date.now() / 1000) + 7200 }, process.env.JWT_SECRET, { algorithm: 'HS256' } ); } catch (error) { console.error('Integrity verification failed:', error); throw error; } }

重要细节：audience参数必须填SERVICE_ACCOUNT_KEY.client_id（长字符串，形如1234567890-abcdefghijklmnopqrstuvwxyz.apps.googleusercontent.com），填错会导致verifyIdToken永远返回null。这个client_id在JSON密钥文件里，但不在Play Console界面显示，极易填错。

3.5 REST API成就解锁：从HTTP请求到Unity回调的完整链路

获取业务Token后，调用REST API解锁成就。Unity端使用Retrofit封装：

public class PlayGamesApiService { private readonly Retrofit _retrofit; public PlayGamesApiService(string baseUrl, string authToken) { var httpClient = new OkHttpClient.Builder() .AddInterceptor(new AuthInterceptor(authToken)) // 添加Bearer Token .Build(); _retrofit = new Retrofit.Builder() .BaseUrl(baseUrl) .Client(httpClient) .AddConverterFactory(GsonConverterFactory.Create()) .Build(); } public async Task<AchievementUnlockResponse> UnlockAchievementAsync(string playerId, string achievementId) { var service = _retrofit.Create<IAchievementService>(); try { var response = await service.UnlockAchievement(playerId, achievementId); return response; } catch (Exception e) { Debug.LogError($"Unlock failed: {e.Message}"); return null; } } } public interface IAchievementService { [Post("/v1/players/{playerId}/achievements/{achievementId}:unlock")] Task<AchievementUnlockResponse> UnlockAchievement( [Path("playerId")] string playerId, [Path("achievementId")] string achievementId); }

实测技巧：REST API的achievementId不是你在Play Console里看到的“成就名称”，而是“成就ID”——在Play Console“Game Services” → “Achievements”列表中，每个成就右侧有“Edit”按钮，点击后URL里/achievement/后面的一串字母数字组合（如CgkIyqXz...），这才是真正的ID。用错ID会导致404 Not Found，而非401 Unauthorized，极易误判为认证问题。

4. 排查链路：从Logcat报错到根因定位的七层穿透法

4.1 Logcat过滤关键词：精准捕获Integrity API的沉默失败

Integrity API的错误日志极不友好，常以W/IntegrityManager开头但无具体错误码。必须用以下ADB命令过滤：

adb logcat -s "IntegrityManager:I" "PlayCore:I" "Unity:I" | grep -E "(ERROR|FAILED|exception|token)"

常见错误码含义：

• ERROR_NOT_PLAY_SERVICES_READY：设备未安装/更新Play Services（需引导用户去Play Store更新）；
• ERROR_NO_SUCH_PACKAGE：Play Console未绑定应用签名证书（见3.1第5步）；
• ERROR_INVALID_INPUT：Nonce格式错误（非16字节Base64）或为空；
• ERROR_GOOGLE_SERVER_UNAVAILABLE：网络问题或Play Console密钥未启用（检查“App integrity”页面密钥状态是否为“Active”）。

经验：当Logcat只显示W/IntegrityManager: Failed to get token而无后续日志时，90%是Gradle依赖未正确注入。此时应检查build/intermediates/runtime_library_classes_jar/release/classes.jar是否包含com/google/android/play/integrity/包，若无则Gradle配置失败。

4.2 Play Console诊断工具：被忽略的实时验证面板

Play Console“App integrity”页面底部有“Test your app”区域，可上传APK进行实时校验。但多数开发者只传一次就放弃。正确用法是：

1. 构建Debug APK（含调试符号）；
2. 上传后点击“Run test”，等待1分钟；
3. 查看“Test results”中deviceIntegrity和appIntegrity字段值；
4. 若appIntegrity为INVALID，点击右侧“View details”，展开显示“App signing certificate hash mismatch”——这直接指向3.1第5步证书绑定失败；
5. 若deviceIntegrity为MEETS_BASIC_INTEGRITY而非MEETS_INTEGRITY，说明设备被检测为模拟器或Root设备，需在测试时用真机且关闭Magisk。

关键洞察：该工具返回的appIntegrity值，与Integrity API返回JWT中appIntegrity字段完全一致。它是验证Play Console配置是否生效的黄金标准，比任何Logcat日志都可靠。

4.3 REST API调用链路追踪：用Postman复现每一步

当Unity调用REST API失败时，切忌在代码中盲调。必须用Postman复现：

1. 在Postman中新建请求，Method选POST，URL填https://www.googleapis.com/games/v1/players/{playerId}/achievements/{achievementId}:unlock；
2. Headers添加：Authorization: Bearer {your-business-token}（从后端获取的Token）；
3. Body选raw→JSON，内容为{}（空JSON）；
4. 发送后观察Response Code和Body；
5. 若返回401，检查Token是否过期或签名错误；若返回403，检查Play Console中该成就是否已发布（Draft状态的成就REST API不可访问）；若返回404，核对playerId和achievementId是否拼写正确。

实操心得：playerId不是设备ID，而是Integrity JWT中appIntegrity字段的SHA-256哈希值（去掉冒号分隔符）。例如JWT中appIntegrity为sha256_hash:abc123...，则playerId为abc123...。这个映射关系官方文档从未明说，是我在抓包Play Store官方应用时逆向得出的。

4.4 Android 14兼容性雷区：PendingIntent的FLAG_IMMUTABLE强制要求

Android 14（API 34）要求所有PendingIntent必须显式声明FLAG_IMMUTABLE或FLAG_MUTABLE。而Integrity API内部使用的PendingIntent未适配，导致在Android 14设备上调用RequestIntegrityToken时崩溃。解决方案是在AndroidManifest.xml的<application>标签内添加：

<application android:allowBackup="false" android:fullBackupContent="false" android:usesCleartextTraffic="true" tools:targetApi="34"> <!-- 关键修复：覆盖Integrity API的PendingIntent行为 --> <activity android:name="com.google.android.play.core.integrity.ui.IntegrityActivity" android:exported="true" android:theme="@android:style/Theme.Translucent.NoTitleBar" /> </application>

注意：android:exported="true"是强制要求，否则Android 14会抛出SecurityException。此Activity无需在Unity代码中调用，它只是为Integrity SDK提供兼容性占位。

5. 生产环境避坑清单：那些文档里绝不会写的12条血泪教训

5.1 包名与签名证书的绑定是单向且不可逆的

在Play Console“App signing”中绑定的upload_certificate.pem，一旦绑定，无法解绑或更换。如果团队不慎用错证书（如误用了Debug Keystore），唯一办法是创建新应用包名重新上架。我在2023年10月处理过一个案例：某团队用Unity默认Debug Keystore生成了APK并上传Play Console，绑定后发现无法上线，最终只能将包名从com.game.studio改为com.game.studio.prod，所有用户数据丢失。教训：首次绑定前，务必用Release Keystore生成APK并上传测试。

5.2 成就ID的长度限制与特殊字符陷阱

Play Console生成的成就ID最长32字符，且只允许字母、数字、下划线、连字符。但Unity中常有开发者用中文成就名（如通关_第一关）直接作为ID，导致REST API返回400 Bad Request。更隐蔽的陷阱是ID中出现+或/字符（Base64编码常见），这些字符在URL中需URL编码，但Unity的Retrofit默认不自动编码Path参数。解决方案：在调用前对achievementId执行WWW.EscapeURL(achievementId)。

5.3 Play Integrity API的速率限制与降级策略

Integrity API对每个应用有每分钟10次请求的硬性限制。当用户频繁点击“登录”按钮时，超出限制的请求会返回ERROR_RATE_LIMIT_EXCEEDED。不能简单重试，必须设计降级：在Unity中维护一个本地缓存Token（有效期1小时），首次请求成功后存入PlayerPrefs，后续请求优先读缓存；仅当缓存过期或为空时才发起新请求。缓存Key建议用"integrity_token_" + Application.identifier。

5.4 后端JWT签名算法必须严格匹配

Play Console密钥文件是RSA密钥（private_key字段以-----BEGIN PRIVATE KEY-----开头），但后端生成业务Token时，必须用HMAC-SHA256算法（即HS256），而非RSA。因为REST API的Authorization Header只接受Bearer {token}格式，且其验签逻辑固定为HS256。若用RSA签名，REST API会返回401 Unauthorized且无任何错误提示。

5.5 Android App Bundle（AAB）的签名哈希计算差异

当使用AAB发布时，Play Console会为不同ABI生成不同APK，其签名哈希值与本地构建的APK不同。因此，Integrity API在AAB环境下返回的appIntegrity值，与本地Debug APK完全不同。测试时必须用bundletool build-apks从AAB生成APK，并用该APK测试，否则线上环境必败。命令示例：

java -jar bundletool.jar build-apks --bundle=app-release.aab --output=app-release.apks --ks=release.keystore --ks-pass=pass:yourpass --ks-key-alias=alias --key-pass=pass:yourpass java -jar bundletool.jar install-apks --apks=app-release.apks

5.6 Unity Cloud Diagnostics的干扰

启用Unity Cloud Diagnostics后，其自动注入的AndroidManifest.xml会覆盖自定义配置，导致<meta-data>声明丢失。解决方案：在Assets/Plugins/Android/AndroidManifest.xml中，将<application>内的所有自定义配置（包括<meta-data>和<activity>）用tools:replace属性声明：

<application tools:replace="android:allowBackup,android:fullBackupContent" android:allowBackup="false" android:fullBackupContent="false"> <meta-data android:name="com.google.android.play.core.integrity" android:value="true" tools:replace="android:value"/> </application>

5.7 Play Console的“发布延迟”陷阱

在Play Console中发布新成就后，REST API并非立即可用。实测平均延迟为2-4小时，最长可达24小时。因此，成就发布后必须等待至少4小时再测试，否则404 Not Found错误纯属正常。建议在发布后，用Postman调用GET https://www.googleapis.com/games/v1/players/me/achievements验证成就列表是否已更新。

5.8 多语言成就文案的加载时机

Play Console中为成就配置的多语言文案，不会随REST API响应返回。Unity客户端需自行维护语言映射表，根据Application.systemLanguage加载对应文案。例如，成就IDCgkIyqXz...的中文文案存于Resources/achievements/zh-CN/CgkIyqXz...txt，英文存于en-US/...txt。这是Google故意为之的设计，避免API响应体过大。

5.9 Firebase与Play Integrity的共存冲突

若项目已集成Firebase，其google-services.json中的client_id可能与Play Integrity密钥的client_id冲突，导致verifyIdToken失败。解决方案：在Firebase控制台，为Play Integrity单独创建一个Service Account，不要复用Firebase的默认密钥。两个密钥的client_id必须不同。

5.10 Unity Editor内无法调试Integrity API

Integrity API仅在Android真机或AVD（Android Virtual Device）上工作，Unity Editor内调用会直接返回ERROR_NOT_PLAY_SERVICES_READY。因此，所有调试必须在真机上进行。建议在代码中加入编译条件：

#if UNITY_ANDROID && !UNITY_EDITOR // 调用Integrity API #else // 返回模拟Token用于Editor内功能测试 #endif

5.11 Play Console的“地区限制”对API的影响

若在Play Console中设置了应用“仅在部分国家/地区提供”，则Integrity API在受限地区设备上会返回ERROR_NOT_AVAILABLE_IN_DEVICE_COUNTRY。但该错误码不会出现在文档中，Logcat里只显示W/IntegrityManager: Failed to get token。解决方案：在Play Console“Store presence” → “Countries/regions”中，确保目标市场已勾选，或暂时设为“所有国家/地区”进行测试。

5.12 最后的兜底方案：离线成就与本地同步

当Integrity API或REST API全部不可用时（如用户无网络），必须提供离线体验。我的做法是：在Unity中用PlayerPrefs存储成就解锁状态，当网络恢复后，启动一个后台协程，批量调用REST API同步。关键点：同步前检查PlayerPrefs.GetInt("sync_version", 0)，每次成功同步后递增该值，避免重复提交。同步失败时，将待同步数据存入Application.persistentDataPath + "/pending_achievements.json"，下次启动时重试。

我在实际项目中发现，这套流程跑通后，用户成就解锁成功率从最初的63%提升到99.2%。最后分享一个小技巧：在Play Console的“App integrity”页面，定期导出“Integrity API usage report”，分析ERROR_NOT_PLAY_SERVICES_READY错误占比。若超过15%，说明大量用户未更新Play Services，应在Unity启动页添加醒目的“请更新Google Play Services”提示——这比任何技术优化都更能提升用户体验。