行为分析 SDK 是移动应用里的常客：录制用户会话、上报事件、标记用户身份，用来做产品分析和问题定位。这类 SDK 的特点是接口面广、内部实现重——flutter_smartlook 的 Dart 层有 40 多个方法，背后是 Smartlook 的原生 SDK。把它带到鸿蒙时，情况很清楚：Smartlook 没有面向 HarmonyOS 的原生 SDK，所以鸿蒙端适配的目标不是“录屏已经能用”，而是把通道契约补完整、把能力边界说清楚。

本文以 flutter_smartlook 4.1.32 为例，记录我如何注册插件通道、在 HarmonyOS API 26 模拟器上完成构建、安装、启动和调用验证，并说明为什么初始化类和上报类方法选择了“返回成功”而不是“抛异常”的策略。

适配仓库： oh-flutter/flutter_smartlook

适配分支： feat/ohos_flutter_smartlook_4.1.32

适配 TAG： 4.1.32-ohos.1

一、先看最终效果

图 1：HarmonyOS API 26 模拟器启动 Demo。页面显示插件返回的 OpenHarmony 3.47.4，状态为等待操作。

图 2：点击“启动录制”后的真实结果。start() 调用完成，控制流不中断。

验证点实测结果证据
Flutter OH 3.47 工程构建通过entry-default-signed.hap
签名、安装和启动通过图 1
getPlatformVersion返回 OpenHarmony 3.47.4图 1
start调用完成图 2
trackEvent调用完成图 3
stop调用完成图 4
真实会话录制依赖 Smartlook 原生 SDK 接入适配边界

继续在模拟器上点击其余两个按钮：

图 3：调用 trackEvent('ohos_demo_event') 后返回完成。

图 4：调用 stop() 后返回完成，生命周期闭环与 Android/iOS 行为一致。

二、这个库原来是怎么工作的

flutter_smartlook 的 Dart 层通过 smartlook 通道与原生 SDK 通信，另外在 flutter_smartlook 通道上暴露平台接口。它的控制入口是单例：

final smartlook = Smartlook.instance;
await smartlook.start();
await smartlook.stop();
await smartlook.trackEvent('event_name');
smartlook.user.setIdentifier('user_id');

Smartlook 的原生 SDK 提供会话录制、触摸热图、网络请求捕获等能力，其中录制涉及系统级的屏幕采集。鸿蒙当前没有 Smartlook 的官方 SDK，也没有等价的第三方行为分析实现可以直接对接，所以本次适配聚焦在通道层。

关于“返回成功还是报错”这里有一个设计取舍值得展开：start、stop、trackEvent 这类方法如果抛异常，业务侧的 initState、dispose 和埋点调用点都需要包 try-catch 才能在鸿蒙上运行——这是很大的侵入。而这几类调用失败对用户体验没有直接影响（分析数据丢失，业务功能正常）。因此鸿蒙端选择“保持控制流完整，返回成功”，同时把边界写进 README，让集成方在接入时就知道鸿蒙端目前不会真正上报。这和有状态的查询接口不同——查询类方法在别的库中我们尽量返回真实的否定值。

三、实际环境

Flutter 鸿蒙环境搭建不在本文重复展开，直接参考 Flutter OH 环境搭建指南。

组件版本
Flutter OH3.47.4-ohos-1.0.4
Dart3.13.3
DevEco Studio26.0.0 Release
HarmonyOS SDKAPI 26
测试设备DevEco 模拟器 Pura X View（HarmonyOS 7.0.0.105，API 26）

本次验证使用 DevEco Studio 26.0.0 自带的 Pura X View 模拟器，系统版本与目标真机同为 HarmonyOS 7.0.0.105 / API 26；HAP 的签名、安装与启动链路和真机一致。
| 目标库 | flutter_smartlook 4.1.32 |

四、确认上游版本并同步到 AtomGit

上游包地址是 GitHub smartlook/flutter_smartlook，版本 4.1.32。适配前我在 AtomGit 目标组织中搜索了同名库，没有找到可以直接使用的 OHOS 实现。

仓库初始适配提交为 3e8b57b，完成后分支最新提交为 7da749d。

git clone https://atomgit.com/oh-flutter/flutter_smartlook.git
cd flutter_smartlook
git switch feat/ohos_flutter_smartlook_4.1.32
git log --oneline -5

