企业官网建设流程全解析

ARFoundation集成SenseAR这件事，最早是我们组里的一次“被迫尝试”。当时手头有一套AR试鞋应用，一直跑在ARFoundation上，跨平台抽象确实省心，iOS端和Android端一套代码就能出包。但问题出在部分中低端安卓机型上：地面平面的识别结果不稳定，3D鞋模放上去之后会轻微悬空或歪斜，用户拿手机转两圈就明显感觉“模型没站在地上”。我试过调置信度阈值、换识别模式，收效都有限。

后来拿到SenseAR的Unity集成包，在同样的真机上做了对比，同一个房间、同一个地面，SenseAR的平面检测稳定性明显好一截。当时的直接想法是把整套AR能力换成SenseAR——但真动手评估之后发现，上层的交互逻辑、生命周期管理、资源加载都是按ARFoundation接口写的，推倒重来不仅工作量巨大，后续维护也是双份成本。所以最后选了一条折中路：保留ARFoundation做上层框架，把SenseAR作为底层算法引擎接进来。

这篇是第一篇，重点讲清楚三件事：为什么值得做这种集成、环境准备阶段要注意什么、以及第一版桥接架构怎么搭、怎么跑通第一个AR场景。如果你也在做类似的事——手里有一套ARFoundation项目，又拿到一个第三方AR引擎要融进去——这篇应该能帮你省不少试错时间。

1. 这个集成的真实动机：两个引擎各有各的“主场”

1.1 我们的场景与真正的痛点

AR试鞋这个场景，听起来简单，实际对上层的稳定性要求很高。用户把手机对准地面，系统需要快速识别出水平平面，然后把鞋模稳定地“放”上去。这里有两个硬指标：识别速度要够快，基本一秒内要出结果；位置要够稳，手机轻微移动时鞋模不能跟着乱跳。

ARFoundation默认提供了一整套统一的AR工作流，从会话生命周期到平面检测、相机画面渲染，都是封装好的。优点是开发效率高，缺点也很明显：底层能力完全依赖系统级AR服务，不同机型、不同系统版本的算法表现差异很大。我们在测试机上梳理过，大概有15%左右的机型会出现平面识别不稳定的情况，模型悬空、识别失败、掉跟踪是主要问题，集中在中低端设备上。

这个痛点不是靠调UI层能解决的，属于算法层的差距。SenseAR在平面检测上采用的是另一套算法管线，在某些设备上确实能补上这个短板。

1.2 为什么舍不得丢掉ARFoundation

可能有人会问：既然SenseAR效果好，为什么不整个换掉？

我的回答是：方案选型不能只看单点效果，要看整个工程的开销。ARFoundation的好处在于，它把所有AR概念统一成了同一个对象模型——ARSession、ARCameraManager、ARPlaneManager、ARTrackable。这些接口不区分你用的是哪家底层能力，切换底层的时候，上层代码基本不用动。

这个价值在做多端版本的时候特别明显。我们的AR试鞋应用不只在Android端跑，iOS端也要同步发版。如果全部迁到SenseAR，意味着iOS端也要重新找一套对应能力，否则两端代码就分叉了。而桥接方案可以让两端继续共用上层的交互和业务逻辑，只是底层能力各自适配，维护成本要低得多。

1.3 集成的边界到底画在哪里

说得直白一点，这次集成不是“用SenseAR替换ARFoundation”，而是在ARFoundation的工作流里，把底层算法换源。

ARFoundation负责的还是那几件事：摄像头权限管理、AR Session生命周期、Unity侧的渲染管线。SenseAR负责的是它更强的那块：底层SLAM、平面识别、位姿估计。我们需要做的，是写一层翻译代码，把SenseAR给出的结果映射成ARFoundation上层能直接消费的数据。

判断你这个项目适不适合做类似集成，我有一个简单清单：

