Vega IDs: UUID, Ad ID, Vendor Tracking, and Device Info

Vega Open Beta Knowledge Base
1

Vega IDs: UUID, Ad ID, Vendor Tracking, and Device Info

Whether you’re building a new app, porting an existing one to Vega, or developing a library, you’ll need to work with identifiers (IDs) for things like session management, advertising, device configuration, and user tracking. Each ID type has a specific purpose and persistence model — picking the wrong one can compromise user privacy or break functionality across reinstalls.

Supported IDs in Vega

ID Description When to use When not to use
UUIDv4 Generates unique IDs for various app needs. Changes with app reinstallation. App-specific unique IDs, session IDs, temporary device tracking, database record IDs Advertising tracking, persistent device identification, user tracking across installations
Advertisement ID (Ad ID) Designed for advertising and user tracking. Persists through app install/uninstall cycles. User-resettable. Use @amazon-devices/kepler-adid-retriever to access. Targeted advertising, ad performance tracking, user behavior analysis for ads, ad personalization, ad conversion tracking Core app functionalities, user authentication, session management, device-specific configurations, system-level identification
Device Friendly Name Human-readable device names. Supports both generic and user-customized names. User interface display, device pairing scenarios, multi-device setups, network device discovery Device tracking, unique device identification, authentication, security validation, persistent storage keys
User Agent Provides standardized device information. Follows standard User Agent format. Device capability detection, browser/client identification, content adaptation, troubleshooting, analytics and metrics User ad tracking, device authentication, unique device identification, security validation, user identification
Vendor Tracking ID Persistent, vendor-specific ID. Consistent across app installations from the same vendor. Single sign-on across vendor apps, cross-app user experience sync, vendor-specific user tracking, app suite integration Advertising tracking, cross-vendor tracking, device-specific identification, public user identification
Model ID Provides device model information. Available through react-native-device-info library. Determine hardware features, model-specific UI adjustments, performance settings configuration, model-specific troubleshooting, model-specific analytics User identification, device tracking, authentication processes, security validation, session management
OS Version Provides operating system version information. Available through device-info library. Feature compatibility checks, OS-specific functionality, support planning, version distribution analytics User/device tracking, security validation, user identification, critical decision-making sole factor, persistent identification
Build ID Provides software version information. Version-specific implementations, compatibility checks, build-specific bug fixes, system update validation User tracking, device tracking, security authentication, session management, user identification

Best practices

1. Use resettable IDs: Your app can achieve most functionality using resettable IDs. Avoid permanent hardware IDs whenever possible. This approach maintains app features while respecting user privacy.

2. Minimize hardware ID usage: Most use cases don’t require hardware IDs like device serial numbers or IP addresses. Find alternatives that work just as well without compromising essential functionality. Your app can operate efficiently without depending on device-specific IDs.

3. Handle advertising IDs properly: Only use advertising IDs for user profiling or advertising purposes. Always respect user choices about ad tracking. When connecting advertising IDs to personal information, obtain explicit user consent first. Never attempt to bypass or link across ID resets.

4. Follow privacy regulations: Ensure ID usage complies with privacy laws like General Data Protection Regulation (GDPR) and Central Consumer Protection Authority (CCPA). Implement proper data handling procedures, including data minimization and user consent mechanisms. Stay updated with changing privacy requirements in your target markets.

1. UUIDv4 (Universally Unique ID)

UUIDv4 provides a standard way to generate unique IDs for various app needs. Each time this method is called, it creates a new, unique ID.

When to use UUIDv4:

Use UUIDv4 (e.g., 123e4567-e89b-42d3-a456-426614174000) when you need app-specific unique IDs, session IDs, temporary device tracking, or database record IDs. These scenarios benefit from UUID’s temporary nature and unique generation each time the method is called, making it ideal for short-term identification needs within your app’s lifecycle. You can also persist UUID in your app as per your use case using your own storage methods.

When not to use UUIDv4:

Avoid using UUIDv4 for advertising tracking (use Advertisement ID instead), persistent device identification, or user tracking across installations.

Since UUID changes with app reinstallation, it’s not suitable for scenarios requiring persistent identification or cross-installation tracking. When using custom UUID, you are taking ownership over management of the user identifiable data, which may result in additional complexity such as data management requirements, and UX for your customers to control the ID. For advertising-related tracking, the Advertisement ID (mentioned below) is specifically designed to provide better user privacy controls and persistent tracking capabilities.

For further details, refer to the Vega Identifiers API Reference page.

