Cordova - Device

Cordova - Device Information

The cordova-plugin-device plugin provides access to information about the underlying device and platform. It defines a global device object that describes the device’s hardware and software.

Step 1 - Install Device Plugin

Install the plugin using the Cordova CLI:

cordova plugin add cordova-plugin-device

After adding the plugin, it’s good practice to rebuild your project: cordova build <platform>.

Step 2 - Prepare the UI (Optional but Recommended)

While you can simply console.log the device information, displaying it in the UI is more user-friendly for testing. In www/index.html:

<body>
    <h1>Device Information</h1>
    <button id="getDeviceInfoBtn">GET DEVICE INFO</button>
    <div id="deviceInfoDisplay">
        <p>Cordova Version: <span id="cordovaVersion"></span></p>
        <p>Model: <span id="deviceModel"></span></p>
        <p>Platform: <span id="devicePlatform"></span></p>
        <p>UUID: <span id="deviceUUID"></span></p>
        <p>OS Version: <span id="deviceOSVersion"></span></p>
        <p>Manufacturer: <span id="deviceManufacturer"></span></p>
        <p>Is Virtual: <span id="deviceIsVirtual"></span></p>
        <p>Serial: <span id="deviceSerial"></span></p>
    </div>

    <script src="cordova.js"></script>
    <script src="js/index.js"></script>
</body>

Step 3 - Accessing Device Information in JavaScript

The device object is available globally after the deviceready event has fired. In www/js/index.js:

document.addEventListener('deviceready', onDeviceReady, false);

function onDeviceReady() {
    console.log('Device is ready. `device` object is available.');
    // The device object is already populated by this point.
    // You can access its properties directly.
    console.log('Device Model: ' + device.model);

    document.getElementById('getDeviceInfoBtn').addEventListener('click', displayDeviceInfo);
    // Optionally, display info immediately on load:
    // displayDeviceInfo();
}

function displayDeviceInfo() {
    if (typeof device !== 'undefined') {
        document.getElementById('cordovaVersion').textContent = device.cordova;
        document.getElementById('deviceModel').textContent = device.model;
        document.getElementById('devicePlatform').textContent = device.platform;
        document.getElementById('deviceUUID').textContent = device.uuid;
        document.getElementById('deviceOSVersion').textContent = device.version;
        document.getElementById('deviceManufacturer').textContent = device.manufacturer;
        document.getElementById('deviceIsVirtual').textContent = device.isVirtual;
        document.getElementById('deviceSerial').textContent = device.serial;

        // Log all device properties to the console for easy inspection
        console.log('Full device object:', device);
    } else {
        console.error('Device plugin not available or deviceready not fired.');
        alert('Device information is not available.');
    }
}

Device Object Properties

The device object typically provides the following properties:

• device.cordova: The version of Cordova running on the device.
• device.model: The device’s model name or product code. The value is manufacturer-specific.
• device.platform: The device’s operating system name (e.g., “Android”, “iOS”).
• device.uuid: The device’s Universally Unique Identifier (UUID). Note: The reliability and persistence of UUIDs can vary across platforms and OS versions. Refer to platform-specific documentation for details on how it’s generated and its permanence.
• device.version: The operating system version (e.g., “10.0” for Android 10, “14.1” for iOS 14.1).
• device.manufacturer: The device’s manufacturer.
• device.isVirtual: A boolean indicating whether the app is running in an emulator/simulator (true) or on a physical device (false).
• device.serial: The device hardware serial number. Access to serial numbers might be restricted on newer OS versions for privacy reasons (e.g., Android 10+).

Important Notes on Properties:

• Availability: Not all properties are available on all platforms or OS versions. Always check the official plugin documentation for the most current details.
• UUID Privacy: Be mindful of user privacy when using device.uuid. On some platforms, this ID may change after a factory reset or app reinstall. For Android 10 (API level 29) and higher, apps must have the READ_PRIVILEGED_PHONE_STATE privileged permission in order to access non-resettable device identifiers, including IMEI and serial number. Cordova apps typically don’t have such privileged permissions.
• device.isVirtual: Useful for enabling specific debugging features or altering behavior when running in a simulator/emulator.

Practical Applications

Device information can be used for:

• Analytics and Logging: Sending device-specific data to servers for tracking usage patterns, crashes, or performance metrics across different device types and OS versions.
• Platform-Specific Logic: Conditionally executing code or applying different UI styles based on device.platform (e.g., if (device.platform === 'iOS') { ... }).
• Debugging: Displaying device info within the app during development to help identify issues specific to certain configurations.
• Feature Toggling: Enabling or disabling features based on OS version or device capabilities (though specific feature detection plugins are often better for capabilities).

Best Practices

• deviceready First: Always access the device object after the deviceready event.
• Graceful Degradation: If your app relies on a specific property, check for its existence before using it, as it might not be available on all devices/platforms.
• Privacy: Be transparent with users if you collect and transmit device identifiers like UUID or serial number. Only collect what is necessary and comply with privacy regulations.

For the most up-to-date information on properties and platform quirks, refer to the Cordova Device Plugin documentation.