• 当前默认AR框架在目标机型上是否真的有明显短板？
• 第三方引擎的能力是否能覆盖这块短板，且差距值得投入开发成本？
• 上层业务是否已经大量依赖现有框架的接口，导致整体替换成本不可接受？
• 是否有足够的真机测试资源，能支撑双引擎长时间的稳定性验证？

如果这四条里能对上三条，那这条集成路线基本是值得试的。

2. 环境准备阶段最容易翻车的三件事

2.1 Unity、ARFoundation、SenseAR的版本对应关系

这个坑我替你们踩过了：版本不匹配是绝大多数编译报错和运行崩溃的来源。

我先说明一下我们最终定下来的版本组合，供参考：

这里要特别提醒一点：ARFoundation的不同小版本，底层接口会有微调。比如某些版本中ARPlaneManager的事件回调时机变化了，某些版本对自定义渲染纹理的支持方式不同。另外SenseAR SDK通常是通过相机纹理和位姿数据来对接Unity渲染层的，如果ARFoundation版本太新，可能会出现渲染纹理获取方式对不上的问题。

还有一个小细节：Unity的Package Manager有时候会自动把ARFoundation解析成和你预期不同的版本，建议在项目里加一个packages-lock.json的版本固定，并且把不需要的ARFoundation扩展包（比如ARCore/ARKit的specific package）暂时都关掉，排除干扰项。

2.2 插件包冲突：最常见的隐性地雷

同时导入多套AR相关SDK，容易出现符号冲突。我们第一次集成时，导入SenseAR的Unity包之后，编译直接报了大量重复定义错误，主要集中在AndroidX库上——ARFoundation及其底层依赖会引入一个版本的AndroidX，SenseAR包又带了一套，Gradle合并时直接打起来。

解决思路分三步，实际操作下来很有效：

1. 先建一个干净的Unity工程，只导入ARFoundation和SenseAR，排除业务代码干扰，确认基础编译能过。
2. 比对两个SDK的依赖关系，把重复的AndroidX库统一保留一个版本，一般以官方较新的版本为准。
3. 如果SenseAR提供的是Android模块（AAR），优先手动放到Assets/Plugins/Android下，并在Player Settings里关掉默认的AndroidX自动解析，改成手动管理依赖。

另外不要忽略Manifest合并问题。SenseAR通常需要在AndroidManifest里声明自己的Activity或Service，两个SDK的Manifest节点偶尔会产生冲突，建议用合并后的最终Manifest检查一遍关键节点是否都在。

2.3 权限、机型适配与初始化前置条件

SenseAR这类第三方AR引擎有一个特点：它对机型有明确的适配列表，不是所有Android设备都能跑。这一点在上项目前必须确认。

我们做的最小权限配置如下：

• CAMERA：必须，AR功能的基础
• INTERNET：部分引擎用于联网验证授权
• ACCESS_NETWORK_STATE：检查网络状态
• WAKE_LOCK：防止识别过程中屏幕休眠

除了权限，机型适配校验也很关键。SenseAR一般会提供一个设备能力检测接口，需要在初始化前先调用，根据返回值判断当前设备是否支持。根据我们的经验，这个检测结果不能单看Unity日志——某些型号在引擎内部校验失败后日志是静默的，建议在真机上专门写一个UI页面展示检测结果，方便测试阶段快速排查。

最后是Gradle配置。建议把minSdkVersion设到23以上，targetSdkVersion跟随Unity默认版本即可。SenseAR某些算法对CPU指令集有要求，部分老机型是armeabi-v7a架构，需要在Player Settings里确认CPU架构勾选是否包含了目标真机的指令集。

3. 架构选择：为什么我建议“桥接”而不是“替换”

3.1 三种可行方案对比

在决定具体实现前，我把可行方案列了一遍，最后选定了方案B。这里把三种方案整理成表格，方便对比：

