Unity接入华为HMS SDK实战：账号、支付、推送与Gradle签名避坑

简介Unity接入华为SDK的完整示例工程面向需要在Unity中集成HMS能力的移动游戏与应用开发者尤其适合准备上线华为渠道、需打通账号登录、推送与游戏服务等模块的中级开发者参考。压缩包共2000个文件、约28.82MB以rar格式提供内含1604个bin、127个class、88个meta、83个java、40个xml、25个jar、13个cs、10个dll等java与xml对应Android层的清单与配置cs与dll是Unity端脚本和华为SDK依赖库bin、class多为示例工程的编译产物另有png界面素材与log运行记录可按目录逐层梳理接入结构。已有1845人学习下载。工程以HuaweiSdkDemo为主线覆盖SDK初始化、华为账号登录、推送消息接收以及成就、排行榜等接口的调用示例并保留IL2CPP打包所需的库文件与工程配置便于读者对照实现自己的功能模块减少版本兼容、权限声明与回调处理上的试错成本。1. 从登录按钮没反应说起Unity 接华为 HMS SDK 要先打通哪几层某开发者把 hmssdk 的几个 aar 直接拖进 Unity 的Assets/Plugins/Android改完包名出包点登录按钮毫无反应Logcat 里只留下一行含糊的初始化失败提示。这类问题在以 unity 华为 sdk 为关键词的检索里出现频率极高根子几乎都不在 C# 那一层而是 Android 侧的依赖版本、签名指纹、配置文件这三件事没对齐。这份 demo 的价值在于把 huawei 账号登录、应用内支付、推送三条最常被接入的链路连同 Gradle 模板、keystore 指纹回填、混淆规则一起做成一个能跑通的最小工程Unity 业务层只面对一层封装好的 C# 接口平台差异全部沉到工程配置里。它适合两类人正准备上架前做接入的 Unity 团队以及接了半截卡在回调拿不到数据阶段的同学。2. 环境与依赖版本组合、插件落点与配置文件的三角对齐接入失败十次里有七次不是代码写错而是版本和文件放错了位置。华为的 Android SDK 以 aar 形式发布Unity 侧通过插件包封装成 C# 接口中间隔着 AGP、Gradle、AndroidX 三层任何一层版本错位都会以初始化失败这种没有上下文的报错形式出现。这一章先把环境钉死再谈代码。2.1 为什么必须先锁死 Unity 与 Gradle 的版本组合Unity 从 2020 版开始默认使用 Gradle 构建自带的 AndroidX 支持包版本由 Unity 内部模板决定而 hmssdk 依赖的 androidx 组件版本往往比 Unity 默认的高。两者混用时Gradle 的依赖仲裁会挑一个较高版本表面不报错运行时却在Activity生命周期上出问题——典型表现是授权页闪一下就退或者回调永远不触发。我的做法是Unity 选一个 LTS 分支并固定下来项目里打开Custom Gradle Template把 Gradle 与 AGP 版本写死不让 Unity 自动升级。具体版本的取值不要抄网上的文章以插件包解压后pom里声明的依赖版本为准用下面的命令把依赖树打出来看# 在 Unity 导出的 Android 工程根目录执行 ./gradlew :launcher:app:dependencies --configuration releaseRuntimeClasspath \ deps.txt 21 # 只看 huawei / androidx 两类的实际解析结果 grep -E com\.huawei|androidx\. deps.txt | grep -E \- | sort -u这段命令的意图是把最终被 Gradle 选中的版本列出来而不是看声明版本。dependencies任务输出里带-的行表示发生了版本仲裁箭头右边才是真正打进包里的版本。参数上releaseRuntimeClasspath对应 release 变体做支付和推送验证时不要用 debug 变体的结果去推断两者的依赖裁剪规则不一样。输出保存成文件是必须的因为依赖树动辄上千行直接看终端会漏掉关键冲突。提示把deps.txt一起提交到版本库后面任何人升级插件时先 diff 这个文件比读变更日志快得多。常见做法是同时维护两份构建配置日常开发用 Unity 内置构建发版用导出 Android 工程后命令行构建。前者迭代快后者可控。代价是两边产物可能不一致所以每次发版前必须用导出工程重新验证一遍登录和支付这一点在后面第 6 章的自动化脚本里会再提到。2.2 插件导入的三种方式与各自的踩坑点HMS 的 Unity 插件通常有三种落地形态官方.unitypackage、手动拷贝aar AndroidManifest.xml、以及打成 UPM 包放进Packages/manifest.json。三者的区别不在功能而在谁负责合并 AndroidManifest和升级时会不会覆盖你的改动。方式适用场景主要风险.unitypackage导入新项目快速验证重复导入会产生同名脚本编译期报歧义手动放 aar只需部分能力包体敏感Manifest 合并冲突权限重复声明UPM 本地包多项目复用、团队协作需要自己维护.asmdef否则脚本被裁掉手动放 aar 是最容易翻车的一种。aar 里自带AndroidManifest.xmlUnity 构建时会和Assets/Plugins/Android/AndroidManifest.xml做 merge如果两边的minSdkVersion不一致构建直接失败。正确做法是让主 Manifest 不要写死 minSdk而是通过 Gradle 模板统一控制!-- Assets/Plugins/Android/AndroidManifest.xml -- manifest xmlns:androidhttp://schemas.android.com/apk/res/android packagecom.yourcompany.yourapp !-- 不要在这里写 uses-sdk交给 mainTemplate.gradle 统一管理 -- application android:labelstring/app_name !-- 华为推送需要显式声明 meta-data值从 AGC 后台拷贝 -- meta-data android:namecom.huawei.hms.client.appid android:valueappid你的AppId / /application /manifestpackage属性必须和 AGC 后台登记的包名逐字符一致包括大小写。com.huawei.hms.client.appid这个 meta-data 在新版本里可以由agconnect-services.json自动带出但老版本插件不会两处都写也不会冲突保险起见保留。如果同时存在推送和账号两个 aar注意它们各自声明的权限会合并重复项由 Manifest Merger 去重不需要手动删。2.3 agconnect-services.json 与包名、签名的三方校验这个文件是 AGC 侧的身份证里面包含了 client_id、app_id、api_key 和证书指纹。它必须放在Assets/Plugins/Android/下文件名不能改且必须参与构建——很多人把它放在了工程根目录Unity 构建时直接忽略运行期就表现为client_id 无效。判断它有没有被打进包里最直接的办法是解包看# 用 apktool 或 unzip 检查 assets 目录 unzip -l app-release.apk | grep -i agconnect # 期望输出类似assets/agconnect-services.json如果这条命令没有输出说明文件没进包先检查路径再检查文件是否被.gitignore误伤。第二步是校验指纹AGC 后台登记的 SHA256 必须和实际签名证书一致否则账号登录会静默失败日志里只有一行权限拒绝。指纹用下面的命令取keytool -list -v -keystore release.keystore -alias your_alias \ -storepass 你的密码 2/dev/null | grep -A 1 SHA256:注意 debug 包和 release 包用的是两个不同的 keystoreAGC 后台需要把两个指纹都填进去。只填 release 会导致开发阶段登录一直失败而你又误以为是代码问题——这个坑我见过太多次。3. 核心链路落地账号、支付、推送的 C# 封装与回调处理环境对齐之后真正的接入工作集中在三件事上初始化时机、回调线程、以及客户端拿到的东西什么时候能信。这一章的代码都来自 demo 里的封装层可以直接抄结构但参数要按自己项目改。3.1 初始化只做一次且必须在业务调用之前AGC 的初始化是异步的如果在它完成之前就发起登录会得到一个语义模糊的错误码。demo 的做法是挂一个常驻的DontDestroyOnLoad对象在Awake里做一次性初始化并用静态标志防止场景重载时重复执行。using HuaweiMobileServices.Base; using HuaweiMobileServices.Utils; using UnityEngine; public class HmsBootstrap : MonoBehaviour { private const string TAG HmsBootstrap; private static bool _inited; void Awake() { DontDestroyOnLoad(gameObject); InitOnce(); } private void InitOnce() { if (_inited) return; _inited true; // 初始化是异步的回调返回之前不要调用任何业务接口 AGConnectInstance.Initialize( () Debug.Log(${TAG} AGC ready), err Debug.LogError(${TAG} AGC init failed: {err}) ); // 日志开关只在 debug 包里打开release 包必须关掉 #if DEVELOPMENT_BUILD ServiceHelper.EnableLogger(); #endif } }逻辑上AGConnectInstance.Initialize承担两件事加载agconnect-services.json并校验签名以及建立与 AGC 的连接。第一个参数是成功回调第二个是失败回调失败时打印的字符串里通常已经带了错误码不要吞掉。DontDestroyOnLoad保证跨场景不销毁否则切场景后所有已注册的监听都会失效。ServiceHelper.EnableLogger会输出完整的请求体和 tokenrelease 包里开着等于把凭证写进日志必须用条件编译裁掉。参数层面要注意的是初始化失败不应该阻塞游戏启动但必须阻塞登录按钮的可用状态。demo 里用一个event Action OnReady把就绪状态广播出去UI 层订阅后按钮才可点这个细节能省掉大量点了没反应的客服工单。3.2 账号登录授权参数与 openId 的落地登录接口的坑集中在授权参数上。默认参数集只返回基础资料如果需要openId和accessToken必须显式追加否则回调里这些字段是空的而 SDK 不会报错。using System; using HuaweiMobileServices.Id; using UnityEngine; public class HmsAccount : MonoBehaviour { private HuaweiIdAuthService _authService; public void SignIn() { // 默认参数集不含 openId必须链式追加 var helper new HuaweiIdAuthParamsHelper( HuaweiIdAuthParams.DEFAULT_AUTH_REQUEST_PARAM); var authParams helper .SetId() // 返回 openId .SetAccessToken() // 返回 accessToken .SetProfile() // 返回昵称头像 .CreateParams(); _authService HuaweiIdAuthManager.GetService(authParams); _authService.SignIn(OnSignInResult); } private void OnSignInResult(IAuthHuaweiId id, Exception error) { if (error ! null) { // 常见错误码签名指纹不匹配、用户取消、HMS Core 版本过低 Debug.LogError($sign in failed: {error.Message}); return; } Debug.Log($openId{id.OpenId}, name{id.DisplayName}); // openId 是账号在本应用内的唯一标识用它去业务服务器换游戏 token // accessToken 只用于服务端校验不要落本地 } }SetId()对应返回openIdSetAccessToken()对应返回访问令牌SetProfile()对应昵称头像。三个是独立的开关缺一个就少一个字段。回调里的Exception参数必须判空取消登录也会走这里不能当成致命错误弹窗。accessToken有有效期且不能存在PlayerPrefs里——它是服务端校验用的凭证本地只保留openId和你自己签发的会话 token。回调线程在 Android 主线程Unity 侧直接操作 UI 是安全的但如果回调触发时对应的GameObject已经被销毁访问会抛异常。demo 里的处理是在回调入口先判this ! null再分发事件。3.3 应用内支付商品查询、下单与服务端校验支付链路最容易犯的错是客户端下单成功就当发货成功。正确的顺序是客户端发起购买 → SDK 返回购买结果 → 把购买数据和签名送到业务服务器 → 服务器向平台校验 → 服务器发货 → 客户端刷新。任何一步跳过去都会在对账时出问题。先看商品查询价格必须来自平台返回不能在客户端写死using HuaweiMobileServices.IAP; using HuaweiMobileServices.Utils; using UnityEngine; public void QueryProducts(string[] productIds) { var req new ProductInfoReq { PriceType PriceType.InAppConsumable, // 消耗型订阅改 InAppSubscription ProductIds productIds }; Iap.GetIapClient().ObtainProductInfo(req) .AddOnSuccessListener(result { foreach (var p in result.ProductInfoList) Debug.Log(${p.ProductId} | {p.Price} | {p.ProductName}); }) .AddOnFailureListener(err Debug.LogError($obtain product failed: {err.Message})); }PriceType决定查询哪一类商品消耗型和订阅型不能混查传错会返回空列表而不是报错。ProductIds建议一次不超过二十个多了会被限流。成功回调里的Price字段是带货币符号的展示字符串不要拿它做计算计算用服务端下发的数值。下单环节返回的数据里有一个PurchaseData和一个Signature这两个必须原样送到服务器public void Buy(string productId) { var req new PurchaseIntentReq { ProductId productId, PriceType PriceType.InAppConsumable }; Iap.GetIapClient().CreatePurchaseIntent(req) .AddOnSuccessListener(result { // 只有这一步还不够必须把这两个字段送到服务端 var data result.PurchaseIntent.PurchaseData; var sign result.PurchaseIntent.Signature; Debug.Log($purchaseData{data}\nsignature{sign}); }) .AddOnFailureListener(err Debug.LogError($create purchase failed: {err.Message})); }PurchaseData是一段 JSON里面包含订单号和商品信息Signature是平台对这段数据的签名。服务器用公钥验签通过后再调用平台的订单查询接口确认状态两步都过了才发货。客户端在拿到成功回调后不要立刻给道具而是等服务器回执这样即使网络中断也不会重复发货。补单逻辑同理启动时把所有未完成的订单号拉一遍逐个走服务端校验。3.4 推送token 上报与通知点击的回传推送在 Unity 侧只能拿到 token真正接收消息需要 Android 层实现一个继承自平台服务的类。demo 里的做法是 Unity 只负责开关和 token 上报消息接收放在Assets/Plugins/Android下的 Java 文件里。using HuaweiMobileServices.Push; using UnityEngine; public void EnablePush() { HmsMessaging.GetInstance().TurnOnPush() .AddOnSuccessListener(token { Debug.Log($push token{token}); // 立刻上报给业务服务器和当前 openId 绑定 }) .AddOnFailureListener(err Debug.LogError($turn on push failed: {err.Message})); }TurnOnPush成功返回的是设备 token它可能随重装、清数据变化所以每次启动都要重新上报不要只在首次启动时传。失败最常见的原因是agconnect-services.json里的包名与实际不符或者推送服务没有在 AGC 后台开通。通知点击的回传有两种方式一种是 SDK 通过 Intent 把数据带回来Unity 侧用OnNewIntent接另一种是在 Java 服务里写静态变量供 Unity 读取。前者更规范后者调试方便demo 两种都留了入口。4. 出包链路签名、Gradle 模板与混淆规则的对齐代码跑通不代表能出包。从 Unity 里点 Build 和在 Android Studio 里跑assembleRelease走的是两条不同的链路前者会覆盖你对 Gradle 模板的改动后者才是发版应该用的方式。4.1 keystore、指纹与 AGC 后台的回填发版用的 keystore 一旦丢失应用就无法再更新这个是老生常谈但仍然有人踩。demo 的做法是把 keystore 放在工程外部的私有目录路径通过环境变量注入 Gradle不写进仓库。// launcherTemplate.gradle 片段 android { signingConfigs { release { storeFile file(System.getenv(RELEASE_STORE_FILE) ?: release.keystore) storePassword System.getenv(RELEASE_STORE_PASSWORD) keyAlias System.getenv(RELEASE_KEY_ALIAS) keyPassword System.getenv(RELEASE_KEY_PASSWORD) } } buildTypes { release { signingConfig signingConfigs.release minifyEnabled true proguardFiles getDefaultProguardFile(proguard-android.txt), proguard-user.txt } } }用环境变量而不是硬编码是为了让 CI 和本地共用一份模板。四个变量缺任何一个构建都会在签名阶段失败报错信息里会明确指出是哪个为空。指纹回填到 AGC 后台之后不会立即生效通常有几分钟延迟改完指纹马上测登录大概率还是失败等一会儿再试。4.2 minSdk、targetSdk 与架构选项三个值必须三方一致Unity 的 Player Settings、Gradle 模板、AGC 后台的应用信息。minSdk 低于平台要求时构建能过但运行期加载 so 失败targetSdk 过高时权限弹窗的行为会变推送和存储权限尤其明显。// mainTemplate.gradle android { compileSdkVersion 34 defaultConfig { minSdkVersion 24 targetSdkVersion 34 ndk { // 只保留 64 位包体小一半如果还要兼容老设备就两个都留 abiFilters arm64-v8a } } packagingOptions { // 平台 aar 与 Unity 内置库在 META-INF 下容易重复 exclude META-INF/DEPENDENCIES exclude META-INF/LICENSE* exclude META-INF/NOTICE* } }abiFilters只留arm64-v8a能显著减小包体代价是不支持 32 位设备。当前主流分发渠道对 64 位的要求已经很明确新项目可以直接只留 64 位如果历史用户里有大量老机型就两个都保留用分包或动态下发处理体积。packagingOptions里的三条排除是解决Duplicate files copied类构建失败的常用手段加之前先确认冲突文件确实是无害的元数据不要盲目排除。4.3 混淆规则release 包崩溃的高发区开了minifyEnabled之后反射调用的类会被裁掉表现是 debug 包一切正常、release 包启动即崩日志里是ClassNotFoundException。平台 SDK 的类必须整体保留# proguard-user.txt -keep class com.huawei.** { *; } -keep class com.huawei.agconnect.** { *; } -dontwarn com.huawei.** # 如果用了 Gson 解析 PurchaseData实体类也要保留 -keep class com.yourcompany.yourapp.model.** { *; } -keepattributes Signature -keepattributes *Annotation*-dontwarn不是可选项平台 aar 里引用了部分可选依赖不抑制会在构建期报一堆 warning 转 error。-keepattributes Signature是为了泛型反射Gson 解析PurchaseData时没有它会把字段解析成LinkedTreeMap取不到值但不报错排查起来非常费劲。5. 避坑与排查Unity 接 HMS SDK 最容易翻车的五个现场这一章按现象 → 原因 → 解决整理都是我在实际项目里遇到过的顺序按出现频率排。5.1 点登录没反应也没有授权页弹出现象按钮点击后日志静默SignIn回调既不成功也不失败。原因绝大多数是签名指纹与 AGC 后台不一致SDK 在发起授权前就做了校验并静默返回。少数情况是设备上没有安装 HMS Core 或版本过低。解决先用keytool取出实际签名指纹和 AGC 后台逐位比对注意冒号分隔格式要一致再确认测试设备上 HMS Core 的版本低于要求时引导用户升级。两步都排除后再看代码。5.2 报 client_id 无效或初始化失败现象启动日志里出现client_id invalid或agconnect init failed。原因agconnect-services.json没有被打进包或者包名与后台登记的不一致。也有人把它放在了工程根目录而不是Assets/Plugins/Android/。解决用第 2.3 节的unzip -l确认文件在assets/下再核对AndroidManifest.xml里的package属性。改包名后必须回 AGC 重新下载配置文件旧的里面绑的还是旧包名。5.3 支付成功但道具没到账现象客户端收到成功回调服务端订单表里没有记录。原因客户端把下单成功当成了支付成功没有把PurchaseData和Signature送到服务端做验签和订单查询。解决补上服务端校验链路客户端只负责发起和展示结果。同时加启动补单逻辑把所有未完成订单扫一遍避免网络中断导致的漏单。5.4 release 包启动闪退debug 包正常现象安装 release 包后点击图标直接退出Logcat 里有ClassNotFoundException。原因混淆规则没有覆盖平台 SDK 的类或者abiFilters只留了 64 位但某个 so 只有 32 位版本。解决按第 4.3 节补全 keep 规则用unzip -l检查 apk 里lib/目录下的架构是否完整缺哪个补哪个。改完必须重新出包验证热更修不了这类问题。5.5 推送 token 拿到了但收不到消息现象TurnOnPush成功返回 token服务端也下发了但设备上没有通知。原因通知权限没申请、推送服务没在 AGC 后台开通、或者应用被系统列入后台限制名单。解决按 targetSdk 对应的方式申请通知权限在 AGC 后台确认推送服务状态测试时把应用加入电池优化白名单。三者缺一不可只查一项容易误判。6. 上线前的回归验证我用一套脚本把冒烟测试压到半小时接入做完到真正敢发版中间还差一轮回归。人工点一遍登录、支付、推送至少要半天而且容易漏。我的习惯是写一个 shell 脚本把 adb 能自动化的部分全部自动化剩下的手工项固定成一张表。脚本做三件事清数据重装、抓关键日志、检查包内容。#!/usr/bin/env bash set -euo pipefail PKGcom.yourcompany.yourapp APK$1 adb uninstall $PKG /dev/null 21 || true adb install -r $APK # 清空日志后启动只抓我们关心的 TAG adb logcat -c adb shell monkey -p $PKG -c android.intent.category.LAUNCHER 1 /dev/null sleep 8 adb logcat -d -s HmsBootstrap:HmsAccount:IapDemo:AndroidRuntime:E smoke.log # 三个关键字任一缺失就判定失败 for kw in AGC ready openId push token; do if ! grep -q $kw smoke.log; then echo FAIL: missing $kw exit 1 fi done echo PASS脚本里logcat -s的 TAG 要和代码里的常量严格对应写错一个字母就抓不到。sleep 8是给初始化留的时间网络差的环境要调大。三个关键字分别覆盖初始化、账号、推送三条链路支付因为涉及真实扣款不适合自动化留手工验证。手工部分我固定成一张表每次发版逐项打勾验证项操作通过标准首次安装登录全新设备安装后登录授权页正常弹出openId 非空取消登录授权页点返回不崩溃按钮可再次点击支付全流程沙盒账号下单服务端订单状态变为已支付断网支付下单后立即断网恢复网络后补单成功推送点击后台下发通知并点击跳到指定页面且带参数覆盖安装旧版本直接覆盖登录态保持不重复初始化这张表里最容易漏的是取消登录和断网支付两项前者考验异常分支后者考验补单逻辑都是线上问题的高发区。有一个教训值得单独说早期我图省事测试时一直用 debug 包release 包只在发版当天出一次结果混淆规则的问题连续两个版本都没被发现。从那以后我每次出包前都强制走一遍上面的脚本加表格且必须用 release 签名包跑debug 包的结果一律不作为发版依据。这套流程看着笨但把发版当天才发现问题的概率压到了接近零。希望帮到你。本文还有配套的精品资源点击获取