@ionic-native/device

This project is developed based on @ionic-native/device@5.36.0.

Introduction

@ionic-native/device is a core plugin in the OpenHarmony Cordova ecosystem. It is used to obtain device hardware information and software environment data for the currently running app, providing device-differentiated adaptation for cross-platform app development. It is compatible with Android, iOS, and OpenHarmony platforms, and provides unified device information acquisition capabilities for cross-platform development. This document mainly describes usage on the OpenHarmony system.

@ionic-native/device provides a global device object. This object is available after the Cordova device-ready event (deviceready) is triggered. It can be used to obtain key information such as device model, operating system version, and unique identifier.

Supported Platforms

• OpenHarmony: 5.0+

Installation

You can quickly install the plugin through command-line installation or manual integration. Installation from the npm repository is supported.

Command-line Installation (Recommended)

Install hionic CLI:

npm install -g hionic

Choose one of the following two methods only.

npm installation:

# Install plugin
npm install @ionic-native/device

# Sync plugin
hionic sync

hionic CLI installation:

hionic plugin add @ionic-native/device

Manual Integration

1. Add Plugin Configuration

According to the config-json item in plugin.xml, locate the config.xml file in the entry module and add configuration according to the param tag:

<feature name="Device">
  <param name="harmony-package" value="Device" />
  <param name="onload" value="true" />
</feature>

2. Update CMake Configuration

According to the CMakeLists item in plugin.xml, locate module cordova. The path is the CMakeLists.txt file specified by target. Add add_library:

add_library(cordova SHARED
  // ...
  Device/Device.cpp
  // ...
)

3. Copy Source Files

According to the source-file item in plugin.xml, copy source code from the src path into the directory specified by target-dir in the cordova module:

Copy Device.h and Device.cpp from src/main/cpp/Device in the source code to src/main/cpp/Device in the cordova module.

Copy Device.ets from src/main/ets/components/Device in the source code to src/main/ets/components/Device in the cordova module.

4. Add ArkTS Configuration

In the build-profile.json5 file of the cordova module, add the ets file path copied in step 3 to the buildOption/arkOptions/runtimeOnly/sources configuration array:

"buildOption":{
  "arkOptions": {
    "runtimeOnly": {
      "sources": [
        // ...
        "./src/main/ets/components/Device/Device.ets"
        // ...
      ]
    }
  }
}

Uninstallation

# Uninstall via hionic CLI
hionic plugin remove @ionic-native/device

Constraints and Limitations

Compatibility

Tested successfully on the following version:

1. SDK: 5.0.5(17); IDE: DevEco Studio: 6.0.0; ROM: 5.1.0.150;

Permission Requirements

Not involved.

Usage Examples

Example 1: Get device information

Implements obtaining device model, operating system, unique identifier, system version, manufacturer, whether it is virtual, serial number, Cordova version, and device information availability.

// Wait for Cordova device ready event
document.addEventListener("deviceready", onDeviceReady, false);

function onDeviceReady() {
  console.log("Cordova device ready, start getting device information...");

  // Print all core device properties
  console.log("Device model (model):", device.model);
  console.log("Operating system (platform):", device.platform);
  console.log("Device unique identifier (uuid):", device.uuid);
  console.log("System version (version):", device.version);
  console.log("Device manufacturer (manufacturer):", device.manufacturer);
  console.log("Is virtual device (isVirtual):", device.isVirtual);
  console.log("Device serial number (serial):", device.serial);
  console.log("Cordova version (cordova):", device.cordova);
  console.log("Is device info available (available):", device.available);
}

Usage Guide

The plugin exposes all functional APIs under the global device object. Before use, ensure the device-ready event (deviceready) has been triggered.

Property List and Description

Property Name	Type	Description
device.model	String	Device model
device.platform	String	Device operating system name
device.uuid	String	ODID
device.version	String	Operating system version
device.manufacturer	String	Device manufacturer
device.isVirtual	Boolean	Indicates whether the device is an emulator/virtual device (true for emulator, false for real device)
device.serial	String	ODID
device.cordova	String	Cordova version information
device.available	Boolean	Whether device information is available

1. Device model

Returns the device model name.

Property signature

device.model

2. Operating system

Returns the device operating system name.

Property signature

device.platform

3. Device unique identifier

Returns the device unique identifier (ODID).

Property signature

device.uuid

4. Operating system version

Returns the device operating system version.

Property signature

device.version

5. Device manufacturer

Returns the device manufacturer name.

Property signature

device.manufacturer

6. Whether device is virtual

Returns whether the device is an emulator or virtual device.

Property signature

device.isVirtual

7. Device serial number

Returns the device serial number (ODID).

Property signature

device.serial

8. Cordova version

Returns Cordova version information.

Property signature

device.cordova

9. Whether device info is available

Returns whether device information is available.

Property signature

device.available

Directory Structure

|---- Directory
|     |---- src/main  # Plugin implementation code
|           |---- cpp  # C++ code
|           |---- ets  # ArkTS code
|     |---- www    # Web-side code
|     |---- README.md          # Documentation
|     |---- package.json       # Configuration file
|     |---- plugin.xml         # Plugin configuration file

Contributing

If you find any issues during usage, you can submit an Issue. You are also very welcome to submit a PR for co-development.

License

This plugin is open-sourced under the MIT License. See the LICENSE file for details.