方案B胜在改动可控——我们不需要动任何业务层的ARFoundation调用，只需要把底层的数据来源换掉。代价是多加一层桥接代码，以及可能要处理双引擎同时活动时的资源冲突。

3.2 桥接层的核心职责：做“翻译官”

桥接层要做的事，本质上是一个翻译过程。

SenseAR给出的底层结果和ARFoundation上层需要的结构并不一致。比如SenseAR识别出一个平面，可能返回的是引擎自己定义的坐标系统、平面参数矩阵；而ARFoundation的ARPlaneManager需要的是它自己定义的BoundedPlane。桥接层就要完成这个映射：把引擎的平面数据转换成ARFoundation的ARTrackable结构，再交给上层业务使用。

我用一个生活化的类比来说明：ARFoundation像是一个只讲普通话的经理，SenseAR只讲方言。桥接层就是那个翻译——经理该指挥还是指挥，方言那边干活的效率还是一样高，但双方的信息能流畅互通。

这个翻译层还有一个重要职责：位姿数据的同步。ARFoundation自身的ARSession会维护一套Unity世界坐标下的相机位姿，SenseAR也有自己引擎内部的相机位姿。如果不做校准，两套坐标系会打架，最典型的表现就是画面里模型在漂移，或者相机转动时追踪结果不对。

3.3 桥接层的代码骨架：一个示例结构

下面是我在工程里实际使用的桥接层结构，类名是我自己封装的，不代表SenseAR官方API，你接入时要以自己拿到的SDK为准：

