DeviceInfo Object

The DeviceInfo object is a hash table in JavaScript and with the following keys. The following return values are available on all platforms:

• screenWidth: Specifies the screen width of the device by considering the device orientation at the time of query. The returned value is in device independent pixels (Dp). This attribute is supported in iOS, Android, Windows, and SPA platforms.
• screenHeight: Specifies the screen height of the device by considering the device orientation at the time of query. The returned value is in device independent pixels (Dp). This attribute is supported in iOS, Android, Windows, and SPA platforms.

Note: The values returned by the screenWidth and screenHeight properties describe the screen space where widgets can be placed using layout parameters. This includes app menu height, headers, and footers, but excludes the screen space occupied by status bar.

• deviceID: The unique device identifier. The following are the device IDs returned by the platforms:
  • Windows Phone: Device Unique ID (20 bytes in length), a unique hash for the device. This value is constant across all applications and does not change even if the phone is updated with a new version of the operating system.

  • iOS 7 and above: A 32-bit unique ID that is generated by using a private hashed constant and the bundle identifier of the application.

    Note: From V8 ServicePack4 Fixpack 93, the MAC address is not used to identify the device due to privacy issues. Therefore, instead of using the MAC address, use the identifierForVendor property. For more information on how to use the identifierForVendor property in your app, refer the Base Camp article.

  • It internally uses the MAC address of the iOS device and the Bundle Identifier of the application to generate a 32-bit id.
  • From V8 SP4 onwards, the deviceID key is available for Desktop Web and SPA platforms with the following features:
    • If a new device is detected for the same user, you can use deviceID to register the user's device and map it with the logged-in user in order to perform an action, such as an email alert on new device login or send a push notification.

    • If a user clears the cache, the next time the user launches the web app on the same device, the user is treated as unique. The deviceID value does not persist after cache cleanup.

    • If a user opens two different web apps on the same device, the deviceID value is also different for both the apps.

    • If a user opens a web app in Incognito mode, deviceID continues to work.
  • Android: Returns the unique device ID, for example, the IMEI for GSM and the MEID or ESN for CDMA phones. For application running on APILevel>=23 (Marshmallow) devices, you must use the uid property in deviceInfo to get the IMEI for GSM and the MEID or ESN for CDMA phones. For application running on APILevel >= 23 (Marshmallow) devices ANDROID_ID is returned as deviceID to get rid of acquiring READ_PHONE_STATE permission for device id from Telephony Manager.
  • For application running on APILevel <= 22, this property tries to retrieve (Device ID) IMEI for GSM and the MEID or ESN for CDMA phones if available from Telephony Manager.If IMEI/MEID/ESN is not available, in any of the devices such as tablets, SERIAL_NO of the device is returned. If both are not present then ANDROID_ID is returned as a device-id.
  • Set the READ_PHONE_STATE permission in the Android Manifest file to view the device ID. For more information on DeviceiD, http://developer.android.com/reference/android/telephony/TelephonyManager.html#getDeviceId()

• SERIAL_NO: Is a hardware serial number which is Alphanumeric and case-insensitive.This is defined for APILevel >= 9. For more information refer, http://developer.android.com/reference/android/os/Build.html#SERIAL. For applications targeting 26 and above and running on OS API Level26 (Oreo) and above, a prompt to acquire android.permission.READ_PHONE_STATE permission appears if the permission is not previously granted by the user. If the user denies the permission, a permission error appears. In this case user also needs to add READ_PHONE_STATE permission in the Android Manifest file. For apps targeting OS API Level25 and below permissions are not required.

  Note: In Android, the property returns null when used on devices running OS API Level 29 (Android-Q) and above without showing any permission dialog.
  
  Starting in Android Q, apps must have the READ_PRIVILEGED_PHONE_STATE privileged permission (which cannot be granted to a regular app) to access the device's non-resettable identifiers, which include both IMEI and serial number. For more information, see Android Documentation.