Note for Android developers: If you’re porting from Android and previously used DeviceInfo.getUniqueIdSync(), this method is not supported on Vega and returns "Unknown". Use generateUuidV4() for a per-install unique ID, or getVendorTrackingId() for a persistent per-vendor ID.

2. Advertisement ID (Ad ID)

The Advertisement ID (e.g., 41a2b522-b19c-4b11-8992-bbe4f8adb59e) is designed for advertising and user tracking scenarios. It persists through app install/uninstall cycles, giving you consistent tracking while still respecting user privacy — users can disable or reset it in Fire TV settings. Ad ID is managed by Amazon and associated with the Amazon account.

Note: The getAdvertisingId() method on the KeplerIdentifiers class is not currently supported. To retrieve the advertising ID, use the dedicated @amazon-devices/kepler-adid-retriever package instead, which provides AdIdRetriever.fetchAdvertisingId().

When to use Ad ID:

Use Ad ID for targeted advertising, ad performance tracking, user behavior analysis for ads, ad personalization, ad conversion tracking, and advertising compliance requirements.

Usage:

import {AdIdRetriever} from '@amazon-devices/kepler-adid-retriever';

const adId = AdIdRetriever.fetchAdvertisingId();
const isTrackingEnabled = AdIdRetriever.isAdvertisingTrackingEnabled();

When not to use Ad ID:

Don’t use Ad ID for core app functionality like authentication, session management, device configuration, user profiles, or database keys. Use other IDs for those purposes.

For further details, refer to the AdIdRetriever API Reference page.

3. Device Friendly Name

Device Friendly Name provides human-readable device names for scenarios like device pairing and multi-device setups. It supports both generic names (e.g., “FTV Stick 4K”) and user-customized names (e.g., “John’s FTV Stick”). Since customized names may contain personal information, accessing them requires a runtime privilege.

Refer to the Vega Identifiers API Reference for more details.

When to use Device Friendly Name:

Use it for UI display, device pairing, multi-device setups, network discovery, and device selection interfaces — anywhere you need a human-readable label.

When not to use Device Friendly Name:

Don’t rely on it for device tracking, authentication, security validation, or persistent storage keys. The name can change at any time and may contain personal information. Use UUID or Vendor Tracking ID for technical identification instead.

Implementation details

Generic names (no privilege needed): The API returns the generic device model name by default — no setup required. This happens when no user-customized name exists or when your app lacks the privilege.

Accessing user-customized names: To retrieve user-customized device names, you’ll need to:

  • Request the runtime privilege: com.amazon.devconf.privilege.identifiers.device-friendly-name
  • A user consent dialog automatically appears for the user to accept or deny

Step 1: Import the API

import {KeplerIdentifiers as Identifiers} from '@amazon-devices/kepler-identifiers';

const friendlyName = await Identifiers.getFriendlyDeviceName();

Step 2: Add the privilege to your manifest

Update your app’s manifest.toml and specify the privilege dependency:

[[needs.privilege]]
id = "com.amazon.devconf.privilege.identifiers.device-friendly-name"

After this, the user consent dialog can be initiated by requesting the runtime privilege "com.amazon.devconf.privilege.identifiers.device-friendly-name" through the Security Manager API.

Step 3: Request the privilege at runtime

Use requestPrivilege() from @amazon-devices/security-manager-lib:

import {SecurityManager, PrivilegeState} from '@amazon-devices/security-manager-lib';
import {KeplerIdentifiers as Identifiers} from '@amazon-devices/kepler-identifiers';

const DEVICE_NAME_PRIVILEGE = 'com.amazon.devconf.privilege.identifiers.device-friendly-name';

async function getFriendlyName(): Promise<string> {
  const state = await SecurityManager.getPrivilegeState(DEVICE_NAME_PRIVILEGE);

  if (state === PrivilegeState.ALLOW) {
    // User already consented
    return Identifiers.getFriendlyDeviceName();
  }

  // Request consent — this blocks until the user responds
  const result = await SecurityManager.requestPrivilege(DEVICE_NAME_PRIVILEGE);

  if (result === PrivilegeState.ALLOW) {
    // User consented
    return Identifiers.getFriendlyDeviceName();
  }

  // User declined — falls back to generic name
  return Identifiers.getFriendlyDeviceName();
}

4. User Agent

User Agent (e.g., Kepler/1.1(Linux; AFTCA002)) provides standardized device information for client identification, content adaptation, and diagnostics.