public sealed class ARFoundBridgeManager : MonoBehaviour { [SerializeField] private ARSession arSession; [SerializeField] private ARCameraManager arCameraManager; [SerializeField] private ARPlaneManager arPlaneManager; private ISenseARClient senseClient; private bool isBridging; private void Start() { // 1. 先初始化SenseAR客户端（自定义封装） senseClient.Init(); // 2. 订阅SenseAR的帧数据和平面结果 senseClient.OnPlaneDetected += OnSensePlaneDetected; senseClient.OnFramePose += OnSenseFramePose; // 3. 等待初始化回调后再启动ARFoundation senseClient.OnReady += OnSenseReady; } private void OnSenseReady() { arSession.enabled = true; arCameraManager.enabled = true; arPlaneManager.enabled = true; isBridging = true; } private void OnSensePlaneDetected(SensePlaneResult plane) { // 将SenseAR的平面结果转换为ARFoundation的BoundedPlane结构 ARPersistenceBridge.TranslatePlane(plane, out var translatedPlane); arPlaneManager.UpdatePlaneData(translatedPlane); } private void OnSenseFramePose(SensePose pose) { // 将SenseAR的相机位姿同步到ARFoundation的跟踪数据中 if (isBridging) { arCameraManager.UpdateExternalPose(pose.ToUnityPose()); } } }

这段代码的核心思想是：ARFoundation的ARSession正常启动，但底层位姿和平面数据不来自系统AR服务，而是来自SenseAR。代码里我并没有去接管Unity的渲染管线，只是把数据源替换了，这样对业务层是透明的。

要提醒的是，这段代码只是一个结构示范。实际对接的时候，你需要仔细查阅SenseAR SDK里关于“外部位姿注入”“平面数据上报”的接口文档，不同版本的接口差异确实比较大。

4. 从零跑通首个AR场景的实操记录

4.1 导入与工程配置的分步清单

实际动手的第一步，是搭一个干净的Demo工程。这个步骤看起来基础，但很关键：不要直接在原有大型工程里试，否则分不清报错是业务引入的还是集成引入的。

我的操作步骤是这样：

1. 新建Unity工程，选择3D模板，版本固定在我们定好的2021.3 LTS。
2. 通过Package Manager安装ARFoundation 4.2.x，同时勾选对应的XR Plugin Management模块。
3. 手动导入SenseAR的UnityPackage，这里注意只勾选核心运行时模块，不要勾Demo场景和示例资源。示例场景里通常会自带相机Rig和旧版本依赖，导入后会和ARFoundation的新建场景冲突。
4. 把SDK自带的Android依赖包（AAR或JAR）复制到Assets/Plugins/Android目录下。
5. 检查AndroidManifest合并结果，确认权限和SDK组件声明都已经合入。
6. 在Player Settings中设置Minimum API Level为23以上，并将Graphics API保持为OpenGLES 3.0或更高版本。

这几步做完之后，建议先做一个最简单的编译验证，确认工程能正常出包。别急着写桥接逻辑，先跑一次空包。

4.2 初始化时序：先SenseAR，后ARFoundation

初始化顺序这个事，当初差点把整个项目带偏。

最开始的写法是让SenseAR和ARFoundation的ARSession在同一个帧里同时启动，结果出现了两个问题：一是摄像头权限竞争，两个模块抢相机会话，画面出现黑帧；二是位姿数据冲突，两套坐标系同时向Unity汇报，渲染结果随机抖动。

后面整理出的标准时序是这样的：

1. 请求相机权限（必须等用户授权回调成功）。
2. 调用SenseAR的设备能力检测接口，判断当前真机是否支持。
3. 初始化SenseAR引擎，等待其内部完成SLAM初始化。
4. 收到SenseAR的Ready回调后，再启用ARFoundation的ARSession。
5. ARSession启动后再依次启用ARCameraManager和ARPlaneManager。

这里最核心的一点是：SenseAR必须作为“主时钟”先启动，ARFoundation作为辅助方后启动。因为SenseAR的算法管线一旦启动就会开始跟踪相机位姿并按帧回调，ARFoundation启动后直接消费这些已有数据，而不是自己再另起一套跟踪逻辑。

这个顺序还有一个额外的好处：方便降级。如果设备不满足SenseAR的适配要求，初始化会提前失败，这时可以退回到ARFoundation默认能力，保证应用不会直接黑屏或崩溃。

4.3 背景纹理挂接与首个平面验证

初始化跑通之后，下一个要解决的问题是：让他能看见SenseAR的画面。

ARFoundation默认的ARCameraBackground会去系统AR能力那边拿相机纹理，但既然底层能力已经换成了SenseAR，ARCameraBackground默认那套逻辑就拿不到数据了。解决办法是：把SenseAR输出的相机纹理绑定到CameraBackground使用的材质上。

这个步骤在不同SDK里差异比较大，我只说通用思路：SenseAR通常会提供相机纹理接口，拿到的是一个Unity纹理对象，然后你需要把ARCameraBackground的目标材质替换成能消费这个纹理的着色器。注意纹理格式要匹配，我遇到过SenseAR输出YUV格式，而默认材质只认RGBA，直接显示出来就是灰绿色的异常画面。

第一次验证成功，是在一个很朴素的场景里完成的：镜头对准地面，Code里监听ARPlaneManager的planesChanged事件，检测到平面后在平面中心点实例化一个Cube。当时在测试机上看到Cube稳稳“躺”到地板上，我知道桥接层已经起效果了。

5. 这一周我踩过的坑：从初始化失败到追踪静止

5.1 设备能力判断在真机上“失效”

第一个坑出现在设备校验环节。在编辑器里调用SenseAR的设备检测接口时返回正常，装机到真机上后，代码里拿到的结果却是“不支持”。

排查后发现，问题不在SDK，而在于我把设备校验放在了相机权限授权之前。某些引擎在硬件检测阶段需要申请相机句柄，权限没给到就进入检测，会导致检测逻辑直接走异常分支。修正方式很简单：先明确拿到相机权限，再调用设备检测接口。

另一个相关点是：设备校验结果最好用引擎自带的状态码去判断，不要只判断布尔值。部分机型虽然适配，但可能处于低电量模式，引擎会返回一个“性能受限”的状态码，这时候启动SLAM虽然能跑，但识别精度会下降。这一步放在正式版本里，可以提前预警。

5.2 黑屏但日志一切正常：纹理格式与渲染时序问题

集成过程中最折磨人的问题就是黑屏。日志没有报错，ARSession状态正常，平面识别的事件也有数据回调，但屏幕就是黑的。

我花了大半天才定位到根因——渲染线程的纹理时序问题。SenseAR输出的相机纹理是在引擎自己的渲染线程上更新的，而Unity的相机背景渲染在另一个线程，两边没有一个同步信号。结果就是时不时出现空纹理帧，表现就是黑屏或者画面每隔几十帧闪一下黑。

解决方式是把纹理更新放到Unity的渲染线程上执行，具体来说是使用OnBeforeRender或者直接订阅ARFoundation的frameReceived事件，确保在Unity渲染该帧之前，已经拿到了SenseAR最新的一帧纹理。简单说就是：先让SenseAR产帧，Unity在渲染前取走，顺序不能反。

5.3 画面会动但追踪物在“原地飘”：矩阵覆盖问题

还有个干扰现象：背景画面看起来是正常移动的，但已经放置在地面上的Cube却在原地小幅抖动，像是粘了根弹簧。

这个问题排查到最后，是位姿矩阵更新冲突。ARFoundation的ARSession和SenseAR都在向同一个相机Pose字段写数据，你以为覆盖成了SenseAR的数据，但实际上ARFoundation在某个内部逻辑里又把系统AR能力算出来的旧位姿写回去了。两套数据交替出现，表现就是追踪物在两点之间来回抖。

解决方式是彻底关掉ARFoundation默认的位姿计算路径，明确让ARSession进入“外部位姿驱动”模式。这个能力在不同版本的ARFoundation里叫法不同，我们用的4.2.x中有对应的开关可以设置，打开后位姿完全由SenseAR通过桥接层注入。这里请大家仔细阅读自己所用ARFoundation版本的更新说明，路径不对会导致设置无效。

5.4 一条完整的排查思路：从权限到坐标系逐步收窄

如果你在集成时也遇到了类似问题，我建议按这个顺序排查，能少走很多弯路：

1. 先确认相机权限已授权，这是最底层的前提。
2. 确认SenseAR初始化回调正常触发，日志中无明显错误状态码。
3. 确认设备适配检查通过，排除引擎不支持当前机型的可能性。
4. 单独验证SenseAR的原生Demo能正常运行，判断SDK本身是否健康。
5. 确认相机纹理能正常错绑到Unity材质上，可以先输出一张静态纹理图做检查。
6. 最后再检查位姿矩阵同步，验证Cube在静止状态下是否真的稳定在平面中心。

按这个链路走，大部分问题都能定位到具体的某一层，而不是在多个变量之间乱猜。

6. 第一篇结束前，先交代一下后续计划

第一轮的成果，是让SenseAR的平面检测能力成功“接入”到ARFoundation项目里，并且跑通了从相机画面到平面识别到Unity对象放置的完整链路。至于SenseAR更强的能力——例如更细粒度的人脸关键点跟踪、手势识别、以及场景重建——目前还没有做深度集成，这些计划留到系列第二篇。

在进入第二篇之前，我建议你先把这几件事准备好：

• 准备至少两台不同厂牌、不同性能档位的Android测试机，优先覆盖引擎适配列表里存在差异的机型。
• 把SenseAR SDK的日志开关打开，尤其是verbose级别的日志，方便后续排查坐标系、平面置信度的问题。
• 对当前能跑的版本做一个固定备份，后续每改一步都能回退对比。

集成第三方AR引擎这件事，难的不是“怎么把包导进去”，而是“怎么让两套系统在边界上不打架”。这篇记录的每一步，基本都是在跟这种边界问题打交道。第二篇我会重点展开平面位姿同步的矩阵细节，以及我们是如何在双引擎共存状态下解决坐标系漂移的。