x_user_agent

Pub Version Swift Package Manager Ready Built-in Kotlin Support style: very good analysis License: MIT Coverage

A modern, high-performance Flutter plugin for inspecting WebView and System User-Agent headers, structured device telemetry, and RFC Client Hints on Android and iOS.

✨ Features

  • 🍎 SPM Ready & CocoaPods Compatible — Fully configured with Swift Package Manager (SPM) for modern Flutter 3.44+ iOS builds while maintaining full CocoaPods backward compatibility.
  • 🤖 Built-in Kotlin (AGP 9+ Ready) — Follows the latest Flutter Android toolchain guidelines with built-in Kotlin compilation, eliminating deprecated Kotlin Gradle Plugin (KGP) application conflicts.
  • 🕊️ Type-Safe Native IPC — Powered by Pigeon for lightning-fast, zero-overhead, strictly-typed native platform communication.
  • 🌐 WebView & System User-Agents — Retrieve the real WebKit/Chromium WebView user-agent and native OS/HTTP network stack user-agents independently.
  • 📊 Structured Device Metadata (XUserAgentData) — Access parsed device architecture, OS version, app details, emulator detection, and Darwin/CFNetwork versions.
  • 🛡️ RFC Client Hints Support — Automatically construct standard Sec-CH-UA-* headers for modern HTTP client telemetry and anti-fraud pipelines.

🚀 Getting Started

Installation

Add x_user_agent to your pubspec.yaml:

flutter pub add x_user_agent

Or manually:

dependencies:
  x_user_agent: ^1.1.0

Platform Requirements

Platform Minimum Version Build System Support
Android API 19 (Android 4.4+) Built-in Kotlin (AGP 8.x / 9.x+), Gradle
iOS iOS 13.0+ Swift Package Manager (SPM) & CocoaPods

💡 Usage

Import the package:

import 'package:x_user_agent/x_user_agent.dart';

1. Fetching User Agents

// 1. Get WebView User-Agent (WebKit on iOS, Chrome/Chromium on Android)
final String? webViewUA = await getWebViewUserAgent();
print('WebView User-Agent: $webViewUA');

// 2. Get System / Native HTTP User-Agent
final String? systemUA = await getSystemUserAgent();
print('System User-Agent: $systemUA');

2. Inspecting Structured Device Metadata

Retrieve structured device details with null-safe fallbacks:

final XUserAgentData? data = await getUserAgentData();

if (data != null) {
  print('Platform: ${data.platform} ${data.platformVersion}');
  print('Device: ${data.brand} ${data.model} (${data.architecture})');
  print('App: ${data.appName} v${data.appVersion} (${data.buildNumber})');
  print('Is Emulator: ${data.isEmulator}');
  
  if (data.platform == 'iOS') {
    print('Darwin Version: ${data.darwinVersion}');
    print('CFNetwork Version: ${data.cfnetworkVersion}');
  }
}

3. Generating HTTP Client Hints Headers

Easily attach standard User-Agent Client Hints to your HTTP client requests (e.g. dio, http):

import 'package:http/http.dart' as http;
import 'package:x_user_agent/x_user_agent.dart';

Future<void> sendRequest() async {
  final clientHints = await getClientHintsHeaders();

  final response = await http.get(
    Uri.parse('https://api.example.com/data'),
    headers: {
      ...clientHints,
      'Accept': 'application/json',
    },
  );
}

Example Generated Headers:

{
  "Sec-CH-UA-Platform": "\"Android\"",
  "Sec-CH-UA-Platform-Version": "\"14\"",
  "Sec-CH-UA-Mobile": "?1",
  "Sec-CH-UA-Model": "\"Pixel 8\"",
  "Sec-CH-UA-Arch": "\"arm64-v8a\""
}

📋 XUserAgentData Properties

Property Type Platform Description
platform String? Android / iOS Operating system name (e.g. Android, iOS).
platformVersion String? Android / iOS OS version release string (e.g. 14, 17.4).
model String? Android / iOS Hardware model name (e.g. Pixel 8, iPhone14,2).
architecture String? Android / iOS CPU architecture (e.g. arm64-v8a, arm64, x86_64).
appName String? Android / iOS Display application label.
appVersion String? Android / iOS Semantic app version from package metadata.
buildNumber String? Android / iOS Application build/version code.
packageName String? Android / iOS Android package ID or iOS bundle identifier.
mobile bool? Android / iOS true if running on a mobile device form factor.
device String? Android / iOS Low-level hardware identifier string.
brand String? Android / iOS Device manufacturer or brand (e.g. Google, Apple).
isEmulator bool? Android / iOS true when running on a simulator or emulator.
darwinVersion String? iOS Kernel Darwin release version (e.g. 23.4.0).
cfnetworkVersion String? iOS CFNetwork framework build version.

🔬 Sample User-Agent Outputs

OS System User-Agent WebView User-Agent
iOS CFNetwork/1494.0.7 Darwin/23.4.0 (iPhone14,2 iOS/17.4) Mozilla/5.0 (iPhone; CPU iPhone OS 17_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148
Android Dalvik/2.1.0 (Linux; U; Android 14; Pixel 8 Build/UQ1A.240205.004) Mozilla/5.0 (Linux; Android 14; Pixel 8 Build/UQ1A.240205.004) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.6261.64 Mobile Safari/537.36

📱 Example Project

A complete demo application is available in the example directory showcasing live inspector cards, copy-to-clipboard actions, and client hints testing.

To run the example app:

cd example
flutter run

🧪 Testing

Run unit tests and verify coverage:

flutter test --coverage

Analyze code quality:

flutter analyze

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Libraries

x_user_agent