Flutter自定义客户端信息获取插件custom_client_information的使用

客户端信息

这是一个允许你从应用程序客户端获取基本信息的插件。它易于使用，并支持不同的平台（Android、iOS 和 Web）。有四种不同类型的信息：“应用信息”、“软件信息”、“操作系统信息”和“设备信息”。

iOS 截图

Android 截图

Web 截图

信息类型

有四种不同类型的客户端信息：

1. 应用信息
2. 软件信息
3. 操作系统信息
4. 设备信息

应用信息

应用信息包括构建的应用程序的所有信息。请注意，applicationId 对于 Web 应用程序不支持。

软件信息

“软件”指的是运行你的应用程序的软件，例如 iOS/Android 项目的“操作系统”或 Web 项目的“浏览器”。

操作系统信息

操作系统信息将显示操作系统的名称和版本。注意：如果浏览器的用户代理不包含任何关于操作系统的信息，Web 项目可能无法获取这些信息。

设备信息

设备信息将显示设备的 ID 和名称。请注意，Web 项目不支持真实的 deviceId，因此它们会使用包 uuid 生成一个唯一的字符串并保存到浏览器的 Cookie 中。

开始使用

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

dependencies:
  ...
  custom_client_information: ^2.1.2

在你的项目中添加以下导入：

import 'package:custom_client_information/custom_client_information.dart';

然后，你可以像这样获取信息：

// 获取客户端信息
ClientInformation info = await ClientInformation.fetch();

print(info.deviceId); // EA625164-4XXX-XXXX-XXXXXXXXXXXX
print(info.osName); // iOS

装饰

从版本 2.1.0 开始，你可以通过传递 decorators 来自定义某些信息。如下所示：

var information = await ClientInformation.fetch(
      // 你可以传递装饰器来装饰返回值之前的信息。
      decorators: ClientInformationDecorators(
        deviceId: (oriInfo, value) => 'prefix-$value-${oriInfo.applicationName}',
      ),
    );

或者，你可以使用扩展方法，如下所示：

var information = await ClientInformation.fetch();
print('Original DeviceId: ${information.deviceId}');
// Original DeviceId: EA625164-4XXX-XXXX-XXXXXXXXXXXX

var decoratedInfo = information.decoration(deviceId: (oriInfo, value) => '$value-some-suffix-string-here');
print('Decorated DeviceId: ${decoratedInfo.deviceId}');
// Decorated DeviceId: EA625164-4XXX-XXXX-XXXXXXXXXXXX-some-suffix-string-here

测试时的模拟数据

从版本 1.0.2 开始，你可以模拟数据或启用“模拟模式”以方便测试。以下是设置方法：

在你的测试文件中：

setUp(() async {
  // 更改为“模拟模式”并设置你需要的默认数据。
  ClientInformation.mockOn(
      deviceId: 'mock_device_id', osName: 'MyCustomOS');
});

tearDown(() {
  // 在 `tearDown` 方法中关闭“模拟模式”
  ClientInformation.mockOff();
});

// 运行你的测试
test('`deviceId` 将是 `mock_device_id`', () async {
  ClientInformation info = await ClientInformation.fetch();
  expect(info.deviceId, 'mock_device_id');
});

示例代码

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

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

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.teal),
        useMaterial3: true,
      ),
      home: const MyHomePage(),
    );
  }
}

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

  [@override](/user/override)
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  ClientInformation? basicInfo, decoratedInfo;

  [@override](/user/override)
  void initState() {
    super.initState();
    _fetchInfo();
  }

  void _fetchInfo() async {
    basicInfo = await ClientInformation.fetch();

    decoratedInfo = await ClientInformation.fetch(
      decorators: ClientInformationDecorators(
        deviceId: (oriInfo, value) => 'prefix-$value-${oriInfo.applicationName}',
      ),
    );

    ///! 或者，你可以使用扩展方法，如下所示：
    // decoratedInfo = (await ClientInformation.fetch()).decoration(
    //     deviceId: (oriInfo, value) => 'prefix-$value-${oriInfo.applicationName}');
    setState(() {});
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        backgroundColor: Theme.of(context).colorScheme.inversePrimary,
        centerTitle: true,
        title: const Text('Client Information Example'),
      ),
      body: LayoutBuilder(builder: (context, _) {
        return Column(
          children: [
            Expanded(
              child: SingleChildScrollView(
                child: basicInfo == null || decoratedInfo == null
                    ? _buildLoading()
                    : _buildInfoView(),
              ),
            ),
          ],
        );
      }),
    );
  }

  Widget _buildLoading() {
    return const Center(child: CircularProgressIndicator());
  }

  Widget _buildInfoView() {
    return Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        _dataItemWidget('deviceId', basicInfo?.deviceId ?? 'unknown_device_id'),
        _dataItemWidget('decorated deviceId', decoratedInfo?.deviceId ?? 'unknown_decorated_device_id'),
        _dataItemWidget('deviceName', basicInfo?.deviceName ?? 'unknown_device_name'),
        _dataItemWidget('osName', basicInfo?.osName ?? 'unknown_os_name'),
        _dataItemWidget('osVersion', basicInfo?.osVersion ?? 'unknown_os_version'),
        _dataItemWidget('osVersionCode', basicInfo?.osVersionCode.toString() ?? 'unknown_os_version_code'),
        _dataItemWidget('softwareName', basicInfo?.softwareName ?? 'unknown_software_name'),
        _dataItemWidget('softwareVersion', basicInfo?.softwareVersion ?? 'unknown_software_version'),
        _dataItemWidget('applicationId', basicInfo?.applicationId ?? 'unknown_application_id'),
        _dataItemWidget('applicationType', basicInfo?.applicationType ?? 'unknown_application_type'),
        _dataItemWidget('applicationName', basicInfo?.applicationName ?? 'unknown_application_name'),
        _dataItemWidget('applicationVersion', basicInfo?.applicationVersion ?? 'unknown_application_version'),
        _dataItemWidget('applicationBuildCode', basicInfo?.applicationBuildCode ?? 'unknown_application_build_number'),
      ],
    );
  }

  Widget _dataItemWidget(String key, String? value) {
    return Padding(
      padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 6),
      child: Wrap(
        children: [
          Text('$key: ', style: const TextStyle(fontSize: 16, fontWeight: FontWeight.bold)),
          Text(value ?? 'null', style: const TextStyle(fontSize: 18, color: Colors.blueAccent)),
        ],
      ),
    );
  }
}