• ANDROID_ID: In versions of the platform lower than Android 8.0 (API level 26), a 64-bit number (expressed as a hexadecimal string) that is randomly generated when the user first sets up the device and should remain constant for the lifetime of the user's device. On devices that have multiple users, each user appears as a separate device, so the ANDROID_ID value is unique to each user. For more information refer, http://developer.android.com/reference/android/provider/Settings.Secure.html#ANDROID_ID
  
  Android IDE behavioral changes on Android 8.0 (API level 26) and higher versions of the platform:

  • A 64-bit number (expressed as a hexadecimal string), unique to each combination of app-signing key, user, and device. Values of ANDROID_ID are scoped by signing key and user. The value may change if a factoryreset is performed on the device or if an APK is signing key changes. As a result, apps with different signing keys running on the same device no longer see the same Android ID (even for the same user).
  • For apps that were installed prior to an OTA to a version of Android 8.0 (API level 26), the value of ANDROID_ID remains the same unless uninstalled and then reinstalled after the OTA.
  • The value of ANDROID_ID does not change on package uninstall or reinstall, as long as the signing key is the same (and the app was not installed prior to an OTA to a version of Android 8.0).
  • The value of ANDROID_ID does not change even if a system update causes the package signing key to change.
  • On Android 8.0 (API level 26) and higher versions of the platform, a 64-bit number (expressed as a hexadecimal string), unique to each combination of app-signing key, user, and device. Values of ANDROID_ID are scoped by signing key and user. The value may change if a factory reset is performed on the device or if an APK is signing key changes.
  • In versions of the platform lower than Android 8.0 (API level 26), a 64-bit number (expressed as a hexadecimal string) that is randomly generated when the user first sets up the device and should remain constant for the lifetime of the user's device. On devices that have multiple users, each user appears as a completely separate device, so the ANDROID_ID value is unique to each user.
  • For apps installed on a device running Android 8.0, the value of ANDROID_ID is now scoped per app signing key, as well as per user. The value of ANDROID_ID is unique for each combination of app-signing key, user, and device. As a result, apps with different signing keys running on the same device no longer see the same Android ID (even for the same user).
• uid: Returns the unique device IDthe IMEI for GSM and the MEID or ESN for CDMA phones from Telephony Manager. Returns null on some devices such as tablets where Telephony Manager is not available is not available. As this requires READ_PHONE_STATE permission, the uid returns device id from Telephony Manager after properly handling permissions. Using the uid identifier (when used on devices running OS APILevel 23 Marshmallow and above, and when application targets APILevel 23 and above) prompts permission dialog to acquire android.permission.READ_PHONE_STATE permission if not already granted by the user. If the user denies the permission, a PermissionError appears. If your application target is less than OS API level 23, then the above permission dialog would not appear. Set the READ_PHONE_STATE permission in the Android Manifest file to view the device ID.

  Note: In Android, the property returns null when used on devices running OS API Level 29 (Android-Q) and above without showing any permission dialog.
  
  Starting in Android Q, apps must have the READ_PRIVILEGED_PHONE_STATE privileged permission (which cannot be granted to a regular app) to access the device's non-resettable identifiers, which include both IMEI and serial number. For more information, see Android Documentation.

• customdeviceid: For iPhone, a custom device identifier is returned. It internally uses the MAC address of the iOS device and the Bundle Identifier of the application to generate this.

Note: The new iPhone retina display contains double the pixels (640) as that of the standard display (320), but iOS treats the resolution as a standard display for measurement and screen output. Websites built for non-retina versions will look very tiny and zoomed out.

• identifierForVendor: An alphanumeric string that uniquely identifies a device to the app’s vendor. The value of this property is the same for apps that come from the same vendor running on the same device. A different value is returned for apps on the same device that come from different vendors, and for apps on different devices regardless of vendor.

if (iOS version is less than 6.0){
	kony.os.deviceInfo().customdeviceid
} else {
	kony.os.deviceInfo().identifierForVendor
}

Important: This property is applicable only for iOS 6 and above.

• name: Specifies the name of the platform as iPhone, iPad, Windows Phone, thin client (The name thin client is used for SPA/ Desktop Web / Mobile Web), and Android.
• model: Specifies the model number of the platform. For example 8900. Not applicable for Mobile Web.
• deviceWidth: The device width in pixels. Valid only on Native Apps channels and not applicable for Mobile Web.
• deviceHeight: The device height in pixels. Valid only on Native Apps channels and not applicable for Mobile Web.
• hasforcetouchsupport: A Boolean value that specifies whether force touch is supported on the device. This value is true if force touch is supported; otherwise, false.

function isForceTouchAvailble() {
    var deviceInfo = kony.os.deviceInfo();
    return deviceInfo.hasforcetouchsupport;
}	

• APILevel: Provides the Android API Level based on the SDK Version.

function getDeviceAPILevel() {
    var devInfo = kony.os.deviceInfo();
    return devInfo.APILevel;
}

The following are the mappings between Android SDK Version and the API Level that is returned:

• SDK 1.5 - 3
• SDK 1.6 - 4
• SDK 2.1 - 7
• SDK 2.2 - 8
• SDK 2.3 - 9
• SDK 2.3.3 - 10
• SDK 3.0 - 11

  Note: The API Level is returned only for Android.

• For Mobile Web, the following values are returned:
  • type [String] - Specifies if the Mobile Web is Advanced or Basic.
  • category [String] - Provides the Mobile Web category.
    For Advanced Mobile Web, the return value can be iPhone or Android.
  • tcsession [String] - Provides the session ID of the current user.
  • imagecat [String] - Image category based on the device width available in Kony Device Database or returns a default value.

Copyright © 2013 Kony, Inc. All rights reserved.