Unity接入HMS SDK全流程指南：从demo到真机登录避坑

简介：在Unity项目中接入华为HMS SDK，是移动端开发者的常见需求。由linxinfa整理的这份Demo工程，完整演示了从SDK导入、IL2CPP配置到初始化、登录、推送等功能的调用流程，适合已掌握Unity基础、想快速接入华为生态的开发者参考。资源包共2000个文件，约28.82MB，以bin、class、java、xml为主，并含jar库、C#脚本与Android工程配置，目录结构清晰，便于按需定位模块。工程内脚本覆盖了初始化回调、登录接口封装、权限请求等关键代码，可移植复用。已有1842人学习下载，对照运行能显著缩短接入调试周期，规避版本兼容与适配问题。

1. Unity 接入 HMS SDK demo：为什么我劝你先从 demo 开始

如果你搜到这篇，手里大概率有一个 Unity 接入 HMS SDK demo 要跑通。别急着把它往正式项目里塞，我在这个方向上翻过几次车，最典型的场景是：包打好了，装到测试机上，账号登录的按钮怎么点都没反应，日志里只有一行HMS Service is not available。后来发现不是代码问题，而是从集成方式到签名、再到配置文件的落位，每一步都有隐藏的前提。这篇我按自己拆 demo 的顺序写：先讲清 HMS SDK 在 Unity 侧到底长什么样，再给出一套能直接复现的接入流程，最后把真机调试阶段最容易踩的坑列出来。适合刚拿到 demo、准备接账号登录或推送的 Unity 开发者，也适合被 Gradle 依赖搞到头疼的熟手回来看边界。

2. HMS SDK 这套东西该怎么看：能力边界、版本三角与集成选型

2.1 HMS SDK 到底拆成哪几块，Unity 工程里只会用到其中一部分

很多第一次接 HMS SDK 的人会有一个错觉：它是一个大而全的 SDK，导入 Unity 就什么能力都有了。实际上 HMS SDK 是一组按 Kit 划分的模块，账号登录、推送、支付、地图、分析各自独立。Unity 侧拿到的 demo 通常只集成其中两三个 Kit，目录结构大致是：Assets/Plugins/Android/下面放着厂商提供的一个或几个 aar，Assets/Plugins/下面放着 C# 封装层，Assets/Scripts/里才是业务调用代码。C# 层不是直接用 Android 的 Java API，而是通过封装类把方法暴露给 Unity 脚本。

我拿到一个 demo 后，习惯先看一眼文件清单而不是直接拖进引擎。下面这个表格是我在模拟项目X里整理出的典型结构，不同版本的文件名会有出入，但作用基本一致：

第一次接入不需要把每个 aar 都搞明白。你要关注的是两件事：一是agconnect-services.json有没有放到正确位置，二是 C# 层暴露出来的 API 是不是你当前 Unity 版本能调用的。demo 里的HMSSDK.cs通常已经写了一版初始化流程，我的建议是先从Account这个 Kit 开始，因为账号登录能直接验证端到端链路是否通。

2.2 Unity、Gradle 插件与 HMS SDK 的版本三角约束

这是整个接入过程里最容易“玄学”的部分。HMS SDK 本身是 Android 库，Unity 打包时会把工程转成 Gradle 工程再编译，所以你的 Unity 版本、AGP（Android Gradle Plugin）版本、HMS SDK 版本三者必须形成一个不会冲突的三角关系。以我常用的 2021.3 LTS 为例，它自带 Gradle 6.x，AGP 4.x；而 HMS SDK 的 Unity 插件在对高版本 AGP 支持上存在滞后。只要其中一个版本跳变过大，就会出现Could not resolve com.huawei.hms:xxx这种看都看不懂的依赖错误。

我一般会按下面几条来约束版本，能省掉大量时间：

• Unity 选 LTS 版本，不建议用最新预览版接厂商 SDK。
• 如果 demo 里标注了 HMS SDK 版本要求，就用它对应的 Unity 版本跑，不要自作主张升级。
• 关闭 Unity 的 Auto Gradle Update 选项，避免它顺手把 AGP 抬到不兼容的版本。
• 在mainTemplate.gradle里明确指定 AGP 版本，而不是用+通配符。

这个三角约束没什么理论上的优雅解法，本质就是一个“官方用哪个版本验证过，你就用哪个版本”的思路。demo 里如果附带README或CHANGELOG，先看它，再看别的。很多人在这一步就放弃了，其实是选型错了，不是代码错了。

