一、插件介绍

fluttertpc_fk_user_agent 是一款用于获取设备用户代理的 Flutter 插件，专门为 HarmonyOS 平台进行了适配。该插件可以帮助开发者轻松获取设备的用户代理信息，包括普通用户代理和 WebView 用户代理，适用于需要根据设备信息进行差异化处理的场景。

核心功能

• 获取用户代理：获取设备的普通用户代理和 WebView 用户代理
• 属性获取：提供丰富的设备属性，方便构建自定义用户代理
• 跨平台兼容：支持 Android、iOS 和 HarmonyOS 平台
• 高效缓存：初始化后缓存属性，提高性能
• 灵活配置：支持强制重新获取用户代理信息

二、安装与配置

2.1 环境要求

• Flutter: 3.7.12-ohos-1.0.6 或更高版本
• HarmonyOS SDK: 5.0.0(12)
• DevEco Studio: 5.0.13.200 或更高版本

2.2 依赖配置

在项目的 pubspec.yaml 文件中添加以下依赖配置：

dependencies:
  fk_user_agent:
    git:
      url: "https://atomgit.com/openharmony-sig/fluttertpc_fk_user_agent.git"
      ref: master

dev_dependencies:
  fk_user_agent_ohos:
    git:
      url: "https://atomgit.com/openharmony-sig/fluttertpc_fk_user_agent.git"
      path: "ohos"
      ref: master

然后执行以下命令获取依赖：

flutter pub get

2.3 权限配置

在 HarmonyOS 平台上，需要在 entry/src/main/module.json5 文件中配置必要的权限：

{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET",
        "reason": "$string:network_reason",
        "usedScene": {
          "abilities": ["EntryAbility"],
          "when": "inuse"
        }
      }
    ]
  }
}

同时在 entry/src/main/resources/base/element/string.json 中添加权限申请原因：

{
  "string": [
    {
      "name": "network_reason",
      "value": "使用网络"
    }
  ]
}

三、API 使用指南

3.1 导入包

import 'package:fk_user_agent/fk_user_agent.dart';

3.2 初始化模块

在使用插件之前，需要先初始化模块：

await FkUserAgent.init();

如果需要强制重新从本地平台获取用户代理属性，可以设置 force 参数为 true：

await FkUserAgent.init(force: true);

3.3 获取用户代理

获取设备的普通用户代理：

String? userAgent = FkUserAgent.userAgent;
print('用户代理: $userAgent');

获取设备的 WebView 用户代理：

String? webViewUserAgent = FkUserAgent.webViewUserAgent;
print('WebView 用户代理: $webViewUserAgent');

3.4 获取特定属性

获取单个属性：

dynamic systemName = FkUserAgent.getProperty('systemName');
print('系统名称: $systemName');

异步获取单个属性：

dynamic systemVersion = await FkUserAgent.getPropertyAsync('systemVersion');
print('系统版本: $systemVersion');

3.5 获取所有属性

获取所有可用属性的映射：

Map<String, dynamic>? properties = FkUserAgent.properties;
if (properties != null) {
  print('所有属性:');
  properties.forEach((key, value) {
    print('$key: $value');
  });
}

3.6 释放资源

当不再需要访问用户代理属性时，可以释放静态缓存的资源：

FkUserAgent.release();

四、完整示例

以下是一个完整的 HarmonyOS 平台使用示例：

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

void main() {
  runApp(const MyApp());
}

class MyApp extends StatefulWidget {
  const MyApp({Key? key}) : super(key: key);

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  String _userAgent = 'Unknown';
  String _webViewUserAgent = 'Unknown';
  Map<String, dynamic>? _properties;

  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance?.addPostFrameCallback((timeStamp) async {
      // 初始化插件
      await FkUserAgent.init();
      // 获取用户代理信息
      getUserAgentInfo();
    });
  }

  Future<void> getUserAgentInfo() async {
    setState(() {
      // 获取用户代理
      _userAgent = FkUserAgent.userAgent ?? 'Unknown';
      // 获取 WebView 用户代理
      _webViewUserAgent = FkUserAgent.webViewUserAgent ?? 'Unknown';
      // 获取所有属性
      _properties = FkUserAgent.properties;
    });
  }

  Future<void> refreshUserAgentInfo() async {
    // 强制重新获取用户代理信息
    await FkUserAgent.init(force: true);
    // 更新用户界面
    getUserAgentInfo();
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(
          title: const Text('FK User Agent 示例'),
          actions: [
            IconButton(
              icon: const Icon(Icons.refresh),
              onPressed: refreshUserAgentInfo,
              tooltip: '刷新',
            ),
          ],
        ),
        body: SingleChildScrollView(
          padding: const EdgeInsets.all(16.0),
          child: Column(
            crossAxisAlignment: CrossAxisAlignment.start,
            children: [
              const SizedBox(height: 16.0),
              const Text(
                '设备用户代理',
                style: TextStyle(fontSize: 18.0, fontWeight: FontWeight.bold),
              ),
              const SizedBox(height: 8.0),
              Text(_userAgent),
              const SizedBox(height: 24.0),
              const Text(
                'WebView 用户代理',
                style: TextStyle(fontSize: 18.0, fontWeight: FontWeight.bold),
              ),
              const SizedBox(height: 8.0),
              Text(_webViewUserAgent),
              const SizedBox(height: 24.0),
              const Text(
                '设备属性',
                style: TextStyle(fontSize: 18.0, fontWeight: FontWeight.bold),
              ),
              const SizedBox(height: 8.0),
              _properties != null
                  ? Column(
                      crossAxisAlignment: CrossAxisAlignment.start,
                      children: _properties!.entries.map((entry) {
                        return Padding(
                          padding: const EdgeInsets.symmetric(vertical: 4.0),
                          child: Text('${entry.key}: ${entry.value}'),
                        );
                      }).toList(),
                    )
                  : const Text('暂无属性数据'),
            ],
          ),
        ),
      ),
    );
  }
}

五、常见问题与解决方案

5.1 权限问题

如果在安装 HAP 包时遇到错误代码 9568289，可能是因为应用权限等级不足。请参考 文档 修改应用等级为 system_basic。

5.2 初始化失败

确保在调用任何获取用户代理的方法之前，已经正确初始化了插件：

await FkUserAgent.init();

5.3 属性获取为空

如果获取的属性为空，可能是因为初始化尚未完成，或者设备不支持该属性。建议在 init() 方法完成后再获取属性。

六、总结

fluttertpc_fk_user_agent 是一款功能强大的用户代理获取插件，为 HarmonyOS 平台提供了便捷的设备信息获取能力。其主要优势包括：

1. 简单易用：提供简洁的 API 接口，易于集成和使用
2. 丰富功能：支持获取普通用户代理和 WebView 用户代理
3. 高性能：初始化后缓存属性，提高访问速度
4. 灵活配置：支持强制重新获取用户代理信息
5. 跨平台兼容：同时支持 Android、iOS 和 HarmonyOS 平台

该插件可以帮助开发者轻松获取设备的用户代理信息，适用于需要根据设备信息进行差异化处理的应用场景，如网络请求、内容适配等。

---

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net