kony.os Namespace
The kony.os namespace provides functions for the Operating System API. It contains the following API elements:
Constants
The kony.os Namespace contains the following types of constants.
These constants specify the current state of the device battery.
Constant | Description |
---|---|
BATTERY_STATE_CHARGING | Indicates that the state of the device battery as being charged. |
BATTERY_STATE_DISCHARGING | Indicates that the state of the device battery as being discharged. |
BATTERY_STATE_FULL | Indicates that the state of the device battery charge is completely full. |
BATTERY_STATE_UNKNOWN | Indicates that the state of the device battery charge as not known. |
Example
When you query for the state of the device battery as shown in this example, any of the four available battery states is returned.
var batteryState = kony.os.getBatteryState(); if (kony.os.BATTERY_STATE_CHARGING == batteryState) { kony.print(“Battery State: Charging”); }
Platform Availability
- iOS
- Android
Functions
The kony.os namespace contains the following functions.
UUID (Universally Unique Identifier) is a universally unique value that can be used to identify types, interfaces, and other items. This API returns a string that contains a formatted UUID value. For example, E621E1F8-C36C-495A-93FC-0C247A3E6E5F.
Syntax
kony.os.createUUID();
Input Parameters
None
Example
function createMyUUIDFunc() { var uuid = kony.os.createUUID(); kony.print("The created UUID is : " + uuid); }
Return Type
String
Platform Availability
- Android
- iOS
This API helps your application to detect the presence of any Dynamic Instrumentation instance. Currently, this API only supports the detection of Frida server presence.
Syntax
kony.os.detectDynamicInstrumentation(object);
Input Parameters
Parameter |
Description |
---|---|
object[Object] -Mandatory | This is a dictionary that contains the following keys:
This callback is executed when the presence of Dynamic Instrumentation is detected. If you do not specify this key, the application safely exits by default whenever it detects Dynamic Instrumentation.
This callback is executed when Dynamic Instrumentation is not detected.
This parameter specifies the type of detection that is to be performed. You can specify any one of the following values for this parameter:
|
Example
var didobject = { detectedCallback: detectedCallbackFunction, undetectedCallback: undetectedCallbackFunction, "type": "fridaquickscan" }; kony.os.detectDynamicInstrumentation(didobject);
Return Value
None
Platform Availability
- Android
This API allows the developers to get information about the device in which the application is launched.
You can view a video on using Device Info API here.
Syntax
deviceInfo();
Input Parameters
None
Example
var deviceInfo = kony.os.deviceInfo(); alert(deviceInfo); for (var key in deviceInfo) { if (deviceInfo.hasOwnProperty(key)) { alert(key + ":" + deviceInfo[key]); } }
Return Values
Return Value |
Description |
---|---|
values[Object] | Returns a DeviceInfo object. |
Platform Availability
Available on all platforms.
This API provides the ability to query and fetch the system-wide memory available on the mobile device for allocation.
You can use this API to:
- Check the amount of free memory on the mobile device before you go ahead with installation of any software or applications.
- Find out the free memory on the mobile device, clear unwanted objects, and thus improve the performance of the application.
Syntax
kony.os.freeMemory();
Input Parameters
None
Example
In the following example, kony.os.freeMemory returns the freememory available for allocation.
var freememory = kony.os.freeMemory(); kony.print(freememory); //After the kony.os.freeMemory operation, the memory available for allocation is printed. //For example, 1070404 (indicates that 1046 KB of memory is available for allocation)
Return Values
Return Value |
Description |
---|---|
Free memory[Number] | The available memory for allocation is returned. The returned memory always indicates the number of bytes available. |
Platform Availability
- Available on all platforms*.
*Dummy implementation on DesktopWeb and returns a dummy value.
Retrieves the current percentage charge level of the device battery, as an integer value.
Syntax
kony.os.getBatteryLevel();
Input Parameters
None
Example
getBatteryLevel: function() { kony.os.registerBatteryService(this.batterySuccessCallback); var battery = kony.os.getBatteryLevel(); kony.os.unregisterBatteryService(); this.view.lblDisplay.text = battery + "%"; },
Return Values
Returns an integer that ranges from 0-100 (inclusive) that specifies the battery's current charge level in percentage. For example, a return value of 30 specifies that the current charge level of the battery is 30%.
Platform Availability
- iOS
- Android
Retrieves the current state of the battery.
Syntax
kony.os.getBatteryState();
Input Parameters
None
Example
//This code is used to obtain your device battery state getBatteryState: function() { kony.os.registerBatteryService(this.batterySuccessCallback); var batteryState = kony.os.getBatteryState(); if (kony.os.BATTERY_STATE_CHARGING == batteryState) { alert("The Device is charging"); kony.os.unregisterBatteryService(); } else if (kony.os.BATTERY_STATE_DISCHARGING == batteryState) { alert("The Device is discharging"); kony.os.unregisterBatteryService(); } else if (kony.os.BATTERY_STATE_FULL == batteryState) { alert("The Device is completely charged"); kony.os.unregisterBatteryService(); } else if (kony.os.BATTERY_STATE_UNKNOWN == batteryState) { alert("The Device charging state is unkonwn"); kony.os.unregisterBatteryService(); } },
Return Values
Returns a constant from the Battery State Constants.
Remarks
The battery state indicates whether it is charging, discharging, and so forth.
Platform Availability
- iOS
- Android
This API returns the unique ID of a device: IMEI for GSM phones and MEID or ESN for CDMA phones from Telephony Manager, based on the slot index that you provide. This API works when used on devices that have an operating system of API Level 23 Marshmallow or later, and when the application targets an API Level of 23 or later.
As this API requires the READ_PHONE_STATE permission, the getDeviceId API returns the device ID from Telephony Manager after properly handling permissions and prompts the permission dialog to acquire the Android permission. If you deny the READ_PHONE_STATE permission, a Permission error is displayed.
You must set the READ_PHONE_STATE permission in the Android Manifest file to retrieve 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.
Syntax
kony.os.getDeviceId(int slot);
Input Parameters
Slot Index as an integer value.
Example
function getMyDeviceIDFunc() { var devId = kony.os.getDeviceId(0); // param is sim slot kony.print("The device ID of the first SIM slot is: " + devId); }
Return Type
String
Unsupported Cases
-
If your application is running on a device with an operating system earlier than API level 23, the API returns "Null."
-
Invalid slot indexes that are not supported by a device are ignored and the API returns "Null."
-
The API returns "Null" on some devices, such as tablets, where Telephony Manager is not available.
Platform Availability
- Android
This API returns the current orientation of the device. The possible values are portrait or landscape.
Syntax
kony.os.getDeviceCurrentOrientation();
Input Parameters
None
Example
kony.os.getDeviceCurrentOrientation(); //Returns the orientation of the device
Return Values
This API returns whether the device orientation is landscape or portrait.
- constants.DEVICE_ORIENTATION_PORTRAIT
- constants.DEVICE_ORIENTATION_LANDSCAPE
Platform Availability
- iOS
- Android
- Desktop Web
This API returns the maximum OpenGLES Version supported by the device.
Depending on the value returned, you can determine if the device supports AR capabilities.
Syntax
kony.os.getOpenGlESVersion();
Input Parameters
None.
Example
if (kony.os.getOpenGLESVersion() >= 3.0 && kony.os.deviceInfo().APILevel >= 24) { kony.print("ARRenderer is supported") } else { kony.print("none of the AR apis will work") }
Return Values
Return Value |
Description |
---|---|
version | Returns the Open GLES Version number. |
Platform Availability
- Android
This API returns whether accelerometer is supported on a device.
Syntax
hasAccelerometerSupport();
Input Parameters
None.
Example
kony.print(kony.os.hasAccelerometerSupport()); //prints true if device has accelerometer support
Return Values
Return Value |
Description |
---|---|
value[Boolean] | Returns whether accelerometer is supported on a device. |
Platform Availability
- iPhone
- Android
This API returns whether Camera is supported on a device.
Syntax
hasCameraSupport();
Input Parameters
None.
Example
kony.print(kony.os.hasCameraSupport()); //prints true if device has camera support
Return Values
Return Value |
Description |
---|---|
value[Boolean] |
true: the platform supports Camera false: the platform does not support Camera |
Platform Availability
Available on all platforms.
This API returns whether GPS is supported on a device.
Syntax
kony.os.hasGPSSupport();
Input Parameters
None.
Example
kony.print(kony.os.hasGPSSupport()); //prints true if device has GPS support
Return Values
Return Value |
Description |
---|---|
value[Boolean] |
true: the platform supports GPS. false: the platform does not support GPS. |
Platform Availability
Available on all platforms.
This API returns whether Orientation is supported on a device.
You can view a video on using Display Orientation here.
Syntax
kony.os.hasOrientationSupport();
Input Parameters
None.
Example
var orientation = kony.os.getDeviceCurrentOrientation(); if (orientation == constants.DEVICE_ORIENTATION_PORTRAIT) { alert("PORTRAIT"); } else if (orientation == constants.DEVICE_ORIENTATION_LANDSCAPE) { alert("LANDSCAPE"); } else { alert("UNKNOWN"); }
Return Values
Return Value |
Description |
---|---|
value[Boolean] |
true: the platform supports orientation. false: the platform does not support orientation. |
Platform Availability
Available on all platforms.
This API returns whether Touch is supported on a device.
Syntax
kony.os.hasTouchSupport();
Input Parameters
None.
Example
kony.print(kony.os.hasTouchSupport()); //prints true if device is a touch device
Return Values
Return Value |
Description |
---|---|
value[Boolean] |
true: the platform supports touch. false: the platform does not support touch. |
Platform Availability
Available on all platforms except Desktop Web.
This API checks whether Huawei Mobile Services is installed and enabled on the device.
Syntax
isHuaweiMobileServicesAvailable();
Input Parameters
None.
Example
kony.os.isHuaweiMobileServicesAvailable();
Return Values
Return Value |
Description |
---|---|
value[Boolean] |
true: Huawei Mobile Services is installed and enabled on the device. false: the device does not have Huawei Mobile Services installed or enabled on the device. |
Platform Availability
- Android
When invoked without any parameter, this API prints the entire form that is currently in view.
Syntax
kony.os.print(containerID);
Input Parameters
Parameter |
Description |
---|---|
containerID [Number] - Optional |
The containerID can be a ID of any container widget that can be directly referenced from a form.
|
Example
kony.os.print();
Return Values
None.
Platform Availability
- Desktop Web.
Registers for the battery monitoring service of the device operating system. The callback is delivered to the most recent registered battery service.
NOTE: Whenever the battery state changes or for every 1% change in the battery level, a callback to the registerBatteryService function is triggered.
Syntax
kony.os.registerBatteryService(callbackMethod);
Input Parameters
Parameter | Description |
---|---|
callbackMethod | A JavaScript function that is automatically invoked when you register to the battery monitoring service of the device OS. |
Example
/*This code is used to register a battery service and deregister the service based on your battery level*/ registerBatteryService: function() { kony.os.registerBatteryService(this.mybatterychangecallback); var batterylevel = kony.os.getBatteryLevel(); }, mybatterychangecallback: function(batteryInfo) { var batterylevel = batteryInfo.batterylevel; if (batterylevel <= 20) { alert("The Battery Level is below 20%, make sure that you charge your device"); } else { kony.os.unregisterBatteryService(); alert("We are unregistering the Battery Service as it might cause an overhead"); } },
Return Values
None
Limitations
- The callback for the registered battery service is delivered only when the application is running; this is because, you can only receive notifications when the application is in the foreground for the iOS and Android platforms.
- The callback to the registered battery service is delivered after every one minute duration for iOS; whereas in case of in Android, the callback is delivered for every 1% change in the battery charge.
Platform Availability
- iOS
- Android
This API allows you to convert the given number to represent currency. At present, only USA currency is supported.
Syntax
kony.os.toCurrency(number);
Input Parameters
Parameters | Description |
---|---|
number[Number] - Mandatory | Specifies the number that must be converted to represent currency. If the input number is a negative number, the negative number is treated as a positive number (this is because a currency does not have any negative symbol) and the converted value is returned. |
Example
Perform a kony.os.toCurrency operation on the number "10000".
var tocurrency = kony.os.toCurrency(10000); kony.print(tocurrency); //prints $ 10,000
Return Values
Return Value | Description |
---|---|
Currency [String] | A string with the number formatted as currency. If the input string has decimal points, the return value is truncated till two decimal points. |
Exceptions
An error is thrown if input is invalid or does not follow the expected structure.
102 - Invalid input error
Platform Availability
Available on all platforms.
This API converts the argument to a number. If the argument is already a number or a string convertible to a number, then the API returns this number; otherwise, it returns null for JavaScript.
Syntax
kony.os.toNumber(argument)
Input Parameters
Parameters | Description |
---|---|
argument [String or Number] - Mandatory | The argument that must be converted to a number. |
Example
In this example, only the string which can be converted to a number returns a number otherwise it returns n.
kony.os.toNumber (ms34rd); //returns null as the string passed cannot be converted to a number kony.os.toNumber ("58"); //returns 58 as the string could be converted to a number
Return Values
Return Value | Description |
---|---|
Converted Number [Number] | The input string or number that has been converted to a number and returned. |
null/nil | The argument cannot be converted to a number. |
Remarks
The input parameter must be a number or a string.
Exceptions
An error is thrown if input is invalid or does not follow the expected structure.
102 - Invalid input error
Platform Availability
Available on all platforms.
This API stops the monitoring process of the device battery. You must call this API when the use of the battery monitoring service has been completed, to reduce the overhead.
NOTE: After your app calls the kony.os.unregisterBatteryService API, the callback function registered by the kony.os.registerBatteryService API is no longer invoked.
Syntax
kony.os.unregisterBatteryService();
Input Parameters
None
Example
/*This code is used to register a battery service and deregister the service based on your battery level*/ registerBatteryService: function() { kony.os.registerBatteryService(this.mybatterychangecallback); var batterylevel = kony.os.getBatteryLevel(); }, mybatterychangecallback: function(batteryInfo) { var batterylevel = batteryInfo.batterylevel; if (batterylevel <= 20) { alert("The Battery Level is below 20%, make sure that you charge your device"); } else { kony.os.unregisterBatteryService(); alert("We are unregistering the Battery Service as it might cause an overhead"); } },
Return Values
None
Platform Availability
- iOS
- Android
This API returns a unique identifier of the mobile device that is extracted from the useragent. This unique ID represents the device model and the manufacturer. Quantum Visualizer Application Server uses this information to adjust the content to match the screen resolution of the device. For example, the content is adjusted to fit the screen width, height, or memory required etc.
The useragent contains the following information:
- device model
- manufacturer
- OS version
- browser version
- Java capabilities, and so on.
The following are a few sample useragents:
Useragent | Description |
---|---|
Nokia6230i/2.0 (03.25) Profile/MIDP-2.0 Configuration/CLDC-1.1
|
Nokia 6230i model mobile device |
SonyEricssonT610/R501 Profile/MIDP-1.0 Configuration/CLDC-1.0
|
SonyEricsson T610 model mobile device |
OPWV-SDK/62 UP.Browser/6.2.2.1.208 (GUI) MMP/2.0
|
Openwave Mobile Browser 6.2.2 |
Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0)
|
Microsoft Internet Explorer 6 |
Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US; rv:1.7.12) Gecko/20050915 Firefox/1.0.7
|
Mozilla Firefox 1.0.7 running on Windows 2000 |
Mozilla/5.0(iPad; U; CPU iPhone OS 3_2 like Mac OS X; en-us) AppleWebKit/531.21.10 (KHTML, like Gecko) Version/4.0.4 Mobile/7B314 Safari/531.21.10
|
iPad |
Device Model. For example, Galaxy Nexus.
|
Android and Android Tablet. |
You can use this API in the following scenarios when you need to identify:
- The model of a specific mobile device.
- The mobile devices based on the manufacturer.
- If the device is a web browser, mobile device, micro browser, or a computer.
Syntax
kony.os.userAgent();
Input Parameters
None
Example
In the following example, the uid returned by the kony.os.userAgent is displayed in the alert.
var devID = kony.os.userAgent(); alert("User Agent return value is::" + devID);
Return Values
Device ID [String]
Any of the available Device ID is returned in the order Device Model, OS Version, Browser Version, Java Capabilities, and Manufacturer.
- For Android and Android Tablet, device model is returned as an user agent.
- For iOS Devices, user agent is returned as a string.
Platform Availability
Available on all platforms.