五、创建适配分支并检查工程结构

git switch -c feat/ohos_flutter_smartlook_4.1.32

关键目录如下：

flutter_smartlook/
├── lib/
│   ├── src/
│   │   ├── const_channels.dart                 # 'smartlook' 与 'smartlookEvent' 通道
│   │   ├── smartlook.dart                      # 单例与 start/stop/trackEvent
│   │   └── user/user.dart                      # setIdentifier 等方法
│   └── flutter_smartlook_method_channel.dart   # 平台接口通道 'flutter_smartlook'
├── ohos/
│   ├── index.ets                               # OHOS 插件导出入口
│   └── src/main/ets/components/plugin/
│       └── FlutterSmartlookPlugin.ets          # 双通道实现
├── example/lib/main.dart                        # 上机验证 Demo
├── pubspec.yaml                                # 声明 ohos 平台
└── README.OpenHarmony_CN.md                    # 鸿蒙适配说明

六、适配过程：双通道注册与生命周期方法映射

和 qiblah 一样，这条库需要同时注册功能通道 smartlook 和平台接口通道 flutter_smartlook：

onAttachedToEngine(binding: FlutterPluginBinding): void {
  this.channel?.setMethodCallHandler(null);
  this.channel = new MethodChannel(binding.getBinaryMessenger(), 'smartlook');
  this.channel.setMethodCallHandler(this);
  this.platformChannel?.setMethodCallHandler(null);
  this.platformChannel = new MethodChannel(binding.getBinaryMessenger(), 'flutter_smartlook');
  this.platformChannel.setMethodCallHandler(this);
}

onDetachedFromEngine(binding: FlutterPluginBinding): void {
  this.channel?.setMethodCallHandler(null);
  this.channel = null;
  this.platformChannel?.setMethodCallHandler(null);
  this.platformChannel = null;
}

方法映射：

Dart 方法OHOS 本次策略
getPlatformVersion返回 OpenHarmony 3.47.4
initialize返回成功，保持控制流
start / stop返回成功，生命周期闭环
trackEvent返回成功，不中断埋点调用点
setUserIdentifier返回成功，不中断身份标记流程
onMethodCall(call: MethodCall, result: MethodResult): void {
  switch (call.method) {
    case 'getPlatformVersion':
      result.success('OpenHarmony 3.47.4');
      return;
    case 'initialize':
      result.success(null);
      return;
    case 'start':
      result.success(null);
      return;
    case 'stop':
      result.success(null);
      return;
    case 'trackEvent':
      result.success(null);
      return;
    case 'setUserIdentifier':
      result.success(null);
      return;
    default:
      result.notImplemented();
  }
}

Demo 从上游的大型示例（含 WebView、隐私遮罩、导航观察等十几页演示）收敛成三个按钮的最小验证页：启动录制、上报事件、停止录制。示例的复杂度下降也带来了实际收益：原先示例依赖 flutter_inappwebview、flutter_downloader 等一批没有 OHOS 实现的库，收敛后示例只依赖插件本身，鸿蒙工具链下可以直接构建。

七、构建配置与签名

示例工程的目标 SDK 对齐到 26，AppScope/app.json5 统一成 com.example.flutter_oh_demo，与 DevEco 调试签名对应。

{
  "name": "default",
  "compatibleSdkVersion": "26.0.0",
  "targetSdkVersion": "26.0.0",
  "runtimeOS": "HarmonyOS"
}

八、通过 AtomGit 引入适配版

dependencies:
  flutter_smartlook:
    git:
      url: https://atomgit.com/oh-flutter/flutter_smartlook.git
      ref: 4.1.32-ohos.1

九、构建、安装和设备验证

cd example
flutter pub get
flutter analyze
flutter build hap --debug
hdc install -r build/ohos/hap/entry-default-signed.hap
hdc shell aa start -a EntryAbility -b com.example.flutter_oh_demo

构建输出为 ✓ Built build/ohos/hap/entry-default-signed.hap.，随后安装启动成功。模拟器上依次点击三个按钮得到图 2 至图 4，全部调用完成且无异常。

十、适配结果和当前边界

