# Device Information
Information about the device.
# Manifest Declaration
You need to declare the use of this API in the manifest's features
member:
{"name": "system.device"}
# Module Import
Before using this service in a component, you need to import the module in the script section of the UX document.
import device from '@system.device'
Or
let device = require("@system.device")
# Attributes
This service has the following attributes:
# platform
Platform information.
- Type:
object
with the following member:versionCode
indicating the platform version
- Mandatory: no
- Value by default: -
# allowTrackOAID
Indicates whether OAIDs and device IDs can be used for tracing (on Android 10+).
- Type:
boolean
- Mandatory: no
- Value by default: -
Value true
indicates that these identifiers may be used for device tracing.
# Methods
This service has the following methods:
getInfo({success,fail,complete})
getInfoSync()
getId({type,success,fail,complete})
getDeviceId({success,fail,complete})
getUserId({success,fail,complete})
getOAID({success,fail,complete})
getTotalStorage({success,fail,complete})
getSerial({success,fail,complete})
getAvailableStorage({success,fail,complete})
getCpuInfo({success,fail,complete})
getTheme({success,fail,complete})
getThemeSync()
getServiceCountryCode({success,fail,complete})
toLocaleDateTimeString(timestamp)
toLocaleDateString(timestamp)
toLocaleTimeString(timestamp)
host({success,fail,complete})
# getInfo({success,fail,complete})
Obtains device information..
# Arguments
This method requires an object
with the following attributes:
success
(function(res)
). Optional callback function for success. The function has anobject
argument with the following members:brand
(string
). Device brand.manufacturer
(string
). Device manufacturer.model
(string
). Device model.product
(string
). Device code.osType
(string
). Operating system name.osVersionName
(string
). Operating system version name.osVersionCode
(number
). Operating system version code.platformVersionName
(string
). Platform version name.platformVersionCode
(number
). Platform version code.language
(string
). System language.region
(string
). System country/region.screenWidth
(number
). Screen width.screenHeight
(number
). Screen height.engineProvider
(string
). Provider of the quick app engine.windowWidth
(number
). Available window width, which is determined by the actual screen resolution.windowHeight
(number
). Available window height, which is determined by the actual screen resolution. (Available window height = Screen height - Status bar height - Title bar height - Virtual navigation bar height)statusBarHeight
(number
). Status bar height, which is determined by the actual screen resolution.pixelRatio
(number
). Device pixel ratio.screenDensity
(number
). Screen density of the device.timeZone
(string
). Current system time zone.fontScale
(number
). Font size.characteristics
(string
). Device type (options aredefault
,tv
,tablet
, andphone
). The default value isphone
.windowLogicWidth
(number
). The base value for a widget is750
, a normal quick app, the value of this parameter is the same as the value ofdesignWidth
in theconfig
member of the manifest. The default value is750
.windowLogicHeight
(number
). The base value for a widget is750
.marketingName
(string
). Model marketing name of the device.
fail
(function(code)
). Optional callback function for failure.complete
(function()
). Optional callback function for completion.
Example:
device.getInfo({
success: function (res) {
console.log(JSON.stringify(res));
},
fail: function (erromsg, errocode) {
console.log("message:",erromsg,errocode);
}
})
Returning:
{"brand":"HONOR","manufacturer":"HUAWEI","model":"ATH-TL00H","product":"ATH-TL00H","osType":"android","osVersionName":"5.1.1","osVersionCode":22,"platformVersionName":"1.040","platformVersionCode":1040,"language":"en","region":"UK","screenWidth":1080,"screenHeight":1776,"timeZone":"GMT+08:00","emuiVer":"3.1","fontScale":1,"characteristics":"default","windowWidth":1080,"windowHeight":1557,"statusBarHeight":75,"pixelRatio":3,"engineProvider":"huawei","screenDensity":3,"screenLogicWidth":750,"screenLogicHeight":1233,"windowLogicWidth":750,"windowLogicHeight":1081}
# getInfoSync()
Obtains device information.
# Return
This method returns an object
with the following attributes:
brand
(string
). Device brand.manufacturer
(string
). Device manufacturer.model
(string
). Device model.product
(string
). Device code.osType
(string
). Operating system name.osVersionName
(string
). Operating system version name.osVersionCode
(string
). Operating system version code.platformVersionName
(string
). Platform version name.platformVersionCode
(number
). Platform version code.language
(string
). System language.region
(string
). System country/region.screenWidth
(number
). Screen width.screenHeight
(number
). Screen height.engineProvider
(string
). Provider of the quick app engine.windowWidth
(number
). Available window width, which is determined by the actual screen resolution.windowHeight
(number
). Available window height, which is determined by the actual screen resolution. (Available window height = Screen height - Status bar height - Title bar height - Virtual navigation bar height)statusBarHeight
(number
). Status bar height, which is determined by the actual screen resolution.pixelRatio
(number
). Device pixel ratio.screenDensity
(number
). Screen density of the device.timeZone
(string
). Current system time zone.fontScale
(number
). Font size.characteristics
(string
). Device type (options aredefault
,tv
,tablet
, andphone
). The default value isphone
.windowLogicWidth
(number
). The base value for a widget is750
, a normal quick app, the value of this parameter is the same as the value ofdesignWidth
in theconfig
member of the manifest. The default value is750
.windowLogicHeight
(number
). The base value for a widget is750
.marketingName
(string
). Model marketing name of the device.
Example:
try {
const res = device.getInfoSync();
console.log(res.brand);
console.log(res.model);
} catch (e) {
// Do something upon an error.
console.log(e.code + e.message);
}
# getId({type,success,fail,complete})
Obtains the device ID, user ID, and MAC address.
# Arguments
This method requires an object
with the following attributes:
type
(array
). Mandatory attribute with the types of identifier to be retrieved. The options are:device
,mac
, anduser
.success
(function(res)
). Optional callback function for success. The function has anobject
argument with the identifier(s) requested:device
(string
). Unique device ID. In versions earlier than Android 10.0, the IMEI or MEID is returned. In Android 10.0 and later versions, the AAID is returned, which is unique to each quick app.mac
(string
). MAC address of a device. In versions earlier than Android 6.0, the MAC address of the device is returned. In Android 6.0 and later versions, a fixed value is returned.user
(string
). Unique user ID. In versions earlier than Android 10.0, the value ofANDROID_ID
is returned. In Android 10.0 and later versions, the value varies depending on the signing certificate fingerprint of the quick app.
fail
(function(code)
). Optional callback function for failure. The code of this function can be:201
when the user has rejected the request for sharing the information.
complete
(function()
). Optional callback function for completion.
Example:
device.getId({
type: ["device", "mac"],
success:function(data) {
console.log("handling success: " + data.device);
},
fail: function(data, code) {
console.log("handling fail, code=" + code);
}
})
# getDeviceId({success,fail,complete})
Obtains the identifier of the device.
# Arguments
This method requires an object
with the following attributes:
success
(function(res)
). Optional callback function for success. The function has anobject
argument with the identifier requested:deviceId
(string
). Unique device ID. In versions earlier than Android 10.0, the IMEI or MEID is returned. In Android 10.0 and later versions, the AAID is returned, which is unique to each quick app.
fail
(function(code)
). Optional callback function for failure. The code of this function can be:201
when the user has rejected the request for sharing the information.
complete
(function()
). Optional callback function for completion.
Example:
device.getDeviceId({
success: function(data) {
console.log("handling success: " + data.deviceId);
},
fail: function(data, code) {
console.log("handling fail, code=" + code);
}
})
# getUserId({success,fail,complete})
Obtains the identifier of the user.
# Arguments
This method requires an object
with the following attributes:
success
(function(res)
). Optional callback function for success. The function has anobject
argument with the identifier requested:userId
(string
). Unique user ID. In versions earlier than Android 10.0, the value ofANDROID_ID
is returned. In Android 10.0 and later versions, the value varies depending on the signing certificate fingerprint of the quick app.
fail
(function(code)
). Optional callback function for failure.complete
(function()
). Optional callback function for completion.
Example:
device.getUserId({
success: function(data) {
console.log("handling success: " + data.userId);
},
fail: function(data, code) {
console.log("handling fail, code=" + code);
}
})
# getOAID({success,fail,complete})
Retrieves the OAID of a device.
# Arguments
This method requires an object
with the following attributes:
success
(function(res)
). Optional callback function for success. The function has anobject
argument with the identifier requested:oaid
(string
). OAID of the device. If the current device does not support OAID, the system will returnnull
. If the user configures the system to disable personalized ads on the device, the value will be a string with zeros.
fail
(function(code)
). Optional callback function for failure.complete
(function()
). Optional callback function for completion.
Example:
device.getOAID({
success: function (ret) {
that.OAID = JSON.stringify(ret);
},
fail: function (erromsg, errocode) {
that.OAID = errocode + ': ' + erromsg
},
complete: function () {
prompt.showToast({
message: "The request is completed." + device.allowTrackOAID
})
}
})
# getTotalStorage({success,fail,complete})
This method gets the total internal storage space, excluding the storage space provided by an external SD card.
# Arguments
This method requires an object
with the following attributes:
success
(function(res)
). Optional callback function for success. The function has anobject
argument with the value requested:totalStorage
(number
). Total storage space, in bytes.
fail
(function(code)
). Optional callback function for failure.complete
(function()
). Optional callback function for completion.
Example:
device.getTotalStorage({
success:function(data) {
console.log("handling success: " + data.totalStorage);
},
fail: function(data, code) {
console.log("handling fail, code=" + code);
}
})
# getSerial({success,fail,complete})
Gets the serial number of a device.
The user must grant the permission to access this data.
# Arguments
This method requires an object
with the following attributes:
success
(function(res)
). Optional callback function for success. The function has anobject
argument with the identifier requested:serial
(string
). Serial number of the device.
fail
(function(code)
). Optional callback function for failure. This function has an argument that will be201
when the user rejects the authorization.complete
(function()
). Optional callback function for completion.
Example:
device.getSerial({
success: function (ret) {
console.log("handling success: " +JSON.stringify(ret));
},
fail: function (erromsg, errocode) {
console.log("handling success: "+ errocode + ': ' + erromsg)
},
complete: function () {
prompt.showToast({
message: "The request is completed."
})
}
})
# getAvailableStorage({success,fail,complete})
Gets the available internal storage space, excluding the external SD cards.
# Arguments
This method requires an object
with the following attributes:
success
(function(res)
). Optional callback function for success. The function has anobject
argument with the following attribute:availableStorage
(number
). Available storage space, in bytes.
fail
(function(code)
). Optional callback function for failure.complete
(function()
). Optional callback function for completion.
Example:
device.getAvailableStorage({
success:function(data) {
console.log("handling success: " + data.availableStorage);
},
fail: function(data, code) {
console.log("handling fail, code=" + code);
}
})
# getCpuInfo({success,fail,complete})
Method to get information about the CPU of the device.
# Arguments
This method requires an object
with the following attributes:
success
(function(res)
). Optional callback function for success. The function has anobject
argument with the following attribute:cpuInfo
(string
). CPU information. For an Android device, the system returns the content of the/proc/cpuinfo
file.
fail
(function(code)
). Optional callback function for failure.complete
(function()
). Optional callback function for completion.
Example:
device.getCpuInfo({
success:function(data) {
console.log("handling success: " + data.cpuInfo);
},
fail: function(data, code) {
console.log("handling fail, code=" + code);
}
})
# getTheme({success,fail,complete})
Gets information about the theme enabled in the system..
# Arguments
This method requires an object
with the following attributes:
success
(function(res)
). Optional callback function for success. The function has anobject
argument with the the following attributes:title
(string
). Mandatory attribute with the name of the current theme.titleCn
(string
). Optional attribute with the Chinese name of the current theme.author
(string
). Mandatory attribute with the author of the current theme.designer
(string
). Optional attribute with the designer of the current theme.version
(string
). Optional attribute with the version number of the current theme.font
(string
). Optional attribute with the font name of the current theme.fontCn
(string
). Optional attribute with the name of the Chinese font used in the current theme.darkMode
(boolean
). Mandatory attribute that indicates whether the dark theme is used (true
) or not.
fail
(function(code)
). Optional callback function for failure. This function has an argument that may have the following values:200
: General error.203
: Service unavailable.301
: The theme file or dark theme information does not exist.
complete
(function()
). Optional callback function for completion.
Example:
device.getTheme({
success: function(ret) {
console.log("theme title" + ret.title);
}
});
# getThemeSync()
Gets information about the theme enabled in the system (synchronously)..
# Return
This method returns an object
with the following attributes:
title
(string
). Attribute with the name of the current theme.titleCn
(string
). Attribute with the Chinese name of the current theme.author
(string
). Attribute with the author of the current theme.designer
(string
). Attribute with the designer of the current theme.version
(string
). Attribute with the version number of the current theme.font
(string
). Attribute with the font name of the current theme.fontCn
(string
). Attribute with the name of the Chinese font used in the current theme.darkMode
(boolean
). Attribute that indicates whether the dark theme is used (true
) or not.
In case of failure, the method returns the following codes:
200
: General error.203
: Service unavailable.301
: The theme file or dark theme information does not exist.
Example:
try {
const res = device.getThemeSync();
console.log(res. title);
console.log(res. author);
} catch (e) {
// Do something upon an error.
console.log(e.code + e.message);
}
# getServiceCountryCode({success,fail,complete})
Obtains the current service country/region code of the device platform.
# Arguments
This method requires an object
with the following attributes:
success
(function(res)
). Optional callback function for success. The function has anobject
argument with the following attribute:serviceCountryCode
(string
). Current service country/region code of the system. It follows the ISO 3166 (opens new window) standard.
fail
(function(code)
). Optional callback function for failure. This function has an argument that may have the following values:200
: General error.
complete
(function()
). Optional callback function for completion.
Example:
device.getServiceCountryCode({
success: function (ret){
console.log(`serviceCountryCode = ${ret.serviceCountryCode}`)
},
fail: function(erromsg, errocode){
console.log(`error message = ${erromsg}, error code = ${errocode}`)
},
complete: function () {
prompt.showToast({
message: "The request is completed."
})
}
})
# toLocaleDateTimeString(timestamp)
Auxiliary method to convert a timestamp to a string in the same format as the system's date/time configuration.
# Arguments
timeStamp
(number
). Mandatory argument with the timestamp to convert.
# Return
This method returns a string
with the timestamp converted into the same format as the system date and time configuration.
Example:
console.log(device.toLocaleDateTimeString(123456))
# toLocaleDateString(timestamp)
Auxiliary method to convert a timestamp to a string in the same format as the system's date configuration.
# Arguments
timeStamp
(number
). Mandatory argument with the timestamp to convert.
# Return
This method returns a string
with the timestamp converted into the same format as the system date and time configuration.
Example:
console.log(device.toLocaleDateTimeString(123456))
# toLocaleTimeString(timestamp)
Auxiliary method to convert a timestamp to a string in the same format as the system's time configuration.
# Arguments
timeStamp
(number
). Mandatory argument with the timestamp to convert.
# Return
This method returns a string
with the timestamp converted into the same format as the system date and time configuration.
Example:
console.log(device.toLocaleDateTimeString(123456))
# host({success,fail,complete})
Obtains the package name, version code, and version name of the host app.
# Arguments
This method requires an object
with the following attributes:
success
(function(res)
). Optional callback function for success. The function has anobject
argument with the following attributes:package
(string
). Package name of the host app.versionCode
(number
). Version code of the host app.versionName
(string
). Version name of the host app.
fail
(function(code)
). Optional callback function for failure. This function has an argument that may have the following code:203
: Service unavailable.
complete
(function()
). Optional callback function for completion.
Example:
device.host({
success: function (ret) {
console.log("handling success: " + JSON.stringify(ret));
},
fail: function (erromsg, errocode) {
console.log("handling success: " + errocode + ': ' + erromsg)
},
})
# Events
This service provides the following listener:
# onFontScaleChange(callback)
This method is triggered after changes on the system font settings.
# Arguments
The listener callback function has an object
argument that include the following attribute:
fontScale
(number
). This attribute indicates the font size of the system.
Example:
device.onFontScaleChange({
callback: function(ret) {
console.log("fontScale ==" + ret.fontScale);
}
})