2.3 官方自动集成插件 vs 手动导入 demo 文件

接入路径有两条：一条是安装官方 Unity 插件，由工具自动把 SDK 写入工程；另一条是手动把 demo 里的 aar、hmssdk.cs、配置文件和 Gradle 片段拷进自己的工程。两条路我都走过，结论很直接：新手跟 demo 走手动流程，不是为了跟官方工具过不去，而是手动流程能让你看到每个文件到底落在哪里。自动集成工具确实快，但它把过程包成了一个“黑匣子”，一旦打包失败，你连从哪查起都不知道。

手动导入的典型顺序是：先把Assets/Plugins/Android整个目录复制到目标工程，再检查mainTemplate.gradle里是否声明了厂商仓库和依赖，最后把agconnect-services.json放进去。每一步都有对应的失败现象。举个例子，mainTemplate.gradle里的仓库声明写错了，构建时会直接报找不到 HMS 依赖；配置json放错层级，运行时又会静默失败，登录按钮点了没反应。如果你用的是线上自动集成方案，这些问题会被工具隐藏掉一部分，排查反而更难。所以本篇文章后面的步骤全部按手动导入 demo 的方式来讲，这样你拿到任何一套 demo 都能照猫画虎。

3. 搭出第一个能构建的接入 demo：工程准备与配置文件落位

3.1 在厂商开放平台创建应用，拿到一把“钥匙”

接 HMS SDK 的第一步不在 Unity 里，而在厂商开放平台的控制台上。你需要注册开发者账号，创建一个应用，记录下应用包名，然后在「开发服务」里开通账号 Kit。这个包名必须和 Unity 工程最终打包的包名完全一致，否则后面所有接口都会返回鉴权失败。

这里有几个关键信息需要在控制台里配置，我用参数表列出来：

SHA-256 指纹的获取方式比较固定：在命令行导出一个keytool命令，从签名文件里读取指纹。如果你暂时没有正式签名，可以先创建一个专门给 demo 用的 keystore，后续换正式签名时再更新控制台。这里最容易埋雷的是：开发阶段用的 debug 签名和上线用的 release 签名指纹不一样，经常出现“本地能登录，打包给别人就登录失败”的情况。后面第 5 章我会专门讲这个问题的排查。

3.2agconnect-services.json到底该放哪，放错会怎样

从控制台下载下来的agconnect-services.json是一份很小的 JSON 文件，里面包含应用 ID、App Secret、各种服务模块的配置信息。它在 Unity 工程里的正确位置是Assets/Plugins/Android/agconnect-services.json。很多第一次接入的人会随手把它放到Assets/根目录，结果构建时不报错，运行时却拿不到项目信息，所有 HMS 接口都像死了一样。

这个文件的原理是：Unity 打包成 Android 工程时，mainTemplate.gradle里有一段解析脚本会把该文件转换成资源文件并打包进 APK。如果文件放错位置，脚本找不到它，不会中断构建，只会跳过解析。所以你在 Unity 编辑器里看不到任何错误提示，但真机上 SDK 初始化会失败。验证它是否被正确打进包里的常见做法是：用解压工具打开 APK，在assets目录下找有没有一个agconnect-services.json或类似名称的文件。这个动作虽然机械，但非常管用。

如果你的 demo 原本带了一个json，但它来自模拟项目X，包名和你的工程不一致，千万不要直接拿来用。正确流程是：在控制台里把你自己的包名和签名指纹配好，重新下载一份配置文件替换原来的。这份文件是跟着应用 ID 走的，套用别人的配置即使能编译，接口签名也会对不上。

3.3 Unity 工程侧配置：包名、签名、最小系统版本

打开Player Settings，把Other Settings里的Package Name改成控制台注册的包名。这个改动要和你下载agconnect-services.json之前填写的值一致。接下来是签名配置：在Publishing Settings里勾选Custom Main Manifest、Custom Main Gradle Template、Custom Gradle Properties Template，然后创建或指定一个 keystore。

打包之前，建议先确认几个 Android 参数，我用一段mainTemplate.gradle的片段示意，这些参数在 demo 里通常会默认给好：

android { compileSdkVersion 31 defaultConfig { minSdkVersion 19 targetSdkVersion 30 multiDexEnabled true } }

