Merge pull request #3 from OpenFlutter/codex/harmonyos-support

feat: add HarmonyOS support and bump to 1.1.0

Author: JarvanMo

.github/workflows/build_test.yml

@@ -7,6 +7,21 @@ on:
   pull_request:
 
 jobs:
+  contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: subosito/flutter-action@v2
+        with:
+          channel: stable
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+      - run: flutter test
+      - run: node --test test/ohos/*.test.mjs
+      - run: flutter test
+        working-directory: example
+
   test_iOS:
     name: Test iOS on ${{ matrix.os }}
     runs-on: ${{ matrix.os }}

.gitignore

@@ -31,3 +31,13 @@ migrate_working_dir/
 .flutter-plugins
 .flutter-plugins-dependencies
 build/
+
+# HarmonyOS generated files and local signing
+oh_modules/
+.hvigor/
+local.properties
+oh-package-lock.json5
+**/GeneratedPluginRegistrant.ets
+*.p12
+*.p7b
+*.cer

CHANGELOG.md

@@ -1,3 +1,8 @@
+## 1.1.0
+
+- Add HarmonyOS OAID implementation, permission-aware APIs, example and Chinese setup guide. Native build/device verification is pending.
+- Add Dart API, example UI and host-side native logic tests.
+
 ## 1.0.3
 * Add `FlutterFramework` in `Package.swift`.
 

README.OpenHarmony_CN.md

@@ -0,0 +1,134 @@
+# 鸿蒙接入指南
+
+本实现为 `advertising_id_flutter` 提供 HarmonyOS OAID 支持，基于 TPC 的
+`fluttertpc_advertising_id` 鸿蒙代码适配。保留原有 Android、iOS、macOS API。
+
+## 环境与验证状态
+
+- 使用支持 `ohos` 的 Flutter 适配版，随附 Dart 必须满足 `>=3.8.0 <4.0.0`。
+  普通 Flutter 可运行 Dart 测试，但不能构建鸿蒙 HAP。
+- 需要 DevEco Studio、HarmonyOS SDK、应用签名和具备 Ads Kit 的真机。
+- 示例沿用来源项目的 `5.0.0(12)` SDK 配置；这是配置基线，**不是本项目已经验证通过的版本声明**。
+- 当前完成 Dart 和宿主侧原生逻辑测试；尚未完成 ArkTS 编译和真机验证。
+  不承诺所有 OpenHarmony 发行版都具备 `@kit.AdsKit`。
+
+## 1. 引入插件
+
+当前改动尚未发布，开发阶段使用本地路径，指向本仓库根目录：
+
+```yaml
+dependencies:
+  advertising_id_flutter:
+    path: ../flutter_advertising_id
+```
+
+使用鸿蒙 Flutter 执行 `flutter pub get`。插件已经声明 `ohos` 平台，
+宿主应使用工具链生成的插件注册文件，不需要手动创建 MethodChannel。
+
+## 2. 声明应用权限
+
+在宿主 `ohos/entry/src/main/module.json5` 的 `module.requestPermissions` 中添加：
+
+```json
+{
+  "name": "ohos.permission.APP_TRACKING_CONSENT",
+  "reason": "$string:tracking_reason",
+  "usedScene": {
+    "abilities": ["EntryAbility"],
+    "when": "inuse"
+  }
+}
+```
+
+将 `EntryAbility` 替换为实际 Ability 名称。在宿主
+`ohos/entry/src/main/resources/base/element/string.json` 的 `string` 数组中添加：
+
+```json
+{
+  "name": "tracking_reason",
+  "value": "用于获取广告标识符以提供个性化广告服务"
+}
+```
+
+用途说明应符合应用实际用途，有多语言资源时一并翻译。权限必须由宿主声明，
+仅依赖插件 HAR 不会替应用完成权限配置。
+
+## 3. 调用
+
+```dart
+import 'package:advertising_id_flutter/flutter_advertising_id.dart';
+import 'package:flutter/services.dart';
+
+final advertisingId = AdvertisingId();
+
+// 不弹出权限申请：没有权限时返回 null。
+final existingId = await advertisingId.getAdvertisingId();
+
+// 在前台页面、合适的用户操作之后申请权限。
+try {
+  final id = await advertisingId.getAdvertisingId(true);
+  // id == null 表示拒绝授权或没有有效 OAID；由业务决定后续行为。
+} on PlatformException catch (error) {
+  // 可根据 error.code 展示错误或记录诊断信息，避免记录广告 ID。
+}
+
+// 这两个查询不会申请权限。
+final status = await advertisingId.authorizationStatus;
+final limited = await advertisingId.limitAdTrackingEnabled;
+```
+
+| API | 鸿蒙行为 |
+| --- | --- |
+| `getAdvertisingId(false)` | 已授权时读取 OAID；否则返回 null，不弹框 |
+| `getAdvertisingId(true)` | 必要时使用前台 Ability 请求权限；拒绝返回 null |
+| `authorizationStatus` | 已授权为 authorized，未授权为 denied；不区分首次未申请与已拒绝 |
+| `limitAdTrackingEnabled` | APP_TRACKING_CONSENT 未授予时为 true，授予时为 false |
+
+限制状态是**当前应用的跟踪权限状态**，不是独立的全局广告跟踪开关。
+空 OAID 和全零 OAID 返回 null。插件不缓存 OAID，每次查询重新读取权限。
+被拒绝后能否再次弹框由系统控制，应用可提示用户到系统设置修改授权。
+
+| 错误码 | 含义 |
+| --- | --- |
+| `PERMISSION_ERROR` | 权限查询或申请调用失败；检查权限声明和环境 |
+| `NO_ACTIVITY` | 需要申请权限但没有前台 Ability，或申请期间 Ability 被分离 |
+| `GET_AD_ID_FAILED` | OAID 服务调用失败 |
+
+三个 API 都可能抛出 PlatformException。权限拒绝本身不抛异常。
+
+## 4. 运行示例
+
+使用鸿蒙 Flutter，在仓库 `example` 目录执行：
+
+```sh
+flutter pub get
+flutter devices
+flutter build hap --debug
+flutter run -d <设备ID>
+```
+
+首次运行前，在 DevEco Studio 打开 `example/ohos`，配置本机 SDK 和应用签名。
+按工具链要求准备 `@ohos/flutter_ohos`；生成的依赖、注册文件及本地签名不提交。
+示例提供“不申请读取”“申请授权并读取”“查询状态”三个入口，启动时不会申请权限。
+
+## 5. 测试与验收
+
+仓库根目录：
+
+```sh
+flutter test
+node --test test/ohos/*.test.mjs
+```
+
+示例目录：
+
+```sh
+flutter test
+```
+
+Node 测试要求 Node 24，直接执行去除类型的插件源码，仅替换系统 SDK 边界。
+它验证权限分支、并发和错误行为，**不验证 ArkTS 类型规则、SDK 链接或系统弹框**。
+
+发布前必须补齐真机记录：首次不申请、允许、拒绝、系统撤销、重复调用、
+并发申请、无前台 Ability、OAID 重置；同时记录 Flutter/Dart/SDK/IDE/ROM 版本。
+来源项目的兼容性列表不等同于本项目的验收结果。

