iws_device_info 2.0.0

A package that provides information about the device with IWS format.

IWS Device Info

A Flutter package that provides detailed device information in an IWS (Integrated Web Services) compatible format. This package facilitates obtaining device data such as platform, model, brand, operating system, and unique hardware identifiers across all Flutter platforms.

Key Features

• 🚀 Quick and easy implementation - Straightforward, static facade API.
• 📱 Cross-platform support - Compatible with Android, iOS, Web, Windows, macOS, and Linux.
• 🔒 Immutable snapshot model - AppDevice is immutable with copyWith, operator ==, hashCode, and informative toString().
• 🔄 Full JSON serialization - Both toJson() and AppDevice.fromJson() for easy storage, caching, and API communication.
• 🛡️ Fault-tolerant & resilient - Graceful degradation ensures partial information is returned even if specific platform channels fail.
• 🧪 Test-friendly - Supports dependency injection with deviceInfoPlugin and @visibleForTesting platform overrides.
• ⚡ Convenient helpers - Intuitive properties like isMobile, isDesktop, isWeb, and isApple on both AppDevice and IwsDeviceInfo.

Installation

Add this package to your Flutter project:

flutter pub add iws_device_info

Or add it manually to your pubspec.yaml:

dependencies:
  iws_device_info: ^2.0.0

Basic Usage

Import the package

import 'package:iws_device_info/iws_device_info.dart';

Get complete device information

// Retrieve device information with optional IDs
final device = await IwsDeviceInfo.getDeviceInfo(
  deviceId: 'unique-device-id',          // Optional custom device ID
  userIdentifier: 'user-identifier-123', // Optional user identifier
);

// Access device properties
print('Device ID: ${device.id}');
print('Brand: ${device.brand}');
print('Model: ${device.model}');
print('Operating System: ${device.os}');
print('Platform: ${device.platformName?.name}');
print('Fingerprint: ${device.fingerprint}');

// Convenient boolean getters directly on the model
if (device.isMobile) {
  print('Running on mobile (Android or iOS)');
}
if (device.isApple) {
  print('Apple ecosystem device (iOS or macOS)');
}

// Convert to JSON for API transfer
final Map<String, dynamic> json = device.toJson();

// Reconstruct from JSON
final reconstructedDevice = AppDevice.fromJson(json);

// Create an updated copy with modified fields
final updatedDevice = device.copyWith(userIdentifier: 'new-user-id');

Platform detection

// Get the current PlatformName enum
final platformName = IwsDeviceInfo.getDevicePlatformName();
print('Current platform: ${platformName?.name}');

// Check device category
final isMobile = IwsDeviceInfo.isMobile();             // Android or iOS
final isWebOrDesktop = IwsDeviceInfo.isWebOrDesktop(); // Web, Windows, macOS, or Linux

// Check specific platforms
final isWeb = IwsDeviceInfo.isWeb();
final isAndroid = IwsDeviceInfo.isAndroid();
final isIOS = IwsDeviceInfo.isIOS();
final isWindows = IwsDeviceInfo.isWindows();
final isLinux = IwsDeviceInfo.isLinux();
final isMacOS = IwsDeviceInfo.isMacOS();

// Check for Apple devices
final isApple = IwsDeviceInfo.isAppleDevice(); // iOS or macOS

Case-insensitive platform resolution

You can resolve string values (from configs or APIs) into PlatformName case-insensitively:

final platform = IwsDeviceInfo.getPlatformByName('android'); // Returns PlatformName.android
final iosPlatform = IwsDeviceInfo.getPlatformByName('iOS');   // Returns PlatformName.ios

Testing and Mocking

The package provides two mechanisms to facilitate unit testing in your own projects:

1. Injected DeviceInfoPlugin

You can pass a custom or mock DeviceInfoPlugin to getDeviceInfo():

final device = await IwsDeviceInfo.getDeviceInfo(
  deviceInfoPlugin: customDeviceInfoPlugin,
);