这段配置里，compileSdkVersion 31对应 Android 12，是 HMS SDK 比较稳妥的编译基线；minSdkVersion 19保证大多数存量安卓机都能跑；multiDexEnabled true很重要，因为 HMS SDK 的类数量不少，不开启可能导致运行时找不到类。需要注意的是，targetSdkVersion不要直接拉到 33 甚至更高，厂商 SDK 在高版本上如果没适配，会出现获取设备信息等接口被系统限制的“翻车”现象。当你不确定用什么版本时，优先看 demo 自带的gradle文件，那里面的版本组合已经验证过。

4. 在 demo 里把账号登录跑通：初始化、请求参数与 Unity 回调桥

4.1 先搭一个统一入口类来管理 SDK 生命周期

账号登录不该散落在各个业务脚本里。我在模拟项目X里习惯写一个HMSBridge类，作为 Unity 层和 HMS SDK 之间的唯一入口。它负责初始化、登录、登出和回调分发。这样做的原因是 HMS SDK 的初始化和账号生命周期天然是全局的，如果每个页面各自init，不仅慢，还可能重复注册回调导致事件被多次触发。

C# 侧的建议结构如下：

using UnityEngine; using Vendor.Hms; // 真实工程里替换为厂商 SDK 暴露的命名空间 public class HMSBridge : MonoBehaviour { public static HMSBridge Instance { get; private set; } private bool isInitialized; void Awake() { if (Instance != null && Instance != this) { Destroy(gameObject); return; } Instance = this; DontDestroyOnLoad(gameObject); } public void InitSDK() { if (isInitialized) return; // 检查设备上是否存在 HMS Core 服务 bool available = HMSCoreService.IsAvailable(); Debug.Log("[HMSBridge] HMS available: " + available); if (available) { HMSAccountService.Init(); isInitialized = true; } } public void Login() { if (!isInitialized) { Debug.LogWarning("[HMSBridge] SDK not initialized"); return; } HMSAccountService.StartSignIn(); } }

这段代码里，DontDestroyOnLoad保证场景切换时实例还在；HMSCoreService.IsAvailable()是一个前置检查，避免在服务不可用的设备上强行调用；StartSignIn会拉起原生的账号登录页面。我的建议是：Awake里不要立即调用InitSDK，因为某些 ROM 上 HMS Core 服务的绑定需要时间，可以放在第一次点击登录按钮时再初始化，或者在Start协程里稍微延迟一帧再初始化。

4.2 拨号键登录与自定义请求参数

账号登录有两种常见入口：一键登录和自定义账号密码。demo 里通常先实现一键登录，因为它的链路最简单。调用前，业务方通常要构造一个请求对象，把需要申请的权限字段填好。下面这段代码展示登录请求的典型构造方式：

