Flutter 鸿蒙化实战：flutter_udid 适配 OpenHarmony

前言

随着鸿蒙生态的快速发展，越来越多的 Flutter 应用需要适配 OpenHarmony 平台。但生态早期，大量常用三方库只有 Android / iOS 实现，鸿蒙侧只能自己造轮子。

为了解决这个问题，CPF-Flutter 社区对一批高频使用的 Flutter 三方库做了 OpenHarmony 平台适配，统一托管在 GitCode 的 CPF-Flutter 组织 下，全部通过 TAG 版本隔离、配套门禁编译验证，开箱即用。

本篇是系列文章之一，主角是 flutter_udid —— 设备唯一标识获取插件。

flutter_udid 是什么

flutter_udid 是一个获取设备唯一标识符（UDID）的 Flutter 插件，原始标识在应用卸载重装后依然保持不变。

在 OpenHarmony 平台上，该插件有两大能力：

1. FlutterUdid.udid：获取设备唯一标识。OHOS 平台底层基于 OAID（开放匿名设备标识符）实现，Android 返回 ANDROID_ID，iOS/macOS 返回 identifierForVendor；
2. FlutterUdid.consistentUdid：对 udid 做 SHA-256 摘要，在所有平台返回 64 位十六进制的一致格式，方便跨平台比对。

适配情况

Flutter 框架版本	TAG 名称	分支名
3.7	4.1.1-ohos-1.0.0-beta.2	br_v4.1.1_ohos
3.22	4.1.1-ohos-1.0.0-beta.2	br_v4.1.1_ohos
3.27	4.1.1-ohos-1.0.0-beta.2	br_v4.1.1_ohos
3.35	4.1.1-ohos-1.0.0-beta.2	br_v4.1.1_ohos

已验证环境（3.35 为例）：Flutter 3.35.7-ohos；DevEco Studio 6.0.1.260；SDK 6.0.1(21)；ROM 6.0.0.120 SP6。

快速接入

在 pubspec.yaml 中添加 git 依赖：

dependencies:
  flutter_udid:
    git:
      url: https://gitcode.com/CPF-Flutter/fluttertpc_flutter_udid.git
      # 按你的 Flutter 框架版本，从上方映射表选择对应 TAG
      ref: 4.1.1-ohos-1.0.0-beta.2

执行：

flutter pub get

使用示例

获取 UDID

import 'package:flutter_udid/flutter_udid.dart';

final String udid = await FlutterUdid.udid;

获取跨平台一致的 UDID

final String consistentUdid = await FlutterUdid.consistentUdid;

完整示例

import 'package:flutter/material.dart';
import 'package:flutter_udid/flutter_udid.dart';

class UdidPage extends StatefulWidget {
  const UdidPage({super.key});

  @override
  State<UdidPage> createState() => _UdidPageState();
}

class _UdidPageState extends State<UdidPage> {
  String _udid = 'Unknown';
  String _consistentUdid = 'Unknown';

  Future<void> _readIdentifiers() async {
    String udid;
    String consistentUdid;
    try {
      udid = await FlutterUdid.udid;
      consistentUdid = await FlutterUdid.consistentUdid;
    } on Exception {
      udid = 'Failed to get UDID.';
      consistentUdid = 'Failed to get consistentUDID.';
    }

    if (!mounted) return;
    setState(() {
      _udid = udid;
      _consistentUdid = consistentUdid;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('flutter_udid example')),
      body: Center(
        child: Text('udid: $_udid\nconsistentUdid: $_consistentUdid'),
      ),
    );
  }
}

错误处理

首次调用会触发 APP_TRACKING_CONSENT 运行时权限弹窗（OAID 读取需要用户授权）。读取失败时会抛出 PlatformException：

错误码	触发条件
PERMISSION_DENIED	用户拒绝了授权弹窗
UNAVAILABLE	OAID 不可用（关闭个性化广告、设备/模拟器返回空值等）
ERROR	权限请求或读取链路的意外错误

注意事项

• OAID 可以被用户在系统设置中重置，重置后 udid 会变化，持久性弱于 iOS 钥匙串方案，业务侧建议按"设备标识参考"而非"绝对唯一 ID"使用；
• 部分模拟器/模拟器镜像 OAID 不可用，会抛 UNAVAILABLE。

仓库地址

• OpenHarmony 适配仓库：https://gitcode.com/CPF-Flutter/fluttertpc_flutter_udid
• 使用问题反馈：仓库 Issues 区

系列预告

截至目前，CPF-Flutter 社区已完成 250+ 个 Flutter 三方库的 OpenHarmony 平台适配，覆盖权限管理、UI 组件、设备信息、位置服务、媒体处理、网络、支付等多个领域，完整的适配清单（含每个库的版本映射表）见：

• 适配总览文档：https://gitcode.com/CPF-Flutter/docs/blob/main/ThirdpartyLibrarites.md
• 仓库组织：https://gitcode.com/CPF-Flutter

本系列后续会陆续挑选高频库展开讲解，比如屏幕常亮（flutter_wakelock）、本地通知（flutter_local_notifications）、支付宝支付（tobias）、JS 桥接（flutter_jsbridge_plugin）等。

如果你的 Flutter 应用正在计划适配鸿蒙，欢迎关注 CPF-Flutter 组织，也欢迎参与共建。