Quickstart

Three steps to a stable device ID. Android and iOS are supported; the call throws on other platforms.

1. Install

Add the package to your app.

pubspec.yaml

dependencies:
  devicesign_sdk:
    git: https://github.com/your-org/devicesign_sdk.git

2. Initialize

Start the licence session once, at launch. It never throws and never blocks startup, so it is safe to leave unawaited.

main.dart

void main() {
  WidgetsFlutterBinding.ensureInitialized();

  // Not awaited: the SDK must never block app startup.
  Devicesign.initialize(
    apiKey: const String.fromEnvironment('DEVICESIGN_API_KEY'),
  );

  runApp(const MyApp());
}

3. Identify the device

Call it whenever you need the ID. The SDK collects the signals, the server decides, and the answer comes back with the reason behind it.

device.dart

try {
  final device = await Devicesign.identifyDevice();

  // Stable for this device, inside your API key.
  saveDeviceId(device.deviceId);
} on DevicesignPlanException {
  // The key's plan does not include device identification.
} on DevicesignException catch (e) {
  // No session yet, or the server could not be reached.
  debugPrint(e.message);
}

with_user.dart

// Optional: tie the device to your own account ID, which
// also becomes a matching signal on the server.
final device = await Devicesign.identifyDevice(appUserId: user.id);

The result

Field	Meaning
`deviceId`	Stable, opaque ID for this device inside your API key. Random: nothing about the device can be read from it.
`isNew`	True when the server had never seen it before.
`confidence`	0.0 to 1.0. A stored token or a brand new device is 1.0; a hardware ID 0.98; an exact fingerprint 0.90; a similar one scores its own value.
`matchMethod`	Which signal identified the device.

Match methods

Worth logging: a shift from deviceToken towards created means devices are losing their stored token.

Value	What happened
`deviceToken`	The token this SDK stored was found.
`hardwareId`	ANDROID_ID or identifierForVendor matched, typically after a reinstall.
`appUserId`	The app user ID you passed matched.
`exactHash`	The fingerprint matched exactly one known device.
`fuzzy`	A similar device was matched by score.
`created`	Nothing matched, so a new device was recorded.

Errors

Exception	When
`DevicesignPlanException`	The key is valid but its plan does not include device identification. Retrying will not help; upgrade the key.
`DevicesignException`	No active session: the key is wrong or disabled, the app ID is not registered, or the server is unreachable.
`UnsupportedError`	Called on a platform other than Android or iOS.

What is collected

Model, manufacturer, OS version, locale, timezone, whether the device is physical, your app version and build number, and one hardware identifier per platform. Hardware identifiers are HMAC-hashed on arrival and never stored in the clear. No advertising ID, no location, no contacts.

Volatile values such as the full OS version and your app version are recorded but deliberately excluded from the fingerprint, so shipping an update does not make every device look new.