using Vendor.Hms.Request; using Vendor.Hms.Model; public void RequestLoginByPhone() { var options = new AccountLoginOptions { LoginType = "phoneNumber", // 手机号一键登录 ScopeList = new[] { "openid", "email" }, // 需要授权的数据范围 IsFastLogin = true, // 是否走静默快速登录 ForceLogin = false // 是否强制重新输入账号 }; HMSAccountService.StartSignIn(options, OnLoginResult); } private void OnLoginResult(AccountResult result) { if (result.IsSuccess) { Debug.Log("[HMSBridge] login success, code=" + result.AuthCode); } else { Debug.LogError("[HMSBridge] login failed, code=" + result.ErrorCode); } }

LoginType决定了拉起的是不是一键登录页面；ScopeList决定你向用户申请了哪些数据授权，只申请登录必要的最小范围，能降低用户在授权页取消的概率；IsFastLogin为true时，如果用户之前授权过，可能不会弹页面而直接返回成功；ForceLogin为true时则强制走一遍完整登录。这几个参数不是越全越好，我在接入第一个 demo 时把ForceLogin设成了true，结果每次点击都要求输入密码，体验很差。后面改成false，用户之前登录过就能快速回到场景。

4.3 原生回调到 Unity 的桥接：UnitySendMessage 与线程切换

HMS SDK 的原生回调发生在 Java 层，Unity 侧要收到结果，靠的是UnitySendMessage。这条桥的完整链路是：Java 层拿到登录结果后，调用UnityPlayer.UnitySendMessage(gameObjectName, methodName, jsonString)，然后 Unity 场景里对应物体上的方法被触发。把这条链路拆开看，有三个最容易出错的点。

第一，gameObjectName必须和场景里实际存在的物体名完全一致，包括大小写。第二，接收方法必须是public void且参数是string或object，静态方法虽然也能接收，但最好不要和实例方法混用。第三，回调可能来自非主线程，直接操作UnityEngine.Object可能引发诡异错误。下面是一段典型的 Java 侧回调代码（示意）：

// 登录成功后，把结果回传给 Unity 场景里的 "EventSystem" UnityPlayer.UnitySendMessage("EventSystem", "OnNativeLoginResult", jsonResult.toString());

C# 侧对应的接收方法：

public void OnNativeLoginResult(string message) { // 先切到主线程再处理 UI 更新 UnityMainThreadDispatcher.Instance.Execute(() => { var json = JsonUtility.FromJson<LoginResultData>(message); Debug.Log("[HMSBridge] got native result: " + json.errorCode); }); }

这里使用UnityMainThreadDispatcher或者自己在MonoBehaviour.Update里维护一个消息队列都行。我建议不要在OnNativeLoginResult里直接改 UI 文本或刷新动画，因为回调线程不一定是主线程。为了省事，也可以把消息包成对象塞进队列，由Update统一处理，这样风险最小。

4.4 验证链路是否通：看日志、看返回码、看 UI 状态

代码写完后，先在编辑器里跑是看不出来什么的，因为 HMS SDK 依赖真机。把工程构建成 APK 装到支持 HMS Core 的设备上，然后用adb logcat抓日志：

adb logcat -s Unity HMSBridge HMSKit

-s后面的标签可以自己加，如果你的 demo 在代码里打了[HMSBridge]这样的日志，直接搜这个标签就能过滤出海量无关信息。一个连接正常的登录流程，日志里至少会出现三条关键输出：初始化成功、拉起登录页、回调结果。如果看到初始化成功但点击登录没反应，问题多半在签名或配置json；如果看到登录拉起但回调丢失，问题多半在UnitySendMessage的消息名或 GameObject 是否常驻。

返回码也是重要的定位线索。不同的错误码对应着不同的失败位置，常见的有：

需要注意的是，返回码会随 SDK 版本调整，我这里只列出最通用的一组。当你看到不认识的代码时，先搜索厂商的错误码说明，再去看代码。很多开发者在这一步把精力花在改代码上，最后发现只是 HMS Core 版本太旧，升级一下服务就好了。

5. 接入 HMS SDK 的避坑与排查：五条血泪经验

5.1 坑 1：设备上运行时提示 HMS Core 版本过旧，接口返回 907135705

现象：同样的 APK，在一台设备上登录正常，在另一台设备上点击登录按钮却弹窗要求升级 HMS Core，或者接口直接返回 907135705。

原因：HMS Core 作为系统级服务，在不同手机上的版本差异很大。部分设备出厂预装版本较老，新版 SDK 调用的接口在旧版本上不存在，于是返回版本不兼容错误。

解决：在初始化之前做能力检查，不要直接忽略错误继续调用。我一般会在InitSDK里多写一步：如果HMSCoreService.IsAvailable()返回false，就跳转到厂商应用市场升级 HMS Core。这个跳转动作需要打开应用市场的详情页，你可以在原生层处理，也可以把跳转放在 Unity 里引导用户。注意不要试图在代码里静默升级，系统服务不是普通应用，跨应用安装受限。

5.2 坑 2：Gradle 构建时提示找不到 HMS SDK 依赖

现象：Unity 构建到 Gradle 阶段失败，日志里有Could not resolve vendor.hms:account:5.x或Failed to resolve的提示。

原因：HMS SDK 的依赖仓库没有添加到mainTemplate.gradle的repositories里。Unity 默认只配置了 Google 和 Maven Central，厂商的私有仓库地址不在其中，所以 Gradle 根本找不到依赖。

解决：在mainTemplate.gradle的allprojects.repositories中添加厂商仓库地址。如果你使用的是国内镜像仓库，注意镜像的更新频率，某些镜像延迟大，刚发布的 SDK 版本会拉不到。我的做法是优先使用官方仓库，如果网络访问不到，再切换到稳定版本并固定版本号，避免在开发过程中依赖悄悄漂移。这个坑表面上是网络问题，本质上是配置缺失。

5.3 坑 3：登录成功但 Unity 场景里收不到回调

现象：原生登录页面显示了，用户输入账号密码并登录成功，页面关闭后 Unity 的OnNativeLoginResult却一直没有被调用。

原因：最常见的是UnitySendMessage的目标物体被销毁了，或者目标物体名字对不上。另一个容易被忽略的原因是从原生层回传时使用了中文字符串，而 Unity 的JsonUtility对中文转义支持不太友好，回调其实到了，但解析报错导致看起来像没收到。

解决：先把游戏物体设为常驻，DontDestroyOnLoad可以保证场景切换后它还存在；再检查回调方法名是不是公共方法；最后用Debug.Log(rawJson)把原始消息打印出来看一眼。如果回调到了但解析失败，日志里会有JsonUtility的报错提示。常见做法是回传 JSON 时把中文字段做一次UrlEncode或统一转成 ASCII，减少编码上的不确定性。

5.4 坑 4：混淆或裁剪之后回调失效，甚至直接崩溃

现象：开发模式下一切正常，一旦开启 minify 或代码裁剪，登录回调就丢了，有些设备上直接闪退。

原因：HMS SDK 的很多类是通过反射被 Unity 调用的，混淆工具无法识别这些动态引用，会把类名、方法名改掉，导致运行时找不到回调入口。SDK 原生的proguard规则如果没有被合并到主工程的混淆配置里，这个问题必然出现。

解决：在主工程的proguard-rules.pro里把 HMS SDK 相关类加入 keep 名单。通常厂商 SDK 会自带一份混淆规则，你需要确认它有没有被打包进去。如果没有，手动加一行：

-keep class vendor.hms.** { *; } -keepclassmembers class * { @UnitySendMessage <methods>; }

上面这两行规则分别保住 SDK 核心类和所有标记了@UnitySendMessage的方法。理解它的逻辑不是为了背配置，而是为了排查：当你的项目还有直播模块、广告模块时，它们的混淆规则也可能和你加的规则冲突。我遇到过一次情况是规则写得太宽，把 Unity 的 MainActivity 也 keep 了，结果启动速度明显变慢。

5.5 坑 5：签名指纹不匹配，鉴权一直失败

现象：登录拉起后，很快被登出或者返回 6008。开发机没问题，换一台新机器打包就失败。

原因：开放平台上登记的是旧开发机的 debug 签名 SHA-256 指纹，而新电脑构建时用了另一个 keystore。HMS SDK 在鉴权时会把应用签名上报给服务端，服务端比对不一致直接拒绝。

解决：每次更换电脑或更换 keystore 时，重新计算 SHA-256 并更新到控制台。这里给一个验证指纹的命令：

keytool -list -v -keystore your-release.keystore -alias your-alias -storepass your-pass

把输出里的SHA256:一行复制到开放平台，注意去掉冒号和换行。从那以后，我每次换电脑都会第一时间跑一遍这条命令，并把这个动作写进项目交接清单。签名问题有个特点：它不在构建时报错、不在启动时报错，只在你登录那一刻才暴露，所以定位成本非常高。

6. 把 demo 改造成正式项目：一个必须养成的验证习惯

6.1 从 demo 到正式工程的增量改造顺序

demo 跑通只是起点。改造正式工程时，我的顺序是：先保持 demo 的包名与签名不变，把整套 SDK 以最小依赖形式合并进来，跑通一次测试包；然后逐项替换包名、签名、开放平台配置；最后才接入业务登录逻辑。这个顺序反着走很容易把“SDK 问题”和“业务代码问题”混在一起。

替换过程中的关键检查项包括：PlayerSettings里的包名、开放平台应用包名、agconnect-services.json里的应用 ID、签名文件这三者是否指向同一个应用。任何一项不一致，都会让你在调试时产生自我怀疑。你会发现明明代码和 demo 一样，但就是登录不了，这时候不要反复改代码，先把四张身份信息对一遍。

6.2 三端日志对照：我的固定验证动作

我给自己定的一个“强制闭环”是：每次接完一个厂商 SDK，都要在三处同时开日志。第一处是 Unity 的Debug.Log，看业务层日志；第二处是adb logcat，看 Android 原生层日志；第三处是开放平台的接口日志，看服务端是否收到请求。三端日志的时间戳对齐后，问题能立刻圈定到某一端，不用再靠猜。

从那以后，我每次接这类 SDK 都会强制走一遍“先跑通 demo、再动配置、最后确认三端日志对齐”的流程，翻车的概率确实低了很多。希望这篇能帮你少走几趟弯路，省下的时间去处理真正有挑战的业务问题。

本文还有配套的精品资源，点击获取