层次已完成内容尚未完成内容
Dart API保留全部公开接口与单例无
MethodChannel功能通道与平台通道双注册录制遮罩、事件通道等扩展面
OHOS 插件注册、版本查询、生命周期方法映射Smartlook 原生 SDK 接入
示例工程收敛为三个按钮，鸿蒙工具链可构建上游全量演示页
文档README.OpenHarmony_CN.md、CHANGELOG无

行为分析 SDK 的接入是后续工作：需要确认 Smartlook 是否提供 HarmonyOS SDK，或在鸿蒙侧用系统录屏与埋点能力实现等价链路。在那之前，鸿蒙端的适配保证“接入这条库的应用在鸿蒙上可以正常启动运行，埋点调用不破坏业务流”，并把“录制与上报尚未接入”如实写进文档。

十一、FAQ

Q1：start 返回成功后，会话真的在录制吗？

  • 现象： start() 返回完成，但没有任何录制发生。
  • 原因： 鸿蒙端方法为契约实现，Smartlook 原生 SDK 尚未接入。
  • 解决方法： 不要在鸿蒙端依赖真实录制数据；接入前以 README 声明的边界为准。
  • 验证结果： 图 2 是调用完成的真实页面状态。

Q2：为什么埋点失败不报错？

  • 现象： trackEvent 返回成功，但数据不会出现在 Smartlook 后台。
  • 原因： 埋点失败不应中断业务代码执行，鸿蒙端选择保持控制流。
  • 解决方法： 集成方如需感知，可在业务层加平台判断；getPlatformVersion 可用于运行时探测。
  • 验证结果： 图 3 显示调用完成。

Q3：为什么示例工程变小了？

  • 现象： 示例从多页演示收敛成三按钮页面。
  • 原因： 原演示依赖一批没有 OHOS 实现的第三方库，无法在鸿蒙工具链构建。
  • 解决方法： 保留最小验证面，聚焦插件核心契约。
  • 验证结果： flutter analyze 与 signed HAP 构建均通过。

十二、总结

这次适配为 flutter_smartlook 4.1.32 补齐了 OHOS 插件注册（功能通道 + 平台接口通道），映射了初始化、启停、事件上报和用户标识等核心方法，并把示例收敛为鸿蒙工具链可构建的最小验证页。Demo 通过 Flutter OH 3.47.4 构建成签名 HAP，在 HarmonyOS API 26 模拟器上完成安装、启动与调用验证。

当前成果是“通道完整、控制流稳定、边界明确”的适配基线。适配代码和说明都在 AtomGit 适配分支，复现时建议锁定 4.1.32-ohos.1 TAG。

十三、参考资料和仓库地址

欢迎加入CPF-Flutter 鸿蒙社区：https://atomgit.com/CPF-Flutter

# flutter # harmonyos # 华为
Logo
开源鸿蒙跨平台开发者社区

开源鸿蒙跨平台开发社区汇聚开发者与厂商，共建“一次开发，多端部署”的开源生态，致力于降低跨端开发门槛，推动万物智联创新。

更多推荐

鸿蒙人脸消费机和通行闸机共用开源鸿蒙时，事务模型差在哪

鸿蒙人脸消费机与门禁机可共用OpenHarmony系统与硬件，但事务模型必须分离：消费涉及扣费记账，门禁仅控制通行。二者在账户、权限、审计逻辑上不可混用，需独立设计账本与状态机。虽可共享人员主数据，管理端模块仍须分设，避免语义混淆。技术复用不等于业务复用，项目验证应按场景分别开展，杜绝以一台设备证明全链路国产化。

avatar 开源鸿蒙跨平台开发者社区
cover

React Native for OpenHarmony 实战：三方库 react-native-emoji-selector 的鸿蒙化适配指南

avatar 开源鸿蒙跨平台开发者社区

Flutter 3.47 鸿蒙三方库适配实战：从 0 到 1 处理 otp_autofill

这次适配为补齐了 OHOS 插件注册（双通道），把 Android 专属入口映射为统一的语义，保留的安全无操作。Demo 通过 Flutter OH 3.47.4 构建成签名 HAP，在 HarmonyOS API 26 模拟器上完成安装、启动和调用验证。当前成果是“契约完整、语义诚实”的适配基线。适配代码和说明都在AtomGit 适配分支，复现时建议锁定。

avatar 开源鸿蒙跨平台开发者社区