To access the User Agent, use the @amazon-devices/react-native-device-info library. Refer to the react-native-device-info API Reference. You can also override the value of the user agent as needed using the network request API.

When to use User Agent:

Use it for device capability detection, browser/client identification, content adaptation, troubleshooting, analytics, API request headers, and feature toggling.

When not to use User Agent:

Don’t use it for ad tracking (use Ad ID), authentication, unique device identification, security validation, or session management.

5. Vendor Tracking ID

Vendor Tracking ID (e.g., 41a2b522-b19c-4b11-8992-bbe4f8adb59e) provides a persistent, vendor-specific ID that remains consistent across app installations. It enables seamless cross-app experiences for apps from the same vendor while maintaining user privacy controls.

import {KeplerIdentifiers as Identifiers} from '@amazon-devices/kepler-identifiers';

const vendorId = await Identifiers.getVendorTrackingId();

Warning: The opt-out behavior for Vendor Tracking ID is not yet fully implemented. The API currently returns a valid UUID regardless of the user’s opt-out preference. We are currently working on resolving this issue.

This ID persists through app install/uninstall cycles. The ID is vendor-specific — it remains the same for all apps from the same vendor, and can be reset via factory reset. It is equivalent to IDFV on iOS and ANDROID_ID on Android.

For further details, refer to the Vega Identifiers API Reference.

When to use Vendor Tracking ID:

Use it for single sign-on across your apps, cross-app user experience sync, vendor-specific analytics, app suite integration, and feature entitlement across your apps. These capabilities enable you to create a more cohesive and integrated experience across your suite of apps while maintaining appropriate privacy controls.

When not to use Vendor Tracking ID:

Don’t use it for advertising tracking, cross-vendor tracking, device-specific identification, or public user identification.

6. Model ID

Model ID (e.g., AFTCA001) is available through Vega’s react-native-device-info library, providing essential information about the device model that helps determine hardware capabilities and implement device-specific features.

To access Model ID, use the getModel() method from the device info library. Note that Model ID will change as new devices with new models are released on Vega.

import DeviceInfo from '@amazon-devices/react-native-device-info';

let model = DeviceInfo.getModel(); // "AFTCA001"

When to use Model ID:

Use it to determine hardware features, implement model-specific UI adjustments, configure performance settings, troubleshoot model-specific issues, or gather device distribution analytics.

When not to use Model ID:

Don’t use it for user identification, device tracking, authentication, security validation, or session management.

7. OS Version

Device OS version (e.g., 1.1) is available through Vega’s react-native-device-info library, providing information about the software environment your users are running.

To access OS Version, use the getSystemVersion() method from the device info library.

import DeviceInfo from '@amazon-devices/react-native-device-info';

let systemVersion = DeviceInfo.getSystemVersion(); // "1.1"
let systemName = DeviceInfo.getSystemName(); // "Kepler" (internal OS name)

Note: getSystemName() returns "Kepler" — this is the internal OS identifier and is expected behavior.

When to use OS version information:

Use it when your app needs to adapt behavior based on software capabilities — enabling/disabling features, optimizing UI, or providing OS-specific guidance.

When not to use OS version information:

Don’t use it for persistent user or device identification, tracking, security validation, or user-specific data association.

8. Build ID

Build ID (e.g., 32C456) provides information about the software version running on the device. You can access it through the @amazon-devices/kepler-system-info library using the getBuildId() method. Refer to the Vega System Info API Reference for full details.

import {NativeSystemInfo} from '@amazon-devices/kepler-system-info';

const buildId = await NativeSystemInfo.getBuildId(); // "32C456"

When to use Build ID:

Use it for version-specific feature implementations, compatibility checks, build-specific bug fixes, system update validation, and debugging.

When not to use Build ID:

Don’t use it for tracking, user identification, security authentication, or session management.

Choosing the right ID

If you need…

  • A temporary unique value (session, database key) → UUIDv4
  • Ad tracking or personalization → Ad ID (via AdIdRetriever)
  • Cross-app persistence for your vendor → Vendor Tracking ID
  • A human-readable device label → Device Friendly Name
  • Device hardware info → Model ID
  • OS or build version checks → OS Version / Build ID
  • Client identification in network requests → User Agent

When in doubt, pick the least-persistent ID that meets your requirements. Use resettable IDs for most scenarios, reserve Ad ID strictly for advertising workflows, and lean on Device Friendly Name or Model ID for UI and device-specific logic.

Related resources

Last updated: May 14, 2026

1 Like