README.md

@@ -14,6 +14,10 @@ A Flutter plugin to access advertising ID.
 
 Wraps [ASIdentifierManager.advertisingIdentifier](https://developer.apple.com/documentation/adsupport/asidentifiermanager/1614151-advertisingidentifier) (on iOS) and [advertising ID](https://developers.google.com/android/reference/com/google/android/gms/ads/identifier/AdvertisingIdClient) (on Android).
 
+## HarmonyOS
+
+HarmonyOS OAID implementation is available in source. See the [中文接入指南](README.OpenHarmony_CN.md) for permissions, API semantics and toolchain requirements. Native build and device validation are still pending.
+
 ## Getting Started
 
 Run this command

example/integration_test/plugin_integration_test.dart

@@ -1,25 +1,20 @@
-// This is a basic Flutter integration test.
-//
-// Since integration tests run in a full Flutter application, they can interact
-// with the host side of a plugin implementation, unlike Dart unit tests.
-//
-// For more information about Flutter integration tests, please see
-// https://flutter.dev/to/integration-testing
-
-
 import 'package:flutter_test/flutter_test.dart';
 import 'package:integration_test/integration_test.dart';
-
 import 'package:advertising_id_flutter/flutter_advertising_id.dart';
 
 void main() {
   IntegrationTestWidgetsFlutterBinding.ensureInitialized();
 
-  testWidgets('getPlatformVersion test', (WidgetTester tester) async {
-    final AdvertisingId plugin = AdvertisingId();
-    final String? version = await plugin.getAdvertisingId();
-    // The version string depends on the host platform running the test, so
-    // just assert that some non-empty string is returned.
-    expect(version?.isNotEmpty, true);
+  testWidgets('advertising ID may be unavailable without authorization', (
+    tester,
+  ) async {
+    final plugin = AdvertisingId();
+    final id = await plugin.getAdvertisingId(false);
+    expect(id, anyOf(isNull, isNotEmpty));
+    expect(
+      await plugin.authorizationStatus,
+      isA<AdTrackingAuthorizationStatus>(),
+    );
+    expect(await plugin.limitAdTrackingEnabled, anyOf(isNull, isA<bool>()));
   });
 }

example/lib/main.dart

@@ -1,12 +1,8 @@
+import 'package:advertising_id_flutter/flutter_advertising_id.dart';
 import 'package:flutter/material.dart';
-import 'dart:async';
-
 import 'package:flutter/services.dart';
-import 'package:advertising_id_flutter/flutter_advertising_id.dart';
 
-void main() {
-  runApp(const MyApp());
-}
+void main() => runApp(const MyApp());
 
 class MyApp extends StatefulWidget {
   const MyApp({super.key});
@@ -16,52 +12,59 @@ class MyApp extends StatefulWidget {
 }
 
 class _MyAppState extends State<MyApp> {
-  String _platformVersion = 'Unknown';
-  String _status = 'Unknown';
-  final _flutterAdvertisingIdPlugin = AdvertisingId();
+  final _plugin = AdvertisingId();
+  String _id = '尚未读取';
+  String _status = '尚未查询';
+  String? _error;
 
-  @override
-  void initState() {
-    super.initState();
+  Future<void> _readId([bool request = false]) async {
+    try {
+      final id = await _plugin.getAdvertisingId(request);
+      if (!mounted) return;
+      setState(() {
+        _id = id ?? '不可用（未授权或无有效 ID）';
+        _error = null;
+      });
+    } on PlatformException catch (error) {
+      if (mounted) setState(() => _error = error.code);
+    }
   }
 
-  // Platform messages are asynchronous, so we initialize in an async method.
-  Future<void> initPlatformState() async {
-    String platformVersion;
-    // Platform messages may fail, so we use a try/catch PlatformException.
-    // We also handle the message potentially returning null.
+  Future<void> _queryStatus() async {
     try {
-      platformVersion =
-          await _flutterAdvertisingIdPlugin.getAdvertisingId() ?? 'Unknown platform version';
-      _status = (await _flutterAdvertisingIdPlugin.authorizationStatus).toString();
-    } on PlatformException {
-      platformVersion = 'Failed to get platform version.';
+      final status = await _plugin.authorizationStatus;
+      final limited = await _plugin.limitAdTrackingEnabled;
+      if (!mounted) return;
+      setState(() {
+        _status = '${status.name}；限制跟踪：$limited';
+        _error = null;
+      });
+    } on PlatformException catch (error) {
+      if (mounted) setState(() => _error = error.code);
     }
-
-    // If the widget was removed from the tree while the asynchronous platform
-    // message was in flight, we want to discard the reply rather than calling
-    // setState to update our non-existent appearance.
-    if (!mounted) return;
-
-    setState(() {
-      _platformVersion = platformVersion;
-    });
   }
 
   @override
-  Widget build(BuildContext context) {
-    return MaterialApp(
-      home: Scaffold(
-        appBar: AppBar(
-          title: const Text('Plugin example app'),
-        ),
-        body: Center(
-          child: Text('Running on: $_platformVersion\n status: $_status'),
-        ),
-        floatingActionButton: FloatingActionButton(onPressed: (){
-          initPlatformState();
-        },child: Icon(Icons.ssid_chart),),
+  Widget build(BuildContext context) => MaterialApp(
+    home: Scaffold(
+      appBar: AppBar(title: const Text('Advertising ID')),
+      body: ListView(
+        padding: const EdgeInsets.all(24),
+        children: [
+          Text('广告 ID：$_id'),
+          Text('授权状态：$_status'),
+          if (_error != null) Text('错误：$_error'),
+          ElevatedButton(
+            onPressed: () => _readId(),
+            child: const Text('读取 ID（不申请）'),
+          ),
+          ElevatedButton(
+            onPressed: () => _readId(true),
+            child: const Text('申请授权并读取'),
+          ),
+          ElevatedButton(onPressed: _queryStatus, child: const Text('查询状态')),
+        ],
       ),
-    );
-  }
+    ),
+  );
 }

example/ohos/.gitignore

@@ -0,0 +1,20 @@
+/node_modules
+/oh_modules
+/local.properties
+/.idea
+**/build
+/.hvigor
+.cxx
+/.clangd
+/.clang-format
+/.clang-tidy
+**/.test
+**/BuildProfile.ets
+**/oh-package-lock.json5
+/package.json
+/package-lock.json
+
+**/src/main/resources/rawfile/flutter_assets/
+**/libs/**/libapp.so
+**/libs/**/libflutter.so
+**/libs/**/libvmservice_snapshot.so

example/ohos/AppScope/app.json5

@@ -0,0 +1,10 @@
+{
+  "app": {
+    "bundleName": "dev.openflutter.advertising_id_example",
+    "vendor": "example",
+    "versionCode": 1000000,
+    "versionName": "1.0.0",
+    "icon": "$media:app_icon",
+    "label": "$string:app_name"
+  }
+}

example/ohos/AppScope/resources/base/element/string.json

@@ -0,0 +1,8 @@
+{
+  "string": [
+    {
+      "name": "app_name",
+      "value": "flutter_advertising_id_example"
+    }
+  ]
+}