kony.os Namespace

These constants specify the current state of the device battery.

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
• Windows

This API helps the developers to pass dynamic values when the form needs to be submitted to external sites.

Syntax

addHiddenField(key,value,private)

Input Parameters

Example

function addHiddenField() {
    kony.os.addHiddenField("myhiddenfield", "myvalue", "private");
    // private value is specified and hence this hiddenfield can be read through the kony.os.readHiddenField API
    kony.os.addHiddenField("myhiddenfield1", "myvalue");
    // As private value is not specified and hence this hiddenfield cannot be read through the kony.os.readHiddenField API
}

Return Values

None.

Platform Availability

Available only on Mobile Web.

This API adds a meta tag in html header. This API result will effect only on header reload.

Syntax

addMetaTag (key, value)

Input Parameters

Example

kony.os.addMetaTag("test2", {
    "http-equiv": "refresh",
    "content": "30"
});

Return Values

This API has no return values.

Platform Availability

Applicable only on Mobile Web.

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

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

Platform Availability

Available on all platforms.

This API can be invoked on an event of a widget. This API should be invoked on forms of the application where user validation is not required or cross site request forgery is not a concern.

Syntax

kony.os.endSecureTransaction()

Input Parameters

None

Example

kony.os.endSecureTransaction();

Return Values

None

Platform Availability

Available only on Mobile Web.

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

Platform Availability

Available on all platforms* except Windows Phone 8, Windows Phone 8.1, Windows Tablet 8, and Windows 7 / Kiosk. *Dummy implementation on Server Side Mobile Web, SPA, and DesktopWeb and returns a dummy value.

This API allows the developers to get information about the mode in which the application is launched.

Syntax

kony.os.getAppContext()

Input Parameters

None

Example

function getAppContext() {
    var mycontext = kony.os.getAppContext();
    kony.print(mycontext); 
    /*prints {launchmode=0} if the application was launched in normal mode ,prints {launchmode=1} if the application was launched in full screen mode*/
}

Return Values

Platform Availability

Applicable only on Mobile Web.

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
• Windows

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
• Windows

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 device orientation

Return Values

This API returns whether the device orientation is landscape or portrait.

• constants.DEVICE_ORIENTATION_PORTRAIT
• constants.DEVICE_ORIENTATION_LANDSCAPE

Platform Availability

Available on iPhone, iPad, Windows 8, Android, Windows 7 / Kiosk, and Desktop Web ( Always returns DEVICE_ORIENTATION_PORTRAIT in Desktop Web Channel)

This API returns whether accelerometer is supported on a device.

Syntax

hasAccelerometerSupport()

Input Parameters

None.

Return Values

Platform Availability

Applicable only on iPhone, Android, and Windows platforms.

Example

kony.print(kony.os.hasAccelerometerSupport());
//prints true if device has accelerometer support

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

Platform Availability

Available on all platforms* except Mobile Web and Windows 7 / Kiosk. *Dummy implementation for SPA and Desktop Web that always returns False.

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

Platform Availability

Available on all platforms except Mobile Web and Windows 7 / Kiosk.

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

Platform Availability

Available on all platforms except Mobile Web.

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

Platform Availability

Available on all platforms except Mobile Web and Desktop Web.

When invoked without any parameter, this API prints the entire form that is currently in view.

Syntax

kony.os.print(containerID)

Input Parameters

Example

kony.os.print()

Return Values

None.

Platform Availability

Applicable only on Desktop Web.

This API allows the developers to read the hidden fields added by the os.addHiddenField API.

Syntax

readHiddenField(key)

Input Parameters

Example

function readHiddenField() {
    kony.os.readHiddenField("myhiddenfield");
    // Reads the value that corresponds to the myhiddenfield key, i.e., myvalue
}

Return Values

Platform Availability

Available only on Mobile 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

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, Windows, 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 and Windows, the callback is delivered for every 1% change in the battery charge.

Platform Availability

• iOS
• Android
• Windows

Registers callbacks for speech recognition events.

Syntax

kony.os.registerSpeechRecognizer(callbackTable)

Input Parameters

Example

function registerCallbacks() {
    kony.os.registerSpeechRecognizer({
        "resultGenerated": resultGenCallback,
        "timeouts": {
            "initialSilenceTimeout": 5,
            "autoStopSilenceTimeout": 60,
            "endSilenceTimeout": 80
        }
    });
}

function resultGenCallback(data) {
    frmHome.txtareaSpeech.text = "Text: " + data.result + "confidence: " + data.confidence + "Status: " + data.status;
}

Return Values

None.

Platform Availability

Available only on Windows 10.

This API removes all the user defined meta tags from a html header. This API result will effect only on header reload.

Syntax

removeAllMetaTags()

Input Parameters

None.

Example

kony.os.removeAllMetaTags()

Return Values

None.

Platform Availability

Applicable only on Mobile Web.

This API removes a specific meta tag from a html header. This API result will effect only on header reload.

Syntax

removeMetaTag (key)

Input Parameters

Example

kony.os.removeMetaTag("test1")

Return Values

This API has no return values.

Platform Availability

Applicable only on Mobile Web.

This API can be invoked on an event of a widget. When this API is invoked it makes all the data and subsequent transactions of the application secure. For example, the login page of an application has the following: user name field, password field, and a button. On the onclick event of the button, the user is verified and navigated to pages with sensitive information. If you want to prevent cross site request forgery or double submissions, you can invoke this API ensuring that all the subsequent transactions are secure.

Syntax

startSecureTransaction(callback, scope)

Input Parameters

Example

function callback() {}
kony.os.startSecureTransaction(callback, 1)

Return Values

This API has no return values.

Remarks

Whenever os.startsecuretransaction is invoked, a krfid for that session or request is generated internally as a hidden field. The krfid is validated for each transaction/request. If the krfid is invalid, the callback function of os.startsecuretransaction API is invoked, and the request processing fails or a message appears stating that the session has expired.

Platform Availability

Available only on Mobile Web.

Starts the speech recognition process.

Note: Speech recognition callback(s) must be registered before invoking this API. Refer kony.os.registerSpeechRecognizer API for more information.

Syntax

kony.os.startSpeechRecognition(successCallback, errorCallback)

Input Parameters

Example

function startSpeech() {
    kony.os.startSpeechRecognition(successCallback, errorCallback);
}

function successCallback(result) {
    alert("Success " + result);
}

function errorCallback(error) {
    alert("Failure " + error);
}

Return Values

None.

Platform Availability

Available only on Windows 10.

Stops existing (already started with kony.os.startSpeechRecognition API) speech recognition operations.

Note: Speech recognition callback(s) must be registered before invoking this API. Refer kony.os.registerSpeechRecognizer API for more information.

Syntax

kony.os.stopSpeechRecognition(successCallback, errorCallback)

Input Parameters

Example

function stopSpeech() {
    kony.os.stopSpeechRecognition(successCallback, errorCallback);
}

function successCallback(result) {
    alert("Success " + result);
}

function errorCallback(error) {
    alert("Failure " + error);
}

Return Values

None.

Platform Availability

Available only on Windows 10.

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

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

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

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

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
• Windows

Deregisters existing (already registered with kony.os.registerSpeechRecognizer API) callbacks for speech recognition events.

Syntax

kony.os.unregisterSpeechRecognizer()

Input Parameters

None.

Example

function unRegisterCallbacks() {
kony.os.unregisterSpeechRecognizer();
}

Return Value

None.

Platform Availability

Available only on Windows 10.

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. Kony 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:

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.

Note:  

• 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 except Windows 7.