Setting Up the Utilities SDK

What you'll learn

• Generating the Utilities SDK with optional device, package, and biometric modules
• Understanding the clean architecture pattern for utility wrappers
• Accessing device info, app version, and biometric auth across features
• Toggling modules on or off at generation time

Prerequisites

• An existing Archipelago monorepo (see Monorepo Scaffolding)

Step 1: Generate the Utilities SDK

archipelago generate utilities_sdk

You will be prompted for:

• appName — MyApp
• organization — MyCompany
• domain — com (top-level domain: com, org, io)
• prefix — unique prefix for naming (e.g., App)
• includeDeviceInfo — true for device info utilities
• includePackageInfo — true for package/version info
• includeBiometric — true for biometric auth utilities
• isForMonorepo — true
• includeGenerated — false (whether to commit .g.dart files)

Or use a config file:

{
  "appName": "MyApp",
  "organization": "MyCompany",
  "domain": "com",
  "prefix": "App",
  "includeDeviceInfo": true,
  "includePackageInfo": true,
  "includeBiometric": true,
  "isForMonorepo": true,
  "includeGenerated": false
}

Step 2: Understand the Generated Structure

infrastructure/
└── utilities_sdk/
    └── lib/src/
        ├── utilities_sdk.dart            # SDK entry point
        ├── device_info/
        │   ├── data/
        │   │   └── device_info_datasource.dart
        │   ├── domain/
        │   │   └── device_info_repository.dart
        │   └── di/
        ├── package_info/
        │   ├── data/
        │   │   └── package_info_datasource.dart
        │   ├── domain/
        │   │   └── package_info_repository.dart
        │   └── di/
        └── biometric/
            ├── data/
            │   └── biometric_datasource.dart
            ├── domain/
            │   └── biometric_repository.dart
            └── di/

Only the modules you enabled at generation time are included.

Step 3: Register the Utilities SDK

import 'package:utilities_sdk/utilities_sdk.dart';

// Register in your DI setup
UtilitiesSdk.register();

Step 4: Use Device Info

final deviceInfo = GetIt.I<DeviceInfoRepository>();

final model = await deviceInfo.getDeviceModel();    // "iPhone 15 Pro"
final os = await deviceInfo.getOsVersion();          // "iOS 17.4"
final isPhysical = await deviceInfo.isPhysicalDevice(); // true

Step 5: Use Package Info

final packageInfo = GetIt.I<PackageInfoRepository>();

final version = await packageInfo.getAppVersion();   // "1.2.3"
final buildNumber = await packageInfo.getBuildNumber(); // "42"
final packageName = await packageInfo.getPackageName(); // "com.mycompany.myapp"

Step 6: Use Biometric Auth

final biometric = GetIt.I<BiometricRepository>();

final isAvailable = await biometric.isAvailable();
if (isAvailable) {
  final authenticated = await biometric.authenticate(
    reason: 'Verify your identity',
  );
}

Common Customizations

Customization	Where to Change
Add custom device fields	device_info/data/ datasource
Change biometric prompt	biometric/data/ datasource
Cache device info	Add caching layer in repository
Mock in tests	Override DI registration with mock
Disable a module	Regenerate without the module flag

Next Steps

• Set up Auth to use biometric login
• Configure Monitoring to attach device info to crash reports