2. Platform Override for Tests

Simulate different operating systems during testing without requiring physical devices:

import 'package:flutter_test/flutter_test.dart';
import 'package:iws_device_info/iws_device_info.dart';

void main() {
  tearDown(() {
    // Reset override after test execution
    IwsDeviceInfo.debugPlatformOverride = null;
  });

  test('simulates Android environment', () {
    IwsDeviceInfo.debugPlatformOverride = PlatformName.android;

    expect(IwsDeviceInfo.isAndroid(), isTrue);
    expect(IwsDeviceInfo.isMobile(), isTrue);
    expect(IwsDeviceInfo.isAppleDevice(), isFalse);
  });
}

Complete Example

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

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  final device = await IwsDeviceInfo.getDeviceInfo(
    deviceId: 'device-123',
    userIdentifier: 'user-456',
  );

  runApp(MyApp(device: device));
}

class MyApp extends StatelessWidget {
  final AppDevice device;

  const MyApp({super.key, required this.device});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      debugShowCheckedModeBanner: false,
      home: DeviceInfoScreen(device: device),
    );
  }
}

class DeviceInfoScreen extends StatelessWidget {
  final AppDevice device;

  const DeviceInfoScreen({super.key, required this.device});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Device Information')),
      body: Padding(
        padding: const EdgeInsets.all(16.0),
        child: ListView(
          children: [
            ListTile(
              title: const Text('Platform'),
              subtitle: Text(device.platformName?.name ?? 'Unknown'),
            ),
            ListTile(
              title: const Text('Brand'),
              subtitle: Text(device.brand ?? 'N/A'),
            ),
            ListTile(
              title: const Text('Model'),
              subtitle: Text(device.model ?? 'N/A'),
            ),
            ListTile(
              title: const Text('Operating System'),
              subtitle: Text(device.os ?? 'N/A'),
            ),
            ListTile(
              title: const Text('Device ID'),
              subtitle: Text(device.id ?? 'N/A'),
            ),
            ListTile(
              title: const Text('Fingerprint'),
              subtitle: Text(device.fingerprint ?? 'N/A'),
            ),
            const Divider(),
            ListTile(
              title: const Text('Category'),
              subtitle: Text(
                device.isMobile
                    ? 'Mobile device'
                    : device.isWeb
                        ? 'Web browser'
                        : 'Desktop device',
              ),
            ),
          ],
        ),
      ),
    );
  }
}

Data Models

AppDevice

class AppDevice {
  final String? id;              // Unique device ID
  final String? fingerprint;     // Device hardware or vendor fingerprint
  final String? brand;           // Device manufacturer / brand
  final String? model;           // Hardware model
  final String? name;            // Hostname or device name
  final String? os;              // Operating system and version
  final String? userIdentifier;  // Associated user identifier
  final PlatformName? platformName; // Resolved platform

  // Serialization
  Map<String, dynamic> toJson();
  factory AppDevice.fromJson(Map<String, dynamic> json);

  // Utilities
  AppDevice copyWith({...});
  
  // Category helpers
  bool get isMobile;
  bool get isDesktop;
  bool get isWeb;
  bool get isApple;
}

PlatformName (Enum)

enum PlatformName {
  web('Web'),
  android('Android'),
  ios('iOS'),
  macos('macOS'),
  windows('Windows'),
  linux('Linux');

  // Case-insensitive parser
  static PlatformName? fromName(String? name);

  // Category helpers
  bool get isMobile;
  bool get isDesktop;
  bool get isWeb;
  bool get isApple;
}

Supported Platforms

Platform	✅ Supported	Retrieved Information
Android	✅	Brand, model, OS release & version, device name, build fingerprint
iOS	✅	Model, system name and version, identifierForVendor
Web	✅	Browser name, vendor, user agent
Windows	✅	Product name, product ID fingerprint, computer name
macOS	✅	Model, macOS version, system GUID, computer name
Linux	✅	Distribution name, pretty name, machine ID