Kony 7.0 Beta Mobile Application Development Platform API Developer's Guide

PDF

Dokument

Oglas

Kony

Mobile Application Development

Platform (MADP)

API Developer's Guide

Release 7.0 Beta

Document Relevance and Accuracy

This document is considered relevant to the Release stated on this title page and the document version stated on the Revision History page. Remember to always view and download the latest document version relevant to the software release you are using.

Kony Studio API Developer's Guide

Version 3.1

January, 2016

This document contains information proprietary to Kony, Inc., is bound by the Kony license agreements, and may not be used except in the context of understanding the use and methods of

Kony, Inc., software without prior, express, written permission. Kony, Empowering Everywhere, Kony

Modeler, and Kony Visualizer are trademarks of Kony, Inc. MobileFabric is a registered trademark of

Kony, Inc. Microsoft, the Microsoft logo, Internet Explorer, Windows, and Windows Vista are registered trademarks of Microsoft Corporation. Apple, the Apple logo, iTunes, iPhone, iPad, OS X,

Objective-C, Safari, Apple Pay, Apple Watch, and Xcode are trademarks or registered trademarks of

Apple, Inc. Google, the Google logo, Android, and the Android logo are registered trademarks of

Google, Inc. Chrome is a trademark of Google, Inc. BlackBerry, PlayBook, Research in Motion, and

RIM are registered trademarks of BlackBerry. All other terms, trademarks, or service marks mentioned in this document have been capitalized and are to be considered the property of their respective owners.

Kony Studio API Developer's Guide

Version 3.1

Revision History

Date

13/1/2016

11/10/2015

07/13/2015

05/19/2015

Document Version

3.1

Description of Modifications/Release

Added the

App Group API

Added

functions

in the kony.image namespace.

3.0

Following information added: l

Self Sufficient Modules

TouchID APIs

2.0

1.0

Following information is added: l

MobileFirst APIs

Threading APIs

Wearables -Kony WatchKit Library Utils

Following information is added: l

Local Notifications

Notification Settings

Wearables l

setApplicationCallbacks updated for iOS

1. Preface

1.1 Purpose

1.2 Intended Audience

1.3 Formatting Conventions

1.4 Related Documents

1.5 Contact Us

2. Overview

2.1 Platform Availability

2.2 Accelerometer APIs

2.3 Alert API

2.4 App Group API

2.5 Application APIs

2.6 Application Settings API

2.7 Background Jobs

2.8 Badge APIs

2.9 Beacon FFI APIs

2.10 Bookmark and Refresh API

2.11 Camera API

2.12 Charm Setting APIs

2.13 Cryptography APIs

Kony Studio API Developer's Guide

Version 3.1

4 of 838

2.14 Data Store API

2.15 Functional Modules API

2.16 GeoLocation APIs

2.17 Gesture API

2.18 Hybrid API

2.19 Input and Output APIs

2.20 Internationalization APIs

2.21 kony.localAuthentication Namespace

2.22 Language APIs

2.23 Live Tiles API

2.24 Math APIs

2.25 Mobile First APIs

2.26 Network APIs

2.27 Notifications

2.28 Offline Data Access APIs

2.29 Operating System APIs

2.30 Phone APIs

2.31 Self Sufficient Modules

2.32 Standard Kony APIs

2.33 Streaming API

2.34 String APIs

Kony Studio API Developer's Guide

Version 3.1

5 of 838

2.38 Guidelines for using Threading APIs

2.39 Timer APIs

2.40 Worker Thread APIs

2.41 Appendix: General FAQ

2.42 Appendix: JavaScript FAQ

2.43 Appendix: SQLite

2.44 Background Jobs

3. References

3.1 com.kony Namespace

3.2 DeviceInfo Object

3.3 FormData Object

3.4 HttpRequest Object

3.5 kony Namespace

3.6 kony.accelerometer Namespace

3.7 kony.application Namespace

3.8 kony.application.settings Namespace

3.9 kony.camera Namespace

3.10 kony.contact Namespace

Kony Studio API Developer's Guide

Version 3.1

6 of 838

3.11 kony.crypto Namespace

3.12 kony.db Namespace

3.13 kony.ds Namespace

3.14 kony.filter Namespace

3.15 kony.hybrid Namespace

3.16 kony.image Namespace

3.17 kony.io.File Namespace

3.18 kony.io.FileList Namespace

3.19 kony.io.FileSystem Namespace

3.20 kony.i18n Namespace

3.21 kony.lang Namespace

3.22 kony.localAuthentication Namespace

3.23 kony.localnotifications Namespace

3.24 kony.location Namespace

3.25 kony.map Namespace

3.26 kony.modules Namespace

3.27 kony.net Namespace

3.28 kony.notificationsettings Namespace

3.29 kony.os Namespace

3.30 kony.phone Namespace

3.31 kony.push Namespace

Kony Studio API Developer's Guide

Version 3.1

7 of 838

3.32 kony.store Namespace

3.33 kony.stream Namespace

3.34 kony.string Namespace

3.35 kony.theme Namespace

3.36 kony.timer Namespace

3.37 kony.types.RawBytes Namespace

3.38 kony.UI Namespace

3.39 kony.worker Namespace

3.44 WorkerThread Object

Kony Studio API Developer's Guide

Version 3.1

1. Preface

Kony Studio API Developer's Guide

Version 3.1

1. Preface

Kony Visualizer is an integrated development environment (IDE) for rapid development and deployment of mobile applications. Kony Visualizer is provided as a plug-in to Eclipse , an open-source environment. The IDE offers you an easy to learn and use visual development environment to design and develop the mobile applications. The primary element of Kony Visualizer is a visual developer panel that is used to design the application forms in a device independent wire-frame format.

All the Kony supported devices, development languages, and browsers are listed at, Supported

Devices and Browsers.

1.1 Purpose

This document explains the Application Program Interface (API) used in Kony Visualizer and also provides procedural information to use them to achieve functionality.

1.2 Intended Audience

This document is targeted at developers who use Kony Visualizer to develop applications.

1.3 Formatting Conventions

The following are the formatting conventions used throughout the document:

Click here

1. Preface

Kony Studio API Developer's Guide

Version 3.1

Conventions

Monospace

Italic

Bold

URL

Explanation l

User input text, system prompts, and responses l

File path l

Commands l

Program code l

File names.

Emphasis l

Names of books and documents l

New terminology.

Windows l

Menus l

Buttons l

Icons l

Fields l

Tabs l

Folders.

Active link to a URL.

Provides helpful hints or additional information.

Note:

Important:

Highlights actions or information that might cause problems to systems or data.

1. Preface

Kony Studio API Developer's Guide

Version 3.1

1.4 Related Documents

Document

Kony Server Installation

Guides

Kony Visualizer

Installation Guide

Kony Widget User Guide

Purpose

This guide will help you understand the server installation procedure.

This guide will help you understand the Kony Visualizer installation procedure.

This guide will help you understand the widgets and their functionality in Kony Visualizer.

1.5 Contact Us

We welcome your feedback on our documentation. Write to us at [email protected]

For technical questions, suggestions, comments or to report problems on Kony's product line, contact [email protected]

2. Overview

Kony Studio API Developer's Guide

Version 3.1

2. Overview

The API reference guide comprises all the non GUI APIs that you can use on Kony Visualizer. The non

GUI APIs enable you to perform multiple operations on an application, such as performing various operations on tables, manipulating strings, or invoking a service. The APIs are categorized in this guide by the corresponding namespaces. For example, all the APIs which have the namespace kony.i18n.<xyz> are present in the Internationalization section.

The Kony API library consists of the following: l

String Library: The string Library has APIs that you can use to manipulate strings. The namespace is kony.string.

Standard Kony: The generic APIs with the namespace kony.

Window Library: The APIs with the namespace kony.ui using which you can invoke alerts.

Internationalization: The i18n APIs enable you to design or develop an application in such a way that it supports various languages and regions. The namespace for internationalization is kony.i18n.

Timer: The APIs in this library provide you the ability to schedule the execution of a function block at regular intervals. The namespace for Timer API is kony.timer.

Push Notification: Push Notifications APIs enable you to initiate a message delivery to a device without receiving a request. The namespace for Push API is kony.push.

Phone: The APIs in this chapter provide you the ability to access the default applications of the underlying platform on the mobile device and perform operations. The namespace for Phone

API is kony.phone.

OS: This chapter comprises all the APIs with the namespace kony.os.

Application: During the lifecycle of an application, the mobile device usually triggers several events. The APIs in this chapter allow you to listen to these events and override them with

2. Overview

Kony Studio API Developer's Guide

Version 3.1

application specific functionality. The chapter comprises all the APIs with the namespace kony.application.

Streaming : Streaming is a feature that is capable of listening to a continuous data stream and use the data. The data is available on Streaming Servers. The common use of streaming is to utilize the multimedia from an external source (like audio or video) in your application. Streaming data uses different protocols to fetch the data. The chapter comprises all the APIs with the namespace kony.stream.

Cryptography: Cryptography is the process of securing the information. It can be defined as the conversion of data into scrambled text (concealing its readability and meaning) and deciphering it using a key. This data can be sent across safely over public and private networks. The chapter comprises all the APIs with the namespace kony.crypto.

Network: The Network APIs enable you to invoke service calls or cancel network calls. The chapter comprises all the APIs with the namespace kony.net.

Data Access: The Data Access APIs comprise the WebSQL APIs and the Local Storage APIs and you can store and manipulate data on the device or database. The chapter comprises all the APIs with the namespace kony.db and kony.store.

Accelerometer: The Accelerometer APIs allow you to capture the device motion acceleration in

X, Y, Z directions and also provide out of the box mechanisms to register for shake gestures event. The chapter comprises of all the APIs with the name kony.accelerometer.

Hybrid: Kony Platform provides complete flexibility to choose different packaging and deployment modes according to the needs of the application. This chapter comprises all the

APIs with the namespace kony.hybrid.

Live Tiles: Live Tiles enable you to represent an application as a tile on the Start Screen of your device. You can launch the application using a Live Tile. This chapter comprises of all the APIs that enable you to add Live tiles. The namespace of all the APIs in this chapter is kony.application.

Maps :The kony.map namespace provides constants and functions that are used in conjunction with the Map widget.

2. Overview

Kony Studio API Developer's Guide

Version 3.1

Authentication :The kony.localAuthentication namespace contains functions that enable your apps to do Touch ID biometric fingerprint identification.

Animation :The kony.ui namespace includes functions that help your app to add animations to the rows of SegmentUI widgets.

Mobile First APIs : Kony provides Mobile First APIs that allows you to use native APIs of iOS and Android platforms in Kony Visualizer. The native APIs are provided as JavaScript APIs.

2.1 Platform Availability

The following table provides all the platforms that are supported:

MOBILE

— iPhone

— Android

— BlackBerry l

BlackBerry 10 Z10 l

BlackBerry 10 Q10 l

BlackBerry 10 A10 l

BlackBerry JDE 7.0:

Touch

✔

Native

✔

HTML5

SPA

✔

Web

Server Side Mobile

Web

✔

Hybrid

✔

2. Overview

Kony Studio API Developer's Guide

Version 3.1

BlackBerry JDE 7.0:

Bold l

BlackBerry JDE 7.0:

Touch only l

BlackBerry JDE 7.0:

Curve l

BlackBerry JDE 7.0:

Storm l

BlackBerry JDE 6.0:

Torch l

BlackBerry JDE 5.0:

Storm l

BlackBerry JDE 5.0:

Bold l

BlackBerry JDE 5.0:

Pearl 3G l

BlackBerry JDE 5.0:

8800

— Windows Phone 8

— Windows Phone 7.5

— Non Touch Devices

✔

Native

HTML5

SPA

✔

Web

Server Side Mobile

Web

Hybrid

2. Overview

Kony Studio API Developer's Guide

Version 3.1

Windows Phone 7.5

BlackBerry 6.0 & other

— Other Advanced Devices

— Basic Devices with JS

(BJS)

— Basic Devices

TABLET

— iPad

— Android Tab

— Windows 10 l x86 l x64 l

ARM

— Windows 8 l x86 l x64

✔

Native

✔

HTML5

SPA

✔

Web

Server Side Mobile

Web

Hybrid

✔

2. Overview l

ARM

DESKTOP

— Desktop Web

— Windows 7 / Kiosk l x86 l x64

Kony Studio API Developer's Guide

Version 3.1

✔

Native

HTML5

SPA

✔

Web

Server Side Mobile

Web

Hybrid

Kony Studio API Developer's Guide

Version 3.1

2.2 Accelerometer APIs

The Accelerometer APIs allow you to capture the device motion acceleration in X, Y, Z directions and also provide out of the box mechanisms to register for shake gestures event.

The following diagram shows the standard co-ordinate system that is used in indicating the X, Y, Z values:

The following table describes the co-ordinate system to be used for the accelerometer APIs:

Axis

Description

Float value indicating the magnitude of acceleration/ force along the X-Axis

Value positive negative

Direction

Towards the right when the device is facing you

Towards the left when the device is facing you

Kony Studio API Developer's Guide

Version 3.1

Float value indicating the magnitude of acceleration/force along the Y-Axis

Float value indicating the magnitude of acceleration/force along the Z-Axis positive Towards the top of the top of the device

Towards the bottom of the device negative positive negative

The axis coming out from the device screen (towards you) when the device is facing you

The axis coming out from the device back (away from you) when the device is facing you

Important: X, Y, Z are measured in terms of G, where G denotes the standard gravitational force.

G = 9.80665 m/s

(meters per seconds square). For example, if x=1, its actual value is 1G, i.e.,

9.80665 m/s

When a device is laying still with its back on a horizontal surface, each acceleration event has approximately the following values: l

X = 0 l

Y = 0 l

Z = -1

X, Y, Z can also have negative values based on the direction in which the device is positioned.

Note: The accelerometer APIs are applicable only when

os.platform

().hasaccelerometer

returns true.

This chapter explains the following APIs: l

kony.accelerometer.retrieveCurrentAcceleration

kony.accelerometer.startMonitoringAcceleration

Kony Studio API Developer's Guide

Version 3.1

kony.accelerometer.stopMonitoringAcceleration

kony.accelerometer.registerAccelerationEvents

kony.accelerometer.unregisterAccelerationEvents

You can view a video on using Accelerometer API at: http://docs.kony.com/video_ tutorials/default.htm#Accelerometer.htm%3FTocPath%3D_____5 .

2.3 Alert API

Applications use the Alert API to provide feedback to users. The Alert API contains the following function.

l kony.ui.Alert

2.4 App Group API

Apps on an iOS device can share common data through the use of an app group. The Kony MADP

API SDK provides you with the functions and objects that you need to create and manage app groups.

Each app group is associated with a data container that is located in persistent storage outside of the application sandbox of any app on the iOS device. Every app should have the right permissions and provisioning profiles that will enable them to access the app group. Each app group is specified by a unique identifier.

To provide app group functionality, the following functions in the kony.ds namespace (the

Data Store

API

) now take an optional parameter called storeContext.

l read l save l delete

The storeContext parameter is a dictionary that holds the following keys.

Kony Studio API Developer's Guide

Version 3.1

Key storeAsUserPreference konyAppGroupID

Type

Boolean string

Description

Contains true to access the data in an app group.

Otherwise, set to false.

Holds a unique identifier that specifies the app group to be accessed.

To retrieve the root directory path for the app group, your app can call

kony.io.FileSystem.getAppGroupDirectoryPath

Kony Studio API Developer's Guide

Version 3.1

2.5 Application APIs

During the lifecycle of an application, the mobile device usually triggers several events. The APIs in this chapter allow you to listen to these events and override them with application specific functionality.

It is recommend that you register for application events during the application load event of the project or masterdataload event of the startup form. This chapter consists of the APIs with the namespace kony.application.

kony.application.registerForIdleTimeout

kony.application.unregisterForIdleTimeout

kony.application.invalidateSession

kony.application.getPreviousSessionParams

kony.application.setApplicationCallbacks

kony.application.setApplicationInitializationEvents

kony.application.setApplicationMode

kony.application.getApplicationMode

kony.application.getCurrentForm

kony.application.getPreviousForm

kony.application.exit

kony.application.openURL

kony.application.openMediaURL

kony.application.setApplicationBehaviors

kony.application.showLoadingScreen

Kony Studio API Developer's Guide

Version 3.1

kony.application.dismissLoadingScreen

kony.application.setZoomedOutView

kony.application.disableZoomedOutView

kony.application.zoomIn

kony.application.setApplicationLayout

kony.application.setDefaultTextboxPadding

kony.application.setCheckBoxSelectionImageAlignment

kony.application.setRespectImageSizeForImageWidgetAlignment

kony.application.registerOnKeyPress

kony.application.beginBackgroundTask

kony.application.endBackgroundTask

kony.application.getApplicationState

Kony Studio API Developer's Guide

Version 3.1

2.6 Application Settings API

This feature allows the developer to enable application level settings so that the end users of an application can modify configurations and change the application behavior. This property is currently only applicable on iPhone platform. For more information on Application settings refer Kony Visualizer

User's Guide.

For instance developers can choose to set the following for an application: l define views for widgets.

l to configure the themes.

Using the application setting APIs, you can read and write the values the end user has set for an application.

Kony Studio API Developer's Guide

Version 3.1

2.7 Background Jobs

Background Jobs feature in Kony Platform includes

Background Fetch

and

Background Transfers .

2.7.1 Background Fetch

You can allow the application to fetch data from a network on regular basis while it is in a background state, with the background fetch capability in iOS 7 and later. This data can be utilized to keep the content of the application up-to-date and present it to the user when the user launches or re-opens the application. Also, the capability to support long running HTTP/HTTPS tasks like downloading large files if the application is in background state is supported.

In iOS version 7 and above, an app that retrieves content regularly from a network can ask the system for background execution time to check for new content.

An application developer who wishes to perform a background fetch can enable this feature in

Kony Visualizer IDE and register for the feature using

kony.backgroundjob.registerBackgroundFetch

. This API can be used to register predefined fetch job that can handle tasks like file download, upload, or a custom task.

kony.net.HttpRequest

API supports background transfers. Tasks like upload or download from the network (HTTP/HTTPS) that are active even when the app is in background or suspended state is available in iOS.

2.7.2 Background Transfers

The purpose of the background transfer service is to allow long running network downloads or uploads to take place even when the associated application is placed in the background. Background transfers are supported in HTTP and HTTPS protocols.

Following are the features in Background Transfer: l

Uploads and downloads are managed by iOS l

Unlike background fetch, background transfers have unlimited time.

Kony Studio API Developer's Guide

Version 3.1

It can be put in the queue anytime (foreground and background).

App is woken up to handle authentication challenges, errors if any, or completion of the job.

Background transfer tasks can be paused and resumed.

Only HTTP and HTTPS protocols are supported.

2.7.3 Background Fetch Workflow iOS 7 and later contains the

Background Fetch

API which allows an app to get updated content when the app is in background. iOS schedules the background fetch events based on the app usage so that the content is always up-to-date when user opens the application. iOS provides 30 seconds time frame for the app to wake up, fetch new data, update its interface, and go back to sleep.

If the Background Fetch feature is enabled in an app, the system wakes the app in the background from time to time and lets it go online to fetch new data with a goal to refresh its content. In this way the app is always up-to-date and users do not have to wait any more when they launch it.

The system determines how frequent the application can perform a background fetch and depends on the following factors: l

If network connectivity is available at that particular time.

Is the device awake.

Data and time the application has taken in its previous attempt to perform a background fetch.

The iOS system gives power to an application to schedule Background Fetch. Background Fetch can also be used to perform tasks internally in the app. Only synchronous tasks must be performed in background fetch, other than long running Background Transfers that are asynchronous. After the task is done

setBackgroundFetchCompletionStatus

must be called, passing a result that indicates whether content is available.

Invoking

setBackgroundFetchCompletionStatus

tells the system that it can move the app back to the suspended state and evaluate its power usage.

Kony Studio API Developer's Guide

Version 3.1

Apps that download small amounts of content quickly and accurately reflect when they had content to download are more likely to receive execution time in the future than apps that take longer to download their content.

It is advisable to use Background Transfers supported by

kony.net.HttpRequest

in fetch task to optimally utilize the execution time provided in the Fetch task.

2.7.4 Background Fetch and Background Transfers APIs

Background Fetch APIs

Following are the APIs for Background Jobs:

kony.backgroundjob.registerBackgroundFetch

kony.backgroundjob.setBackgroundFetchCompletionStatu

kony.backgroundjob.setBackgroundFetchInterval

Background Transfer

APIs

Following are the

Background Transfer APIs :

2.7.5 Supported Versions and Platforms

The Background Job feature: l

Available in Kony iOS platform versions above 5.6.2.

Supports iOS7 and the platforms above.

Supported only in JavaScript.

Kony Studio API Developer's Guide

Version 3.1

2.7.6 kony.backgroundjob.registerBackgroundFetch

registerBackgroundFetch can be used to register a background fetch job. A JavaScript function that can be invoked whenever the system schedules the fetch task. The app is woken up after the specified amount of fetchInterval.

Note: At the end of the background fetch job, you must invoke the

kony.backgroundjob.setBackgroundFetchCompletionStatus

passing a result that indicates whether content is available or not.

2.7.6.1 Signature

JavaScript: kony.backgroundjob.registerBackgroundFetch ( backgroundCallBack , fetchInterval )

2.7.6.2 Input Parameters backgroundCallBack [Function] - Mandatory

This callback is to be executed when the system invokes the app for a fetch job when the app is in background.

fetchInterval [Number] / [Constant] - Optional

Indicates the minimum time interval in seconds which must elapse before system can invoke the app for next fetch job .This is an optional parameter and value that is specified is only indicative and might not have any real effects on the scheduling frequency, as system decides the actual interval.

Possible values are:

1. constants.BACKGROUND_TASK_FETCH_INTERVAL_MINIMUM

* This is the default value. System decides the fetch interval depending on the usage prediction for the app.

2. constants.BACKGROUND_TASK_FETCH_INTERVAL_NEVER

Kony Studio API Developer's Guide

Version 3.1

Disable background task. Set the time interval to constants.BACKGROUND_TASK_

FETCH_INTERVAL_NEVER so that the job is no longer scheduled for running.

3. Time in seconds. (Negative values are not accepted).

2.7.6.3 Return Values

<N.A> or “NONE".

2.7.6.4 Exceptions and Error Handling

1. If no arguments or less number of arguments than the mandatory number of arguments are provided, it raises an exception and throws a “KonyError” JS Object with the following attributes: errorCode: 4001.

message: "registerBackgroundFetch: MissingMandatoryParameters."

2. If arguments type does not match the allowed type, it raises an exception and throws a

KonyError JavaScript Object with the following attributes: errorCode: 4002.

message: "registerBackgroundFetch: InvalidParameters."

2.7.6.5 Platform Availability

Available in iOS Platform.

2.7.6.6 JavaScript Example function backgroundFetchCallBack() {

//fetch handler invoked whenever the system invokes the App for a fetch job

Kony Studio API Developer's Guide

Version 3.1

// do something here

// in the end of the handler setBackgroundFetchCompletionStatus() need

// to be called mandatorily other wise system might termitane the app.

// task completion status.

//1. constants.BACKGROUND_TASK_STATUS_NEW_DATA

//2. constants.BACKGROUND_TASK_STATUS_FAILED

//3. constants.BACKGROUND_TASK_STATUS_NO_NEW_DATA

var completionStatus = constants.BACKGROUND_TASK_STATUS_NEW_DATA; kony.backgroundjob.setBackgroundFetchCompletionStatus

(completionStatus);

};

//Fetch interval

//1. constants.BACKGROUND_TASK_FETCH_INTERVAL_MINIMUM

//2. constants.BACKGROUND_TASK_FETCH_INTERVAL_NEVER

//3. Time in seconds. (Negative values are not accepted).

var fetchInterval = constants.BACKGROUND_TASK_FETCH_INTERVAL_

MINIMUM;

//register background fetch job kony.backgroundjob.registerBackgroundFetch

(backgroundFecthCallBack, fetchInterval);

Kony Studio API Developer's Guide

Version 3.1

2.7.7 kony.backgroundjob.setBackgroundFetchCompletionStatus

One must call this method in the end of

backgroundCallBack

passing a result that indicates whether content was available or not. This method intimates the system of the completion status of the background fetch job that has been scheduled.

Executing this call tells the system that it can move the app back to the suspended state and evaluate its power usage. Apps that download small amounts of content quickly and accurately display when they have content to download are more likely to receive execution time in the future than apps that take longer to download their content

Failure to call this method results in undefined behavior and could cause the app to be terminated by the system. If an error arises during invoking this API, default value:

constants.BACKGROUND_

TASK_STATUS_FAILED

will be set.

2.7.7.1 Signature

JavaScript: kony.backgroundjob.setBackgroundFetchCompletionStatus(

completionStatus

)

2.7.7.2 Input Parameters completionStatus [constant] - Mandatory

This is a mandatory parameter. Possible values are as follows

1. constants.BACKGROUND_TASK_STATUS_NEW_DATA

This tells the system that the fetch was successful and internally, the system then updates the apps UI (if the fetch resulted in UI change) in the background. This new UI is presented to the user once the app is brought to fore ground. The snapshot of the new UI is also presented when the user tries to switch apps using the App switcher.

2. constants.BACKGROUND_TASK_STATUS_FAILED

This tells the system that the fetch was unsuccessful. UI is not updated and the task will be run later based on the available system resources.

Kony Studio API Developer's Guide

Version 3.1

3. constants.BACKGROUND_TASK_STATUS_NO_NEW_DATA

This intimates the system the fetch did not result in any new data, UI is not updated and the job is run after any point later in time but not before fetchInterval.

2.7.7.3 Return Values

<N.A> or “NONE".

2.7.7.4 Exceptions

message: "setBackgroundFetchCompletionStatus:

MissingMandatoryParameters."

2. If arguments type does not match the allowed type, it raises an exception and throws a

“KonyError” JS Object with the following attributes: errorCode: 4002.

message: "setBackgroundFetchCompletionStatus:

InvalidParameters."

3. If an error arises during invoking of this API, default value: constants.BACKGROUND_TASK_

STATUS_FAILED will be set.

2.7.7.5 Platform Availability

Available in iOS Platform.

Kony Studio API Developer's Guide

Version 3.1

2.7.7.6 JavaScript Example function backgroundFecthCallBack() {

//fetch handler invoked whenever the system invokes the App for a fetch job

// do something here

// in the end of the handler setBackgroundFetchCompletionStatus() need

// to be called mandatorily other wise system might termitane the app.

// task completion status.

//1. constants.BACKGROUND_TASK_STATUS_NEW_DATA

//2. constants.BACKGROUND_TASK_STATUS_FAILED

//3. constants.BACKGROUND_TASK_STATUS_NO_NEW_DATA

var completionStatus = constants.BACKGROUND_TASK_STATUS_NEW_DATA; kony.backgroundjob.setBackgroundFetchCompletionStatus

(completionStatus);

};

//Fetch interval

//1. constants.BACKGROUND_TASK_FETCH_INTERVAL_MINIMUM

//2. constants.BACKGROUND_TASK_FETCH_INTERVAL_NEVER

//3. Time in seconds. (Negative values are not accepted).

var fetchInterval = constants.BACKGROUND_TASK_FETCH_INTERVAL_

Kony Studio API Developer's Guide

Version 3.1

MINIMUM;

//register background fetch job kony.backgroundjob.registerBackgroundFetch

(backgroundFecthCallBack, fetchInterval);

2.7.8 kony.backgroundjob.setBackgroundFetchInterval

This method sets the fetch interval for the background fetch job scheduled.

2.7.8.1 Signature

JavaScript: kony.backgroundjob.setBackgroundFetchInterval(

fetchInterval

)

2.7.8.2 Input Parameters fetchInterval [Number]/[Constant] - Mandatory

Indicative minimum time interval in seconds that should elapse before system can invoke the app for next fetch job. This is only indicative and may not have any real effects on the scheduling frequency, as system decides the actual interval.

Possible values are:

1. constants.BACKGROUND_TASK_FETCH_INTERVAL_MINIMUM

This is the default value. System decides the fetch interval depending on the usage prediction for the app.

2. constants.BACKGROUND_TASK_FETCH_INTERVAL_NEVER

Disable background task. Set the time interval to constants.BACKGROUND_TASK_FETCH_

INTERVAL_NEVER so that the job is no longer scheduled for running.

3. Time in seconds. (Negative values are not accepted).

Kony Studio API Developer's Guide

Version 3.1

2.7.8.3 Return Values

<N.A> or “NONE".

2.7.8.4 Exceptions

message: "setBackgroundFetchInterval:

MissingMandatoryParameters."

2. If arguments type does not match the allowed type, it raises an exception and throws a

“KonyError” JS Object with the following attributes: errorCode: 4002.

message: "setBackgroundFetchInterval: InvalidParameters."

2.7.8.5 Platform Availability

Available in iOS Platform.

2.7.8.6 JavaScript Example

//Fetch interval

//1. constants.BACKGROUND_TASK_FETCH_INTERVAL_MINIMUM

//2. constants.BACKGROUND_TASK_FETCH_INTERVAL_NEVER

//3. Time in seconds. (Negative values are not accepted).

var fetchInterval = constants.BACKGROUND_TASK_FETCH_INTERVAL_

Kony Studio API Developer's Guide

Version 3.1

MINIMUM; kony.backgroundjob.setBackgroundFetchInterval(fetchInterval);

Kony Studio API Developer's Guide

Version 3.1

2.7.9 Long Running Network Tasks

kony.net.HttpRequest

now supports long running network tasks which run to completion even when the app is pushed to Background or Suspended state, these are also known as background transfers and are available from iOS7.

Background transfers can be scheduled while the app is in foreground or while the app is in background (with the help of background fetch jobs in background state).

Background transfers can be enabled by setting the property ‘backgroundTransfer’ to ‘true’ on the

HTTP request object returned by kony.net.HttpRequest.

‘‘<HttpRequestObject>.backgroundTransfer’ has to be set to ‘true’ before open() API is invoked on the

HTTP request after its creation.

It is always advisable to set “<HttpRequestObject>.backgroundTransfer” to ‘true’ immediately after creation of HttpRequest object.

2.7.9.1 Signature var httpclient = new kony.net.HttpRequest(); httpclient.backgroundTransfer = true;

2.7.9.2 Input Parameters

Http request object returned by kony.net.HttpRequest supports additional property

‘backgroundTransfer’ to enable running network tasks to run even when the App is in background state.

backgroundTransfer : <Read/Write property>

Lets the HTTP request to know that Background transfers need to be supported.

Possible values: true / false

Default value: false

Kony Studio API Developer's Guide

Version 3.1

2.7.9.3 Platform Availability

Available in iOS Platform.

2.7.9.4 JavaScript Example var logPrefix = "bg_transfer_test_case_1 :- "; send_request(); function send_request() { var request = new kony.net.HttpRequest(); request.onReadyStateChange = callbackHandler;

//BGtransfer request.backgroundTransfer = true;

//session var req_session = request.getSession(); kony.print(logPrefix + " request.getSession() : " + req_ session);

//url var url =

"https://developer.apple.com/library/ios/documentation/iphone/concep tual/iphoneosprogrammingguide/iphoneappprogrammingguide.pdf"; kony.print(logPrefix + "URL : " + url); request.open(constants.HTTP_METHOD_GET, url); request.send();

}; function callbackHandler(request) { kony.print(logPrefix + " :

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

++++++++++++++++++++++++");

Kony Studio API Developer's Guide

Version 3.1

kony.print(logPrefix + " : Scope :- request.status : " + request.status); kony.print(logPrefix + " : Scope :- request.statusText : " + request.statusText); kony.print(logPrefix + " : Scope :- request.responseType : "

+ request.responseType); kony.print(logPrefix + " : Scope :- request.response : " + request.response); kony.print(logPrefix + " : Scope :request.getAllResponseHeaders() : "); kony.print(request.getAllResponseHeaders()); kony.print(logPrefix + " :

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

++++++++++++++++++++++++");

};

2.7.10 suspend

Temporarily suspends a background transfer task, while suspended, it produces no network traffic and is not subject to timeouts.

A suspended background transfer task if resumable can be resumed using resume() API. If the task cannot be resumed the transfer task will start afresh.

This API is applicable only if

<HttpRequestObject>.backgroundTransfer = true

for a HTTPrequest.

2.7.10.1 Signature

<<HttpRequestObject>>.suspend

2.7.10.2 Input Parameters

None

Kony Studio API Developer's Guide

Version 3.1

2.7.10.3 Return Values

None

2.7.10.4 Platform Availability

Available in iOS Platform.

2.7.10.5 JavaScript Example var request = new kony.net.HttpRequest();

//BGtransfer request.backgroundTransfer = true;

//url var url =

//suspend task request.suspend();

2.7.11 resume l

A resumable suspended task can be resumed using this API. If the task cannot be resumed the transfer task will start afresh.

This API is applicable only if

<HttpRequestObject>.backgroundTransfer = true

for a HTTPrequest.

Kony Studio API Developer's Guide

Version 3.1

2.7.11.1 Signature

<<HttpRequestObject>>.resume()

2.7.11.2 Input Parameters

None

2.7.11.3 Return Values

None

2.7.11.4 Platform Availability

Available in iOS Platform.

2.7.11.5 JavaScript Example var request = new kony.net.HttpRequest();

//BGtransfer request.backgroundTransfer = true;

//url var url =

//suspend task request.suspend();

Kony Studio API Developer's Guide

Version 3.1

//resume task request.resume();

2.7.12 getTaskState l

Returns the current state of the transfer task: active, suspended, in the process of being canceled, or completed l

This API is applicable only if

<HttpRequestObject>.backgroundTransfer = true

for a HTTPrequest.

2.7.12.1 Signature var taskState = <<HttpRequestObject>>. getTaskState()

2.7.12.2 Input Parameters

None

2.7.12.3 Return Values taskState: <constant> l constants.SESSION_TASK_STATE_RUNNING

l constants.SESSION_TASK_STATE_SUSPENDED

l constants.SESSION_TASK_STATE_CANCELING

l constants.SESSION_TASK_STATE_COMPLETED

2.7.12.4 Platform Availability

Available in iOS Platform.

Kony Studio API Developer's Guide

Version 3.1

2.7.12.5 JavaScript Example var request = new kony.net.HttpRequest();

//BGtransfer request.backgroundTransfer = true;

//url var url =

//getTaskStat() var tastState = request_object.getTaskState(); if (tastState == constants.SESSION_TASK_STATE_RUNNING) { kony.print("tastState == constants.SESSION_TASK_

STATE_RUNNING");

} else if (tastState == constants.SESSION_TASK_STATE_

SUSPENDED) { kony.print("tastState == constants.SESSION_TASK_

STATE_SUSPENDED");

CANCELING) {

} else if (tastState == constants.SESSION_TASK_STATE_

kony.print("tastState == constants.SESSION_TASK_

STATE_CANCELING");

COMPLETED) {

} else if (tastState == constants.SESSION_TASK_STATE_

kony.print("tastState == constants.SESSION_TASK_

STATE_COMPLETED");

}

Kony Studio API Developer's Guide

Version 3.1

Kony Studio API Developer's Guide

Version 3.1

2.7.13 Session Configuration API

2.7.13.1 getSession l

By default, if a new background transfer task is created using

kony.net.HttpRequest

[‘<HttpRequestObject>.backgroundTransfer = true’] a new session is created and this new task is associated with it.

<HttpRequestObject> now exposes a new method ‘getSession()’ using which the Session identifier associated with the HttpRequest can be obtained.

Multiple background tasks can be associated with the same Session by passing the Session identifier returned by

<HttpRequestObject>.getSession()

to any new

‘kony.net.HttpRequest’ created there after.

l getSession() API is applicable only if

<HttpRequestObject>.backgroundTransfer = true

for a HTTPrequest.

When ever a new

kony.net.HttpRequest

is created by passing a session identifier then by default backgroundTransfer property will be enabled

[‘<HttpRequestObject>.backgroundTransfer = true’].

Note: A session object life is dependent on the life of any of the request objects or request object it is associated with. Which means to be certain that a session is alive, any of the request objects or request object with which it is associated should be alive.

Signature var session_identifier = <<HttpRequestObject>>.getSession()

//To associate new HTTP Requests created with the same session

<New HttpRequestObject2> = new kony.net.HttpRequest(<session_identifier >);

Input Parameters

None

Kony Studio API Developer's Guide

Version 3.1

Return Values

Session identifier for the Session associated with the HttpRequest instance.

JavaScript Example var request = new kony.net.HttpRequest();

//BGtransfer request.backgroundTransfer = true;

//url var url =

//request session identifier var request_session = request.getSession();

//To associate new HTTP Requests created with the same session

//request 2 var request_2 = new kony.net.HttpRequest(request_session);

//request 3 var request_3 = new kony.net.HttpRequest(request_session);

Kony Studio API Developer's Guide

Version 3.1

2.8 Badge APIs

Badge is a small icon which displays some indicative information to the users. Badge can be used for an application, a specific widget, app menu, or an app menu icon.

The badge looks like the image below:

A badge can be used in the following scenarios to : l display a message on a specific widget l emphasize the price l advertise a promotion l indicate the number of unread messages or notifications.

Note:

Badge APIs are applicable only on iPhone and iPad.

This chapter explains the following APIs: l kony.application.setApplicationBadgeValue

kony.application.getApplicationBadgevalue

setBadge

getBadge

kony.application.setAppMenuBadgeValue

kony.application.getAppMenuBadgeValue

Kony Studio API Developer's Guide

Version 3.1

2.8.1 Badge Widget Methods

The following widget methods are related to and used with the kony.application functions in the Badge

API.

getBadge

This API enables you to read the badge value (if any) attached to the specified widget. If the specified widget does not have a badge attached to it, it returns an empty string.

Syntax

<<widgetreference>>.getBadge

uniqueIdentifier)

Parameters uniqueIdentifier

Unique identifier of a widget which is a handle to the widget.

Return Values

Returns a string containing the badge value applied to the specified widget. If the specified widget has no badge value attached to it, it returns an empty string.

Remarks

Important: When a badge is removed, the widgets are re-laid to accommodate the cleared badge values.

For iOS platform, this method is applicable on Box, Label, Button, Image, TextBox, and TextArea widgets only.

For Android platform, this method is applicable on Button and Image widgets only.

Platform Availability

Available only on iPhone, iPad, and Android.

Kony Studio API Developer's Guide

Version 3.1

Example function getBadge()

{

//To get a badge value on a hbox with ID hbx1 placed on a form frm1, use the following snippet: var badgeVal =frm1.hbx1.getBadge(); alert("badge value is::"+badgeVal);

} setBadge

This API enables you to set the badge value to the given widget at the top-right corner of the widget. If you pass an empty string as a parameter, the badge applied to the widget is cleared..

Signature

<<widgetreference>>.setBadge(

badgetext,

skin)

JavaScript Parameters badgeText

Specifies a string containing the Text value that appears within the badge. If the length of the badgeText is greater than 1 the badge is a rounded rectangle. For example, if you specify the text of the badge as 88, the number appears in a rounded rectangular badge. If the length of the badge text is 1, the badge is always a circle. The badge can occupy upto 70% of the width of the parent widget. For example, on a button with a width of 100 pixels, a badge with about 100 characters will occupy only 70 pixels of the button width. The badge text is truncated and shows about 30 characters followed by three dots.

skinl

Optional. Specifies a string that holds the background color for the badge. The default color is red.

Return Values

None.

Kony Studio API Developer's Guide

Version 3.1

Remarks

The badge appears with white font on a red background. The shape of the badge varies with its value: l

If the badge value is a single character (a character or a number), the badge shape is a circle.

If the badge value contains multiple characters, the badge shape is a rectangle with rounded corners and borders.

The badge can occupy a maximum of 70% width of the parent widget (widget on which badge is applied).

For example, on a button with a width of 100 pixels, a badge with about 100 characters will occupy only

70 pixels of the button width. The badge value is truncated and about 30 characters followed by three dots.

Important: When a badge is set, the widgets are re-laid to accommodate the badge values.

For iOS platform, this method is applicable on Box, Label, and Image widgets only.

For Android platform, this method is applicable on Button and Image widgets only.

Platform Availability

Available only on iPhone, iPad, and Android.

Example function setBadge()

{

//To set a badge value with skin "badgeSkin" on a hbox with ID hbx1 placed on a form frm1, use the following snippet: frm1.hbx1.setBadge("2","badgeSkin");

}

Kony Studio API Developer's Guide

Version 3.1

2.9 Beacon FFI APIs

Beacon FFI APIs help you work with iBeacons. iBeacons are devices that transmit signals using

Bluetooth low-energy wireless technology, and allow you to create and monitor beacons that advertise certain identifying information. Beacon Region is a region defined by a device’s proximity to Bluetooth

Beacons.

2.9.1 Prerequisites

To use Beacon FFI APIs, you need iOS 7 or later, Bluetooth turned on, and a compatible iOS device: l

Xcode 5.0 or later l iPhone 4s or later l iPad (3rd generation) or later l iPad mini or later l iPod touch (5th generation) or later

The following classes are available in Beacon FFI: l

com.kony.Beacon

com.kony.BeaconManager

com.kony.BeaconRegion

com.kony.PeripheralManager

2.9.2 How-to Sections

This overview provides the how-tos that demonstrate the use of the Beacon API in the following topics.

Kony Studio API Developer's Guide

Version 3.1

Determining the Availability of Region Monitoring

Monitoring Beacon Regions

Handling Boundary-Crossing Events

Determining the Proximity of a Beacon Using Ranging

Turning an iOS Device Into an iBeacon

2.9.3 Determining the Availability of Region Monitoring

Before monitoring a Beacon Region on a device, the developer should check for the availability of the region monitoring and the authorization status.To determine the availability, follow these steps:

1. Check the availability of the

Beacon Region

Monitoring.

The

isMonitoringAvailableForBeaconRegions

method helps determine whether a device supports Beacon Region Monitoring. If the method returns false, the application cannot use

Beacon Region Monitoring. If the method returns true, the developer must check the authorization status of the Beacon Region Monitoring.

if (beaconManager.isMonitoringAvailableForBeaconRegions()) { kony.print("Monitoring is available");

// Check for authorization status

}

2. Check the

Beacon Region

Monitoring Authorization Status.

The

authorizationStatus

method of

BeaconManager

determines whether the application is currently authorized to use iOS location services for monitoring the beacons. If the authorization status is

BeaconManagerAuthorizationStatusAuthorized

, the application will receive boundary-crossing notifications for any region it is monitoring. If the authorization status is any other value, the application does not receive those notifications.

Kony Studio API Developer's Guide

Version 3.1

If the application is not authorized to use Beacon Region Monitoring, it can still register Beacon

Regions for later use. If the user grants authorization to the application, monitoring for those regions will begin and will generate subsequent boundary-crossing notifications.

if (beaconManager.authorizationStatus() ==

"BeaconManagerAuthorizationStatusAuthorized") { kony.print("Authorized to use location services");

}

You can use

BeaconManager ’s

authorizationStatusChanged

callback to detect changes in authorization status to the application.

Refer to the Apple’s Location and Maps Programming Guide for more information.

2.9.4 Monitoring Beacon Regions

When a Beacon Region is monitored, respective callbacks are fired when the device crosses the boundary of the region. You can define a Beacon Region using the

BeaconRegion

class with proximityUUID, major, minor and identifier methods. The identifier is required and provides a way to refer to a particular beacon in your code. To register a Beacon Region for monitoring, call the

startMonitoringBeaconRegion

method of the

BeaconManager

object.

To monitoring Beacon Regions, follow these steps:

1. Create a

Beacon Region

object with beacon identifying information.

var aBeaconRegion = new com.kony.BeaconRegion(aProximityUUID, aMajor, aMinor, anIdentifier);

2. Create a Beacon Manager object with event callback functions.

Kony Studio API Developer's Guide

Version 3.1

function monitoringCallback(beaconRegion, state) {} function rangingCallback(beaconRegion, beacons) {} function errorCallback(beaconManagerError, errorName, errorDictionary, beaconRegion) {} var aBeaconManager = new com.kony.BeaconManager

(monitoringCallback, rangingCallback, errorCallback);

3. Start monitoring the beacon region by calling the

startMonitoringBeaconRegion

method of the

BeaconManager object.

aBeaconManager.startMonitoringBeaconRegion(aBeaconRegion);

2.9.5 Handling Boundary-Crossing Events

If the device enters or exits a Beacon Region, you will be notified through the

monitoringCallback

of BeaconManager object. A developer can postpone these notifications until the user turns on the device’s display by calling setNotifyEntryStateOnDisplay with true.

To handle boundary-crossing events, follow these steps:

1. Define a monitoring callback.

A monitoring callback should accept two arguments,

BeaconRegion

object and Device State, of the Beacon Region. The monitoring callback is called on detection of any boundary-crossing event.

function monitoringCallback(beaconRegion, beaconRegionState) {

...

}

Kony Studio API Developer's Guide

Version 3.1

2. Handle events.

If the device enters a Beacon Region,

beaconRegionState

will be

BeaconRegionStateInside

If the device exits a Beacon Region,

beaconRegionState

will be

BeaconRegionStateOutside

function monitoringCallback(beaconRegion, beaconRegionState) { if (beaconRegionState == "BeaconRegionStateInside") {

// Device is inside the beacon region -- start ranging beacons

}

2.9.6 Determining the Proximity of a Beacon Using Ranging

Beacon Region

can be ranged to determine the proximity of the beacon from the device using the

startRangingBeaconsRegion

method of the

BeaconManager

object.

You should call the

isRangingAvailableForBeaconRegions

method of the

BeaconManager

before attempting to range beacons.

Whenever the beacons come within range or go out of range, the

BeaconManager

object will notify you through rangingCallback with an array of

Beacon

objects. The beacon objects are detected in the order of closest to farthest. Use the

getProximity

property to determine relative distance of the beacon to the device. Determine the beacon identifying information using other properties of the beacon object.

To determine proximity, follow these steps:

Kony Studio API Developer's Guide

Version 3.1

1. Determining the availability of beacon ranging.

The

isRangingAvailableForBeaconRegions

method determines whether the current device supports beacon region ranging. If the method returns false, the application cannot use beacon region ranging.

2. Define ranging callback for notifications.

Ranging callback should accept two arguments, a

beaconRegion

and array beacons, which are in range.

function rangingCallback(beaconRegion, beacons) {

// Determine the proximity of beacons to the device.

}

3. Ranging beacons in a region.

To start ranging beacons in a beacon region, use

startRangingBeaconsInRegion

method to start ranging updates for beacons in that region.

var aBeaconRegion = new com.kony.BeaconRegion(aProximityUUID, aMajor, aMinor, anIdentifier); var aBeaconManager = new com.kony.BeaconManager

(monitoringCallback, rangingCallback, errorCallback); aBeaconManager.startRangingBeaconsInRegion(aBeaconRegion);

4. Determine proximity and other properties.

In the

rangingCallback

, the developer can determine the relative distance of the beacon from the device.

function rangingCallback(beaconRegion, beacons) { for (var beacon in beacons) {

Kony Studio API Developer's Guide

Version 3.1

if (beacon.getProximity() ==

"BeaconProximityImmediate") {

// Immediate

} else if (beacon.getProximity() ==

"BeaconProximityNear") {

// Near

} else { // beacon.getProximity() ==

"BeaconProximityFar"

// Far

}

2.9.7 Turning an iOS Device Into an iBeacon

Any iOS device that supports sharing data using Bluetooth low energy can be used as an iBeacon.

Because the application you write must run in the foreground, iBeacon support on iOS devices is intended for testing purposes and for applications that always run in the foreground, such as point-ofsale apps. For other types of iBeacon implementations, you need to acquire dedicated beacon hardware from third-party manufacturers.

To turn an iOS device into an iBeacon, follow these steps:

1. Create a

Beacon Region

object.

To use your iOS device as a beacon, you first generate a 128-bit UUID that will be your Beacon

Region’s proximity UUID. Open Terminal(in Mac OS) and type uuidgen on the command line.

You receive a unique 128-bit value in an ASCII string that is punctuated by hyphens, as in this example.

Kony Studio API Developer's Guide

Version 3.1

$ uuidgen

FBA1FFE5-7CD6-451B-8F1F-22B2AC70AA45

Next, create a Beacon Region with the UUID you generated for the beacon’s proximity UUID, defining the major and minor values as needed. Be sure to also use a unique string identifier for the new region. This code shows how to create a new Beacon Region using the example UUID above.

var proximityUUID = "FBA1FFE5-7CD6-451B-8F1F-22B2AC70AA45"; var major = 10; var minor = 12; var identifier = "KonyBeaconSample" var beaconRegion = new com.kony.BeaconRegion(proximityUUID, major, minor, identifier);

2. Advertise the beacon information using the

peripheral manager .

Now that you have created a Beacon Region, you need to advertise your beacon’s proximity

UUID (and any major or minor value you specified) using the com.kony.PeripheralManager

object.

var peripheralManager = new com.kony.PeripheralManager

(stateUpdatedCallback, advertisingStatusCallback); peripheralManager.startAdvertisingWithMeasuredPower

(beaconRegion, null);

Kony Studio API Developer's Guide

Version 3.1

2.9.8 Turning an iOS Device Into an iBeacon

Any iOS device that supports sharing data using Bluetooth low energy can be used as an iBeacon.

To turn an iOS device into an iBeacon, follow these steps:

1. Create a

Beacon Region

object.

To use your iOS device as a beacon, you first generate a 128-bit UUID that will be your Beacon

Region’s proximity UUID. Open Terminal(in Mac OS) and type uuidgen on the command line.

You receive a unique 128-bit value in an ASCII string that is punctuated by hyphens, as in this example.

$ uuidgen

FBA1FFE5-7CD6-451B-8F1F-22B2AC70AA45

Kony Studio API Developer's Guide

Version 3.1

2. Advertise the beacon information using the

peripheral manager .

Now that you have created a Beacon Region, you need to advertise your beacon’s proximity

UUID (and any major or minor value you specified) using the com.kony.PeripheralManager

object.

var peripheralManager = new com.kony.PeripheralManager

(stateUpdatedCallback, advertisingStatusCallback); peripheralManager.startAdvertisingWithMeasuredPower

(beaconRegion, null);

Kony Studio API Developer's Guide

Version 3.1

2.10 Bookmark and Refresh API

In Kony's current desktop architecture which is based on SPA, the URL of the page is never changed throughout the navigation of the application. This leads to a scenario where in if a user tries to bookmark a page, no matter where in the application the user is, the same URL is displayed. So subsequently when the user tries to open the bookmarked page, the desktop application has no way of knowing the actual bookmarked page and as a result, the user is invariably taken to the home page of the application.

An example of the URL in the desktop web application built on Kony would be: http://xyz.kony.com/kdw/#frm1

The same experience can be extended to other cases like refresh, sharing of a link etc. In all these scenarios, as there is no change in the URL, the user is by default taken to the home page of the application.

In the traditional desktop web application development, the developers create URLs with some context information so that when they are used, the URL carries necessary context and the application can change based on the context information and take the user to the appropriate page of the application instead of always redirecting them to the home page. Similar to this approach, Kony One

Platform provides the following set of APIs which enable the developer to add context to the URL so that when the end user bookmarks it or shares it, the URL carries necessary parameters so that the application is rendered accordingly.

Use Case Scenario

After signing into an application, if the user wants to stay in same page upon refresh, then the following code should be invoked in the App Service:

For example: function appServiceCallBack(params){

//alert(JSON.stringify(params)); if (params.launchparams['formID']) {

Kony Studio API Developer's Guide

Version 3.1

var formID = params.launchparams['formID']; return formID;

}

The Bookmark and Refresh API contains the following functions.

l addBMState l getBMState l removeBMState l resetBMState l setBMState

Kony Studio API Developer's Guide

Version 3.1

2.11 Camera API

When you capture an image using the Camera Widget, camera captures the rawbytes of the image.

This API allows you to delete rawbytes for the image. If you use this API, the captured image is deleted from the disk or in-memory.

The following APIs are explained in this chapter: l

kony.camera.releaseRawBytes

You can view a video on using the Camera API at: http://docs.kony.com/video_ tutorials/default.htm#Camera.htm%3FTocPath%3D_____6 .

Kony Studio API Developer's Guide

Version 3.1

2.12 Charm Setting APIs

The Charm settings on the Windows 8 platform contains settings that you can apply to the application.

The settings can be configured to control an application's access to system capabilities and some specific settings of the current application. To view the Charm settings pane, swipe from the right side of the screen from right to left. For more information about Charm settings, refer Charm Settings.

The Charm APi consists of the following functions.

l kony.application.createSettingsMenu

l kony.application.setCurrentSettingsMenu

l kony.application.getCurrentSettingsMenu

l kony.application.addSettingsMenuItemAt

l kony.application.removeSettingsMenuItemAt

Kony Studio API Developer's Guide

Version 3.1

Kony Studio API Developer's Guide

Version 3.1

2.13 Cryptography APIs

Cryptography is the process of securing the information. It can be defined as the conversion of data into scrambled text (concealing its readability and meaning) and deciphering it using a key. This data can be sent across safely over public and private networks.

When you have to transmit sensitive or critical information over the network (private or public), you need to encrypt the information to ensure information security. Decryption mechanism is used to convert the encrypted text into a readable format.

Note: Windows Phone 7 does not support TripleDES and RSA algorithms.

The following APIs are explained in this chapter: l kony.crypto.newKey

l kony.crypto.encrypt

l kony.crypto.decrypt

l kony.crypto.retrievePublicKey

l kony.crypto.createHash

l kony.crypto.saveKey

l kony.crypto.deleteKey

l kony.crypto.readKey

l kony.crypto.createPBKDF2Key

l kony.crypto.createHMacHash

You can view a video on using Cryptography API at: Video Tutorial .

Kony Studio API Developer's Guide

Version 3.1

2.13.1 Concepts

This section explains few concepts of Cryptography.

Encryption

Conversion of data into an encoded format using a key is known as encryption.

Decryption

Converting the encoded text into clear text using a key is known as decryption.

Note: Encryption and decryption are done using a cipher.

Cipher

Cipher is an object capable of carrying out encryption and decryption following a scheme

( algorithm).

Block Ciphers

A block cipher is a symmetric key cipher that operates on fixed-length groups of bits called blocks.

For example, a block cipher encryption algorithm takes a 128-bit block of plaintext as input, and produces an output of a corresponding 128-bit block of cipher text. The process of transformation is governed by a secret key. Decryption is a similar process - the decryption algorithm takes a 128bit block (in this example) of cipher text along with the secret key, and yields the original 128-bit block of plaintext.

Note: Kony Platform currently supports only Block Ciphers.

Stream Ciphers

A stream cipher, also called a stream algorithm, combines plaintext bits with a keystream. A keystream is a pseudorandom algorithm bit stream. Plaintext digits are encrypted one at a time.

Kony Studio API Developer's Guide

Version 3.1

Padding

Block cipher algorithms like DES mode require their input to be an exact multiple of the block size.

If the plaintext to be encrypted is not an exact multiple, you need to pad before encrypting by adding a padding string.

The following table describes the supported padding for different algorithms:

Algorithm

AES/TripleDES

RSA

Platform iPhone

Android/Android Tablet

BlackBerry

SPA iPhone

Android/Android Tablet

BlackBerry

Windows

Phone/Windows

8.1/Kiosk

Possible Padding pkcs7(default) none,pkcs1,pkcs5(default) none,pkcs5(default)

ISO10126, ISO97971, zeropaddding, nopadding, pkcs7 none,pkcs1(default) none,pkcs5,pkcs1(default) none,pkcs5,pkcs1(default) pkcs1

Mode

The modes specify how the data will be encrypted (cryptographically protected) and decrypted

(returned to original form). The modes included in this standard are: l

Electronic Codebook (ECB) mode l

Cipher Block Chaining (CBC) mode

Kony Studio API Developer's Guide

Version 3.1

Cipher Feedback (CFB) mode l

Output Feedback (OFB) mode l

ECB and CBC are valid modes for the Block ciphers

The following table describes the supported modes for different algorithms:

Algorithm

AES/TripleDES

RSA iPhone

Platform

Android

BlackBerry

SPA iPhone

Android/Android Tablet

BlackBerry

Possible Modes ecb,cbc(default) ecb,cbc(default) ecb,cbc(default) ecb, cfb, ofb, cbc, ctr ecb(default) ecb(default) ecb(default)

Initialization Vector

The initialization vector (IV) adds randomness to the cipher text. As a result, if the same message is encrypted twice with the same key, the resulting cipher texts will be different, as long as different initialization vectors are used.

The length (number of bytes) of Initialization Vector should be the same as the block size of the algorithm (AES and TripleDES). For AES the IV has to be 16 bytes (128 bits). For TripleDES the

IV has to be 8 bytes (64 bits).

Kony Studio API Developer's Guide

Version 3.1

RSA Algorithm

RSA is an algorithm for public-key cryptography. It is the first algorithm known for both signing and encryption. This algorithm involves a public key and a private key. The public key can be known to everyone and is used for encrypting messages. Messages encrypted with the public key can only be decrypted using the private key.

Note: SPA does not support the RSA algorithm.

2.13.2 Types of Cryptography

The following are the types of cryptography supported by Kony: l

Symmetric cryptography - cryptography that uses the same key for both encryption and decryption. Both encryption and decryption are done on the device.

Asymmetric cryptography - cryptography that uses a public key to encrypt data and a private key to decrypt data. The public key is available in a trusted certificate, whereas the private key is confidential and not shared. Encryption is done on the device and decryption on the server (that has access to the private key). As the private key is not exposed, we support only encryption using symmetric cryptography.

2.13.3 Supported Algorithms

Kony Studio API Developer's Guide

Version 3.1

The following table lists the supported algorithms:

Kony Studio API Developer's Guide

Version 3.1

Kony Studio API Developer's Guide

Version 3.1

Cryptography

Type

Algorithm

Symmetric l aes

- Advanced Encryption Standard l tripledes - Triple Data Encryption Standard.

This algorithm uses two keys for encryption and one key for decryption . The algorithm works as follows:

encryptedtext = E

(D

(E

(text to be encrypted)))

The text is encrypted with key1 , decrypted with key2 , and then again encrypted with key3 .

Decryption is the reverse:

decryptedtext = D

(E

(D

(text to be decrypted)))

tripledes applies the DES cipher algorithm three times to each data block.

The following are the three different combinations of using this algorithm: o

Option 1: K1, K2, and K3 are different (all three keys are independent) o

Option 2: K1 and K2 are different; K3=K1

(two keys are independent) o

Option 3: K1=K2=K3 (all three keys are identical)

Note: We recommend using Option 1 as it is more secured compared to the other two options.

Supported Key

Strengths (in bits) l

128, 192, and 256 for aes algorithm l

192 for tripledes algorithm

73 of 838

Kony Studio API Developer's Guide

Version 3.1

Cryptography

Type

Asymmetric

Algorithm l

RSA

Note:

We currently support ONLY encryption (not decryption) using the asymmetric cryptography.

Supported Key

Strengths (in bits)

1024 and above

2.14 Data Store API

Data Store Library

A data store is a storage area on the mobile device that is capable of holding persistent data. The data store is available on the mobile device at a location that is dependent on the underlying platform. The data store is not directly exposed to the users.

The underlying platform of the mobile device maintains the integrity of the persistent data stored in the following scenarios when: l the application accesses the data l the device reboots l the battery is changed l the application upgrades: o

Native Clients - data stored earlier is not deleted when an application upgrades. On some of the J2ME phones, the user is prompted with an option to delete the data during the application upgrade process. If the end user chooses the delete option then the data will be lost even on application upgrade.

Mobile Web when storage mode is cookie - the data is lost when you delete the cookies on the client browser.

Kony Studio API Developer's Guide

Version 3.1

Mobile Web when storage mode is cache - the data is lost every time you restart the application server.

Mobile Web when storage mode is session- the data is lost as soon as the server-side session is terminated/expired.

The actual storage used to store this data depends upon the underlying Operating System:

Operating

System iPhone

Android/Android

Tablet

Within a file in the application sandbox. The storage area is unique to the application.

BlackBerry

J2ME

Windows 6x

Windows

Phone

Symbian

Mobile Web

(mode set as cookie)

Storage Space

Within a file outside the application sandbox.

The storage area is shared by multiple applications.

RMS (Record Management Store)

Within a file

Within a file in the application sandbox. The storage area is unique to the application.

Browser Cookie

Yes

Accessible to other applications

Yes

Kony Studio API Developer's Guide

Version 3.1

Mobile Web

(mode set as cache)

Application Context No (but shared across all the users for the same application)

Mobile Web

(mode set as session)

HTTP Session No

The previous stored data is lost (permanently) in the following cases when : l the application is deleted from the device l the kony.ds.delete API is used to delete the data.

Kony provides APIs that allow the application to: l save data on the data store l read data from the data store l remove data from the data store.

The Data Store API contains the following functions.

kony.ds.read

kony.ds.remove

kony.ds.save

2.15 Functional Modules API

The Functional Modules API are used to load a functional module (that is defined using

functionalModule.xml

file) through synchronous and asynchronous operations on demand.

The Functional Modules API provides the following functions.

loadFunctionalModule

loadFunctionalModuleAsync

Kony Studio API Developer's Guide

Version 3.1

2.16 GeoLocation APIs

The GeoLocation APIs define a high-level interface to location information, such as latitude and longitude associated with the mobile device. The API uses the common sources of location information like Global Positioning System (GPS) to infer details like IP address, RFID, WiFi and

Bluetooth MAC addresses, and GSM/CDMA cell IDs. This API does not always return the device's actual location.

The API is designed to enable both one-shot position requests and repeated position updates, as well as the ability to explicitly query the cached positions. Location information is represented by latitude and longitude coordinates.

The GeoLocation APIs are modeled after W3C GeoLocation specification.

Important: If you are developing a BlackBerry 10 application, you must provide access permission in Kony Visualizer IDE. To provide permission, go to Preferences > Native > BlackBerry 10 and enable access_location_services.

The following are the Geolocation APIs: l kony.location.getCurrentPosition

l kony.location.watchPosition

l kony.location.clearWatch

You can view a video on using Geolocation API at: http://docs.kony.com/video_ tutorials/default.htm#GeoLocation.htm%3FTocPath%3D_____14 .

2.16.1 Deprecated APIs

This section lists all the deprecated APIs

Kony Studio API Developer's Guide

Version 3.1

2.16.1.1 phone.mylocation

This API is deprecated from Kony Visualizer 4.0 release onwards. As an alternate, to capture the location details use the

geolocation.getcurrentposition

API.

This API provides you with the ability to capture the current location of the user based on the Global

Positioning System (GPS) and Location Based Services (LBS) capabilities.

Use Case

You can use this API to: l pre-populate your current location details in applications like Flight Search or Hotel Search.

l identify outlets like Shopping Mall, Gas Station, ATM, and so on nearest to your current location.

Signature

JavaScript: phone.mylocation()

Input Parameters

This API does not require any input parameters.

Return Values

Reference [userdata]

Contains three keys: cellular ID longitude latitude

Status [Number]

Status can be one of the following:

Kony Studio API Developer's Guide

Version 3.1

0: Success in finding the location

-1: Unable to find the location

Error Codes

The following error codes are returned:

Error Code

101

Description

Network Related Error

102

103

104

105

Location API access is denied by user

Unknown location or Location not found

Unknown error

Location Services Disabled

Implementation Details

To fetch location details on Mobile Web, enable the

Requires GPS property of a project and set the

CaptureGPS property to true. For more information about capturing location details on Mobile Web, see the appendix

GPS Functionality in Kony Visualizer User Guide.

This API does not fetch data if it is used in the

appinit

event or on the first call of

form.preshow

API.

Rules and Restrictions l

On Mobile Web, this API is available on: o iPhone o

Android

Kony Studio API Developer's Guide

Version 3.1

BlackBerry Torch o other HTML5 browsers.

You cannot test this API from Windows Phone Mango emulator as with current release of

WP7.0

cellular ID cannot be retrieved.

2.16.1.2 Platform Availability

Available on all platforms except IE8 and prior to IE8 releases.

Available on all platforms except prior to IE8 releases.

Kony Studio API Developer's Guide

Version 3.1

2.17 Gesture API

A gesture is an action associated with movement of a mouse or a touch screen action. The developers determine how a gesture should be interpreted and the function that must be executed when a gesture is recognized.

Gestures are applicable only on mobile or tablet devices that have touch support.

Note: l

Currently, Kony Platform supports only Tap, Swipe, Longpress, Pan, Rotation, and Pinch gesture types. l

In tablet, longpress is only triggered when it is a touch event and not a mouse event.

The Gesture API functions are as follows: l

addGestureRecognizerForAllForms

removeGestureRecognizerForAllForms

In addition, the Kony Widgets support the following methods. They are documented in the Kony

Widget Programmer's Guide .

l addGestureRecognizer l removeGestureRecognizer

2.17.1 Important Considerations l

Single tap matches with the onClick functionality. If a box has an onClick event defined, both gesture event and onClick are triggered.

Number of taps is limited to one or two, only single tap or double tap are recognized.

Number of fingers is limited to one, only single finger is recognized.

Kony Studio API Developer's Guide

Version 3.1

Kony Studio API Developer's Guide

Version 3.1

2.18 Hybrid API

Mobile applications can be built and deployed using various techniques and approaches. One extreme is to use the native SDK to build Enterprise applications, while the other extreme is to use traditional web technologies to build mobile web applications. There is a category that falls in between these two extremes, which mixes the native and web technologies to create a mobile application.

Kony Platform provides complete flexibility to choose different packaging and deployment modes according to the needs of the application.

Hybrid

Hybrid application is partly a native application and partly a web-based application. In the native part of the application, some of the forms are rendered using

UIWebView and Browserfield, while other forms are rendered using Native SDK. The developer can pick and choose the forms that need to be native or web-based. The web-based forms can be either packaged statically along with the application or loaded from a URL dynamically.

Single Page Application (SPA)

Single Page Applications (SPA) are a type of web applications, in which all the HTML, CSS, and JavaScripts necessary for the application are retrieved with a single page load. The page does not automatically reload during user interaction with the application or control the transfer to another page. The application requires server interaction only for data retrieval.

Unlike a traditional mobile web application, the browser executes all the application logic on the client-side. The logic include validations, UI rules (hiding or showing fields), form transitions/navigations, and so on.

In an SPA app all the application screens are expressed as a JavaScript model/CSS (unlike

JavaScript, ASPX in typical mobile web application). This model is downloaded to the clientside with the first page download and resides on the client for the lifetime of the session.

For characteristics of each of these application types, see Kony Visualizer User Guide.

Kony Studio API Developer's Guide

Version 3.1

Kony Platform utilizes the Single Page Application (SPA) implementation for rendering the statically packaged forms in the wrapper and hybrid applications. In the Wrapper Mode, the application is an

SPA running inside a native shell provided by the native platforms. For the forms with dynamic nature, the traditional Mobile Web implementation is utilized.

The API contains the following functions.

executeFunctionInNativeContext

executeFunctionInSPAContext

executeFunctionInTCContext

Kony Studio API Developer's Guide

Version 3.1

2.19 Input and Output APIs

The section describes file system APIs. Kony Visualizer enables you to browse file system and select multiple files to upload on the server. This chapter explains the APIs available in the kony.io.FileSystem, kony.io.File, kony.io.FileList, and kony.types namespaces.

l kony.io.FileSystem

l kony.io.File

l kony.io.FileList

l kony.types

Kony Studio API Developer's Guide

Version 3.1

2.20 Internationalization APIs

The process of designing or developing an application in such a way that it supports various languages and regions is known as Internationalization. For an application to support Internationalization, you need not make any changes in the application code or logic.

Internationalization is abbreviated as i18n.

i18n support for an application has to be defined at the time of developing the application.

The APIs in this library perform various operations related to internationalization. The i18n APIs are as follow: l

kony.i18n.getCurrentLocale

kony.i18n.getSupportedLocales

kony.i18n.getCurrentDeviceLocale

kony.i18n.setResourceBundle

kony.i18n.updateResourceBundle

kony.i18n.isResourceBundlePresent

kony.i18n.getLocalizedString

kony.i18n.deleteResourceBundle

kony.i18n.setDefaultLocaleAsync

kony.i18n.setCurrentLocaleAsync

kony.i18n.isLocaleSupportedByDevice

2.20.1 Concepts

This section explains a few concepts about Internationalization:

Kony Studio API Developer's Guide

Version 3.1

2.20.1.1 Resource Bundle

Resource bundle is a properties file that contains all the i18n Keys along with their values. The resource bundle is locale specific, that is, you will have one resource bundle per locale. The resource bundle follows the naming convention of

<language_Country>.properties

. For example, l for English locale in United States, the resource bundle will be

en_US.properties.

l for French locale in Canada, the resource bundle will be

fr_CA.properties

The resource bundle has a list of key-value pairs that are used as internationalization keys within the application.

2.20.1.2 Implementation Details

The current practice to support i18n for applications is to place the text (i18n keys) in the resource bundles that are loaded into the application. Applications are built to access the resource bundles depending on the selected locale data. For an application to support multiple languages, you have to design the application to select the relevant resource bundle at runtime. The keys in the resource bundles are translated to the required languages at runtime.

An internationalized application has the following benefits: l

The same application can run on multiple locales.

Widget's text is not hard-coded in the application. Instead the localized keys are retrieved dynamically.

Support for new locales does not require recompilation.

Region-dependent data such as dates and currencies, appear in formats that conform to the end user's region and language.

2.20.2 Deprecated APIs

The following APIs have been deprecated from 5.0 onwards and are only supported for backward compatibility.

Kony Studio API Developer's Guide

Version 3.1

kony.i18n.setCurrentLocale

kony.i18n.setDefaultLocale

2.20.2.1 kony.i18n.setCurrentLocale

This API provides you the ability to set the specified locale as the current locale of the application. If the locale is not supported by the device, junk characters will be displayed on the screen for the locale specific string.

Signature

JavaScript:

kony.i18n.setCurrentLocale( locale

)

Input Parameters locale [String] - Mandatory

Specifies the locale that must be set as the current locale of the application

Return Values errorcode [Number]

A number that denotes the error.

0 - Locale is successfully applied l

100 - The supplied locale is not available in the device.

101 - The supplied locale is not available in application

Error Codes l

100 - if the locale is not supported by device l

101 - if the locale is supported by device but not by the application

Implementation Details

This section explains how this API is implemented. This API:

Kony Studio API Developer's Guide

Version 3.1

l sets the appropriate display language and region for displaying content and images in the application l sets the specified locale as the input locale (keyboard and calendar display) if the specified locale is available - on Android and BlackBerry l displays junk characters for the locale specific string if the specified locale is not supported by the device l does not re-initialize the widgets that have already loaded the i18n content. For example, assume that an application has 2 forms frmA and frmB.

o frmA is the startup form and loads the content using i18n.getlocalizedstring API. The current locale for the device is en_US and English text is populated on the form.

o onclick event of the button on this form invokes i18n.setcurrentlocale("fr_FR") o

Invoking this API at this stage will not cause the widgets to reload the data for frmA widgets from fr_FR resource bundle.

2.20.2.2 Platform Availability l

Android l

BlackBerry l

BlackBerry 10 l

Windows Phone/Windows Kiosk/Mango

2.20.2.3 kony.i18n.setDefaultLocale

Every application that has support for internationalization needs a locale to be set as a default locale.

This API allows you to set the specified locale as the default locale for the application. You can also set the default locale from the IDE. However, this API allows you to perform that task programmatically.

Signature

JavaScript: kony.i18n.setDefaultLocale(

locale

)

Kony Studio API Developer's Guide

Version 3.1

Input Parameters locale [String] - Mandatory

Specifies the locale that needs to be set as default locale for the application

Return Values

None.

Error Codes l

100 - if the locale is not supported by device l

101 - if the locale is supported by device but not by the application

Implementation Details

This API is invoked in the background when the code is generated for an application to set the default locale.

2.20.2.4 Platform Availability

Available on all platforms except J2ME.

2.21 kony.localAuthentication Namespace

The kony.localAuthentication Namespace enables authentication in iOS applications. The namespace provides APIs for various authentication modes. Currently, the kony.localAuthentication namespace supports the Touch ID mode for authenticating.

Touch ID is an authenticating mechanism introduced mainly for local authentication in iOS devices.

Touch ID is a biometric fingerprint reader that takes the place of the traditional Home button on iPhone

5 and later version devices. The Touch ID feature unlocks the device, authenticates various payments, and so on. Touch ID is stored securely in the secure layer of the iPhone and is not accessible outside.

The Touch ID feature is specific to the iOS platform and available from iOS 8 onward.

Kony Studio API Developer's Guide

Version 3.1

Note:

The applications using the kony.localAuthentication APIs must be in the foreground. If an application uses kony.localAuthentication APIs, the application handle errors and respond properly with UI to ensure an alternative method for logging into the application.

Following are the kony.localAuthentication APIs: l

kony.localAuthentication.authenticate

kony.localAuthentication.getStatusForAuthenticationMode

Kony Studio API Developer's Guide

Version 3.1

2.22 Language APIs

In JavaScript, exceptions that occur during runtime are usually handled using try/catch blocks.

Language APIs are implemented for exceptions that are not handled using try/catch blocks.

Following are the two Language APIs implemented to handle uncaught exceptions: l

kony.lang.setUncaughtExceptionHandler

kony.lang.getUncaughtExceptionHandler

Kony Studio API Developer's Guide

Version 3.1

2.23 Live Tiles API

Live Tiles enable you to represent an application as a tile on the Start Screen of your device. You can launch the application using a Live Tile. Secondary Live tiles are secondary tiles for the same application and can be used for deeplinking to forms. For more information on Live Tiles refer to http://msdn.microsoft.com/en-us/library/hh202948%28v=vs.92%29.aspx.

The APIs in this chapter provide you with the ability to set tiles for an application.

l kony.application.setAppTile

l kony.application.setSecondaryTile

l kony.application.removeSecondaryTile

Kony Studio API Developer's Guide

Version 3.1

2.24 Math APIs

The Math Library has APIs that you can use to perform mathematical operations.

The Math Library has the following APIs: l

2.25 Mobile First APIs

2.25.1 Introduction

In Kony Visualizer, Mobile First APIs help you use native APIs for iOS and Android platforms. The native APIs are provided as JavaScript APIs. To access these APIs, you need to follow certain guidelines in

iOS

and

Android

platforms. Mobile First APIs include: l

Kony Studio API Developer's Guide

Version 3.1

Near Field Communication (NFC)

Speech

2.25.2 Enabling Mobile First APIs in Kony Visualizer

To enable Mobile First APIs in Kony Visualizer for iOS platform, follow these steps:

1. From your Kony Visualizer, go to the Application Properties window.

2. Navigate to Native > iPhone/iPad tab, and select Enable MobileFirst APIs (HealthKit, Apple

Pay).

3. Click Finish.

To enable Mobile First APIs in Kony Visualizer for Android platform, follow these steps:

Kony Studio API Developer's Guide

Version 3.1

1. From your Kony Visualizer, go to Application Properties window.

2. Navigate to Native > Android tab, and select Enable MobileFirst APIs (NFC, JobScheduler,

Speech, Bluetooth).

3. Click Finish.

Kony Studio API Developer's Guide

Version 3.1

2.25.2.1 iOS Guidelines for Using Mobile First APIs in Kony Visualizer

To use Mobile First APIs in Kony Visualizer, follow these guidelines:

Category

Accessing classes

Description

To access a class, use the following API: objc.import

This API allows you to import any iOS native class into JavaScript. You must use the keyword "new" to instantiate (create an object) an instance of a JavaScript class. All the

APIs, methods, constants, and all members of the native class are directly accessible with the instantiated object.

Signature

JavaScript: objc.import (objectiveC_class_name)

Input Parameters objc.import (objectiveC_class_name) - Mandatory

Specifies the native class name including the package name that you want to use in

JavaScript.

Return Values

Returns a JavaScript object

Platform Availability

Available on iOS platform.

JavaScript Example

//Sample code var HKHealthStore = objc.import('HKHealthStore');

Kony Studio API Developer's Guide

Version 3.1

Category

Invoking static methods

Description

Static methods can be accessed as properties of the JavaScript object returned by the API objc.import

. For example, the static method isHealthDataAvailable of the class

HKHealthStore can be invoked using the following syntax:

Creating instances var HKHealthStore = objc.import('HKHealthStore'); kony.print(HKHealthStore.isHealthDataAvailable());

For the methods that take one or more arguments in JavaScript, refer to

Method name convention.

For the methods that are supported, refer to

Type support .

In Objective-C, instances of a class are created by using the alloc/init combination or convenience constructors. The alloc and convenience constructors are static methods that can be invoked as described in the

section. Invoking init method is described in the

section.

Instances created either way are JavaScript objects that wrap the underlying Objective-C objects.

Invoking instance methods var HKUnit = objc.import('HKUnit'); var unit = HKUnit.unitFromString('count');

Instance methods of an Objective-C object are available as properties of the JavaScript object that represents the Objective-C object. For example, the instance method reciprocalUnit of HKUnit can be invoked as: var HKUnit = objc.import('HKUnit'); var unit = HKUnit.unitFromString('count'); var runit = unit.reciprocalUnit();

Kony Studio API Developer's Guide

Version 3.1

Category

Accessing properties of

Objective-C objects

Description

The properties of an Objective-C object are available as properties of the JavaScript object that wraps the Objective-C object.

Note: OBjective-C accessor methods are not exposed. You can access the properties using JS property notation.

Constants

Prefixed properties:

Any property with type selector/class/block must be prefixed by js.

Both enums and global constants are available as JavaScript globals.

Example 1:

The enum value KHMetricPrefixPico of the enum type HKMetricPrefix is available as HKMetricPrefixPico in JavaScript global space.

//prints 1 kony.print(HKMetricPrefixPico)

Example 2:

The global constant HKCorrelationTypeIdentifierFood is available as the

JavaScript global value of type string with the same name.

Kony Studio API Developer's Guide

Version 3.1

Category Description

Method name convention

A selector that takes one or more arguments can be invoked by using a JavaScript property name that is arrived at by removing all colons and capitalizing any lowercase letter that follows a colon. For example, doFoo:withBar: becomes doFooWithBar.

Prefixed methods: l new, copy, and mutableCopy must be invoked as jsnew, jscopy, and jsmutableCopy

, respectively.

Any instance method that starts with init and accepts no parameters must be prefixed by js.

Any method that returns a selector and accepts no parameters has to be prefixed by js

Kony Studio API Developer's Guide

Version 3.1

Category Description

Type support An Objective-C method is available only if the parameter type and return type belong to any of the following: n

Primitive types such as char, int, and short are represented as JavaScript number

Objective-C objects are represented as JavaScript objects.

Structures CGPoint, CGRect, CGSize, and NSRange are represented as

JavaScript objects with the struct field names as properties.

//For example

CGPoint p={0.0,0.0} is represented by a JavaScript object

{x: 0.0, y: 0.0} n

Any other structures that have fields of types in a, b, and c, then nested structures become nested objects.

//For example

CGRect rect={{0.0,0.0},{1.0,2.0}} is represented by a

JavaScript object {origin:{x: 0.0, y: 0.0}, size:

{width:1.0, height:2.0}} n

Opaque types (for example, CFStringRef:) are represented as JavaScript objects.

Selectors are represented as strings. That is the value returned by

NSStringFromSelector

. If a method accepts a selector, then pass a string. If a method returns a selector, a string is returned.

Classes are represented as JavaScript objects as returned by objc.import API.

Blocks are represented as JavaScript functions.

Pass a JavaScript function to a method that accepts a block as a parameter,

The JavaScript function gets invoked when the block is invoked.

If a method returns a block, a JavaScript function is returned.

Only blocks with parameter types and return type as described in above are supported. The exceptions are:

Blocks that return another block are not supported.

101 of 838 n

Parameter types bool* and id* are supported. When the JavaScript function gets invoked, a JavaScript object is passed in place of these parameters. To set a value to the parameter, set the property 'contents' of the JavaScript object that the JavaScript function receives.

When a method accepts NSError** as a parameter, pass a JavaScript object.

Upon return, this object will have the property 'error' set if there was an error.

The same types apply for Objective-C properties.

Kony Studio API Developer's Guide

Version 3.1

Category Description

Memory management

Memory management occurs automatically. You need not invoke release/retain/autorelease.

Kony Studio API Developer's Guide

Version 3.1

Category

Creating classes

Description

To create a class, use the following API:

Note: This API can only be used from the main thread and JavaScript thread. Do not call it from a worker thread.

objc.newClass

At several places in iOS SDK, a protocol needs to be implemented or an abstract class needs to be extended, so that the iOS framework can invoke a user-defined code. For example, asynchronous APIs expect a callback method that gets invoked with the result.

The purpose of this API is to enable such calling. It is not designed to define arbitrary new

Objective-C classes.

Only the instance methods with

types

as described can be overridden. The exceptions are: l

Methods that return blocks cannot be implemented.

Parameter types bool* and id* are supported. While invoking a JavaScript function that implements an Objective-C method that takes a parameter of these types, a

JavaScript object is passed. To set a value to the parameter, set the property contents of the JavaScript object passed.

From JavaScript side, the resulting class behaves like its base class: l

Instances of the class can be created by calling a base class's constructors.

Instances of the class can be acted on as if they are the base class's instances.

In addition, instances also have access to a super method when a method is overridden. The super method can be invoked by prefixing super to the method name.

Inside a JavaScript function that defines or overrides a native instance method, the instance can be accessed by "this".

Signature

JavaScript: objc.newClass(native_class_name, base_class_name, interface_name, interface_name_to_override)

Input Parameters native_class_name [String] - Mandatory

Specifies the native class name including the package name.

103 of 838 base_class_name [String] - Mandatory

Specifies the class name from which the new class is extended or inherited.

interface_name [String] - Mandatory

Specifies the interface name that can be implemented by the new class.

interface_name_to_override [String] - Mandatory

Specifies the interface name that must be overridden or implemented by the new class.

Return Values

Returns the class that is extended.

Platform Availability

Available on iOS platform.

JavaScript Example

//Sample code var ViewController = objc.newClass('ViewController',

'UIViewController',

['PKPaymentAuthorizationViewControllerDelegate'], { paymentAuthorizationViewControllerDidAuthorizePaymentCompletio n: function(controller, payment, completion) {}, paymentAuthorizationViewControllerDidFinish: function

(controller) {}, paymentAuthorizationViewControllerDidSelectShippingMethodComple tion: function(controller, shippingmethod, completion) {}

});

Note:

A handle to the JavaScript object has to be retained to be able to add properties, that represents an instance of a class created using objc.newClass API. If the handle is not retained, you will lose the properties that are added as part of callback functions.

Kony Studio API Developer's Guide

Version 3.1

Category

Variadic methods

Autoconverted types

Description

Support for variadic methods is limited. You can pass a maximum of 10 arguments.

The instances of NSNull, NSString, NSNumber, NSDictionary, NSArray, and NSDate and their derivatives are not available in JavaScript because they are automatically converted to and from null, string, number, object, array, and date JavaScript types.

For example, an Objective-C method, (void) doFooWithId: (NSString*) id data: (NSArray*)data must be called in JavaScript as doFooWithId("foo",

[1,2,3]);

Zones

Threads

Note: A "NSNull" in Objective-C is mapped to a "null" in JavaScript, and "nil" in

Objective-C is mapped to "undefined in JavaScript."

The zones are not available.

In an application developed using Kony Visualizer, most of the JavaScript execution happens on a separate thread (referred to as JavaScript thread). When you need to invoke a

Java API that can only be called from the main thread, use the API

kony.runOnMainThread

To resume execution back on JavaScript thread, use the API

kony.runOnWorkerThread.

For more information on Threading APIs,

click here

Kony Studio API Developer's Guide

Version 3.1

Category Description

Presenting viewControlle r

If you want to present your own viewController, you have to present it as a modal View

Controller on top of the existing rootView Controller. The current rootViewController can be accessed as UIApplication.sharedApplication

().keyWindow.rootViewController

For example, if "vc" is the new viewController, you can use the following methods to present and dismiss the view controllers.

//To display the new UI viewController

UIApplication.sharedApplication().keyWindow.rootViewController.

presentViewControllerAnimatedCompletion(vc, true, null);

//To dismiss the new UI viewController

UIApplication.sharedApplication().keyWindow.rootViewController.

dismissViewControllerAnimatedCompletion(true, null);

Kony Studio API Developer's Guide

Version 3.1

2.25.2.2 HealthKit

HealhKit is a framework provided Apple Inc., that stores data on your device in a central location called

Health app. Health app is pre built in iOS 8 and above devices. The app has different health parameters to measure your health like sleep analysis, body mass index, etc. The app can store two types of data, characteristic and non-characteristic. A characteristic data is a type of data that is not represented by a sample such as Sex, Birth Date, and Blood Type. HealthKit treats this data differently than the rest of the data it stores as you do not have multiple copies of it. Non-characteristic data are represented by a sample such as Blood Glucose, Body Temperature, Blood Pressure etc., are stored in your Health app. You can decide which information to be shared with your health and fitness apps.

Important: This API is available on iOS platform only.

Some benefits of HealthKit are: l

Users can monitor their own blood pressure and heart beat.

Doctors can collate data and monitor the patient’s condition remotely.

Users can track the burnt Calories, Body Mass Index (BMI), Body Temperature and so on.

For more information on HealthKit, click here .

APIs

Click here , to view HealthKit APIs.

Sample Application

Click here to download sample health application.

Kony Studio API Developer's Guide

Version 3.1

2.25.2.3 Apple Pay

Apple Pay is a secure mobile payment and digital wallet service by Apple Inc., using which you can make contactless payments using your iPhone 6, iPhone 6 Plus, and Apple Watch. Your credit and debit card information is stored in Apple Passbook. Your card information is securely encrypted and a unique Device Account Number is used when you make your payments. If your iPhone is stolen or lost, you can sign in to iCloud and put your device in Lost Mode. This will eventually suspend Apple

Pay from misuse.

Important: This API is available on iOS platform only.

The stores that accept contactless payments will display one of these symbols at checkout.

Some benefits of Apple Pay are: l

Simple to set up and ease of use.

Secure and safe payment method.

You need not carry your cards all the time to make payments.

For more information on Apple Pay, follow the links: l

Configuring Your Environment l

Creating a Payment Request l

Authorizing a Payment l

Payment Processing

APIs

Click here , to view Apple Pay APIs.

Kony Studio API Developer's Guide

Version 3.1

Note:

The PKPaymentButton class is not available in JavaScript. Alternatively, you have to download the Apple Pay button resources and use them on a Kony button to achieve the look desired for an Apple Pay button.

Sample Application

Click here to download sample application for Apple Pay.

2.25.2.4 Android Guidelines for Using Mobile First APIs in Kony Visualizer

To use the Mobile First APIs in Kony Visualizer, follow these guidelines:

Kony Studio API Developer's Guide

Version 3.1

Category

Accessing classes

Description

To access a class, use the following API: java.import

This API helps you import any Android native class into JavaScript. You must use the keyword "new" to instantiate (create an object) an instance of a

JavaScript class. All the APIs, methods, constants, and all members of the native class are directly accessible with the instantiated object.

Signature

JavaScript: java.import (native_class_name)

Input Parameters native_class_name [String] - Mandatory

Specifies the native class name including the package name that you want to use in JavaScript.

Return Values

Returns a JavaScript constructor function that can be used to instantiate the class. The constructor function also has properties that map to the following:

1. Static fields: Any static fields that the Java class exposes.

2. Static methods: Any static methods that the Java class exposes.

3. Inner classes: Any inner classes that the Java class defines.

Platform Availability

Available on Android platform.

JavaScript Example

//Sample code var Thread = java.import('java.lang.Thread');

Kony Studio API Developer's Guide

Version 3.1

Category

Instantiating Java classes

Description

The instances of a Java class can be created with the keyword "new" on the constructor function returned by the API java.import. For example, var ArrayList = java.import('java.util.ArrayList'); var alist = new ArrayList();

If the class has overloaded constructor methods, each of them can be called with the keyword "new" by passing the correct parameter types.

Alternatively, the API java.newInstance can be used to instantiate a Java class by passing the instance name as its first argument and the arguments to the constructor method enclosed in a JavaScript array as the second argument.

java.newInstance('class_name', [arg1, arg2, ...]);

Invoking static methods Static methods can be accessed as properties of the constructor function returned by the API java.import. Static methods can be invoked using the following syntax: var c = java.import('...'); c.static_method(arg1, arg2, ...);

Alternatively, the API java.callStaticMethod can be used as follows: java.callStaticMethod('class_name', 'static_method',

[arg1, arg2, ...]);

Kony Studio API Developer's Guide

Version 3.1

Category

Accessing static fields

Description

Static fields can be accessed as properties of the constructor function.

c.static_field = 10; var f = c.static_field;

Alternatively, you can use the following APIs: l

The API java.getStaticFieldValue can be used to retrieve a static field by passing the class name as the first argument and the field name as the second argument.

java.getStaticFieldValue('class_name', 'field_ name') l

The API java.setStaticFieldValue can be used to set a static field by passing the class name as the first argument, and the field name as second argument and the value to set as last argument.

java.setStaticFieldValue('class_name', 'field_ name', value)

Kony Studio API Developer's Guide

Version 3.1

Category

Accessing inner classes defined by a Java class.

Description

When a Java class defines inner classes, these classes can be accessed as properties of the constructor function that java.import returns. The value returned when such properties are accessed is again another JavaScript constructor function.

var c = java.import('class_name'); var ic = c.ic; var i = new ic(arg1, arg2, ...);

Note: It is possible for a Java class to have a static field, a static method, and an inner class with the same name. In such case, the inner class gets highest priority. Between the field and method, field gets higher priority.

When a method is unavailable as a property, then use the API java.callStaticMethod

to access the static method. When a field is unavailable as a property, then use the API java.setStaticField or java.getStaticField.

Using Java objects The value returned by calling new on the constructor function returned by java.import

is a JavaScript object that represents the underlying Java object.

It has properties that represent the following:

1. Instance methods of the object.

2. Instance fields of the object.

Kony Studio API Developer's Guide

Version 3.1

Category

Invoking instance methods

Description

You can invoke instance methods as follows: var c = java.import('class_name'); var i = new c(arg1, arg2, ...); i.instance_method();

Alternatively, the API java.callMethod can be used as follows: java.callMethod(i, 'instance_method',

[arg1,arg2,....]);

Accessing instance fields You can access the instance fields as follows: var if = i.instance_field; i.instance_field = 'abc';

Note:

In Java a class can have an instance method and instance field with same name. Fields get priority over method. Therefore when a method is shadowed by a field, the method can be invoked using java.callMethod.

Category

Types

Kony Studio API Developer's Guide

Version 3.1

Description

Java to JavaScript

When Java returns a value to JavaScript, or passes a value to a callback, Java values are converted to JavaScript values, as follows: l null -> null l void -> undefined l boolean -> boolean l

String -> string l byte -> Byte object l long -> Long object l int -> Integer object l short -> Short object l double -> Double object l float -> Float object

Java arrays are converted to JavaScript arrays with individual elements converted, as above.

All other Java objects are wrapped in JavaScript objects. These objects behave as described in

Using Java objects

JavaScript to Java

When invoking Java methods, JavaScript values passed are converted to Java values, as below: l null, undefined -> null l string -> String object l int -> Integer object l number - >Double object boolean -> Boolean object

114 of 838 l

JavaScript objects that represent Java objects -> Java objects l

All other JavaScript Objects - > null

JavaScript arrays are converted to Java object arrays with individual elements converted as above.

When a Java method parameter type is byte, short, long, char, and float (that do not have an equivalent representation in JavaScript), the APIs java.newByte, java.newShort, java.newLong, java.newChar

, and java.newFloat

can be used to create correct type. Each of these APIs accepts a JavaScript number as argument.

var b = java.newByte (10);

When a Java method parameter type is an array, the API java.newArray can be used to create a Java array. The first argument to java.newArray can be

'byte', 'char', 'short', 'double', 'int', 'boolean' or a class name. The second argument to java.newArray is a JavaScript array with individual elements that belong to the type described by the first argument.

var byteArray = java.newArray(‘byte’, [ java.newByte

(1), java.newByte(2), java.newByte(3) ]);

Category

Exceptions

Kony Studio API Developer's Guide

Version 3.1

Description

When Java throws an exception while performing any of the following operations, an error is thrown in JavaScript. The message property of the error object contains the Java exception in its entirety - exception type, exception message, and stack trace.

Import a Java class n

Create instances of a class n

Invoke static methods n

Get/Set static fields (including inner classes) n

Invoke instance methods n

Get/Set instance fields

Kony Studio API Developer's Guide

Version 3.1

Category

Creating classes

Description

To create a class, use the following API: java.newClass

This API allows you to extend or implement any Android native, Java class, or interface.

Note: This API can only be used from the main thread and JavaScript thread. Do not call it from a worker thread.

Signature

JavaScript: java.newClass(native_class_name)

Input Parameters native_class_name [String] - Mandatory

Specifies the native class name including the package name.

base_class_name [String] - Mandatory

Specifies the class name from which the new class is extended or inherited.

Interface_name [String] - Mandatory

Specifies the interface name that is implemented by the new class.

Interface_name_to_override [String] - Mandatory

Specifies the interface name that must be overridden or implemented by the new class.

Return Values

Returns the class that is created.

Platform Availability

Available on Android platform.

JavaScript Example

//Sample code var c = java.newClass('MyRunnable',

116 of 838 run: function () { print('hello from thread');

}

}); var i = new c(); var Thread = java.import('java.lang.Thread'); var thread = new Thread(i); thread.start();

Note: Memory Management: An Instance of a class created using the API java.newClass

requires a JavaScript object to operate. This JavaScript object becomes “this” in the JavaScript functions that implement the methods of the class. As such the JavaScript object holds a reference to the

Java object (for example, to be able to call super methods) and the Java object holds a reference to the JavaScript object (to be able pass it as

“this”

), creating a circular reference. Hence it is required to call the API java.unref

on an instance of a class created by using java.newClass

when the instance is no longer needed. For example, if a class is created to make an HTTP request, when the HTTP request finishes, java.unref

needs to be called on “this” in both success and failure callbacks.

Category

Other APIs

Threads

Kony Studio API Developer's Guide

Version 3.1

Description

The following is an API that must be used in Mobile First APIs: java.instanceOf

This API is used to find out if a Java object wrapped in a JavaScript object is an instance of a class.

Signature

JavaScript: java.instanceOf (firstargument, secondargument)

Input Parameters firstargument [String] - Mandatory

Specifies the JavaScript object.

secondargument [String] - Mandatory

Specifies the class name.

Return Values

Returns true if the passed Java object is an instance of the class else it returns false.

Platform Availability

Available on Android platform.

In a Kony application, most of a JavaScript execution happens on a separate thread (JavaScript thread). When you need to invoke a Java API that can only be called from the main thread, use the API

kony.runOnMainThread

. To resume execution back on the JavaScript thread, use the API

kony.runOnWorkerThread.

For more information on Threading APIs,

click here .

Kony Studio API Developer's Guide

Version 3.1

Category

Getting Android activity context

Description

The following is a sample code to get the Android activity context: var KonyMain = java.import

('com.konylabs.android.KonyMain'); var context = KonyMain.getActivityContext();

Kony Studio API Developer's Guide

Version 3.1

Category

Lifecycle events

Description

The Kony Android UI framework is based on a single Activity model, and all the application forms are rendered in the same KonyMain activity. You need to be notified about KonyMain activity life cycle events in FFI and MobileFabric APIs space. The Kony Android platform helps you register for KonyMain activity life cycle events using the following API:

KonyMain.addActivityLifeCycleListener(KonyActivityLifeCycleListener listener);

You can also unregister for Activity life cycle events using following API.

KonyMain.removeActivityLifeCycleListener(KonyActivityLifeCycleListener listener)

For more information on Activity lifecycle events, click here .

public class MyKonyActivityLifeCycleListener extends

KonyActivityLifeCycleListener {

Override public void onCreate(Bundle savedInstanceState) {}

Override public void onStart() {}

Override public void onRestart() {}

Override public void onResume() {}

Override public void onPause() {}

119 of 838

Override public void onStop() {}

Override public void onDestroy() {}

Override public void onNewIntent(Intent intent) {}

Override public void onActivityResult(int requestCode, int resultCode, Intent data) {}

}

//Registering listener

KonyActivityLifeCycleListener listener = new

MyKonyActivityLifeCycleListener();

KonyMain.addActivityLifeCycleListener(listener);

//Unregistering listener when not needed

KonyMain.removeActivityLifeCycleListener(listener);

Kony Studio API Developer's Guide

Version 3.1

2.25.2.5 Bluetooth

Bluetooth APIs allow a mobile device to scan other devices, connect, and wirelessly exchange data with other Bluetooth devices. These APIs let applications wirelessly connect to other Bluetooth devices, enabling point-to-point and multipoint wireless features.

Important:

This API is available on Android platform only.

Using the Bluetooth APIs, an Android application can perform the following: l

Scan for other Bluetooth devices.

Identify paired Bluetooth devices.

Establish Radio Frequency Communication (RFCOMM) channels.

Connect to other devices through service discovery.

Transfer data to and from other devices.

Manage multiple connections.

For more information on Bluetooth APIs, click here .

APIs

Click here to view Bluetooth APIs.

2.25.2.6 JobScheduler

The JobScheduler API helps schedule background tasks that are executed in your application. This

API allows you to execute batch jobs that are nonuser facing jobs or that do not require any interaction, such as jobs that download/upload data from the network.

Important: This API is available on Android platform only.

Kony Studio API Developer's Guide

Version 3.1

You may want to run a task later or under certain conditions, such as when a device is plugged into a power source or connected to a Wi-Fi network. The JobScheduler API performs an operation for your application when such predefined conditions are met.

Following are some examples of when to use JobScheduler APIs: l

Tasks that do not require user interaction.

Tasks that should be done once the device is connected to the power supply.

Tasks that require network access or a Wi-Fi connection.

Tasks that should regularly run as batch where the timing is not critical.

For more information on JobScheduler APIs, click here .

APIs

Click here to view JobScheduler APIs.

Limitations

Following are the limitations of JobScheduler APIs: l

Jobs scheduled using the JobScheduler API will work only when the application is running in the foreground or background.

Jobs scheduled using the JobScheduler API will not work when the application is not running, because of the following reasons: n

To schedule any job, a JobService needs to be created and passed as a parameter to

Jobscheduler.

A service in Android can run when the app is in the foreground as well as in the background. If you initiate JobService from JavaScript code, the service can run even when the app is in the background.

A JobService can get triggered by an event configured even when the app is in the background. When that occurs JobService will not be available because this class is created at run time from JavaScript code. This class is not a Java class.

Kony Studio API Developer's Guide

Version 3.1

Other limitations, mostly from Android M developers preview version: n

Every service must be declared in the AndroidManifest.xml file with the Java class name implementing the Service. For example:

<service android:name="<packagename>.TestJobService" android:permission="android.permission.BIND_JOB_SERVICE" android:exported="true"/ > n

AndroidManifest.xml

expects the Java class to be exist at the build time to register the service with the Android system.

In Kony Visualizer, using Mobile First APIs, the class that implements this JobService is created at run time using java.newClass API.

AndroidManifest.xml

restricts the service to be registered with the native Android system. Thus service will not work.

To achieve the requirement, follow these steps: n

You can write the JobService class in Java and bundle it as a jar library with the app.

A JobService can be mentioned as an entry into the Manifest file through Kony Visualizer

> Properties > Native > Android > Tags > Child Tag entries under <application>.

To enable the communication between JavaScript and JobService, you can write an FFI component and use Function callbacks.

2.25.2.7 Near Field Communication

Near Field Communication (NFC) is a technology that enables communication between smartphones and other devices up to a distance of 4cm. The connection between NFC devices happens within a tenth of a second. NFC consumes less power. NFC-supported devices are indicated with NFC Tags or tickets.

Kony Studio API Developer's Guide

Version 3.1

Important:

This API is available on Android platform only.

Some uses of this technology are: l

You can make payments with your smartphones without using any credit card or cash.

You can buy tickets.

You can share files, photos, or videos.

The data is stored in tags in a standard format. You can also store data in different formats. For more information on NFC, click here .

APIs

Click here to view Near Field Communication APIs.

Sample Application

Click here to download a sample application for Near Field Communication.

2.25.2.8 Speech

The Speech API on the Android platform helps integrate speech input/output capabilities into your application. When you speak into your device, your words are converted into text. Using this API, you can add voice navigation, fill in a form with voice input, and so on. For more information, click here .

Important: This API is available on Android platform only.

The Text-to-speech functionality allows you to create applications that can convert text into speech.

The Text-to-speech feature can be tailored to different languages and locales, allowing you to create an experience that is targeted to your application users. Using this API, you can enable your phone to read pages of text out loud. You can also change the pitch and speech rate. For more information, click here .

APIs

Click here to view Speech APIs.

Sample Application

Click here to download a sample application for Speech.

Kony Studio API Developer's Guide

Version 3.1

2.26 Network APIs

The APIs under Network APIs are: l

kony.net.invokeServiceAsync

kony.net.cancel

kony.net.isNetworkAvailable

kony.net.setNetworkCallbacks

kony.net.getActiveNetworkType

getAllResponseHeaders

append

kony.net.getCookies

kony.net.clearCookies

Deprecated APIs

Any network call goes through the following phases:

Kony Studio API Developer's Guide

Version 3.1

125 of 838

Kony Studio API Developer's Guide

Version 3.1

1. Phase 1: preparing network request.

2. Phase 2: making a network connection.

3. Phase 3: handling the returned response.

You can view a video on using Network APIs at: http://docs.kony.com/video_ tutorials/default.htm#Network.htm%3FTocPath%3D_____18 .

Note: All network APIs use the post method to fetch data from a specified URL. The post method is not configurable.

2.26.1 Asynchronous Network Calls

Asynchronous services can be invoked over existing web protocols (http or https). An asynchronous service does not wait for a response, but continues its work and handles the response later during the execution of the application. When you invoke an asynchronous service call, the user interface (UI) is not blocked, and you can perform other actions such as invoking other services such as updating data on the forms. Use asynchronous service calls if you have long running tasks in the application (like querying a database, making another service call etc).

You need to define a separate callback function to handle return values of an asynchronous service call. An asynchronous call always returns a handle to the service call as an immediate response, and the callback function handles logic to process the return values and error codes (if any).

On the Mobile Web platform, where the virtual machine runs the server, an asynchronous network call is also treated like a synchronous call. When the asynchronous network call API is used, the Mobile

Web platform invokes the network call with the URL and the parameters provided. While the native applications continue processing of the next line of code after the network call (without waiting for the network call to return), the Mobile Web platform waits until the response is fetched from the network call, executes the callback function, and then executes the next line of code after the network call.

In native applications, the print statements appear in the following order:

Kony Studio API Developer's Guide

Version 3.1

1. Hello World - Before invoking network call.

2. Hello World - After invoking network call.

3. Hello World - Inside callback function.

On the Mobile Web platform, the print statements appear in the following order:

1. Hello World - Before invoking a network call.

2. Hello World - Inside a callback function.

3. Hello World - After invoking a network call.

Advantages

With an asynchronous service call, you can: l

Make multiple service calls at the same time based on the application requirement.

Perform other actions because code execution and user interface are not blocked.

Make your application perform better and be more responsive.

Use the resources to the fullest extent (of the system on which the application is running).

Disadvantages

You need to define appropriate actions within the callback functions, and manage the application states and the UI.

Use Cases

You should use asynchronous services in the following scenarios:

1. When the service calls are independent of each other, you can use the asynchronous service calls. For example, you can search for flights, hotels, cars, and more (all these tasks are independent of each other).

Kony Studio API Developer's Guide

Version 3.1

2. When the response of a service call is not consumed immediately in the application flow, but is used later.

2.26.2 Deprecated APIs

This section lists all the deprecated APIs.

2.26.2.1 kony.net.invokeservice

This API allows you to invoke a service synchronously with the specified parameters.

Signature

JavaScript: kony.net.invokeService(url,inputParamTable,isblocking)

Input Parameters url [String] - Mandatory

The URL containing the remote location from where the content is to be retrieved.

inputParamTable [None.]

It is the list of parameters that need to be passed to the remote service. The parametermap is a table that has the following key-value pairs: l appID - Unique ID of the application l serviceID - Unique ID of the service l httpheaders

[None.] - The httpheaders is an Optional key in the parameter table . You can use this key when you want to pass custom headers to the remote service.

For example, httpheaders={authkey:"myauthkey", authtoken="myauthtoken"}

Kony Studio API Developer's Guide

Version 3.1

Certain headers like User-Agent will be overridden by the underlying SDK and hence cannot be set using this key.

If the remote service requires basic authentication, you can set the header as follows:

Authorization="Basic <base64encoding of the username:password>". For example, httpheaders={Authorization=

"Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="}

Note: Make sure there is a space between

Basic

and the actual base64 encoded string.

The following is an example on how to use this parameter: local myhttpheaders={authkey=

"myauthkey",authtoken="myauthtoken"} local inputParamTable={appID="SampleApp", serviceID="accountLogin", httpheaders=myhttpheaders}; isblocking [Boolean] - Mandatory

Indicates if further actions on the user-interface needs to be blocked or not. If set to true, further clicks or actions on the form are blocked. If set to false, the user can to scroll through the userinterface but cannot perform any actions.

Return Values resulttable

This table contains three values: l opstatus l errcode l errmsg.

Kony Studio API Developer's Guide

Version 3.1

If the opstatus is 0, it indicates that the service call is a success while a non-zero value indicates a failure.

If the opstatus is a non-zero value, it is captured in errcode . The following are the possible error codes: l

1000

- Unknown Error while connecting (If the platform cannot differentiate between the various kinds of network errors, the platform reports this error code by default) l

1011 - Device has no WIFI or mobile connectivity. Please try the operation after establishing connectivity.

1012 - Request Failed l

1013 - Middleware returned invalid JSON string l

1014

- Request Timed out l

1015 - Cannot find host l

1016 - Cannot connect to host l

1022 - Service call is canceled. You can customize the behavior of the application if a service call is canceled.

Note: When you explicitly call form.show, then the iOS device will cancel the service call.

1200 - SSL - Certificate related error codes.

The error message corresponding to each error code is captured in the errmsg parameter.

API Usage

Based on the application requirement and logic, the developer should decide whether to invoke a service synchronously or asynchronously. For a synchronous service call, you should use the net.invokeservice API. For an asynchronous service call, you should use the net.invokeserviceasync

API.

Kony Studio API Developer's Guide

Version 3.1

UI Behavior

When the synchronous service call is in progress, you can scroll through the user-interface but cannot perform any actions until the application receives the response for the synchronous service from the server. A progress indicator (something similar to ) appears on the screen indicating to the user that a service call is in progress.

Note: Currently, iPhone and BlackBerry platforms allow you to cancel a synchronous service call while it is in progress. When a service call is canceled, 1022 error code is thrown and you have to handle the logic that needs to be executed for that specific error code.

On iPhone, if the isblocking parameter is set to true, a message similar to the following message appears at the bottom of the screen allowing you to cancel the service call.

If the isblocking parameter is set to false, this message does not appear.

Note: On iPhone platform, the default value of isblocking parameter is true.

Rules and Restrictions

Use synchronous service calls only when you need the service output to be consumed immediately for other actions in the application. In other words, use synchronous service calls when you want the code in the application to be executed sequentially.

2.26.2.2 Platform Availability

Available on all platforms except BlackBerry 10.

local myhttpheaders={authkey="myauthkey",authtoken="myauthtoken"} local params=

{appID="12345",serviceID="test1",httpheaders=myhttpheaders};

Kony Studio API Developer's Guide

Version 3.1

local myresulttable=net.invokeservice("http://test.konylabs.net", params,true); if (myresulttable.opstatus == 0) then

// display some other form else// display error end;

2.27 Notifications

The notification system allows users to keep informed about relevant and timely events in your app, such as new chat messages from a friend or a calendar event. For example, if you have installed news app in your devices, you will receive timely news updates for that app.

Notifications are of two types. They are local notifications and remote notifications. Remote notifications are also known as push notifications.

Local Notifications

Remote Notifications

Notification Settings

2.27.1 Local Notifications

Local notifications are scheduled by an app and delivered on the same device. They are suited for apps with time-based behaviors, such as calendar events.

Note: Each app on a device is limited to 64 scheduled local notifications. The system discards scheduled notifications exceeding this limit. Recurring notifications are treated as a single notification.

Kony Studio API Developer's Guide

Version 3.1

The local notification APIs are: l

kony.localnotifications.setCallbacks

kony.localnotifications.create

kony.localnotifications.cancel

Kony Studio API Developer's Guide

Version 3.1

2.27.1.1 Modifying localnotificationconfig.xml File in Android Platform

The default behavior of the local notification message can be customized by modifying the localnotificationconfig.xml

file. The localnotificationconfig.xml file contains key value pairs that allow applications to configure individual keys to override the default behavior.

You can customize the notification using the keys provided in localnotificationconfig.xml.

The table below shows a list of key value pairs, each with a brief description.

Notification ID notify_local_msg notify_local_msg_notifications_count

Default

Value true

Description

Enable or disable new local message notifications. If false, no status bar notification is shown when application is running in background.

1 By default, only the latest local message notification is kept in the status bar. Use this option to control the number of messages to be stored. The maximum limit allowed in Android is 50.

Note: After exceeding the storage limit, older messages are replaced with newer messages. However, sometimes older notifications are replaced with newer messages even before the storage reaches the specified count (this happens when the app is closed by the Android system).

Notification ID notify_local_msg_icon notify_local_msg_sound notify_local_msg_vibrate notify_local_msg_lights notify_local_msg_clear

Kony Studio API Developer's Guide

Version 3.1

Default

Value icon

Description

Specify icon resource without extension. For example, set a logo to use an image for the message icon for which the file name is logo.png. The default is icon.png.

true true true true

Enable or disable sound for local message notification.

Enable or disable vibrate for local message notification.

Enable or disable lights for local message notification.

Indicates if a user can clear the unread local message notification.

Kony Studio API Developer's Guide

Version 3.1

2.27.2 Push Notification APIs

Push Notifications is a mechanism using which you can initiate a message delivery to a device without receiving a request. Remote notifications, also known as push notifications, are sent by Kony Message

Service (KMS) to the Apple Push Notification Service (apns), which pushes the notification to devices.

Note: Remote Notifications will not work in the simulator.

The Notification Payload For Remote Notification

Each remote notification includes a payload In iOS 8 and later, the maximum size allowed for a notification payload is 2 kilobytes. Apple Push Notification service refuses any notification that exceeds this limit. (Prior to iOS 8, the maximum payload size is 256 bytes.)

Note: Delivery of notifications is a “best effort”, not guaranteed. It is not intended to deliver data to your app.

2.27.2.1 How it Works

The following are the primary processes involved in an application being setup for Push Notifications:

Enabling Push Notifications

: When an application needs to use the Push Notifications service, it uses the

kony.push.setCallbacks

API and specifies the functions to be executed for Push

Notifications.

The application then uses the

kony.push.register

API to register the application and the device with the corresponding Push Notification Service provider of the device os.

Sending Push Notifications : If the registration is successful, the application can receive Push

Notifications on the device from the third-party application server.

Receiving a Message

: The third-party application server sends a Push Notification to the application and the device extracts the data from the message and passes it to the application.

Kony Studio API Developer's Guide

Version 3.1

Disabling Push Notifications

: The application can deregister from Push Notification service by using the

kony.push.deRegister

API.

Platforms Supporting Push Notifications

Push Notifications are currently supported only by Android, BlackBerry, iPhone and Windows Phone platforms.

For Push Notifications to work, the application and the device must first register with the corresponding Push Notification Service provider of the device os.

The following is the list of platforms and their corresponding Push Notifications Service providers they must register with:

Platform

Android/Android Tablet

BlackBerry iPhone

Windows Phone

Push Notifications Service

Google Cloud Messaging (GCM)

Deprecated:Android Cloud to Device Messaging (C2DM)

BlackBerry Infrastructure

Apple Push Notification Service (APNS)

Microsoft Push Notification Service (MPNS)

Enabling Push Notifications

To enable Push Notifications for an application do the following:

1. The application uses the

kony.push.setCallbacks

API and specifies the functions to be executed for Push Notifications.

2. The application uses the

kony.push.register

API to register for Push Notifications with the corresponding Push Notification Service provider of the device OS.

Kony Studio API Developer's Guide

Version 3.1

3. If the registration is successful, the Push Notification Service provider returns a unique identifier to the device.

The following is the list of Push Notification Service providers and the unique identifier they return:

Push Notifications Service

Google Cloud Messaging(GCM)

Deprecated: Android Cloud to Device

Messaging (C2DM)

BlackBerry Infrastructure

Returned Unique Identifier

Registration ID

Apple Push Notification Service (APNS)

Microsoft Push Notification Service

(MPNS)

Device ID (can be obtained by using the os.platform.deviceid API)

DeviceToken

Unique URL

4. The application sends the identifier to the third-party application server. The third-party application server can use this identifier to send Push Notifications to it.

Kony Studio API Developer's Guide

Version 3.1

The following image illustrates the steps involved in enabling Push Notifications for an application on a device:

Sending Push Notifications

The following are the steps involved in a third-party application server sending Push Notifications to an application on a device:

1. The third-party application server uses the unique identifier (sent by the application ) in sending the Push Notifications to the Push Notification Service provider of the device.

2. The Push Notification Service provider then sends the Push Notification message to the application on the device.

Kony Studio API Developer's Guide

Version 3.1

The following image illustrates the steps involved in sending Push Notifications to an application on a device:

Receiving a Message

When an application on a device receives a message, the following sequence of events occur:

1. The device receives the incoming Push Notification and extracts the data from the message payload.

2. The device passes the data to the application.

3. The application processes the data and displays it to the user.

Disabling Push Notifications

You can use the

kony.push.deRegister

API and deregister the application and the device from the

Push Notifications service.

Kony Studio API Developer's Guide

Version 3.1

2.27.2.2 APIs for Push Notifications

Kony Platform provides APIs that you can use to enable Push Notifications for an application on a device and also an API to deregister from the Push Notifications service.

The following are the APIs for Push Notifications:

kony.push.setCallbacks

kony.push.register

kony.push.deRegister

Note: The following are the generic error codes for Push Notification APIs:

Error

Code

1400 Invalid number of arguments.

1401

1402

1406

Error Message

Illegal arguments.

Unable to connect to push service - PNS service is not available

Platform-specific issue. Full details are available in the errormessage. For example, received payload but payload is in incorrect format.

Important: Use Error Codes to refer and do not rely on Error Messages as each message may differ from platform to platform.

BlackBerry additionally supports the following APIs: l

kony.push.getMessageCount

kony.push.getMessages

Kony Studio API Developer's Guide

Version 3.1

2.27.2.3 Important Considerations for Android

The following are the important considerations you must be aware for Android platform: l

Before you build the application for Android, navigate to the Project Properties of the application and navigate to Native App -> Android tab, and select the GCM under the Push Notification section. Selecting this option will copy the required Push Notification libraries into the application during build time." l

For C2DM to GCM conversion refer, http://developer.android.com/guide/google/gcm/c2dm.html

Google may occasionally refresh the Registration ID. Hence, you must design the application to update the third-party Application server with the new ID.

If the Kony Android platform receives a new registration ID, the following takes place: l

If the application is running in the foreground or the background onsuccessfulregistration function is called.

If the application is not running - a status bar notification is displayed. If you select the notification, the application is launched and onsuccessfulregistration function is called.

If the Kony Android platform receives a new Push Notification message, the following takes place: l

If the application is running in the foreground onlinenotification function is called.

If the application is running in the background - status bar notification is displayed. If you select the notification, the application is brought to the foreground and its onlinenotification function is called.

If the application is not running - status bar notification is displayed. If you select the notification, the application is launched and offlinenotification function is called.

The status bar notification is displayed by the platform with the default settings.

The default settings are in the pushconfig.xml file (available after the application is built) in "dist\

{APP-ID}\res\values" location.

Kony Studio API Developer's Guide

Version 3.1

You can override and configure the notification parameters like title, vibrate and sound by placing the pushconfig.xml in the"resources\mobilerichclient\android\values" directory (located under your project workspace folder).

To customize GCM broadcast receiver, refer Kony Visualizer User Guide .

2.27.2.4 Important Considerations for BlackBerry

The following are the important considerations that you must be aware of for BlackBerry platform: l

You must test the Push Notifications on an actual device and not on an emulator. Since the emulator does not have a unique device id, you cannot test all network related error cases.

Push Notifications is supported on all BlackBerry devices. However, the Home Screen notifications (appicon, starappicon, and statusbaricon) are available only on BlackBerry devices

5.0 and above.

Push Notifications service is available only to the users who have subscribed to a

Full BIS data plan. Push Notifications service does not work on any other BlackBerry transports. For example, MDS, WAP2, or TCP/IP.

The appid and the port must be unique to the application. You can acquire them by registering the application (the registration process takes up to two weeks to complete).

To register, you can use the following links:

For Evaluation: https://www.blackberry.com/profile/?eventId=8121

For Production: https://www.blackberry.com/profile/?eventId=8207 l

If you receive an error code rc=10002 during registration, it means that there is an issue related to the appid. The appid is either empty or has expired.

2.27.2.5 Reference Links

You can get detailed information regarding the implementation of Push Notifications on various platforms, by visiting the following links:

Kony Studio API Developer's Guide

Version 3.1

Android http://code.google.com/android/c2dm

BlackBerry http://us.blackberry.com/developers/platform/pushapi.JavaScriptp

iPhone http://developer.apple.com/library/ios/documentation/NetworkingInternet/

Conceptual/RemoteNotificationsPG/Introduction/Introduction.html#//apple_ref/doc/uid/TP40008194-

CH1-SW1

Windows Phone: http://msdn.microsoft.com/en-us/library/ff402537(VS.92).aspx

2.27.3 Notification Settings

Note: Notification setting APIs work on the following OS versions.

• iOS8 and above

• Android 4.1 and above

You can send actionable notifications using the notification setting APIs. User notifications can have additional custom actions. Two actions can be displayed on the lock screen, in a banner, and in the

Notification Center. In alerts, notifications can display up to four actions when a user taps the Options button. To use notification actions in your app, you need to register the actions, schedule a local notification or a remote notification, and handle the action chosen by the user.

Following are the types of notifications: l

Alert or Banner: Based on the preferences a user sets in the devices, a notification is shown using either an alert view or a banner. Both the alert and banner should contain the message of

Kony Studio API Developer's Guide

Version 3.1

the notification.

Sound: A predefined or a custom sound is played when the notification is fired. In most cases, users will not look at the device all the time, so any notifications could be easily overlooked.

Badge: A badge number can also be shown in the app’s icon when a new notification is fired.

The badge number must be increased by one with a new notification, and then decreased when the notification is handled. iOS automatically shows and hides the badge, depending on whether there is a value other than zero to display.

Actions, Categories, Settings

Actions: Specifies the actions that any user can perform to interact with the notification message.

Actions are presented as buttons and defined by the kony.notificationsettings.createAction

Categories: Specifies a group of actions into a category. They categories are defined by the kony.notificationsettings.createCategory

Settings: The settings must be registered by the application, and they contain all the categories and notification types that we create. These settings are defined by the kony.notificationsettings.registerCategory

Following are the notification settings APIs: l kony.notificationsettings.createAction

l kony.notificationsettings.createCategory

l kony.notificationsettings.registerCategory

Kony Studio API Developer's Guide

Version 3.1

2.28 Offline Data Access APIs

These APIs allow you to store data onto the device data store persistently (available after application or device restart). Such data can be accessed even if the device is offline (not connected to any wireless network [cellular or WIFI]. The API libraries are as follows: l

LocalStorage Library

o kony.store.key

o kony.store.setItem

o kony.store.getItem

o kony.store.removeItem

o kony.store.clear

o kony.store.length

WebSQL Library

kony.db.openDatabase

kony.db.transaction

kony.db.readTransaction

kony.db.executeSql

kony.db.sqlResultsetRowItem

kony.db.changeVersion

2.28.1 Local Storage APIs

LocalStorage APIs allow the users to store and retrieve data in HTML pages from the same domain.

The data can be retrieved from all the windows in the same domain even if the browser is restarted.

Kony Studio API Developer's Guide

Version 3.1

The data stored using the LocalStorage APIs is accessible only from the client-side as opposed to the data stored in cookies (accessible from both client-side and server-side). You can store huge data using these APIs.

2.28.2 Web SQL APIs

The WebSQL APIs allow you to manipulate client-side databases using SQL. You can use these APIs to store data in databases that can be queried using a variant of SQL.

For BlackBerry, these APIs are supported only on 5.0 and above versions.

Important:

WebSQL implementation utilizes the database engines bundled along with the underlying SDK (SQLite in most of the cases). Kony Platform ensures that the WebSQL semantics are same across platforms, but the uniformity of SQL semantics across native platforms is not guaranteed. For example, the WebSQL APIs have no control over the way CONSTRAINTS are supported as per the SQL92 specification. For more information on SQLite refer

Appendix

Important: WebSQL APIs are not supported on Internet Explorer and Firefox.

Important: The framework does not store the password argument to kony.db.openDatabase()

API, it is the responsibility of application developer to secure the password.

The actual database used for storing the data and its visibility to other applications is defined in the following table:

Platform iPhone/iPad

Android/Android Tablet

Client Database

Engine

SQLite

Accessible to other applications

The storage area is unique to the application.

Kony Studio API Developer's Guide

Version 3.1

BlackBerry

Windows 6x

Windows Phone 7.5

Windows Phone 8

Windows Phone 8.1

Windows Desktop/Kiosk

Windows 8

Windows 8.1

Symbian

Platform

Single Page Application

(SPA)

Client Database

Engine

SQLite

SQL Server CE

SQLite

Accessible to other applications

SDCard. Data is accessible to other applications.

File System. Data is accessible to other applications.

The storage area is unique to the application.

Determined by the browser implementation.

The following table indicates the JavaScript datatypes and their corresponding SQLite datatypes:

Kony Studio API Developer's Guide

Version 3.1

JavaScript Datatype string number byte array (rawbytes) boolean

SQLite Datatype

TEXT

REAL

BLOB

BOOLEAN

Note: You must create an SD Card to use the WebSQL APIs on a BlackBerry emulator.

To create the SD card, follow these steps:

1. Launch the required BlackBerry emulator.

2. Go to Simulate -> Change SD Card -> Mount Directory.

3. Point the location to any directory of your choice.

4. Click OK.

5. Click Close.

Limitations

This section describes the limitations of WebSQL APIs: l

Table names and Column names are case-sensitive. For example, "Employee" and "employee" refer to two different tables. It is observed that table names and columns name are caseinsensitive on Android and BlackBerry platforms, but case-sensitive on iPhone platform. For a cross platform uniform behavior, assume that the table names and column names are casesensitive.

When using the binding "?" placeholders, ensure that the number of binding parameters and the number of values are the same. Else, the database can be inconsistent.

Kony Studio API Developer's Guide

Version 3.1

For example, the following statement can cause the database to be inconsistent as the number of binding parameters are 6 and the number of values are 3: local stmt3 = "insert into EMP_DETAILS values(?,?,?,?,?,?)" kony.db.executeSql(tx,stmt3,{'1','2','3'}, successCallback,errorCallback); l

Nested database transactions are not supported across platforms. Avoid starting a new transaction in the successcallback function of an existing transaction.

The error codes might vary between the platforms. This is due to the fact that underlying SDKs do not expose all the errors that can be mapped to HTML5 WebSQL Specification. The application should not build its business logic around these error codes. These error codes are only for diagnostic purpose.

Accessing insertid key in the resultset rows leads to an error in SPA.

The WebSQL APIs are not supported on Internet Explorer and Firefox.

2.29 Operating System APIs

This chapter explains the APIs available in the OS namespace.

kony.os.addHiddenField

kony.os.readHiddenField

kony.os.startSecureTransaction

kony.os.endSecureTransaction

kony.os.getAppContext

kony.os.hasAccelerometerSupport

kony.os.deviceInfo

kony.os.deviceInfo().httpheaders

kony.os.addMetaTag

kony.os.removeMetaTag

kony.os.removeAllMetaTags

kony.os.hasGPSSupport

l kony.os.hasCameraSupport

kony.os.hasTouchSupport

Kony Studio API Developer's Guide

Version 3.1

151 of 838

kony.os.hasOrientationSupport

kony.os.getDeviceCurrentOrientation

kony.os.print

Kony Studio API Developer's Guide

Version 3.1

Kony Studio API Developer's Guide

Version 3.1

2.30 Phone APIs

The APIs in this chapter helps you to access default applications in the underlying platform of the mobile device and perform operations. The following are a few operations that you can perform using the APIs in this library: l

Send text messages (SMS).

Call a specified number.

Capture location details (GPS or Non-GPS).

Add/find/delete contacts (from the underlying native Address Book.

Add/find/delete events (from the native device calendar).

Access the maps application of the underlying platform.

Access the media from the media gallery of the device or from an external URL.

The Phone API library comprises the following: l kony.phone.sendSMS

l kony.phone.dial

l kony.phone.openMediaGallery

l kony.phone.openEmail

l kony.phone.addCalendarEvent

l kony.phone.removeCalendarEvent

l kony.phone.findCalendarEvents

l kony.contact.add

l kony.contact.find

Kony Studio API Developer's Guide

Version 3.1

l kony.contact.remove

l kony.contact.details

You can view a video on using Device Address Book at: http://docs.kony.com/video_ tutorials/default.htm#DeviceContacts.htm%3FTocPath%3D_____10 .

2.31 Self Sufficient Modules

2.31.1 Introduction

Self Sufficient Module (SSM) is a module contains APIs for a piece of native functionality. The primary purpose of this feature is to facilitate the native functions individually rather than packaging in the upcoming product versions or in the plug-ins. These modules are delivered as zip files, which can be imported directly into the Kony Visualizer to enable the functionality and use it, instead of waiting for the next version of the product or plug-in for the functionality.

The self sufficient module zip files with specific native functionality are released separately for each platform. For example, if an SSM is supported for both the Android and iOS platforms, separate zip files are released for each platform. Following are the available self sufficient modules: l

ZipUnzip for iOS and Android

Bluetooth for iOS

To use these APIs, you need to follow certain guidelines. For the iOS platform guidelines, see

iOS

Guidelines

and for the Android platform, see

Android Guidelines

Note: As SSMs are dependent on the underlying SDK versions, make sure that appropriate

SSMs are imported to the Kony Visualizer. Otherwise build errors may occur because of the compatibility issues.

2.31.2 Importing SSM in the Kony Visualizer

To import the SSM, follow the below steps:

Kony Studio API Developer's Guide

Version 3.1

1. Download the appropriate SSM from http://developer.kony.com/KonyBetaRelease70 .

2. Open the Kony Visualizer.

3. On the Project menu, click Add JS Modules. The Add JS Modules dialog box opens.

4. In the Add JS Module box, select the SSM zip file that you want to import using the Browse button.

Kony Studio API Developer's Guide

Version 3.1

5. Click Finish. The success message box appears.

6. Click OK.

7. Click the Project Settings icon. The Project Settings window opens with the Self Sufficient

Module tab added.

Kony Studio API Developer's Guide

Version 3.1

8. Click the Self Sufficient Module tab. The tab opens with the name of the native functionality that is imported. The native functionality is displayed with check box under the platform to which it is applicable.

9. Select the check box and click Finish.

2.31.3 ZipUnzip

The ZipUnzip feature helps to package multiple files into single compressed file in the mobile devices, which takes less space on the device memory and also takes less time to share. It also extracts the compressed files.

Using this feature, the iOS and Android applications can:

Kony Studio API Developer's Guide

Version 3.1

Package a set of files into one single zipped file. You can also select the required files from a list of files and package.

View the files of a zipped file along with the file size.

Unzip the zipped files.

The iOS platform does not provide any set of APIs for the ZipUnzip feature. Using the Objective-Zip library, a third party library, a set of JS binding are generated, which gives complete functionality of zip and unzip .

For more information on ZipUnzip APIs for Android, click here .

For more information on ZipUnzip APIs for iOS, click here .

2.31.4 Bluetooth

The Core Bluetooth is a framework used by the iOS apps to communicate with other devices inbuilt with Bluetooth wireless technology. For example, heart rate monitors and digital thermostats. With this feature, your iOS apps can interact, share data, perform some task and so on with other Bluetooth equipped devices.

The Bluetooth wireless technology embedded in the iOS devices is based on Bluetooth 4.0

specifications. This defines a set of protocols to enable communication between the devices.

Using the Bluetooth feature, the iOS applications can: l

Scan for devices or peripherals equipped with Bluetooth.

Request to connect with the peripheral.

Interact with the peripheral’s data.

For more information on Bluetooth APIs for iOS, click here .

Kony Studio API Developer's Guide

Version 3.1

2.32 Standard Kony APIs

This chapter explains the APIs that are not tied to any specific namespace.

The following APIs are explained in this chapter: l kony.convertToBase64

l kony.convertToRawBytes

l kony.getError

l kony.print

l kony.type

l kony.props.getProperty

Deprecated APIs

2.32.1 Deprecated APIs

The APIs in this section are supported only for backward compatibility. This section lists all the deprecated APIs: l

kony.application.setAppHeaders

kony.application.setAppFooters

kony.application.appReset

readfrombase64

2.32.1.1 kony.application.setAppHeaders

This API allows you to set header at the application level with the given input values.

Kony Studio API Developer's Guide

Version 3.1

Signature

JavaScript: kony.application.setAppHeaders(

headerlist )

Input Parameters headerlist [Array] - Mandatory

Specifies the list of attributes for the header

Return Values

None.

2.32.1.2 Platform Availability

Available on all platforms.

2.32.1.3 kony.application.setAppFooters

This API allows you to set footer at the application level with the given input values.

Note: This API is deprecated and only works for backward compatibility.

Signature

JavaScript: kony.application.setAppFooters(

footerlist )

Input Parameters footerlist [Array] - Mandatory

Specifies the list of attributes for the footer

Return Values

None.

Kony Studio API Developer's Guide

Version 3.1

Implementation Details

To access the footer elements, use the following syntax: app.footers.hboxID.widgetID

2.32.1.4 Platform Availability

Available on all Platforms.

2.32.1.5 kony.application.appReset

This API is used to reset the application. When this method is called, the data which was loaded during transactionaldataload event of forms is cleared (reset).

Note: This API is deprecated and only works for backward compatibility.

Signature

JavaScript :kony.application.appReset()

Input Parameters

None

Return Values

None.

2.32.1.6 Platform Availability

Available on all platforms except BlackBerry 10.

Example kony.application.appReset();

Resets the application data.

Kony Studio API Developer's Guide

Version 3.1

2.32.2 readfrombase64

This API provides you the ability to read rawbytes from a base 64 encoded string.

2.32.2.1 Input Parameters

The following table explains the input parameters for this API:

Parameter/Type Required base64String

[String] yes

Description

The base64 encoded string from which you want to read the rawbytes

2.32.2.2 Return Values

The following are the return values for this API:

Value/Type myrawbytes [JSObject] nil

Interpretation of return value

The rawbytes of the specified base64 encoded string nil is returned if the input is not a base64 encoded string

Remarks

2.32.2.3 Platform Availability

Android, BlackBerry, Windows, and SPA.

2.32.2.4 JavaScript Example

-- Converts the base64String to rawbytes.

local myrawbytes = readfrombase64(base64String)

-- The rawbytes extracted from the readfrombase64 API are passed to the crypto.decrypt API.

local decryptedstring = crypto.decrypt("aes",aeskey,myrawbytes);

Kony Studio API Developer's Guide

Version 3.1

Kony Studio API Developer's Guide

Version 3.1

2.33 Streaming API

Streaming is a feature that enables the device to listen to a continuous data stream and use the data.

The data is available on Streaming Servers. The common use of streaming is to utilize the multimedia from an external source (like audio or video) in your application. Streaming data uses different protocols to fetch the data.

Note: Kony currently supports only HTTP 1.1 protocol.

This chapter explains the various streaming APIs. The APIs available are: l kony.stream.registerDataStream

l kony.stream.deregisterDataStream

l kony.stream.setCallback

Kony Studio API Developer's Guide

Version 3.1

2.34 String APIs

The string Library has APIs that you can use to manipulate strings. The kony.string name space provides static string APIs. These static APIs augment the APIs in the Global string object which is available by default. For more information refer, https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/string.

2.34.1 Distinction between string primitives and string objects

Note that JavaScript distinguishes between String objects and primitive string values.

String literals (denoted by double or single quotes) and strings returned from String calls in a nonconstructor context (i.e., without using the new keyword) are primitive strings. JavaScript automatically converts primitives and String objects, so that it's possible to use String object methods for primitive strings. In contexts where a method is to be invoked on a primitive string or a property lookup occurs. JavaScript automatically wraps the string primitive and calls the method or performs the property lookup.

All the APIs in the string library have the namespace kony.string. The following APIs are described in the sections below: l kony.string.endsWith

l kony.string.equalsIgnoreCase

l kony.string.rep

l kony.string.reverse

l kony.string.startsWith

l kony.string.trim

l kony.string.isAsciiAlpha

l kony.string.isAsciiAlphaNumeric

Kony Studio API Developer's Guide

Version 3.1

l kony.string.isNumeric

l kony.string.containsChars

l kony.string.containsOnlyGivenChars

l kony.string.containsNoGivenChars

l kony.string.isValidEmail

2.34.2 Deprecated APIs

The following APIs are deprecated in JavaScript: l

2.34.3 string.compare

This API compares the contents of two strings numerically. For example, "Adam" is smaller than

"adam" as per the ASCII table because A(65) is smaller than a(97).

2.34.3.1 Signature

JavaScript: Deprecated. Use less-than and greater-than operators for comparing strings instead.

Kony Studio API Developer's Guide

Version 3.1

2.34.3.2 Return Values

Status [Number]: status of the compare operation l

1 - s1 > s2 l

0 - s1 = s2 l

-1 - s1 < s2

2.34.3.3 Platform Availability

Available on all platforms.

2.34.4 string.charat

This API returns a string which contains a single character from the source string at the specified index.

2.34.4.1 API Signature

JavaScript: Deprecated. Use the charAt() string object method

2.34.4.2 Return Values character [String]

Character at the specified index in the source string.

nil index is lesser or greater than the length of the source string

2.34.4.3 Platform Availability

Available on all platforms.

Kony Studio API Developer's Guide

Version 3.1

2.34.5 string.len

This API returns the length of the source string.

2.34.5.1 Signature

JavaScript: Deprecated. Use the length string object property instead.

2.34.5.2 Return Values length [Number]

The value returned is the length of the source string

2.34.5.3 Rules and Restrictions

If the input string has an escape character in it, this API returns the length of the string as 0.

2.34.5.4 Platform Availability

Available on all platforms.

2.34.6 string.lower

This API changes the upper case characters of the source string to lower case characters.

2.34.6.1 Signature

JavaScript: Deprecated. Use toLowerCase() string object method instead

2.34.6.2 Return Values lower case [String]

A string containing lower case characters is returned.

2.34.6.3 Platform Availability

Available on all platforms

Kony Studio API Developer's Guide

Version 3.1

2.34.7 string.upper

This API changes the lower case characters of the source string to upper case characters.

2.34.7.1 Signature

JavaScript: Deprecated. Use the toUpperCase() string object method instead.

2.34.7.2 Return Values upper case [String]

A string containing upper case characters is returned

2.34.7.3 Platform Availability

Available on all platforms.

2.34.8 string.sub

This API returns the substring of the source string.

2.34.8.1 Signature

JavaScript: Deprecated. Use the substring() string object method instead.

2.34.8.2 Return Values substring [String]

The substring of the source string is returned.

If j is not given, the substring will begin from the character specified in i and ends at the end of the source string.

If j is given, the substring will begin from the character specified in i and ends at the character specified in j and includes j.

Kony Studio API Developer's Guide

Version 3.1

2.34.8.3 Platform Availability

Available on all platforms.

2.34.9 string.split

This API splits the source string based on the separator (default is comma) and returns a table containing the string.

2.34.9.1 Signature

JavaScript: Deprecated. Use the split() string object method instead.

2.34.9.2 Return Values l

A Table containing the string is returned.

2.34.9.3 Platform Availability

Available on all platforms.

2.34.10 string.find

This API finds the first occurrence of the search string in the source string.

2.34.10.1 Signature

JavaScript: Deprecated. Use the indexOf() object method instead.

2.34.10.2 Return Values

Start Position [Number]

The search string is found and the start position of the search string is returned nil

The search string is not found

Kony Studio API Developer's Guide

Version 3.1

2.34.10.3 Platform Availability

Available on all platforms.

2.34.11 string.replace

This API finds and replaces the occurrences of a string in the source string with a string you specify.

2.34.11.1 Signature

JavaScript: Deprecated. Use the replace() string object method instead.

2.34.11.2 Return Values modified string [String]

All occurrences of the string specified in the find parameter are replaced with the string specified in the replace parameter

2.34.11.3 Platform Availability

Available on all platforms.

Kony Studio API Developer's Guide

Version 3.1

2.35 Table APIs

This library provides generic functions for table manipulation. It provides all its functions inside the table.

Most functions in the Table library assume that the table represents an array or a list. For these functions, when we talk about the "length" of a table we mean the result of the length operator.

Note: This library is also available in JavaScript under the namespace kony.table.

Note: If you are developing a new application in JavaScript we recommend using the Array and

JSObject structures.

The Table API is implemented in the

table namespace .

Kony Studio API Developer's Guide

Version 3.1

2.36 Theme APIs

Theme is a set of skins available at the application level. Themes let you specify common skins for widgets in different states (normal, focus, and so on).

You can define your own themes in Kony Visualizer or download themes from the network (a specific

URL) and use them in the application.

A theme, which consists of a set of skins, is represented as a file containing a JSON string. The JSON string has the key-value pairs in which the key is skinid and the value is JSON string that represents the skin.

Note: Every application should have a "default" theme (stored in the in the default.theme

file).Deleting or overriding the contents of this file will lead to undesired behavior. Kony Visualizer does not allow the developer to delete this theme. All other user defined themes can be deleted.

The following APIs are explained in the sections: l kony.theme.setCurrentTheme

l kony.theme.createTheme

l kony.theme.createThemeFromJSONString

l kony.theme.isThemePresent

l kony.theme.getAllThemes

l kony.theme.getCurrentThemeData

l kony.theme.getCurrentTheme

l kony.theme.deleteTheme

Kony Studio API Developer's Guide

Version 3.1

2.36.1 Use Cases l

Themes allow you to package the skins in a way that resemble a particular user interface or branding for a particular set of users. For example, all the Gold customers will see all the buttons in Golden Yellow color.

Themes allow you to personalize the look and feel of the application for the end users. For example, the users can choose between a green theme or a blue theme.

Themes, when downloaded over the network, allow to remotely control the branding of the native application. For example, during the Christmas season, the marketing or the branding team can push a Christmas Theme to the native application.

2.36.2 Prerequisites

The themes or the skins must be pre-defined in the IDE or should have been downloaded over the network.

2.36.2.1 Capabilities

The theme APIs provided by Kony Platform have the following capabilities: l

Defining new themes.

Applying the theme to the application or only for the current session.

Switching the application from one theme to another theme dynamically.

Deleting and loading the skins for memory efficiency.

Provision for custom meta data.

Kony Studio API Developer's Guide

Version 3.1

2.36.2.2 Important Considerations l

The default theme is the base-point for new theme.

If the referred skin does not exist both in the current theme and default theme, a runtime error occurs.

When a skin is referred, the IDE searches for the skin in the order of precedence) o

Current theme o

Default theme.

2.36.2.3 Important Considerations for SPA, Desktop Web, and Mobile Web l

For the SPA, Desktop Web and Mobile Web platforms, the theme files should be CSS files. It cannot accept the theme files as JSON files. If the project is developed using IDE, the platform automatically generates CSS files for the above platforms based on the skins/themes defined by the developer in the IDE. The css files will be generated under "<ThemeID>" folder.

Note: The names of the css files in the theme are same as the css files in the normal build.

For those customers/developers, interested in developing applications without IDE, the platform will provide an offline tool to convert a given .theme JSON file into corresponding CSS file. This will be provided post 5.0.

For the createTheme API, ensure that the URL mentioned in the createTheme API should point only to a CSS file. The platforms do not support a URL with a .Theme file and convert it into a

CSS file at run time.

l getCurrentThemeData will always return null. As theme files are converted into CSS, the platforms cannot have custom structures/variables in CSS files as browsers fail to parse them.

Kony Studio API Developer's Guide

Version 3.1

Do the above platforms support skin level fallback?

The platforms expect each theme file i.e

. CSS file to have all the skins. In the case of projects developed in IDE the platform takes care of skin conversion of this during generation. For customers, hand coding the application, the above mentioned tool should take care of that. But essentially at run time the platforms cannot look up into multiple CSS's and check for a class.

Technically it is possible to do so but it requires the platform to load multiple CSS files and in a specific order. Adding new downloads is an always avoidable and we intend to handle this during the generation of the CSS file itself.

2.36.2.4 Limitations

You cannot dynamically modify the skin attributes.

Kony Studio API Developer's Guide

Version 3.1

2.37 Threading APIs

A subset of native APIs runs only on the main or UI thread. In a Kony application, the bulk of

JavaScript code runs on a VM thread (also called a closure thread). Threading APIs help JavaScript bindings work on main thread. When the code completes its run on the main thread, you need a mechanism to resume JavaScript execution on the VM thread.

The Threading APIs are: l kony.runOnMainThread

l kony.runOnWorkerThread

2.38 Guidelines for using Threading APIs

To use Threading APIs in Kony Visualizer, follow the guidelines: l

Threading APIs natively support multi-threading environment.

An application can be composed of multiple concurrent threads.

The UI or main thread is responsible for dispatching events to the user interface widgets and drawing the elements of the UI.

Do not block the UI thread. Performing long operations, like network access or database queries on the UI thread, will block the user interface.

Do not access the UI components from outside the UI thread. l

JavaScript Thread: l

Application logic written in JavaScript that does not require UI update executes in a different thread than the Main or UI thread.

Operations that update the UI are posted on to the Main or UI thread.

Kony Studio API Developer's Guide

Version 3.1

Use the API kony.runOnMainThread(function, args) to execute JavaScript bindings and JavaScript logic on UI Thread.

Kony Studio API Developer's Guide

Version 3.1

2.39 Timer APIs

The APIs in this library provide you the ability to schedule the execution of a function block at regular intervals. The namespace for TimerAPI is kony.timer.

The timer APIs are as follows: l kony.timer.schedule

l kony.timer.cancel

l kony.timer.setCallBack

Kony Studio API Developer's Guide

Version 3.1

2.40 Worker Thread APIs

Worker threads are a means to execute different tasks in multiple parallel contexts of execution in a concurrent manner, which can take advantage of multiprocessor and multithreaded environments as well as to keep UI Thread in Application responsive by delegating or offloading work which need not be handled in UI Main thread, to a different secondary thread.

Worker thread is a continuous parallel thread that runs and accepts messages until the time it is explicitly closed or terminated. Messages to a worker thread can be sent from the parent thread or its child worker threads. Through out this document, parent thread is referred as thread where a worker thread is spawned.

Worker can have logic that gets executed parallel for each of the messages that it receives. If worker thread is busy handling messages, incoming messages that it receives will be queued for processing.

Sharing data between parent thread and worker threads is done through message passing and by default variables, functions, or state is not shared.

The current specification is inspired from and based on HTML5 Web Worker threads standard, that use

Message Passing model or mechanism for communication between threads.

The scenarios of using

WorkerThread() constructor are as follows: l

The WorkerThread() constructor creates a new worker thread and returns a handle to the new worker thread, which can be used by the parent thread for any further communication with the worker thread.

Creating a worker thread requires a JavaScript file name or a functional module name. The

WorkerThread() constructor is invoked with the JavaScript file or a functional module name as its only argument and a worker thread instance is then created and returned: var worker = new kony.worker.WorkerThread('helper.js'); var worker = new kony.worker.WorkerThread

('functionModuleName');

Kony Studio API Developer's Guide

Version 3.1

A message event handler can be registered with the worker by parent thread to receive messages from the worker thread.

worker.addEventListener("message", function (event) {

... }); l

To send data from parent to a worker, postMessage() method can be used from parent.

'buffer', threshold: 0.6 } ); l

To send messages back from worker thread to parent thread scope, postMessage() can be used.

postMessage({'msg':'Data'}); l

To receive a messages inside the worker thread from parent thread, the message event handler can be registered using addEventListener() inside worker thread.

self.addEventListener( "message", function (event) { ...

});

2.40.1 Scope

1. Kony Platform version >= 5.6.2.

2. Support for JavaScript.

3. Supported mobile Platforms: a. iOS b. Android c. SPA: Supported List of browsers starting from versions.

4. Supported List of Browsers

Kony Studio API Developer's Guide

Version 3.1

SPA iOS

5.0-

5.1

Blackberry

10.0

4.4

Android

Native

DesktopWeb

10.0

Firefox Chrome Safari

4.0

20 5.0

33.0

Android

Chrome

Windows phone

5. Windows: a. Windows Phone 8 b. Windows Phone 8.1

c. Windows Kiosk d. Windows 8.1

2.40.2 Worker Thread APIs l

Introduction to Constructor

l hasWorkerThreadSupport l postMessage l

addEventListener

message event handler

Kony Studio API Developer's Guide

Version 3.1

error event handler

l removeEventListener l terminate l close l

Importing scripts

2.40.3 Introduction to Constructor - WorkerThread() l

The WorkerThread() constructor creates and returns the handle to the newly created worker thread. The new worker thread can be used by the Parent thread for any further communication with the worker thread.

To create a worker thread, it requires a JavaScript file name or a functional module name. The

WorkerThread() constructor is invoked with the JavaScript file or a functional module name as its only argument and a worker thread instance is then created and returned.

Worker threads may in turn initiate new worker threads.

If a Javascript file name with ".js" extension is passed as

WorkerThread() constructor argument, it looks up only in the

workerthreads

directory in

modules/js

path and loads if the file is found. This holds good for functional modules based projects as well as non-functional modules based projects.

If a function module name is provided as an argument for WorkerThread() constructor, in case of functional modules based project then the module will be loaded if found in the modules listing.

2.40.3.1 Worker Thread Life Cycle

The following steps provide the work flow to use worker thread:

Kony Studio API Developer's Guide

Version 3.1

1. Call to Worker constructor will create a new Worker instance and a new parallel execution environment context is created, and immediately starts execution in the new parallel thread of control in an asynchronous manner. In this new thread, first the Worker will try to load the

‘workerjs’ script.

2. As a result of the asynchronous parallel nature of execution in worker thread context, invocation of Worker constructor call in Parent thread will return a new Worker instance handle and Parent proceeds with execution of next instructions.

3. Every Worker thread will have its own event loop which takes care of the execution of all the received message tasks which are queued for this worker in that order until ‘self.close()’ in worker scope or ‘worker.terminate()’ in parent worker scope are invoked.

4. From the moment of successful creation of worker thread and until ‘self.close()’ in worker scope or ‘worker.terminate()’ in parent worker scope are invoked, the worker thread will be alive and can receive and process messages which are sent to this worker form its parent or from its child workers if created, as well as it can send messages using postMessage() to its parent thread and its child worker threads if created.

2.40.3.2 Example of Worker Thread

Here is an example for creating a WorkerThread: new kony.worker.WorkerThread(workerjs);

2.40.3.3 Input Parameters l workerjs [String] - Mandatory workerjs can be the name of javascript file name or functional module name which contains worker thread code.

Kony Studio API Developer's Guide

Version 3.1

2.40.3.4 Return Values

Object - kony.worker.WorkerThread

2.40.3.5 Exceptions

When an error is encountered, the KonyError JS object is thrown with the following information:

Error

Code

3001

Name

WorkerThreadError

Message

WorkerThread:

MissingMandatoryParameter.

Failed to construct

WorkerThread

3002 WorkerThreadError WorkerThread:

InvalidParameter. Invalid script name

Reason

If no argument is given to the constructor API, this exception is thrown and workerThread object is not created.

If workerjs argument is not a string, then this exception is thrown and workerThread object is not created.

If the script or module mentioned by workerjs argument is not found, and if an "error" event handler is registered for this worker object in Parent scope then it is invoked with an error

"event" object and its "message" attribute set to following.

message:"WorkerThread: InvalidParameter. WorkerThread script not found" o

In this error scenario no ‘KonyError’ exception will be raised.

Also the filename, lineno properties in the error event object for this error scenario have undefined values.

If multiple arguments are provided separated by a comma, the first argument is considered as the "workerjs" filename or module name and rest all are ignored.

Kony Studio API Developer's Guide

Version 3.1

2.40.3.6 Platform Availability

Available for iOS, Android, Windows, SPA, and Desktop Web. For more information, see

Scope

2.40.3.7 JavaScript Example try { var worker = new kony.worker.WorkerThread("worker1.js");

} catch (e) { var err = kony.getError(e);

}

} if (err instanceof KonyError) { kony.print("KonyError Catch : " + JSON.stringify(err));

2.40.4 message event handler

"message" event handler receives an "event" object which contains the JSON or string message that is passed to postMessage() during invocation and the same message can be accessed from its

"event.data" field. The data passed to postMessage() should be a String or JSON object.

Adhering to the JSON standard, the JSON object passed to postMessage() API should be serializable

JSON without opaque object handles or function object handles etc. The data which is passed between the parent thread and worker thread using postMessage() API are copied, not shared, so the end result is that a duplicate is created on each end.

Kony Studio API Developer's Guide

Version 3.1

Multiple "message" event handlers can also be registered in Parent scope and in workers inner scope and all the registered event handlers will be invoked in the registered order whenever a postMessage

() is called.

2.40.4.1 Signature

JavaScript : function(event) { });

2.40.4.2 Input Parameters

String / JSON Object l

"message" event handler receives an "event" object which contains the JSON or string message that is passed to postMessage() during invocation and the same message can be accessed from its "event.data" field.

The data passed to postMessage() should be a String or JSON object.

Adhering to the JSON standard, the JSON object passed to postMessage() API should be serializable JSON without opaque object handles or function object handles etc.

The data which is passed between the parent thread and worker thread using postMessage()

API are copied, not shared, so the end result is that a duplicate is created on each end.

2.40.4.3 Platform Availability

Available for iOS, Android, Windows, SPA, and Desktop Web. For more information, see

Scope

2.40.4.4 JavaScript Example var evtMessageHandler_1 = function(event) {

//In case of JSONkony.print ("Received message :" + event.data

["msg"]);"

Kony Studio API Developer's Guide

Version 3.1

//In case of string kony.print ("Received message :" + event.data);

};

2.40.5 error event handler

"error" event handler receives an "event" object which has the has the following three fields: message, filename, lineno. Registered ‘error’ event handler is invoked whenever an unhandled exception arises in worker’s scope. "error" event handler can be registered in parent thread scope on worker object and as well as in worker thread’s inner scope, where both event handlers will be invoked if present whenever an unhandled exception occurs in workers inner scope.

Multiple "error" event handlers can also be registered in Parent scope and in workers inner scope and all registered event handlers will be invoked in the registered order whenever an unhandled exception arises in worker’s scope.

2.40.5.1 Signature

JavaScript : function(event) { });

2.40.5.2 Input Parameters error event object (message, filename, lineno)

2.40.5.3 Platform Availability

Available for iOS, Android, Windows, SPA, and Desktop Web. For more information, see

Scope

2.40.5.4 JavaScript Example function(event) { kony.print ('ERROR: Line '+ event.lineno + ' in ' + event.filename

Kony Studio API Developer's Guide

Version 3.1

+ ': ' + event.message);

}

2.40.6 Importing scripts

Worker threads can use importScripts() function to import external scripts their scope by providing the

JS file name to import. This method takes one or more JavaScript file names to import.

This API is only available in worker thread scope and not in main parent thread scope.

In case of Functional modules based project " kony.modules.loadFunctionalModule()" API can be used to import a functional module into workers scope. Refer

Functional Modules

specification document for usage help on loadFunctionalModule() API.

importScripts() if invoked with .js file, looks up only in the "workerthreads" directory under "modules/js/" in Kony IDE Project structure to import scripts into workers scope. This holds good for both functional modules based projects and non-functional modules based projects.

In case of loading multiple files using importScripts(), if an error occurs while loading one of the script, then the remaining scripts are not loaded into context scope.

For more information on Functional Module APIs, refer

Functional Modules APIs

2.40.6.1 Signature

JavaScript

: importScripts(".js_file_name"); or

JavaScript : importScripts("functional_module_name");

Kony Studio API Developer's Guide

Version 3.1

2.40.6.2 Input Parameters

JSFileNames [Object] or

Functional_Module_Name [Object] l

One or more comma separated list of JavaScript file names.

2.40.6.3 Return Values

None

2.40.6.4 Exceptions

Note: If no argument is given, no exception is raised and it does nothing.

When an error is encountered, the KonyError JS object is thrown with the following information:

Error

Code

3002

Name

WorkerThreadError

Message

3002 WorkerThreadError importScripts:

InvalidParameter. Invalid script name importScripts:

InvalidParameter. Unable to import script. <scriptname>

Reason

This exception occurs when the argument passed is not a string.

This exception occurs when it is unable to find and load the JS script.

In worker scope, if these exceptions are not handled and if an error event handler is registered in worker’s inner scope or/and in parent scope for this worker object, then it is invoked with an error event object and its message attribute is set as follows:

Kony Studio API Developer's Guide

Version 3.1

Exception 1 - message: "importScripts: InvalidParameter. Invalid script name"

Exception 2 - message: "importScripts: InvalidParameter. Invalid script name"

Differences in behavior of importScripts() and

kony.modules.loadFunctionalModule()

API with respect to Functional Modules:

Without Functional Modules

From inside Worker context if importScripts() is used to import external JS scripts the search criteria would be : only "workerthreads" directory.

With Functional Modules

From inside Worker context if importScripts() is used to import external JS scripts the search criteria would be : only "workerthreads" directory.

kony.modules.loadFunctionalModule() function cannot be used in workers scope to load any

FunctionalModule.

kony.modules.loadFunctionalModule()

function can be used in workers scope to load any

JavaScript script which is part of some

Functional Module.

2.40.6.5 Platform Availability

Available for iOS, Android, Windows, SPA, and Desktop Web. For more information, see

Scope

2.40.6.6 JavaScript Example importScripts("Utility.js"); // loads Util.js

importScripts("Utility1.js", "Utility2.js", "Utility3.js");

2.40.7 Using Worker Threads Feature

The following topics helps you to use the worker thread feature:

Kony Studio API Developer's Guide

Version 3.1

Communicating and Data Processing Between Threads

Nesting of Threads and Performing Parallel Tasks

Scope Rules and Supported APIs

FFI and Custom Widgets

Guidelines and Limitations

Debugger Support

2.40.7.1 Communicating and Data Processing Between Threads

Main.js

//create new worker var worker = new kony.worker.WorkerThread('1_worker.js');

//invoked when worker calls postmessage() from its inner scope worker.addEventListener("message", function (event) { kony.print('Parent Scope : onmessage : event.data : ' + event.data["message"]);

}); kony.print('Parent Scope : Invoking worker.postmessage()');

//will invoke worker's inner scope onmessage() worker.postMessage({

'message': 'Hello World From Parent'

});

1_worker.js

//workers inner scope

//invoked when Parent calls worker.postmessage() self.addEventListener("message", function (event) {

Kony Studio API Developer's Guide

Version 3.1

kony.print('Worker Scope : onmessage : event.data : ' + event.data["message"]);

//call func do_something_in_worker();

}); function do_something_in_worker() { kony.print('Worker Scope : invoking postMessage()');

//will invoke Parent worker.onmessage() postMessage({

'message': "Hello World From Worker "

});

};

Expected Output

"Parent Scope: Invoking worker.postmessage()"

"Worker Scope: onmessage : event.data : " "Hello World From Parent"

"Worker Scope: invoking postMessage()"

"Parent Scope: onmessage : event.data : " "Hello World From Worker "

Explanation

1. In Parent Scope: Creates new worker using new kony.worker.WorkerThread ()

2. In Parent Scope: Call to worker.postMessage() invokes message event handler registered using addEventListener() in worker threads inner scope.

3. In Worker Scope: Call to postMessage() invokes message event handler registered using addEventListener() in the parent thread scope.

Kony Studio API Developer's Guide

Version 3.1

2.40.7.2 Nesting of Threads and Performing Parallel Tasks

Main.js

try { kony.print("Parent Scope: Init test_case_parent_thread()"); kony.print("Parent Scope: In try block");

//create new kony.worker.WorkerThread

var worker = new kony.worker.WorkerThread('WorkerThread.js');

//invoked when worker calls postmessage() from its inner scope worker.addEventListener("message", function (event) { kony.print('Parent Scope : onmessage : event.data : ' + event.data);

}); worker.postMessage("Hello from Parent");

} catch (err) { kony.print("Parent Scope: In Catch block");

}

//invoke a function invoke_timer_task();

// function invoke_timer_task() { kony.print("Parent Scope :- kony.timer.schedule - "); var timerId = "mytimer12111"; var i = 0;

Kony Studio API Developer's Guide

Version 3.1

function timerFunc() { i++; kony.print("Parent Scope :- kony.timer.schedule - In timerFunc() : " + i); if (i > 20) { kony.print("Parent Scope :- kony.timer.schedule -

Stopping timer : "); kony.timer.cancel(timerId);

}

};

// kony.timer.schedule(timerId, timerFunc, 1, true); kony.print("Parent Scope :- kony.timer.schedule - Done");

}; kony.print("Parent Scope: Exit test_case_parent_thread()");

WorkerThread.js

//worker

//workers inner scope kony.print("Worker Scope: Init"); var worker = new kony.worker.WorkerThread('WorkerThread2.js');

//invoked when Parent calls worker.postmessage() this.addEventListener("message", function(event) { kony.print('Worker Scope : onmessage : event.data : ' + event.data);

});

Kony Studio API Developer's Guide

Version 3.1

self.postMessage("Hello from Worker");

// invoke_timer_task();

// function invoke_timer_task() { kony.print("Worker Scope :- kony.timer.schedule - "); var timerId = "mytimer121"; var i = 0; function timerFunc() { i++; kony.print("Worker Scope :- kony.timer.schedule - In timerFunc() : " + i); if(i > 20) { kony.print("Worker Scope :- kony.timer.schedule -

Stopping timer : "); kony.timer.cancel(timerId);

}

};

// kony.timer.schedule(timerId,timerFunc, 1, true); kony.print("Worker Scope :- kony.timer.schedule - Done");

}; kony.print("Worker Scope: Loading done");

Kony Studio API Developer's Guide

Version 3.1

WorkerThread2.js

//Grand child worker2 – nested worker

//workers inner scope kony.print("Grand child: Worker2 Scope: Init");

//invoked when Parent calls worker.postmessage() this.addEventListener("message", function(event) { kony.print('Grand child: Worker2 Scope : onmessage : event.data : '

+ event.data);

}); self.postMessage("Hello from Worker2");

// invoke_timer_task();

// function invoke_timer_task () { kony.print("Grand child: Worker2 Scope :- kony.timer.schedule -

"); var timerId = "mytimer1211"; var i = 0; function timerFunc()

{ i++; kony.print("Worker2 Scope :- kony.timer.schedule - In timerFunc() : " + i + " : Grand child "); if(i > 20) { kony.print("Grand child: Worker2 Scope :-

Kony Studio API Developer's Guide

Version 3.1

kony.timer.schedule - Stopping timer : "); kony.timer.cancel(timerId);

}

};

// kony.timer.schedule(timerId,timerFunc, 1, true); kony.print("Grand child: Worker2 Scope :- kony.timer.schedule -

Done");

}; kony.print("Grand child: Worker2 Scope : Loading done");

2.40.7.3 Scope Rules and Supported APIs

Global resources in the App context will not be available in the worker thread context as it can lead to

Race conditions since no locking mechanisms are provided.

Every worker has its own context of execution, which is not shared between the parent and its worker.

As a result the global variables in parent scope are not available in worker scope and vice versa.

Not

Supp orted

APIs l

Kony UI APIs and UI object handles l

App Global variables

Kony Studio API Developer's Guide

Version 3.1

Supp orted

APIs and

Platfo rm

String

API

Math

API

Table

API

Standar d Kony

API

Networ k API

Cryptog raphy

API iO

S iO

Offline

Data

Access

API

Lo cal

Sto rag e

Operati ng

System

API

We b

L iO

S iO

An dro id iO

An dro id

Win dow s

SPA

Desktop

Web

Desktop

Web

Desktop

Web

Win dow s

Andr oid

Limited Availability

* For SPA and Desktop Web, the following APIs are supported: l kony.convertToBase64

l kony.convertToRawByte

s l kony.type

l kony.props.getProperty

l kony.print() is not supported in Safari.

Kony.print() is supported in Mozilla from version

29.0.

For SPA and DesktopWeb:

Limited Availability n

The following API will not be available in SPA &

Desktop Web.

kony.net.setNetworkCall

backs

199 of 838

Windows

Andr oid

Windows

Win dow s

An dro id

Win dow s

SPA and

DesktopWeb

* For SPA and Desktop Web, the following APIs are NOT supported: l kony.os.addHiddenField

l kony.os.readHiddenField

l kony.os.startSecureTran

saction l kony.os.endSecureTrans

action l kony.os.getAppContext

l kony.os.hasAcceleromet

erSupport l kony.os.deviceInfo

l kony.os.deviceInfo

().httpheaders

l kony.os.addMetaTag

l kony.os.removeMetaTag

l kony.os.removeAllMetaT

ags l kony.os.hasGPSSupport

l kony.os.hasCameraSupp

ort l kony.os.hasTouchSuppor

t l kony.os.hasOrientationS

upport l kony.os.getDeviceCurren

tOrientation l kony.os.print

* For SPA and Desktop Web, the following APIs are NOT supported: l kony.crypto.saveKey

l kony.crypto.deleteKey

l kony.crypto.readKey

Kony Studio API Developer's Guide

Version 3.1

2.40.7.4 FFI and Custom Widgets

With and without Functional Module in Worker context:

FFI

Custom Widgets iOS Android

Platform will load modules by default

Windows

No need to load Custom Widgets in worker scope.

SPA

2.40.7.5 Guidelines and Limitations

The following guidelines are recommended before using worker thread:

1. The objects "this" and "self" are available in worker thread inner scope that is referred as worker thread itself.

2. Event propagation cannot be stopped by using event.stopPropagation() as in HTML specification. Where event.stopPropagation() stops the DOM event to be propagated further by breaking the event chain.

3. Data passed between the main thread and workers are copied, but not shared. Objects are serialized as they are handed to the worker, and subsequently, de-serialized on the other end.

The main thread and worker do not share the same instance. So the end result is that a duplicate is created on each end. HTML5 worker threads support transferable objects that allow transferring the objects from one thread to other without making a copy.

4. As explicit thread synchronization mechanisms like locking or mutexes are not available in JS environment, you must take required care in scenarios where multiple threads concurrently or simultaneously are trying to access and write/insert data into local database or local datastore using WebSQL or Local datastore APIs, as these are shared resources across the Application context.

Kony Studio API Developer's Guide

Version 3.1

The outcome of these simultaneous or concurrent accesses to database/datastore might push the database/datastore to inconsistent state and is dependent on the individual platforms WebSQL or DataStore implementations. It is always suggested to avoid such scenarios of multiple threads accessing the database/datastore simultaneously/concurrently.

Limitations in SPA and DesktopWeb:

1. Nested Workers support will be available only if they are supported by the underlying browser platforms.

2. Error event messages in error event handler sometimes might be appended with extra prefix or suffix string messages from underlying browsers (like Uncaught, Uncaught error etc).

3. Even though error event handler is invoked in case of unhandled exceptions, the same event messages might also be logged on browser console.

4. Line number, file name populated in error event object passed to error event handler might be different from user defined files.

Note: For SPA and Desktop Web, nested workers are not supported in Google Chrome.

terminate API

As the worker threading model is mapped to underlying native threading models in native platforms, there can be some deviations from what specification says, this is due to technical limitations in the underlying platforms which include:

1. If terminate() is invoked in Parent thread on worker, and if worker is currently executing a large task, it might not immediately terminate, it will continue to execute the task to completion and terminate.

2. If terminate() is invoked in Parent thread on worker, and if there are pending tasks waiting in the message queues for this worker to perform, some platforms might discard all the pending tasks

Kony Studio API Developer's Guide

Version 3.1

without accepting them for execution and terminate, and on some platform all the pending tasks are executed to completion and then the worker terminates.

3. It is to be noted that to achieve cross platform consistency, it is always advised that terminate() be invoked on the worker once all the tasks in message queues are completed.

close API

1. As the worker threading model is mapped to underlying native threading models in native platforms, there can be some deviations from what specification says, this is due to technical limitations in the underlying platforms which include:

2. When close() is invoked in worker scope, and if worker is currently executing a large task, it might not immediately terminate, it will continue to execute the task to completion and then terminate.

3. When close () is invoked in worker scope, and if there are pending tasks waiting in the message queues for this worker to perform, some platforms might discard all the pending tasks without accepting them for execution and terminate, and on some platform all the pending tasks are executed to completion and then the worker terminates.

4. Hence it is to be noted that to achieve cross platform consistency, it is always advised that close

() be invoked in worker scope once all the tasks in message queues are completed.

2.40.7.6 Debugger Support

Debugger support for worker threads is not available in 5.6.2 release.

2.40.7.7 Worker Life Cycle Notes

Following are some worker life cycle notes: l

Call to Worker constructor will create a new Worker instance and a new parallel execution environment context is created, and immediately starts execution in the new parallel thread of control in an asynchronous manner. In this new thread, first the Worker will try to load the

‘workerjs’ script.

Kony Studio API Developer's Guide

Version 3.1

As a result of the asynchronous parallel nature of execution in worker thread context, invocation of Worker constructor call in Parent thread will return a new Worker instance handle and Parent proceeds with execution of next instructions.

Every Worker thread will have its own event loop which takes care of the execution of all the received message tasks which are queued for this worker in that order until ‘self.close()’ in worker scope or ‘worker.terminate()’ in parent worker scope are invoked.

From the moment of successful creation of worker thread and until ‘self.close()’ in worker scope or ‘worker.terminate()’ in parent worker scope are invoked, the worker thread will be alive and can receive and process messages which are sent to this worker form its parent or from its child workers if created, as well as it can send messages using postMessage() to its parent thread and its child worker threads if created.

In worker thread scope when there is no "message" event handler registered which indicates that no tasks can be posted or queued by parent for this worker, and if no callbacks are registered in this worker scope for network, timer APIs etc, then after postMessage() call in

Workers inner scope if any, worker can terminate itself without worker.terminate() being called in Parent scope or self.close() called in inner scope.

In case of orphaned threads if no tasks are queued in message handler and if the worker is not waiting for any callbacks to be returned from network, timer APIs etc then the orphaned thread can be terminated.

If Parent stops either due to unhandled exception raised in it scope, Worker threads still continues to exist and execute.

Kony Studio API Developer's Guide

Version 3.1

2.40.7.8 Worker Thread

Worker threads are used to execute events simultaneously. Worker thread can take advantage of multiprocessor environments and to keep responsive UI thread in the application (by delegating or offloading work, which need not be handled in the main thread).

Sharing data between parent thread and worker threads is done through message passing and by default variables, functions, or state is not shared.

The current specification is inspired from and based on HTML5 Web Worker threads standard, that use

Message Passing model or mechanism for communication between threads.

Message Passing model based threads need proper communication constructs and protocol to be defined for data passing and also can consume more CPU cycles and memory because of local copies, and can have an impact on application performance if huge data needs to be transferred. Also, proper scoping rules need to be specified for access control of Shared or Global resources within the application context.

The following topics helps you to use the worker thread feature: l

Communicating and Data Processing Between Threads

Nesting of Threads and Performing Parallel Tasks

Scope Rules and Supported APIs

FFI and Custom Widgets

Kony Studio API Developer's Guide

Version 3.1

Guidelines and Limitations

Worker Thread Life Cycle

Communicating and Data Processing Between Threads

Main.js

//create new worker var worker = new kony.worker.WorkerThread('1_worker.js');

//invoked when worker calls postmessage() from its inner scope worker.addEventListener("message", function (event) { kony.print('Parent Scope : onmessage : event.data : ' + event.data["message"]);

}); kony.print('Parent Scope : Invoking worker.postmessage()');

//will invoke worker's inner scope onmessage() worker.postMessage({

'message': 'Hello World From Parent'

});

1_worker.js

//workers inner scope

//invoked when Parent calls worker.postmessage() self.addEventListener("message", function (event) { kony.print('Worker Scope : onmessage : event.data : ' + event.data["message"]);

//call func do_something_in_worker();

});

Kony Studio API Developer's Guide

Version 3.1

function do_something_in_worker() { kony.print('Worker Scope : invoking postMessage()');

//will invoke Parent worker.onmessage() postMessage({

'message': "Hello World From Worker "

});

};

Expected Output

"Parent Scope: Invoking worker.postmessage()"

"Worker Scope: onmessage : event.data : " "Hello World From Parent"

"Worker Scope: invoking postMessage()"

"Parent Scope: onmessage : event.data : " "Hello World From Worker "

Explanation

1. In Parent Scope: Creates new worker using new kony.worker.WorkerThread ()

2. In Parent Scope: Call to worker.postMessage() invokes message event handler registered using addEventListener() in worker threads inner scope.

3. In Worker Scope: Call to postMessage() invokes message event handler registered using addEventListener() in the parent thread scope.

Nesting of Threads and Performing Parallel Tasks

Main.js

try { kony.print("Parent Scope: Init test_case_parent_thread()"); kony.print("Parent Scope: In try block");

//create new kony.worker.WorkerThread

Kony Studio API Developer's Guide

Version 3.1

var worker = new kony.worker.WorkerThread('WorkerThread.js');

//invoked when worker calls postmessage() from its inner scope worker.addEventListener("message", function (event) { kony.print('Parent Scope : onmessage : event.data : ' + event.data);

}); worker.postMessage("Hello from Parent");

} catch (err) { kony.print("Parent Scope: In Catch block");

}

//invoke a function invoke_timer_task();

// function invoke_timer_task() { kony.print("Parent Scope :- kony.timer.schedule - "); var timerId = "mytimer12111"; var i = 0; function timerFunc() { i++; kony.print("Parent Scope :- kony.timer.schedule - In timerFunc() : " + i); if (i > 20) { kony.print("Parent Scope :- kony.timer.schedule -

Stopping timer : ");

Kony Studio API Developer's Guide

Version 3.1

kony.timer.cancel(timerId);

};

}

// kony.timer.schedule(timerId, timerFunc, 1, true); kony.print("Parent Scope :- kony.timer.schedule - Done");

}; kony.print("Parent Scope: Exit test_case_parent_thread()");

WorkerThread.js

//worker

//workers inner scope kony.print("Worker Scope: Init"); var worker = new kony.worker.WorkerThread('WorkerThread2.js');

//invoked when Parent calls worker.postmessage() this.addEventListener("message", function(event) { kony.print('Worker Scope : onmessage : event.data : ' + event.data);

}); self.postMessage("Hello from Worker");

// invoke_timer_task();

// function invoke_timer_task() { kony.print("Worker Scope :- kony.timer.schedule - ");

Kony Studio API Developer's Guide

Version 3.1

var timerId = "mytimer121"; var i = 0; function timerFunc() { i++; kony.print("Worker Scope :- kony.timer.schedule - In timerFunc() : " + i); if(i > 20) { kony.print("Worker Scope :- kony.timer.schedule -

Stopping timer : "); kony.timer.cancel(timerId);

}

};

// kony.timer.schedule(timerId,timerFunc, 1, true); kony.print("Worker Scope :- kony.timer.schedule - Done");

}; kony.print("Worker Scope: Loading done");

WorkerThread2.js

//Grand child worker2 – nested worker

//workers inner scope kony.print("Grand child: Worker2 Scope: Init");

//invoked when Parent calls worker.postmessage() this.addEventListener("message", function(event) { kony.print('Grand child: Worker2 Scope : onmessage : event.data : '

+ event.data);

Kony Studio API Developer's Guide

Version 3.1

}); self.postMessage("Hello from Worker2");

// invoke_timer_task();

// function invoke_timer_task () { kony.print("Grand child: Worker2 Scope :- kony.timer.schedule -

"); var timerId = "mytimer1211"; var i = 0; function timerFunc()

{ i++; kony.print("Worker2 Scope :- kony.timer.schedule - In timerFunc() : " + i + " : Grand child "); if(i > 20) { kony.print("Grand child: Worker2 Scope :kony.timer.schedule - Stopping timer : "); kony.timer.cancel(timerId);

}

};

// kony.timer.schedule(timerId,timerFunc, 1, true); kony.print("Grand child: Worker2 Scope :- kony.timer.schedule -

Done");

}; kony.print("Grand child: Worker2 Scope : Loading done");

Kony Studio API Developer's Guide

Version 3.1

Scope Rules and Supported APIs

Global resources in the App context will not be available in the worker thread context as it can lead to

Race conditions since no locking mechanisms are provided.

Every worker has its own context of execution, which is not shared between the parent and its worker.

As a result the global variables in parent scope are not available in worker scope and vice versa.

Not

Supp orted

APIs l

Kony UI APIs and UI object handles l

App Global variables

Kony Studio API Developer's Guide

Version 3.1

Supp orted

APIs and

Platfo rm

String

API

Math

API

Table

API

Standar d Kony

API

Networ k API iO

Offline

Data

Access

API

Lo cal

Sto rag e

Operati ng

System

API

We b

L iO

S iO

An dro id

Cryptog raphy

API iO

S iO

An dro id

Win dow s

SPA

Desktop

Web

Desktop

Web

Desktop

Web

Win dow s

Andr oid

Limited Availability

* For SPA and Desktop Web, the following APIs are supported: l kony.convertToBase64

l kony.convertToRawByte

s l kony.type

l kony.props.getProperty

l kony.print() is not supported in Safari.

Kony.print() is supported in Mozilla from version

29.0.

For SPA and DesktopWeb:

Limited Availability n

The following API will not be available in SPA &

Desktop Web.

kony.net.setNetworkCall

backs

212 of 838

Windows

An dro id

Andr oid

Win dow s

Windows SPA and

Desktop

Web not supported

* For SPA and Desktop Web, the following APIs are NOT supported: l kony.os.addHiddenField

l kony.os.readHiddenField

l kony.os.startSecureTran

saction l kony.os.endSecureTrans

action l kony.os.getAppContext

l kony.os.hasAcceleromet

erSupport l kony.os.deviceInfo

l kony.os.deviceInfo

().httpheaders

l kony.os.addMetaTag

l kony.os.removeMetaTag

l kony.os.removeAllMetaT

ags l kony.os.hasGPSSupport

l kony.os.hasCameraSupp

ort l kony.os.hasTouchSuppor

t l kony.os.hasOrientationS

upport l kony.os.getDeviceCurren

tOrientation l kony.os.print

* For SPA and Desktop Web, the following APIs are NOT supported: l kony.crypto.saveKey

l kony.crypto.deleteKey

l kony.crypto.readKey

Kony Studio API Developer's Guide

Version 3.1

Supported List of Browsers

SPA iOS

5.0-

5.1

Blackberry

7.0

4.4

Android

Native

DesktopWeb

10.0

Firefox Chrome Safari

4.0

20 5.0

33.0

Android

Chrome

FFI and Custom Widgets

With and without Functional Module in Worker context:

FFI

Custom Widgets iOS Android

Platform will load modules by default

Windows

No need to load Custom Widgets in worker scope.

Windows phone

SPA

Guidelines and Limitations

The following guidelines are recommended before using worker thread:

1. The objects “this” and “self” are available in worker thread inner scope that is referred as worker thread itself.

Kony Studio API Developer's Guide

Version 3.1

3. Data passed between the main thread and workers are copied, but not shared. Objects are serialized as they are handed to the worker, and subsequently, de-serialized on the other end.

Guidelines for SPA and DesktopWeb:

1. Nested Workers support will be available only if they are supported by the underlying browser platforms.

2. Error event messages in error event handler sometimes might be appended with extra prefix or suffix string messages from underlying browsers (like Uncaught, Uncaught error etc).

3. Even though error event handler is invoked in case of unhandled exceptions, the same event messages might also be logged on browser console.

4. Line number, file name populated in error event object passed to error event handler might be different from user defined files.

Note: For SPA and Desktop Web, nested workers are not supported in Google Chrome.

Worker Thread Life Cycle

The following steps provide the work flow to use worker thread:

1. Create a new worker instance (by calling the worker thread constructor). The new instance starts executing in a separate thread of control in an asynchronous manner. In this new thread, first the worker will try to load the ‘workerjs’ script.

Kony Studio API Developer's Guide

Version 3.1

2. As a result of the asynchronous nature of execution of worker thread, invocation of worker constructor call in parent thread will immediately return a new worker instance handle and parent proceeds execution of next instructions.

3. In worker thread scope when there is no message event handler registered that indicates no tasks can be posted or queued by parent for this worker, and if no callbacks are registered in this worker scope for network, timer APIs etc, then after postMessage() call in workers inner scope, worker can terminate itself without worker.terminate() being called in parent scope or self.close

() called in inner scope.

4. In case of orphaned threads, if no tasks are queued in message handler and if the worker is not waiting for any callbacks to be returned from network, timer APIs etc then the orphaned thread can be terminated.

5. If parent stops either due to unhandled exception raised in its scope, worker threads still continue to exist and execute.

Kony Studio API Developer's Guide

Version 3.1

2.41 Appendix: General FAQ

This appendix explains a few frequently asked questions (FAQs).

2.41.1 Network Calls

Can I cancel synchronous network calls?

Canceling synchronous network calls in not a cross platform feature. Platforms like iPhone and

BlackBerry provide a means of canceling synchronous network calls, which is very specific to those platforms.

For example, on iPhone, the developer can choose to show the Cancellation popup. If this option is available, the cancel option pops up from the bottom of the screen allowing the developer to cancel the synchronous service call.

Can I handle the logic that needs to be executed when a synchronous network call is canceled?

Yes. When a network call is canceled, an error is thrown with opstatus 1021. Because cancellation of synchronous calls is not cross platform, ensure that any logic that is written to handle 1021 opstatus does not have any business logic but displays a proper message to the user.

Is blocking the UI still an option that I can choose while making a synchronous network call?

The isBlocking parameter is not considered by platforms (except for iPhone). Only way to block the user interface is by explicitly using

showLoadingScreen

API supported by Kony Platform.

What is the advantage of asynchronous network calls compared to the synchronous network calls?

Any network call goes through the following phases:

1. Phase 1: preparing network request

2. Phase 2: making a network connection and wait for response

Kony Studio API Developer's Guide

Version 3.1

3. Phase 3: handle the returned response.

In case of synchronous calls, user clicks and touches on any widget of the form are ignored until network call finishes all the three phases. In case of asynchronous network calls, users can execute any logic while the network is busy waiting for the response.

Phase 1 and Phase 2 are handled by Kony Platform and Phase 3 a callback function is executed (the function that is passed to the asynchronous network call).

What are the important considerations for using Asynchronous network calls?

Kony Platform runs all the functions attached to the widgets and the callback for asynchronous network call in a single thread except for some of the system events.

The callback function is queued if any of the functions are in execution. This may lead to the order of execution issues.

Because the user can execute any other functions while waiting for the response of the network call, this may lead to the order of execution issues.

For example, user is performing account deletion logic by invoking a network call asynchronously.

During the same time, user may end up updating the same account by executing another network call or a function. This could lead to erroneous data.

For example, user is performing the retrieval of accounts through asynchronous network call and if the user moves to the functionality that depends on the availability of the accounts, then application should display the appropriate message or block the UI till account retrieval is completed.

When to use asynchronous network calls?

In general, asynchronous calls should be preferred over synchronous calls in all situations. However, user should be aware that order of execution issues may creep in and handle such situations.

When you want to make network calls as part of the following events, use asynchronous network calls: l pre-appinit

Kony Studio API Developer's Guide

Version 3.1

l post-appinit l transactionalDataLoad l onIdleTimeout l onBackground l onForeground l appmenuevents.

How to handle error codes thrown by the network calls?

Define handlers for all the error codes including the generic error code. If a particular platform cannot distinguish an error case specifically, the platform throws a generic error.

Can I click/touch the widgets on a form and trigger an action when a function is getting executed?

No. As explained earlier, because executing the logic corresponding to touches/gestures on the form is run in a single thread.

Are the asynchronous callbacks (associated with asynchronous network call) executed when a function is under execution?

Yes. All Asynchronous callbacks are queued and executed on the main thread. Hence the callbacks are always guaranteed for execution when the current thread completes its current job.

Can I control the timeout of a network call?

No. Kony Platform does not support changing the timeout period. The default timeout period is 3 minutes.

Can I make the network calls outside the Kony Application Server?

No. Kony Platform does not support making network calls outside the Kony Application Server.

Kony Studio API Developer's Guide

Version 3.1

Are the network calls authenticated against the Kony Application Server?

Yes. The basic form based authentication is used between devices and the Kony Application Server.

The relevant authentication headers are added to the application code in a transparent way.

Can the platform support un-trusted certificates when making HTTPS network calls ?

Apple does not allow usage of the private APIs (used to support un-trusted certificates) in the applications as part of application certification process. In platforms like Android, though there are ways to allow un-trusted certificates it is not guaranteed across the family of Android devices. Using un-trusted certificates also leads to security issues. Hence, on Kony Platform use of valid and trusted certificates is mandatory for secure (HTTPS) communication.

What are the certificates that are treated as trusted and work cross-platform?

iPhone http://support.apple.com/kb/HT3580 http://support.apple.com/kb/HT4415 .

Android

Only the certificates issued by CA that are bundled with the application.

BlackBerry

All the certificates installed on the device. Navigate to Options -> Security -> Advanced

Security Settings -> Certificates to see the installed certificates.

Windows Phone l

America Online Root Certification Authority 2 l

America Online Root Certification Authority 1 l

COMODO RSA Certification Authority

Kony Studio API Developer's Guide

Version 3.1

USERTrust RSA Certification Authority l

COMODO ECC Certification Authority l

USERTrust ECC Certification Authority l

UTN-USERFirst-Hardware l

UTN - DATACorp SGC l

AddTrust External CA Root l

DigiCert Assured ID Root CA l

DigiCert High Assurance EV Root CA l

DigiCert Global Root CA.

For more certificates, see http://www.microsoft.com

For uniform cross-platform behavior, select a trusted root certificate which works across the devices.

How do I disable the widgets (such as text box, text area) or the complete form while a network call is in progress ?

You have the following options: l

Use the window.showloadingscreen API to block the UI while the network call is in progress.

Use widget.setenabled method to disable the widgets one after the other. But in this approach, you must remember to enable the widgets after the completion of the network call.

Kony Studio API Developer's Guide

Version 3.1

2.41.2 form.destroy API

When I invoke form.destroy API, will I lose the widgets and data associated with the widgets also?

Yes. When

form.destroy

is invoked, complete form along with its widgets and data associated with the widgets will be lost. It is the developer's responsibility to save any critical, easily nonreproducible data using

ds.save

before invoking

form.destroy

API.

Can I access the form that was destroyed?

Yes. If you access the form that was destroyed, either by calling form.show or by accessing the widgets on the form or by accessing the properties of the form, the form will undergo through the entire form lifecycle.

Kony Studio API Developer's Guide

Version 3.1

2.42 Appendix: JavaScript FAQ

Can I use the standard JavaScript features like prototypes, "this", function semantics, or do I have to use a "restricted JavaScript"?

Yes, the JavaScript runtime environment embedded by the Kony platform is ECMA 262 compliant. So all the standard JavaScript features are available out of the box. All the custom Functions and Objects defined by the developer have access to standard JavaScript features. Though the JavaScript

Objects/Functions created/defined by the Kony APIs adhere to this specification there are some known limitations that one must be aware of. These limitations mostly arise from the limitations posed by the JavaScript runtime environment when invoking native SDK APIs (defined in a different language). These limitations have been captured under the sections " JavaScript Function Semantics " and " JavaScript Object Semantics ".

What are the different JavaScript runtime environments that Kony platform bundles for each of the Mobile platforms?

iOS

Platform

Android

BlackBerry

MobileWeb

SPA

Windows Phone

Windows

Desktop

Supported Version

4.0 and above

2.1 and above

5.0 and above

All iOS,Android,BlackBerry,Windows

7.5

7.5 and above

Coming soon

JavaScript Engine

JS Core

Google V8 (via NDK)

Native BrowserField

---

JS engine embedded in the browser

Jurassic

Coming soon

Kony Studio API Developer's Guide

Version 3.1

Are there any JavaScript constraints or cross platform nuances that I should be aware of when developing on Kony platform ?

Yes, even though Kony platform bundles or uses widely used JavaScript runtime environment, there are some JavaScript APIs that don't work consistently across the JavaScript runtime environments.

Below are some of the JavaScript operators and semantics that can result in inconsistent experience across runtimes and should be avoided: l typeof operator for the Objects created and returned by the Kony APIs l instanceof operator for the Objects created and returned by the Kony APIs

I like that Kony now supports JavaScript. Can I pick a JavaScript based 3rd party library and include it in my project codebase ?

Yes, you can integrate any Javascript library which is purely written in Javascript language without any native, browser dependencies. In case the JavaScript library depends upon a browser DOM then it would only work on the SPA channel.

I see some of the widgets like Form and Image have got a "2" as suffix when creating the widget.

For instance, when creating the form we have to say com.kony.ui.Form2. Why do we need to have "2" as suffix for these widgets ?

When drafting the specifications for the JavaScript APIs there was a conscious effort to ensure common cross platform behavior of some of the widgets. We realized that unless we break some backward compatibility the widget behavior cannot be made consistent across platforms. Hence Kony came with new API definitions for these widgets with the intention to consolidate the cross platform behavior. A version "2" of these widgets was introduced.

So in general is it recommended to use kony.ui.Image2 or kony.ui.Image, should I use the version "2" of the widgets or their original version ?

For better cross platform behavior we recommend you to use the kony.ui.Image2 widget wherever possible. The original version of the widgets have been retained only for backward compatibility.

Kony Studio API Developer's Guide

Version 3.1

Can I use Octal literals in my JavaScript Code?

Octal literals should be avoided in JavaScript Code. Numbers prefixed with 0 will be treated as octal numbers by most of the Javascript Engines but some throw an exception. If you want to parse the octal number from a string variable, use parseInt with radix parameter.

Kony Studio API Developer's Guide

Version 3.1

2.43 Appendix: SQLite

SQLite is a database engine packaged along with the native sdk. This section comprises the following: l

SQLite characteristics

SQLite Column Types

Type Affinity

Determination of Column Affinity

Affinity Name JavaScript Example

Column Affinity Behavior JavaScript Example

2.43.1 SQLite Characteristics

SQLite has the following characteristics: l

It is embedded with the native sdk.

It is ACID-compliant (atomicity, consistency, isolation, durability).

It is weakly-typed i.e, any object can be stored in any column, regardless of how that column was declared. For example you can insert a string into a database column of type integer l

It does not officially support foreign key constraints, although triggers can be used as a workaround.

It does not support RIGHT OUTER JOINs.

2.43.2 SQLite Column Types

Most databases use strong, static column typing which means that the elements of a column can only hold values compatible with the defined type of a column. SQLite utilizes a dynamic typing technique known as manifest typing. For each row value, manifest typing records the value's type along with the

Kony Studio API Developer's Guide

Version 3.1

value data. This allows nearly any element of any row to hold almost any type of value. In the strictest sense, SQLite supports only five concrete datatypes. These are known as storage classes, and represent the different ways SQLite stores data on disk.

Every value has one of these five native storage classes: l

NULL: NULL is considered its own distinct type. A NULL type does not hold a value. Literal

NULLs are represented by the keyword NULL.

Integer: A signed integer number. Integer values are variable length, being 1, 2, 3, 4, 6, or 8 bytes in length, depending on the minimum size required to hold the specific value. Integer have a range of 9,223,372,036,854,775,808 to +9,223,372, 036,854,775,807, or roughly 19 digits.

Literal integers are represented by any bare series of numeric digits (without commas) that does not include a decimal point or exponent.

REAL: The value is a floating-point number, stored as an 8-byte value in the processor's native format. For most modern processors, this is an IEEE 754 double-precision number. Literal floating-point numbers are represented by any bare series of numeric digits that include a decimal point or exponent.

Text: A variable-length string, stored using the database encoding (UTF-8, UTF-16BE, or UTF-

16LE). Literal text values are represented using character strings in single quotes.

BLOB: A length of raw bytes, copied exactly as provided. Literal BLOBs are represented as hexadecimal text strings preceded by an x. For example, the notation x'1234ABCD' represents a 4-byte BLOB. BLOB stands for Binary Large OBject. SQLite text and BLOB values are always variable length. The maximum size of a text or BLOB value is limited by a compile-time directive.

The default limit is exactly one billion bytes, or slightly less than a full gigabyte. The maximum value for this directive is two gigabytes.

2.43.3 Type Affinity

The elements of most columns can hold any value type, the "type" of a column could be misleading.

Rather than being an absolute type,like most databases, an SQLite column type (as defined in

CREATE TABLE) becomes more of a suggestion than a hard and fast rule. This is known as type affinity, and essentially represents a desired category of type. Each type affinity has specific rules

Kony Studio API Developer's Guide

Version 3.1

about what types of values it can store, and how different values will be converted when stored in that column. Generally, type affinity will cause conversion or migration of types only if it can be done without losing data or precision.

Each table column must have one of five type affinities: l

Text: A column with a text affinity will only store values of type NULL, text, or BLOB. If you attempt to store a value with a numeric type (float or integer) it will be converted into a text representation before being stored as a text value type.

Numeric: A column with a numeric affinity will store any of the five types. Values with integer and float types, along with NULL and BLOB types, are stored without conversion. Any time a value with a text type is stored, an attempt is made to convert the value to a numeric type

(integer or float). Assuming the conversion works, the value is stored in an appropriate numeric type. If the conversion fails, the text value is stored without any type of conversion.

Integer: A column with an integer affinity works essentially the same as a numeric affinity. The only difference is that any value with a float type that lacks a fractional component will be converted into an integer type.

Real: A column with REAL affinity behaves like a column with NUMERIC affinity except that it forces integer values into floating point representation.

None: A column with a none affinity has no preference over storage class. Each value is stored as the type provided, with no attempt to convert anything.

2.43.4 Determination Of Column Affinity

Since type affinities are not part of the SQL standard, SQLite has a series of rules that attempt to map traditional column types to the most logical type affinity. The type affinity of a column is determined by the declared type of the column, according to the following rules (substring matches are caseinsensitive):

1. If no column type was given, then the column is given the none affinity.

2. If the column type contains the substring "INT," then the column is given the integer affinity.

Kony Studio API Developer's Guide

Version 3.1

3. If the column type contains any of the substrings "CHAR," "CLOB," or "TEXT," then the column is given the text affinity.

4. If the column type contains the substring "BLOB," then the column is given the none affinity.

5. If the column type contains any of the substrings "REAL," "FLOA," or "DOUB," then it is given the float real affinity.

6. If no match is found, the column is assigned the numeric affinity.

As implied by the first rule, the column type is completely Optional. SQLite will allow you to create a table by simply naming the columns, such as CREATE TABLE t ( i, j,k);. You'll also notice that there isn't any specific list of column types that are recognized. You can use any column type you want, even making up your own names. This might sound a bit fast and loose for a typing system, but it works out quite well. By keying off specific substrings, rather than trying to define specific types, SQLite is able to handle SQL statements (and their database-specific types) from just about any database, all while doing a pretty good job of mapping the types to an appropriate affinity. Note that a declared type of

"FLOATING POINT" would give INTEGER affinity, not REAL affinity, due to the "INT" at the end of

"POINT". And the declared type of "STRING" has an affinity of NUMERIC, not TEXT.

2.43.5 Affinity Name Example

The following table shows how many common datatype names from more traditional SQL implementations are converted into affinities by the six rules of the previous section.

JavaScript Example Typenames From The CREATE

TABLE Statement or CAST Expression

Resulting

Affinity

INT, INTEGER, TINYINT, SMALLINT, MEDIUMINT, BIGINT,

UNSIGNED BIG INT, INT2, INT8

INTEGER 2

Rule Used

Determine

Affinity

Kony Studio API Developer's Guide

Version 3.1

JavaScript Example Typenames From The CREATE

TABLE Statement or CAST Expression

Resulting

Affinity

TEXT 3

Rule Used

Determine

Affinity

CHARACTER(20), VARCHAR(255), VARYING CHARACTER

(255), NCHAR(55), NATIVE CHARACTER(70), NVARCHAR

(100), TEXT, CLOB

BLOB no datatype specified NONE 1,4

REAL, DOUBLE, DOUBLE PRECISION, FLOAT

NUMERIC, DECIMAL(10,5) , BOOLEAN, DATE, DATETIME

REAL

NUMERIC

2.43.6 Column Affinity Behavior Example

CREATE TABLE t1( t TEXT, -- text affinity by rule 3 nu NUMERIC, -- numeric affinity by rule 6 i INTEGER, -- integer affinity by rule 2 r REAL, -- real affinity by rule 5 no BLOB -- no affinity by rule 1,4

);

-- Values stored as TEXT, INTEGER, INTEGER, REAL, TEXT.

INSERT INTO t1 VALUES('500.0', '500.0', '500.0', '500.0', '500.0');

SELECT typeof(t), typeof(nu), typeof(i), typeof(r), typeof(no) FROM t1;

4 text|integer|integer|real|text

-- Values stored as TEXT, INTEGER, INTEGER, REAL, REAL.

DELETE FROM t1;

INSERT INTO t1 VALUES(500.0, 500.0, 500.0, 500.0, 500.0);

Kony Studio API Developer's Guide

Version 3.1

SELECT typeof(t), typeof(nu), typeof(i), typeof(r), typeof(no) FROM t1; text|integer|integer|real|real

-- Values stored as TEXT, INTEGER, INTEGER, REAL, INTEGER.

DELETE FROM t1;

INSERT INTO t1 VALUES(500, 500, 500, 500, 500);

SELECT typeof(t), typeof(nu), typeof(i), typeof(r), typeof(no) FROM t1; text|integer|integer|real|integer

-- BLOBs are always stored as BLOBs regardless of column affinity.

DELETE FROM t1;

INSERT INTO t1 VALUES(x'0500', x'0500', x'0500', x'0500', x'0500');

SELECT typeof(t), typeof(nu), typeof(i), typeof(r), typeof(no) FROM t1; blob|blob|blob|blob|blob

-- NULLs are also unaffected by affinity

DELETE FROM t1;

INSERT INTO t1 VALUES(NULL,NULL,NULL,NULL,NULL);

SELECT typeof(t), typeof(nu), typeof(i), typeof(r), typeof(no) FROM t1; null|null|null|null|null

Note: Columns of type INTEGER PRIMARY KEY may only hold a 64-bit signed integer. An error will result if you try to put anything other than an integer into an INTEGER PRIMARY KEY column.

Kony Studio API Developer's Guide

Version 3.1

2.44 Background Jobs

Background Jobs feature in Kony Platform includes

Background Fetch

and

Background Transfers .

2.44.1 Background Fetch

In iOS version 7 and above, an app that retrieves content regularly from a network can ask the system for background execution time to check for new content.

An application developer who wishes to perform a background fetch can enable this feature in

Kony Visualizer IDE and register for the feature using

kony.backgroundjob.registerBackgroundFetch

. This API can be used to register predefined fetch job that can handle tasks like file download, upload, or a custom task.

kony.net.HttpRequest

API supports background transfers. Tasks like upload or download from the network (HTTP/HTTPS) that are active even when the app is in background or suspended state is available in iOS.

2.44.2 Background Transfers

Following are the features in Background Transfer: l

Uploads and downloads are managed by iOS l

Unlike background fetch, background transfers have unlimited time.

Kony Studio API Developer's Guide

Version 3.1

It can be put in the queue anytime (foreground and background).

App is woken up to handle authentication challenges, errors if any, or completion of the job.

Background transfer tasks can be paused and resumed.

Only HTTP and HTTPS protocols are supported.

2.44.3 Background Fetch Workflow iOS 7 and later contains the

Background Fetch

The system determines how frequent the application can perform a background fetch and depends on the following factors: l

If network connectivity is available at that particular time.

Is the device awake.

Data and time the application has taken in its previous attempt to perform a background fetch.

setBackgroundFetchCompletionStatus

must be called, passing a result that indicates whether content is available.

Invoking

setBackgroundFetchCompletionStatus

tells the system that it can move the app back to the suspended state and evaluate its power usage.

Kony Studio API Developer's Guide

Version 3.1

It is advisable to use Background Transfers supported by

kony.net.HttpRequest

in fetch task to optimally utilize the execution time provided in the Fetch task.

2.44.4 Background Fetch and Background Transfers APIs

Background Fetch APIs

Following are the APIs for Background Jobs:

kony.backgroundjob.registerBackgroundFetch

kony.backgroundjob.setBackgroundFetchCompletionStatu

kony.backgroundjob.setBackgroundFetchInterval

Background Transfer

APIs

Following are the

Background Transfer APIs :

2.44.5 Supported Versions and Platforms

The Background Job feature: l

Available in Kony iOS platform versions above 5.6.2.

Supports iOS7 and the platforms above.

Supported only in JavaScript.

Kony Studio API Developer's Guide

Version 3.1

2.44.6 kony.backgroundjob.registerBackgroundFetch

Note: At the end of the background fetch job, you must invoke the

kony.backgroundjob.setBackgroundFetchCompletionStatus

passing a result that indicates whether content is available or not.

2.44.6.1 Signature

JavaScript: kony.backgroundjob.registerBackgroundFetch ( backgroundCallBack , fetchInterval )

2.44.6.2 Input Parameters backgroundCallBack [Function] - Mandatory

This callback is to be executed when the system invokes the app for a fetch job when the app is in background.

fetchInterval [Number] / [Constant] - Optional

Possible values are:

1. constants.BACKGROUND_TASK_FETCH_INTERVAL_MINIMUM

* This is the default value. System decides the fetch interval depending on the usage prediction for the app.

2. constants.BACKGROUND_TASK_FETCH_INTERVAL_NEVER

Kony Studio API Developer's Guide

Version 3.1

Disable background task. Set the time interval to constants.BACKGROUND_TASK_

FETCH_INTERVAL_NEVER so that the job is no longer scheduled for running.

3. Time in seconds. (Negative values are not accepted).

2.44.6.3 Return Values

<N.A> or “NONE".

2.44.6.4 Exceptions and Error Handling

message: "registerBackgroundFetch: MissingMandatoryParameters."

2. If arguments type does not match the allowed type, it raises an exception and throws a

KonyError JavaScript Object with the following attributes: errorCode: 4002.

message: "registerBackgroundFetch: InvalidParameters."

2.44.6.5 Platform Availability

Available in iOS Platform.

2.44.6.6 JavaScript Example function backgroundFetchCallBack() {

//fetch handler invoked whenever the system invokes the App for a fetch job

Kony Studio API Developer's Guide

Version 3.1

// do something here

// in the end of the handler setBackgroundFetchCompletionStatus() need

// to be called mandatorily other wise system might termitane the app.

// task completion status.

//1. constants.BACKGROUND_TASK_STATUS_NEW_DATA

//2. constants.BACKGROUND_TASK_STATUS_FAILED

//3. constants.BACKGROUND_TASK_STATUS_NO_NEW_DATA

var completionStatus = constants.BACKGROUND_TASK_STATUS_NEW_DATA; kony.backgroundjob.setBackgroundFetchCompletionStatus

(completionStatus);

};

//Fetch interval

//1. constants.BACKGROUND_TASK_FETCH_INTERVAL_MINIMUM

//2. constants.BACKGROUND_TASK_FETCH_INTERVAL_NEVER

//3. Time in seconds. (Negative values are not accepted).

var fetchInterval = constants.BACKGROUND_TASK_FETCH_INTERVAL_

MINIMUM;

//register background fetch job kony.backgroundjob.registerBackgroundFetch

(backgroundFecthCallBack, fetchInterval);

Kony Studio API Developer's Guide

Version 3.1

2.44.7 kony.backgroundjob.setBackgroundFetchCompletionStatus

One must call this method in the end of

backgroundCallBack

passing a result that indicates whether content was available or not. This method intimates the system of the completion status of the background fetch job that has been scheduled.

Failure to call this method results in undefined behavior and could cause the app to be terminated by the system. If an error arises during invoking this API, default value:

constants.BACKGROUND_

TASK_STATUS_FAILED

will be set.

2.44.7.1 Signature

JavaScript: kony.backgroundjob.setBackgroundFetchCompletionStatus(

completionStatus

)

2.44.7.2 Input Parameters completionStatus [constant] - Mandatory

This is a mandatory parameter. Possible values are as follows

1. constants.BACKGROUND_TASK_STATUS_NEW_DATA

2. constants.BACKGROUND_TASK_STATUS_FAILED

This tells the system that the fetch was unsuccessful. UI is not updated and the task will be run later based on the available system resources.

Kony Studio API Developer's Guide

Version 3.1

3. constants.BACKGROUND_TASK_STATUS_NO_NEW_DATA

This intimates the system the fetch did not result in any new data, UI is not updated and the job is run after any point later in time but not before fetchInterval.

2.44.7.3 Return Values

<N.A> or “NONE".

2.44.7.4 Exceptions

message: "setBackgroundFetchCompletionStatus:

MissingMandatoryParameters."

2. If arguments type does not match the allowed type, it raises an exception and throws a

“KonyError” JS Object with the following attributes: errorCode: 4002.

message: "setBackgroundFetchCompletionStatus:

InvalidParameters."

3. If an error arises during invoking of this API, default value: constants.BACKGROUND_TASK_

STATUS_FAILED will be set.

2.44.7.5 Platform Availability

Available in iOS Platform.

Kony Studio API Developer's Guide

Version 3.1

2.44.7.6 JavaScript Example function backgroundFecthCallBack() {

//fetch handler invoked whenever the system invokes the App for a fetch job

// do something here

// in the end of the handler setBackgroundFetchCompletionStatus() need

// to be called mandatorily other wise system might termitane the app.

// task completion status.

//1. constants.BACKGROUND_TASK_STATUS_NEW_DATA

//2. constants.BACKGROUND_TASK_STATUS_FAILED

//3. constants.BACKGROUND_TASK_STATUS_NO_NEW_DATA

var completionStatus = constants.BACKGROUND_TASK_STATUS_NEW_DATA; kony.backgroundjob.setBackgroundFetchCompletionStatus

(completionStatus);

};

//Fetch interval

//1. constants.BACKGROUND_TASK_FETCH_INTERVAL_MINIMUM

//2. constants.BACKGROUND_TASK_FETCH_INTERVAL_NEVER

//3. Time in seconds. (Negative values are not accepted).

var fetchInterval = constants.BACKGROUND_TASK_FETCH_INTERVAL_

Kony Studio API Developer's Guide

Version 3.1

MINIMUM;

//register background fetch job kony.backgroundjob.registerBackgroundFetch

(backgroundFecthCallBack, fetchInterval);

2.44.8 kony.backgroundjob.setBackgroundFetchInterval

This method sets the fetch interval for the background fetch job scheduled.

2.44.8.1 Signature

JavaScript: kony.backgroundjob.setBackgroundFetchInterval(

fetchInterval

)

2.44.8.2 Input Parameters fetchInterval [Number]/[Constant] - Mandatory

Possible values are:

1. constants.BACKGROUND_TASK_FETCH_INTERVAL_MINIMUM

This is the default value. System decides the fetch interval depending on the usage prediction for the app.

2. constants.BACKGROUND_TASK_FETCH_INTERVAL_NEVER

Disable background task. Set the time interval to constants.BACKGROUND_TASK_FETCH_

INTERVAL_NEVER so that the job is no longer scheduled for running.

3. Time in seconds. (Negative values are not accepted).

Kony Studio API Developer's Guide

Version 3.1

2.44.8.3 Return Values

<N.A> or “NONE".

2.44.8.4 Exceptions

message: "setBackgroundFetchInterval:

MissingMandatoryParameters."

2. If arguments type does not match the allowed type, it raises an exception and throws a

“KonyError” JS Object with the following attributes: errorCode: 4002.

message: "setBackgroundFetchInterval: InvalidParameters."

2.44.8.5 Platform Availability

Available in iOS Platform.

2.44.8.6 JavaScript Example

//Fetch interval

//1. constants.BACKGROUND_TASK_FETCH_INTERVAL_MINIMUM

//2. constants.BACKGROUND_TASK_FETCH_INTERVAL_NEVER

//3. Time in seconds. (Negative values are not accepted).

var fetchInterval = constants.BACKGROUND_TASK_FETCH_INTERVAL_

Kony Studio API Developer's Guide

Version 3.1

MINIMUM; kony.backgroundjob.setBackgroundFetchInterval(fetchInterval);

3. References

Kony Studio API Developer's Guide

Version 3.1

3. References

This section provides reference material for the Kony Mobile Application Development Platform in the following topics.

com.kony Namespace

kony Namespace

kony.accelerometer Namespace

l kony.application Namespace l

kony.application.settings Namespace

kony.camera Namespace

l kony.contact Namespace l kony.crypto Namespace l kony.db Namespace l kony.ds Namespace l kony.hybrid Namespace l kony.image Namespace l kony.io.File Namespace l kony.io.FileList Namespace l kony.i18n Namespace l kony.io.FileSystem Namespace l kony.lang Namespace l kony.localAuthentication Namespace

3. References l kony.location Namespace l kony.map Namespace l kony.modules Namespace l kony.net Namespace l kony.os Namespace l kony.phone Namespace l kony.props Namespace l kony.store Namespace l kony.stream Namespace l kony.string Namespace l kony.theme Namespace l kony.timer Namespace l kony.types.RawBytes Namespace l kony.ui Namespace l kony.worker Namespace l math Namespace l string Namespace (Deprecated) l table Namespace

3.1 com.kony Namespace

The com.kony namespace provides the following API elements.

Kony Studio API Developer's Guide

Version 3.1

3. References

Kony Studio API Developer's Guide

Version 3.1

Functions

Objects

3.1.1 Functions

The com.kony namespace contains the following functions.

com.kony.AddPassesViewController

The AddPassesViewController creates an AddPassesViewController object.

Syntax com.kony.AddPassesViewController(

passbookArray,

statusCallback);

Parameters passbookArray

An optional array of passbooks. Uses only first passbook in the array if the operating system is iOS below 7.0.

statusCallback

Optional callback function that get the status of the AddPassesViewController object. Must have the following signature.

statusCallbackFunctionName(status); where status is a string that contains the status of the AddPassesViewController object

Return Values

Returns a AddPassesViewController object.

3. References

Kony Studio API Developer's Guide

Version 3.1

Example var AddPassesViewController1 = new com.kony.AddPassesViewController(an, statusCallback);

3.1.2 Objects

The com.kony namespace contains the following objects.

Beacon Object

BeaconManager Object

Beacon Region Object

Peripheral Manager Object

3.1.2.1 AddPassesViewController Object

The AddPassesViewController class provides a view to add passes to the user’s library of passes.

Methods

The AddPassesViewController object has the following methods.

dismissAnimated

This API is used to dismiss the view of add passes view controller.

3.1.3 Signature

JavaScript : <<PassObject>>.dismissAnimated(animated)

Input Parameters l animated [Object] - Mandatory

Set True to dismiss with animation.

3. References

Kony Studio API Developer's Guide

Version 3.1

3.1.4 Return Values

String

The authentication token of Pass.

3.1.5 Platform Availability

Available only on iOS

3.1.6 JavaScript Example

AddPassesViewController1.dismissAnimated(animated);

...

var AddPassesViewController1 =

AddPassesViewController1.dismissAnimated(animated); getLocalizedDescription( )

The localized description of the pass’s kind. You can use this property to provide accessibility information for a UI element that represents a pass, such as a cell in a table view.

3.1.7 Signature

JavaScript : <<PassObject>>.getLocalizedDescription()

Input Parameters

None

3.1.8 Return Values

String

Localized description of Pass.

3. References

Kony Studio API Developer's Guide

Version 3.1

3.1.9 Platform Availability

Available only on iOS

3.1.10 JavaScript Example var AddPassesViewController1 =

AddPassesViewController1.getLocalizedDescription(); getLocalizedName

You can use this property to provide accessibility information for a UI element that represents a pass, such as a cell in a table view.

3.1.11 Signature

JavaScript: <<PassObject>>.getLocalizedName()

3.1.12 Input Parameters

None

3.1.13 Return Values

String localized description of Pass.

3.1.14 Platform Availability

Available only on iOS

3. References

Kony Studio API Developer's Guide

Version 3.1

3.1.15 JavaScript Example var AddPassesViewController1 =

AddPassesViewController1.getLocalizedName(); getLocalizedValueForKeyForDeviceLocale

Returns the localized value for specified field of the pass.

3.1.16 Signature

JavaScript : <<PassObject>>.getLocalizedValueForKeyForDeviceLocale()

3.1.17 Input Parameters l key [String] - Mandatory

The field's key, as specified in the pass.

3.1.18 Return Values

String

The localized value for the pass’s field.

3.1.19 Platform Availability

Available only on iOS

3.1.20 JavaScript Example

(key);

AddPassesViewController1.getLocalizedValueForKeyForDeviceLocale

...

var AddPassesViewController1 =

3. References

Kony Studio API Developer's Guide

Version 3.1

AddPassesViewController1.getLocalizedValueForKeyForDeviceLocale

(key); getOrganizationName

The name of the organization that created the pass.

3.1.21 Signature

JavaScript: <<PassObject>>.getOrganizationName()

3.1.22 Input Parameters

None

3.1.23 Return Values

String

Organization name of Pass.

3.1.24 Platform Availability

Available only on iOS

3.1.25 JavaScript Example var AddPassesViewController1 =

AddPassesViewController1.getOrganizationName(); getPassTypeIdentifier

The pass’s type identifier.

3. References

Kony Studio API Developer's Guide

Version 3.1

3.1.26 Signature

JavaScript: <<PassObject>>.getPassTypeIdentifier()

3.1.27 Return Values

String

The pass’s type identifier.

3.1.28 Platform Availability

Available only on iOS

3.1.29 JavaScript Example var AddPassesViewController1 =

AddPassesViewController1.getPassTypeIdentifier(); getPassURL

The URL that opens the pass in the Passbook app.

3.1.30 Signature

JavaScript

: <<PassObject>>.getPassURL(()

3.1.31 Input Parameters

None

3. References

Kony Studio API Developer's Guide

Version 3.1

3.1.32 Return Values

String absolute string of passURL

3.1.33 Platform Availability

Available only on iOS

3.1.34 JavaScript Example var AddPassesViewController1 = AddPassesViewController1.getPassURL

(); getSerialNumber

A value that uniquely identifies the pass.

3.1.35 Signature

JavaScript

: <<PassObject>>.getSerialNumber()

3.1.36 Input Parameters

None

3.1.37 Return Values

String

The serial number of Pass

3.1.38 Platform Availability

Available only on iOS

3. References

Kony Studio API Developer's Guide

Version 3.1

3.1.39 JavaScript Example var AddPassesViewController1 =

AddPassesViewController1.getSerialNumber(); getUserInfo

Developer-specific custom data.

Note:

Only available in iOS7 and above.

3.1.40 Signature

JavaScript : <<PassObject>>.getUserInfo()

3.1.41 Input Parameters

None

3.1.42 Return Values

String userInfo dictionary of Pass.

3.1.43 Platform Availability

Available only on iOS

3.1.44 JavaScript Example var AddPassesViewController1 = AddPassesViewController1.getUserInfo

();

Kony Studio API Developer's Guide

Version 3.1

3.1.44.1 com.kony.Beacon

You cannot create Beacon objects directly. Beacon objects are created by native platforms only.

The com.kony.Beacon class has the following methods: l

getProximityUUIDString

getrssi

getAccuracy

The accuracy of the proximity value, measured in meters from the beacon.

Indicates the one sigma horizontal accuracy in meters. Use this property to differentiate between beacons with the same proximity value. Do not use it to identify a precise location for the beacon.

Accuracy values may fluctuate due to RF interference.

A negative value in this property signifies that the actual accuracy could not be determined. For more information, see Apple Documentation .

Signature

JavaScript

: <<BeaconObject>>.getAccuracy()

Input Parameters

None

Kony Studio API Developer's Guide

Version 3.1

Return Values

Number

Accuracy of the proximity value.

Platform Availability

Available only on iOS

JavaScript Example var beacon1 = new com.kony.Beacon();

...

var accuracy1 = beacon1.getAccuracy(); getMajor

The most significant value in the beacon. A major value, which is a number that can be used to group related beacons that have the same proximity UUID.

Signature

JavaScript: <<BeaconObject>>.getMajor()

Input Parameters

None

Return Values

Number

Platform Availability

Available only on iOS

JavaScript Example var beacon1 = new com.kony.Beacon();

...

Kony Studio API Developer's Guide

Version 3.1

var major1 = beacon1.getMajor(); getMinor

The least significant value in the beacon. A minor value, which is a number that differentiates beacons with the same proximity UUID and major value.

Signature

JavaScript : <<BeaconObject>>.getMinor()

Input Parameters

None

Return Values

Number

Platform Availability

Available only on iOS

JavaScript Example var beacon1 = new com.kony.Beacon();

...

var minor1 = beacon1.getMinor(); getProximity

The proximity value gives a general sense of the relative distance to the beacon. Use it to quickly identify beacons that are nearer to the user rather than farther away.

Signature

JavaScript: <<BeaconObject>>.getProximity()

Kony Studio API Developer's Guide

Version 3.1

Input Parameters

None

Return Values

String

A string can be any of the following values: l

BeaconProximityUnknown - The proximity of the beacon could not be determined.

BeaconProximityImmediate - The beacon is in the user’s immediate vicinity.

BeaconProximityNear - The beacon is relatively close to the user.

BeaconProximityFar - The beacon is far away.

Platform Availability

Available only on iOS

JavaScript Example var beacon1 = new com.kony.Beacon();

...

var proximity1 = beacon1.getProximity(); getProximityUUIDString

The proximity UUID (string representation) of the beacon. A proximity UUID (universally unique identifier), which is a 128-bit value that uniquely identifies one or more beacons as a certain type or from a certain organization

Signature

JavaScript: <<BeaconObject>>.getProximityUUIDString()

Input Parameters

None

Kony Studio API Developer's Guide

Version 3.1

Return Values

String

Proximity UUID of the beacon.

Platform Availability

Available only on iOS

JavaScript Example var beacon1 = new com.kony.Beacon();

...

var proximityUUIDString1 = beacon1.getProximityUUIDString(); getrssi

The received signal strength of the beacon, measured in decibels. This value is the average RSSI value of the samples received since the range of the beacon was last reported to your app.

Signature

JavaScript : <<BeaconObject>>.getrssi()

Input Parameters

None

Return Values

Number

Platform Availability

Available only on iOS

JavaScript Example var beacon1 = new com.kony.Beacon();

...

var rssi1 = beacon1.getrssi();

Kony Studio API Developer's Guide

Version 3.1

Kony Studio API Developer's Guide

Version 3.1

3.1.44.2 com.kony.BeaconManager Object

BeaconManager is for managing iBeacons in iOS.

The com.kony.BeaconManager class has the following methods: l

authorizationStatus( )

getAuthorizationStatusChanged( )

getMonitoredRegions( )

getRangedRegions( )

isMonitoringAvailableForBeaconRegions( )

isRangingAvailableForBeaconRegions( )

requestStateForRegion( )

setAuthorizationStatusChangedCallback( )

setMonitoringStartedForRegionCallback( )

startMonitoringBeaconRegion( )

startRangingBeaconsInRegion( )

stopMonitoringBeaconRegion( )

stopRangingBeaconsInRegion( )

Here is an example for creating a BeaconManager with callbacks: var aBeaconManager = new com.kony.BeaconManager(monitoringCallback, rangingCallback, errorCallback);

Input Parameters

Kony Studio API Developer's Guide

Version 3.1

l monitoringCallback [Function] - Optional

To get monitoring beacon region updates from BeaconManager: o beaconRegion [Object] - com.kony.BeaconRegion - An object containing information about the region that was entered or exited.

o beaconRegionState [String] - Can represent one of the following strings: n

BeaconRegionStateUnknown - It is unknown whether the device is inside or outside of the region.

BeaconRegionStateInside - The device is inside the given region.

BeaconRegionStateOutside - The device is outside of the given region.

function monitoringCallback(beaconRegion, beaconRegionState)

{

} l rangingCallback [Function] - Optional

To get ranging updates from BeaconManager: o beaconRegion [Object] - com.kony.BeaconRegion - Object representing a Beacon

Region.

o beacons [Object Array] - com.kony.Beacon - An array of com.kony.Beacon objects representing the beacons currently in range (in the order of closest first). You can use the information in these objects to determine the range of each beacon and its identifying information.

function rangingCallback(beaconRegion, beacons) {

} l errorCallback [Function] - Optional

To get error updates from BeaconManager:

Kony Studio API Developer's Guide

Version 3.1

o beaconManagerError [String] - Can represent one of the following strings: n

BeaconManagerMonitoringError - If an error occurs while trying to monitor a given region.

BeaconManagerRangingError - If the region object itself is invalid or if it contains invalid data.

BeaconManagerFailedError - The beacon manager was unable to retrieve a location value.

o errorName [String] - Name of the error.

o errorDictionary [Object] - Dictionary object.

o beaconRegion [Object] - com.kony.BeaconRegion.

function errorCallback(beaconManagerError, errorName, errorDictionary, beaconRegion) {

}

Return Values

Object - com.kony.BeaconManager

Platform Availability

Available only on iOS.

authorizationStatus( )

This API helps you know the authorization status of the location services for the application. The authorization status of a given application is managed by the system and determined by several factors. Applications must be explicitly authorized to use location services by the user, and location services must currently be enabled for the system. A request for user authorization is displayed automatically when your application first attempts to use location services.

Signature

JavaScript : <<BeaconManagerObject>>.authorizationStatus()

Kony Studio API Developer's Guide

Version 3.1

Input Parameters

None

Return Values

String

Returns one of the following strings: l

BeaconManagerAuthorizationStatusNotDetermined - The user has not made a choice regarding whether this application can use location services.

BeaconManagerAuthorizationStatusRestricted - This application is not authorized to use location services. The user cannot change this application’s status, possibly due to active restrictions such as parental controls being in place.

BeaconManagerAuthorizationStatusDenied - The user explicitly denied the use of location services for this application or location services are currently disabled in Settings.

BeaconManagerAuthorizationStatusAuthorized - This application is authorized to use location services.

Platform Availability

Available only on iOS.

JavaScript Example var authorizationStatus1 = aBeaconManager.authorizationStatus(); getMonitoredRegions( )

This API gets the Beacon Regions that are currently being monitored. You cannot add regions to this property directly. Instead, you must register regions by calling the

startMonitoringForRegion

method.

Signature

JavaScript : <<BeaconManagerObject>>.getMonitoredRegions()

Kony Studio API Developer's Guide

Version 3.1

Input Parameters

None

Return Values

Array of com.kony.BeaconRegion objects

All the Beacon Regions that are being monitored by the BeaconManager.

Platform Availability

Available only on iOS.

JavaScript Example var monitoredRegions = aBeaconManager.getMonitoredRegions(); getRangedRegions( )

This API helps to get the Beacon Regions currently being ranged. The objects in the set are instances of the com.kony.BeaconRegion class.

Signature

JavaScript: <<BeaconManagerObject>>.getRangedRegions()

Input Parameters

None

Return Values

Array of com.kony.BeaconRegion objects

All the Beacon Regions being ranged by the BeaconManager.

Platform Availability

Available only on iOS.

Kony Studio API Developer's Guide

Version 3.1

JavaScript Example var rangedRegions1 = aBeaconManager.getRangedRegions(); isMonitoringAvailableForBeaconRegions( )

This API helps to determine if the monitoring is available for Beacon Regions.

Note: The availability of region monitoring support is dependent on the hardware on the device.

This method does not consider the availability of location services or the fact that the user might have disabled them for the app or system. You must determine your app’s authorization status separately.

Signature

JavaScript

: <<BeaconManagerObject>>.isMonitoringAvailableForBeaconRegions()

Input Parameters

None

Return Values

Boolean

True, if it is available; false, if it is not available.

Platform Availability

Available only on iOS.

JavaScript Example var isMonitoringAvailableForBeaconRegions1 = aBeaconManager.isMonitoringAvailableForBeaconRegions();

Kony Studio API Developer's Guide

Version 3.1

isRangingAvailableForBeaconRegions( )

This API helps to determine if the ranging is available.

Signature

JavaScript : <<BeaconManagerObject>>.isRangingAvailableForBeaconRegions()

Input Parameters

None

Return Values

Boolean

True, if it is available; false, if it is not available.

Platform Availability

Available only on iOS.

JavaScript Example var isRangingAvailableForBeaconRegions1 = aBeaconManager.isRangingAvailableForBeaconRegions(); requestStateForRegion( )

This API helps to determine the state of the current device relative to the Beacon Region. This method performs the request asynchronously and delivers the results through monitoringCallback.

Signature

JavaScript : <<BeaconManagerObject>>.requestStateForRegion()

Input Parameters beaconRegion

Mention the beacon region to know the state.

Kony Studio API Developer's Guide

Version 3.1

Return Values

None

Platform Availability

Available only on iOS.

JavaScript Example aBeaconManager.requestStateForRegion(beaconRegion); setAuthorizationStatusChangedCallback( )

This API helps to set the authorization status changed callback.

Signature

JavaScript : <<BeaconManagerObject>>.setAuthorizationStatusChangedCallback()

Input Parameters l authorizationStatusChanged [Function] o

Status [String] - either of the following strings are passed: n

BeaconManagerAuthorizationStatusNotDetermined - The user has not made a choice regarding whether this application can use location services.

BeaconManagerAuthorizationStatusDenied - The user explicitly denied the use of location services for this application or location services are currently disabled in

Settings.

Kony Studio API Developer's Guide

Version 3.1

BeaconManagerAuthorizationStatusAuthorized - This application is authorized to use location services.

function setAuthorizationStatusChangedCallback

(authorizationStatusChanged) {

} function authorizationStatusChanged(Status){

}

Return Values

None

Platform Availability

Available only on iOS.

JavaScript Example aBeaconManager.setAuthorizationStatusChangedCallback

(authorizationStatusChanged); setMonitoringStartedForRegionCallback( )

This API helps to set the monitoring started for region callback. This API informs the user though this callback that a new region is being monitored.

Signature

JavaScript : <<BeaconManagerObject>>.setMonitoringStartedForRegionCallback()

Input Parameters monitoringStartedForRegionCallback [Function] l beaconRegion [Object] - com.kony.BeaconRegion

function monitoringStartedForRegionCallback (Object){

}

Kony Studio API Developer's Guide

Version 3.1

Return Values

None

Platform Availability

Available only on iOS.

JavaScript Example aBeaconManager.setMonitoringStartedForRegionCallback

(monitoringStartedForRegionCallback); startMonitoringBeaconRegion( )

This API helps to start monitoring for the specified Beacon Region. You must call this method once for each region you want to monitor. If an existing region with the same identifier is already being monitored by the application, the old region is replaced by the new one. Region events are delivered through monitoringCallback. The errorCallback informs the user of any errors.

Signature

JavaScript : <<BeaconManagerObject>>.startMonitoringBeaconRegion()

Input Parameters beaconRegion [Object] - com.kony.BeaconRegion

Mention the Beacon Region to monitor.

Return Values

None

Platform Availability

Available only on iOS.

Kony Studio API Developer's Guide

Version 3.1

JavaScript Example aBeaconManager.startMonitoringBeaconRegion(beaconRegion); startRangingBeaconsInRegion( )

This API helps to start ranging beacons in a specified Beacon Region.

Signature

JavaScript : <<BeaconManagerObject>>.startRangingBeaconsInRegion()

Input Parameters beaconRegion - com.kony.BeaconRegion

A Beacon Region for ranging.

Note: Make this call once the region monitored state is "BeaconRegionStateInside."

Return Values

None

Platform Availability

Available only on iOS.

JavaScript Example aBeaconManager.startRangingBeaconsInRegion(beaconRegion); stopMonitoringBeaconsRegion( )

This API stops the monitoring of a specified beacon region.

Kony Studio API Developer's Guide

Version 3.1

Signature

JavaScript

: <<BeaconManagerObject>>.stopMonitoringBeaconRegion()

Input Parameters beaconRegion

Mention the beacon region to stop ranging.

Return Values

None

Platform Availability

Available only on iOS.

JavaScript Example aBeaconManager.stopMonitoringBeaconsRegion(beaconRegion); stopRangingBeaconsInRegion( )

This API helps to stop ranging beacons in a specified Beacon Region. If the specified region object is not currently being monitored, this method has no effect.

Signature

JavaScript : <<BeaconManagerObject>>.stopRangingBeaconsInRegion()

Input Parameters beaconRegion

Mention the Beacon Region to stop ranging. The beacon attributes should be the same object that you registered.

Return Values

None

Kony Studio API Developer's Guide

Version 3.1

Platform Availability

Available only on iOS.

JavaScript Example aBeaconManager.stopRangingBeaconsInRegion(beaconRegion);

Kony Studio API Developer's Guide

Version 3.1

3.1.44.3 com.kony.BeaconRegion Object

A Beacon Region object defines the type of region based on the device’s proximity to a Bluetooth beacon. A Beacon Region monitors for devices whose identifying information matches the information the user provides. If a device appears in range, the region triggers the delivery of an appropriate notification.

The com.kony.BeaconRegion class includes the following methods: l

getIdentifier

getMajor

getMinor

getNotifyEntryStateOnDisplay

getProximityUUIDString

setNotifyEntryStateOnDisplay

Here is an example for creating a Beacon Region with callbacks: var BeaconRegion1= new com.kony.BeaconRegion(UUIDString1, major1, minor1, identifier1)

Input Parameters l proximityUUID [String] - contains the identifier that identifies your company’s beacons. You usually generate only one UUID for your company’s beacons but can generate more as needed. You can generate this value using the uuidgen command-line tool.

l major [Number] - property contains a value that groups related sets of beacons. For example, a bank can assign the same major value for all beacons on the same floor.

l minor [Number] - Optional

This property specifies the individual beacon within a group. For example, for a group of

Kony Studio API Developer's Guide

Version 3.1

beacons on the same floor of a bank, this value can be assigned to a beacon in a particular section.

l identifier [String] - Optional

A unique identifier to associate with the Beacon Region object returned. Use this identifier to differentiate regions within your application. This value must not be null.

Return Values

Object - com.kony.BeaconRegion

Platform Availability

Available only on iOS.

getIdentifier

The getIdentifier() is an identifier for the region object. This is a value you specify and can use to identify a region inside your application.

Signature

JavaScript : <<BeaconRegionObject>>.getIdentifier()

Input Parameters

None

Return Values

String

Platform Availability

Available only on iOS.

JavaScript Example var identifier1 = BeaconRegion1.getIdentifier();

Kony Studio API Developer's Guide

Version 3.1

getMajor

The getMajor() is a value identifying a group of beacons. This is a read-only value.

Note: If you do not specify a major value for the beacon, the value in this property is

nil

. When this property is

nil

, the major value of the beacon is ignored when determining if it is a match.

Signature

JavaScript : <<BeaconRegionObject>>.getMajor()

Input Parameters

None

Return Values

Number

Platform Availability

Available only on iOS.

JavaScript Example var major1 = BeaconRegion1.getMajor(); getMinor

The value identifying a specific beacon within a group.

Note: If you do not specify a minor value for the beacon, the value in this property is

nil

. When this property is nil, the minor value of the beacon is ignored while determining if it is a match.

Signature

JavaScript : <<BeaconRegionObject>>.getMinor()

Kony Studio API Developer's Guide

Version 3.1

Input Parameters

None

Return Values

Number

Platform Availability

Available only on iOS.

JavaScript Example var minor1 = BeaconRegion1.getMinor(); getNotifyEntryStateOnDisplay

A Boolean indicating whether beacon notifications are sent when the device’s display is ON.

If set to YES, the location manager sends beacon notifications when the user turns on the display and the device is already inside the region. These notifications are sent even if your application is not running. In these situations, the system launches your application into the background so that it can handle the notifications.

Note: The default value for this property is NO.

Signature

JavaScript : <<BeaconRegionObject>>.getNotifyEntryStateOnDisplay( )

Input Parameters

None

Kony Studio API Developer's Guide

Version 3.1

Return Values

Boolean

Platform Availability

Available only on iOS.

JavaScript Example var notifyEntryStateOnDisplay1 =

BeaconRegion1.getNotifyEntryStateOnDisplay(); getProximityUUIDString

The unique ID of the beacons being targeted. This is a read-only ID.

Signature

JavaScript : <<BeaconRegionObject>>.getProximityUUIDString( )

Return Values

String

Platform Availability

Available only on iOS.

JavaScript Example var proximityUUIDString1 = BeaconRegion1.getProximityUUIDString(); setNotifyEntryStateOnDisplay

A Boolean indicating whether beacon notifications are sent when the device’s display is ON.

Kony Studio API Developer's Guide

Version 3.1

If set to TRUE, the location manager sends beacon notifications when the user turns on the display and the device is already inside the region. These notifications are sent even if your application is not running. In these situations, the system launches your application into the background so that it can handle the notifications.

Note: The default value for this property is FALSE.

Signature

JavaScript

: <<BeaconRegionObject>>.setNotifyEntryStateOnDisplay()

Input Parameters

State [Boolean]

Return Values

None

Platform Availability

Available only on iOS.

JavaScript Example

BeaconRegion1.setNotifyEntryStateOnDisplay(true);

3.1.44.4 com.kony.Pass

Pass represents a Pass in iOS.

The com.kony.PassLibrary class has the following methods: l

getAuthenticationToken( )

getLocalizedDescription( )

getLocalizedName( )

getLocalizedValueForKeyForDeviceLocale( )

getOrganizationName( )

getPassTypeIdentifier( )

getPassURL( )

getSerialNumber( )

getUserInfo( )

Here is an example for creating a Pass with callbacks: var pass1 = new com.kony.Pass();

Return Values

Object - com.kony.Pass

getAuthenticationToken( )

The token used to authenticate with the web service.

Signature

JavaScript : <<PassObject>>.getAuthenticationToken()

Input Parameters

Kony Studio API Developer's Guide

Version 3.1

279 of 838

Kony Studio API Developer's Guide

Version 3.1

None

Return Values

String

The authentication token of Pass

Platform Availability

Available only on iOS

JavaScript Example var pass1 = pass1.getAuthenticationToken(); getLocalizedDescription( )

The localized description of the pass’s kind. You can use this property to provide accessibility information for a UI element that represents a pass, such as a cell in a table view.

Signature

JavaScript : <<PassObject>>.getLocalizedDescription()

Input Parameters

None

Return Values

String localized description of Pass.

Platform Availability

Available only on iOS

JavaScript Example var pass1 = pass1.getLocalizedDescription();

Kony Studio API Developer's Guide

Version 3.1

getLocalizedName( )

You can use this property to provide accessibility information for a UI element that represents a pass, such as a cell in a table view.

Signature

JavaScript: <<PassObject>>.getLocalizedName()

Input Parameters

None

Return Values

String localized description of Pass.

Platform Availability

Available only on iOS

JavaScript Example var pass1 = pass1.getLocalizedName(); getLocalizedValueForKeyForDeviceLocale( )

Returns the localized value for specified field of the pass.

Signature

JavaScript : <<PassObject>>.getLocalizedValueForKeyForDeviceLocale()

Input Parameters l key [String] - Mandatory

The field's key, as specified in the pass.

Kony Studio API Developer's Guide

Version 3.1

Return Values

String

The localized value for the pass’s field.

Platform Availability

Available only on iOS

JavaScript Example pass1.getLocalizedValueForKeyForDeviceLocale(key);

...

var pass1 = pass1.getLocalizedValueForKeyForDeviceLocale(key); getOrganizationName( )

The name of the organization that created the pass.

Signature

JavaScript: <<PassObject>>.getOrganizationName()

Input Parameters

None

Return Values

String organization name of Pass.

Platform Availability

Available only on iOS

JavaScript Example var pass1 = pass1.getOrganizationName();

Kony Studio API Developer's Guide

Version 3.1

getPassTypeIdentifier( )

The pass’s type identifier.

Signature

JavaScript: <<PassObject>>.getPassTypeIdentifier()

Return Values

String

The pass’s type identifier.

Platform Availability

Available only on iOS

JavaScript Example var pass1 = pass1.getPassTypeIdentifier(); getPassURL(( )

The URL that opens the pass in the Passbook app.

Signature

JavaScript : <<PassObject>>.getPassURL(()

Input Parameters

None

Return Values

String absolute string of passURL

Platform Availability

Available only on iOS

JavaScript Example var pass1 = pass1.getPassURL(); getSerialNumber( )

A value that uniquely identifies the pass.

Signature

JavaScript : <<PassObject>>.getSerialNumber()

Input Parameters

None

Return Values

String

The serial number of Pass.

Platform Availability

Available only on iOS

JavaScript Example var pass1 = pass1.getSerialNumber(); getUserInfo( )

Developer-specific custom data.

Only available in iOS7 and above.

Signature

JavaScript

: <<PassObject>>.getUserInfo()

Kony Studio API Developer's Guide

Version 3.1

284 of 838

Input Parameters

None

Return Values

String userInfo dictionary of Pass.

Platform Availability

Available only on iOS

JavaScript Example var pass1 = pass1.getUserInfo();

Kony Studio API Developer's Guide

Version 3.1

Kony Studio API Developer's Guide

Version 3.1

3.1.44.5 com.kony.PassLibrary

The PassLibrary class provides an interface to the user’s library of passes.

The com.kony.PassLibrary class has the following methods: l

addPassWithCompletionCallback( )

addPassesWithCompletionCallback( )

containsPass( )

getPassWithTypeIdentifierAndSerialNumber( )

getPasses( )

removePass( )

replacePassWithPass( )

Here is an example for creating a PassLibrary with callbacks: var passLibrary1 = new com.kony.PassLibrary();

Return Values

Object - com.kony.PassLibrary

addPassWithCompletionCallback( )

Presents UI to add pass.

If the status is KonyPKPassLibraryShouldReviewPasses in completionCallback, present an instance of com.kony.AddPassesViewController with the same pass, to let the user review and add them.

Signature

JavaScript : <<PassObject>>.addPassWithCompletionCallback(

pass ,

completionCallback

)

Input Parameters

Kony Studio API Developer's Guide

Version 3.1

l pass [Object] - com.kony.Pass - Mandatory

The pass being added.

l completionCallback [Function] - Mandatory

The completion callback called after the user.

l status [String]

Status of the passes adding task to PassLibrary. One of the below values: l

KonyPKPassLibraryDidAddPasses l

KonyPKPassLibraryShouldReviewPasses l

KonyPKPassLibraryDidCancelAddPasses

Return Values

None

Platform Availability

Available only on iOS

JavaScript Example passbook1.addPassWithCompletionCallback(pass, completionCallback); addPassesWithCompletionCallback( )

Presents UI to add multiple passes.

If the status is KonyPKPassLibraryShouldReviewPasses in completionCallback, present an instance of com.kony.AddPassesViewController with the same pass, to let the user review and add them.

Signature

JavaScript: <<PassObject>>.addPassesWithCompletionCallback()

Kony Studio API Developer's Guide

Version 3.1

Input Parameters l passes [Array] - Mandatory

The pass being added.

l completionCallback [Function] - Mandatory

The completion callback called after the user.

l status [String]

Status of the passes adding task to PassLibrary. One of the below values: l

KonyPKPassLibraryDidAddPasses l

KonyPKPassLibraryShouldReviewPasses

Return Values

Number

Platform Availability

Available only on iOS

JavaScript Example l

KonyPKPassLibraryDidCancelAddPasses passbook1.addPassWithCompletionCallback(passes, completionCallback); containsPass( )

Returns whether the user’s pass library contains a pass. This method lets you determine that the pass library contains a pass even though your app wouldn’t be able to read or modify the pass.

Signature

JavaScript

: <<PassObject>>.containsPass()

Kony Studio API Developer's Guide

Version 3.1

Input Parameters l pass [Object] - com.kony.Pass - Mandatory

The pass being queried.

Return Values

Boolean

True if pass is in the PassLibrary.

Platform Availability

Available only on iOS

JavaScript Example passbook1.addPassWithCompletionCallback(passes, completionCallback);

...

var passbook1 = passbook1.addPassWithCompletionCallback(passes, completionCallback); getPassWithTypeIdentifierAndSerialNumber( )

The proximity value gives a general sense of the relative distance to the beacon. Use it to quickly identify beacons that are nearer to the user rather than farther away.

Signature

JavaScript: <<PassObject>>.getPassWithTypeIdentifierAndSerialNumber(

identifier

serailNumber )

Input Parameters l identifier [String] - Mandatory

The pass’s pass type identifier.

Kony Studio API Developer's Guide

Version 3.1

l serailNumber [String]

The pass’s serial number.

Return Values l com.kony.Pass [Object]

The pass with the given pass type identifier and serial number, or nil if there is no such pass or if the app doesn’t have the appropriate entitlement.

Platform Availability

Available only on iOS

JavaScript Example passbook1.getPassWithTypeIdentifierAndSerialNumber(identifier, serailNumber);

...

var passbook1 = passbook1.getPassWithTypeIdentifierAndSerialNumber

(identifier, serailNumber); getPasses( )

Returns the passes in the user’s pass library.

Your app only has access to certain passes, based on its entitlements. Passes that your app doesn’t have access to are not returned. The ordering of the passes is not fixed; calling this method multiple times may return the same passes but in a different order.

Signature

JavaScript: <<PassObject>>.getPasses()

Return Values

Array

An array of com.kony.Pass objects.

Kony Studio API Developer's Guide

Version 3.1

Platform Availability

Available only on iOS

JavaScript Example var passbook1 = passbook1.getPasses(); removePass( )

Removes the pass from the user’s pass library. This method does nothing if your app doesn’t have the appropriate entitlement. The new pass replaces the existing pass with the same pass type identifier and serial number. If there is no such pass in the user’s pass library, the replacement fails.

Signature

JavaScript

: <<PassObject>>.removePass()

Input Parameters l identifier [String] - Mandatory

The pass’s pass type identifier.

l serailNumber [String]

The pass’s serial number.

Return Values

None

Platform Availability

Available only on iOS

JavaScript Example passbook1.removePass(identifier, serailNumber);

Kony Studio API Developer's Guide

Version 3.1

replacePassWithPass( )

Replaces a pass in the user’s pass library with the given pass.

Signature

JavaScript : <<PassObject>>.replacePassWithPass()

Input Parameters l pass [Object] - Mandatory

The new pass.

Return Values

Boolean

True if the pass was replaced successfully; otherwise false.

Platform Availability

Available only on iOS

JavaScript Example passbook1.replacePassWithPass(pass);

...

var passbook1 = passbook1.replacePassWithPass(pass);

Kony Studio API Developer's Guide

Version 3.1

3.1.44.6 com.kony.PeripheralManager

A Peripheral Manager object is used to manage published services within the local peripheral device’s

Generic Attribute Profile (GATT) database and to advertise these services to central devices. If a service is in the database, it is visible and can be accessed by any connected central. If your application does not have the specified Bluetooth-peripheral background mode, the contents of its services become disabled when it is in the background or in a suspended state. Any remote central trying to access the service’s characteristic value or characteristic descriptors receives an error.

Before you call Peripheral Manager methods, the state of the peripheral manager object must be powered ON, as indicated by the PeripheralManagerStatePoweredOn. This state indicates that the peripheral device (for example, your iPhone or iPad) supports Bluetooth low energy, and Bluetooth is switched ON and available to use. Peripheral Manager is used for turning iOS device into iBeacon.

The com.kony.PeripheralManager class has the following APIs: l

authorizationStatus( )

isAdvertising( )

startAdvertisingWithMeasuredPower( )

stopAdvertising( )

Here is an example to create a new Peripheral Manager object.

var BeaconRegion1= new com.kony.PeripheralManager();

Here is an example to create a PeripheralManager with callbacks: var peripheralManager = new com.kony.PeripheralManager

(stateUpdatedCallback,advertisingStatusCallback);

Kony Studio API Developer's Guide

Version 3.1

Input Parameters l stateUpdatedCallback [Function] - Optional

To get updated callback state from the Peripheral Manager o peripheralManagerState [String ] - Can represent one of the following values: n

PeripheralManagerStatePoweredOff - Indicates Bluetooth is currently powered off.

PeripheralManagerStatePoweredOn - Indicates Bluetooth is currently powered on.

PeripheralManagerStateResetting - The connection with the system service was momentarily lost. An update will occur.

PeripheralManagerStateUnauthorized - The app is not authorized to use the

Bluetooth low energy peripheral or server role.

PeripheralManagerStateUnknown - The current state of the peripheral manager is unknown. An update will occur.

PeripheralManagerStateUnsupported - The platform does not support the

Bluetooth low energy peripheral or server role.

function stateUpdatedCallback (peripheralManagerState){} l advertisingStatusCallback [Function] - Optional

To get the status callback of advertising from the Peripheral Manager.

o errorName [String] - Name of the error if error occurrs, null otherwise.

o errorInfo [Object] - Information about the error if error occurs, null otherwise.

function advertisingStatusCallback (errorName, errorInfo){}

Kony Studio API Developer's Guide

Version 3.1

Return Values

Object - com.kony.PeripheralManager

Platform Availability

Available only on iOS.

authorizationStatus( )

The authorization status of an application is managed by the system and determined by several factors. Applications must be clearly authorized to share data using Bluetooth services while in the background state. The system automatically displays a request for user authorization when your app first attempts to use Bluetooth services to share data.

Calling this method does not prompt the user for access. Instead, you can use this method to detect restricted access and simply hide any affected UI features from the user.

Signature

JavaScript

: <<PeripheralObject>>.authorizationStatus( )

Input Parameters

None

Return Values

String

Returns any one of the following values: l

PeripheralManagerAuthorizationStatusDetermined - The user has made a choice regarding whether this application can share data using Bluetooth services while in the background state.

PeripheralManagerAuthorizationStatusRestricted - This application is not authorized to share data using Bluetooth services while in the background state. The user cannot change this application's status, possibly due to active restrictions such as parental controls.

Kony Studio API Developer's Guide

Version 3.1

PeripheralManagerAuthorizationStatusDenied - The user clearly denied this app from sharing data using Bluetooth services while in the background state.

PeripheralManagerAuthorizationStatusAuthorized - This application is authorized to share data using Bluetooth services while in the background state.

Platform Availability

Available only on iOS.

JavaScript Example var authorizationStatus1 = PeripheralManager1.authorizationStatus

(); isAdvertising( )

To determine if the Peripheral Manager is currently advertising data.

Signature

JavaScript

: <<PeripheralObject>>.isAdvertising( )

Input Parameters

None

Return Values

Boolean

Platform Availability

Available only on iOS.

JavaScript Example var isAdvertising1 = PeripheralManager1.isAdvertising();

Kony Studio API Developer's Guide

Version 3.1

startAdvertisingWithMeasuredPower()

Starts advertising beacon data with Measured Power.

Signature

JavaScript : <<PeripheralObject>>.startAdvertisingWithMeasuredPower()

Input Parameters l beaconRegion [Object] - com.kony.BeaconRegion

A Beacon Region whose data is to be advertised.

l measuredPower [Number] - Optional

The Received Signal Strength Indicator (RSSI) value (measured in decibels) for the device.

This value represents the measured strength of the beacon from one meter away and is used during ranging. Specify null to use the default value for the device.

Return Values

None

Platform Availability

Available only on iOS.

JavaScript Example

PeripheralManager1.startAdvertisingWithMeasuredPower(beaconRegion, measuredPower); stopAdvertising( )

Stops advertising Peripheral Manager data.

Signature

JavaScript

: <<PeripheralObject>>.stopAdvertising( )

Kony Studio API Developer's Guide

Version 3.1

Input Parameters

None

Return Values

None

Platform Availability

Available only on iOS.

JavaScript Example var stopAdvertising1 = PeripheralManager1.stopAdvertising();

3.2 DeviceInfo Object

The DeviceInfo object is a hash table in JavaScript and with the following keys: l

The following return values are available on all platforms: o 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.

o 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.

o deviceid: The unique device identifier. The following are the device IDs returned by the platforms:

Kony Studio API Developer's Guide

Version 3.1

BlackBerry: PIN (Personal Identification Number) l

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.

For iOS 7 and above, this API returns a fixed value 02:00:00:00:00:00 l

Android: Returns the unique device ID, for example, the IMEI for GSM and the

MEID or ESN for CDMA phones. Return null if device ID is not available. Set the following permission in the Android Manifest file: READ_PHONE_STATE to view the device ID. For more information, http://developer.android.com/reference/android/telephony/TelephonyManager.html

#getDeviceId().

SERIAL_NO: If Device ID is not present in any of the devices such as tablets, SERIAL Number of the device is returned for the devices with

Android version greater than 2.2. A hardware serial number, if available.

Alphanumeric only, case-insensitive. For more information refer, http://developer.android.com/reference/android/os/Build.html#SERIAL.

ANDROID_ID: If both are not present then ANDROID_ID is returned as a device-id. A 64-bit number (as a hex string) that is randomly generated on the device's first boot and should remain constant for the lifetime of the device.

(The value may change if a factory reset is performed on the device.) For more information refer, http://developer.android.com/reference/android/provider/Settings.Secure.ht

ml#ANDROID_ID o customdeviceid: l

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.

For iOS 7 and above, this property returns a fixed value 02:00:00:00:00:00.

Kony Studio API Developer's Guide

Version 3.1

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.

o 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 only applicable for iOS 6 and above.

o name: Specifies the name of the platform as iPhone, iPad, blackberry,Windows

Phone, thin client (The name thin client is used for SPA/ Desktop Web / Mobile

Web), Android, and J2ME.

o model: Specifies the model number of the platform. For example 8900 etc. Not applicable for Mobile Web.

o version: Specifies the version of the platform in a string format Not applicable for

Mobile Web.

o deviceWidth: The device width in pixels Valid only on Native Apps channels and not applicable for Mobile Web.

Kony Studio API Developer's Guide

Version 3.1

o deviceHeight: The device height in pixels Valid only on Native Apps channels and not applicable for Mobile Web.

o channel for all platforms.

API Level: Provides the Android API Level based on the SDK Version.The following are the mappings between Android SDK Version and the API Level that is returned: o

SDK 1.5 3 o

SDK 1.6 -

4 o

SDK 2.1 7 o

SDK 2.2 8 o

SDK 2.3 9 o

SDK 2.3.3 10 o

SDK 3.0 -

Note:

The API Level is returned only for Android.

For Mobile Web, the following values are returned: o type [String] - Specifies if the Mobile Web is Advanced or Basic.

o category [String] - Provides the Mobile Web category.

For Advanced Mobile Web, the return value can be iPhone, Android, or Palm.

o tcsession [String] - Provides the session ID of the current user.

o imagecat [String] - Image category based on the device width available in Kony Device

Database or returns a default value.

3.2.1 Methods

The DeviceInfo object provides the following methods.

Kony Studio API Developer's Guide

Version 3.1

3.2.1.1 DeviceInfo.httpheaders

This API returns the http headers configured in the HTTP request object.

Signature

JavaScript : <DeviceInfoObject>.httpheaders

Input Parameters

None.

Return Values value[Object]

A hash table of httpheaders with keys as the header name and values as the header value.

Platform Availability

Available only on SPA.

JavaScript Example kony.print(kony.os.deviceInfo().httpheaders);

//prints the array of http headers

3.3 FormData Object

The FormData object represents an ordered collection of entries with name-value pairs.

To create a FormData object, follow this: var httpinputparams1 = new kony.net.FormData()

Kony Studio API Developer's Guide

Version 3.1

3.3.1 Methods

The FormData object supports the following methods.

3.3.1.1 append

This API appends the specified entry to the collection of the FormData object.

Signature

JavaScript

:<<formobject>>.append(

name , value

)

Input Parameters name [string] - Mandatory

The name of the entry to be added to the collection.

value [string] - Mandatory

The value of the entry to be added to the collection.

Return Values

None

Platform Availability

Available on all platforms except Windows and SPA.

JavaScript Example function sendbeforeopen()

{ try{ var request = new kony.net.HttpRequest(); glob_req = request;

.....

Kony Studio API Developer's Guide

Version 3.1

var frmData= new kony.net.FormData(); frmData.append("param1","KONY LABS");

}catch(ex){ frmSend.responseTA.text=ex.message;

}

Consolidated Working Example var glob_req; function notimeoutset()

{ var request = new kony.net.HttpRequest(); glob_req=request; request.open(constants.HTTP_METHOD_GET,

"http://ws.geonames.org/weatherIcaoJSON?ICAO=KMCO"); request.send();

} function timeoutsettozero()

{ try{ var request = new kony.net.HttpRequest(); glob_req=request; request.timeout=0; request.open(constants.HTTP_METHOD_GET,

"http://ws.geonames.org/weatherIcaoJSON?ICAO=KMCO"); request.send();

}catch(ex){ frmtimeout.resultTA.text=ex.message();

}

} function timeoutset()

Kony Studio API Developer's Guide

Version 3.1

{ try{ var request = new kony.net.HttpRequest(); glob_req=request; request.timeout=5000;

//request.open(constants.HTTP_METHOD_GET,

"http://ws.geonames.org/weatherIcaoJSON?ICAO=KMCO"); request.open(constants.HTTP_METHOD_GET,

"www.planetsoft.com"); request.send();

}catch(ex){ frmtimeout.resultTA.text=ex.message();

}

} function syncnotimeoutset()

{ var request = new kony.net.HttpRequest(); glob_req=request; request.open(constants.HTTP_METHOD_GET,

"http://ws.geonames.org/weatherIcaoJSON?ICAO=KMCO",false); request.send();

} function synctimeoutsettozero()

{ try{ var request = new kony.net.HttpRequest(); glob_req=request; request.timeout=0;

Kony Studio API Developer's Guide

Version 3.1

request.open(constants.HTTP_METHOD_GET,

"http://ws.geonames.org/weatherIcaoJSON?ICAO=KMCO",false); request.send();

}catch(ex){ frmtimeout.resultTA.text=ex.message();

}

} function synctimeoutset()

{ try{ var request = new kony.net.HttpRequest(); glob_req=request; request.timeout=5000;

//request.open(constants.HTTP_METHOD_GET,

"http://ws.geonames.org/weatherIcaoJSON?ICAO=KMCO",false); request.open(constants.HTTP_METHOD_GET,

"www.planetsoft.com",false); request.send();

}catch(ex){ frmtimeout.resultTA.text=ex.message();

}

} function synctimeoutsethigh()

{ try{ var request = new kony.net.HttpRequest(); glob_req=request;

Kony Studio API Developer's Guide

Version 3.1

request.timeout=5000; request.open(constants.HTTP_METHOD_GET,

"http://ws.geonames.org/weatherIcaoJSON?ICAO=KMCO",false); request.send();

}catch(ex){ frmtimeout.resultTA.text=ex.message();

}

} function timeoutsethigh()

{ try{ var request = new kony.net.HttpRequest(); glob_req=request; request.timeout=null; request.open(constants.HTTP_METHOD_GET,

"http://ws.geonames.org/weatherIcaoJSON?ICAO=KMCO"); request.send();

}catch(ex){ frmtimeout.resultTA.text=ex.message();

}

} function timeoutStatusClick(){ frmtimeout.statusCd.text=glob_req.status; frmtimeout.StatusTxt.text=glob_req.statusText; frmtimeout.responseType.text=glob_req.responseType; frmtimeout.resultTA.text=glob_req.response; frmtimeout.readyState.text=glob_req.readyState;

} function statusText()

Kony Studio API Developer's Guide

Version 3.1

{ var request = new kony.net.HttpRequest(); glob_req = request; request.open(constants.HTTP_METHOD_GET,

"http://ws.geonames.org/weatherIcaoJSON?ICAO=KMCO"); frmStatus.statusLabel.text=request.status; frmStatus.statusTextLabel.text=request.statusText; request.send();

} function errorStatusText()

{ var request = new kony.net.HttpRequest(); glob_req = request; request.onReadyStateChange=statusreceived; request.open(constants.HTTP_METHOD_GET,

"http://10.10.5.19:9090/middleware/version1.html"); frmStatus.statusLabel.text=request.status; frmStatus.statusTextLabel.text=request.statusText; request.send();

} function statBtnClick(){ frmStatus.statusAfterSend.text=glob_req.status; frmStatus.statusTextAfterSend.text=glob_req.statusText; frmStatus.readyState.text=glob_req.readyState;

} function statusreceived(){ if(this.readyState == constants.HTTP_READY_STATE_HEADERS_

Kony Studio API Developer's Guide

Version 3.1

RECEIVED){ frmStatus.statusLabel.text=this.status;

}

} function jsonResponseType()

{ var request = new kony.net.HttpRequest(); request.open(constants.HTTP_METHOD_GET,

"http://ws.geonames.org/weatherIcaoJSON?ICAO=KMCO"); request.send(); frmResponseType.respTypeLabel.text=request.responseType;

} function xmlResponseType()

{ var request = new kony.net.HttpRequest(); request.open(constants.HTTP_METHOD_GET,

"http://feeds.foxnews.com/foxnews/health"); request.send(); frmResponseType.respTypeLabel.text=request.responseType;

} function rawDataResponseType()

{ var request = new kony.net.HttpRequest(); request.open(constants.HTTP_METHOD_GET,

"http://ilabs.uw.edu/sites/default/files/sample_0.pdf"); request.send(); frmResponseType.respTypeLabel.text=request.responseType;

} function textDataResponseType()

{ var request = new kony.net.HttpRequest();

Kony Studio API Developer's Guide

Version 3.1

request.open(constants.HTTP_METHOD_GET,

"http://10.10.5.19:9090/middleware/version.html"); request.send(); frmResponseType.respTypeLabel.text=request.responseType;

} function readyState1()

{ var request = new kony.net.HttpRequest(); request.onReadyStateChange=callbackHandler1; request.open(constants.HTTP_METHOD_GET,

"http://ws.geonames.org/weatherIcaoJSON?ICAO=KMCO"); request.send();

} function readyStateSync()

{ var request = new kony.net.HttpRequest(); request.onReadyStateChange=callbackHandler1; request.open(constants.HTTP_METHOD_GET,

"http://ws.geonames.org/weatherIcaoJSON?ICAO=KMCO",false); request.send();

} function callbackHandler1(){ frmReadyState.readyStateLabel.text=frmReadyState.readyStateLabel.tex

t+","+request.readyState; if(request.readyState == constants.HTTP_READY_STATE_HEADERS_

RECEIVED){ frmReadyState.responseHeadersTA.text=request.getAllResponseHeaders

Kony Studio API Developer's Guide

Version 3.1

(); frmReadyState.headerValue.text=request.getResponseHeader

("Date");

}else if(request.readyState == constants.HTTP_READY_STATE_

DONE){ frmReadyState.responseTA.text=request.response;

}

} function onreadyStateChng()

{ var request = new kony.net.HttpRequest(); request.onReadyStateChange=onreadStateHandler1; request.open(constants.HTTP_METHOD_GET,

"http://ws.geonames.org/weatherIcaoJSON?ICAO=KMCO"); request.send();

} function onreadStateHandler1(){ frmReadyState.readyStateLabel.text=frmReadyState.readyStateLabel.tex

t+","+request.readyState; if(request.readyState == constants.HTTP_READY_STATE_HEADERS_

RECEIVED){ frmReadyState.responseHeadersTA.text=request.getAllResponseHeaders; request.onReadyStateChange=onreadStateHandler2;

}else if(request.readyState == constants.HTTP_READY_STATE_

DONE){ frmReadyState.responseTA.text=request.response;

}

Kony Studio API Developer's Guide

Version 3.1

} function onreadStateHandler2(){ frmReadyState.ovrdlabel.text = "FROM OVERRIDE CALL BACK

METHOD"; frmReadyState.readyStateLabel.text=frmReadyState.readyStateLabel.tex

t+","+request.readyState; if(request.readyState == constants.HTTP_READY_STATE_HEADERS_

RECEIVED){ frmReadyState.responseHeadersTA.text=request.getAllResponseHeaders; request.onReadyStateChange=onreadStateHandler2;

}else if(request.readyState == constants.HTTP_READY_STATE_

DONE){ frmReadyState.responseTA.text=request.response;

}

} function setReqHeader()

{ var request = new kony.net.HttpRequest(); request.open(constants.HTTP_METHOD_GET,

"http://ilabs.uw.edu/sites/default/files/sample_0.pdf"); request.send(); request.setRequestHeader("From","[email protected]");

} function getResponseHeaderValid()

{ var request = new kony.net.HttpRequest();

Kony Studio API Developer's Guide

Version 3.1

request.onReadyStateChange=getHeaderValue; request.open(constants.HTTP_METHOD_GET,

"http://ws.geonames.org/weatherIcaoJSON?ICAO=KMCO"); request.send();

} function InValidgetResponseHeader()

{ var request = new kony.net.HttpRequest(); request.onReadyStateChange=getHeaderValue; request.open(constants.HTTP_METHOD_GET,

"http://ws.geonames.org/weatherIcaoJSON?ICAO=KMCO"); request.send();

} function getResponseHeaderBfrSend()

{ var request = new kony.net.HttpRequest();

//request.onReadyStateChange=getHeaderValue; request.open(constants.HTTP_METHOD_GET,

"http://ws.geonames.org/weatherIcaoJSON?ICAO=KMCO"); frmResponseHeaders.headerValue.text=request.getResponseHeader

("Date"); request.send();

} function getSetCookie()

{ var request = new kony.net.HttpRequest(); request.open(constants.HTTP_METHOD_GET,

"http://ws.geonames.org/weatherIcaoJSON?ICAO=KMCO"); request.send(); frmResponseHeaders.headerValue.text=request.getResponseHeader

Kony Studio API Developer's Guide

Version 3.1

("Set-Cookie");

} function getheaderclick()

{ frmResponseHeaders.headerValue.text=request.getResponseHeader

("Set-Cookie");

} function getHeaderValue()

{ if(this.readyState == constants.HTTP_READY_STATE_HEADERS_

RECEIVED){ frmResponseHeaders.headerValue.text=this.getResponseHeader("Date"); frmResponseHeaders.InvalidHeaderlb.text=this.getResponseHeader

("Date11");

}

} function redirectService()

{ var request = new kony.net.HttpRequest(); glob_req=request; request.open(constants.HTTP_METHOD_GET,

"http://10.10.5.19:9090/HttpRequestStub/ServiceStub?testCase_

id=redirect_tc"); request.send();

}

Kony Studio API Developer's Guide

Version 3.1

function redirectResultClick(){ frmRedirects.redirectStatus.text=glob_req.status; frmRedirects.redirectResponseType.text=glob_ req.responseType; frmRedirects.redirectresultTA.text=glob_req.response;

}

3.4 HttpRequest Object

The HttpRequest object is used in conjunction with functions in the

kony.net namespace

to send requests to any resource on the network and fetch the response.

3.4.1 Methods

The HttpRequest object supports the following methods.

3.4.1.1 abort

This cancels the network operation . If the abort is successful in canceling the send request, the readyState is set to UNSENT. Otherwise, the readyState is set to Done.

Signature

JavaScript : <<HttpRequestObject>>.abort()

Input Parameters

None.

Return Values

None.

Kony Studio API Developer's Guide

Version 3.1

Platform Availability

Available on all platforms except Windows and SPA.

JavaScript Example var request = new kony.net.HttpRequest();

...

request.abort();

3.4.1.2 getAllResponseHeaders

This API returns all headers using the response for a given header, except the fields with names Set-

Cookie or Set-Cookie2.

Signature

JavaScript : <<HttpRequestObject>>.getAllResponseHeaders()

Input Parameters

None.

Return Values

Object

The header field name and the value map object.

If the readyState is UNSENT, OPENED, or any of the failure case, null is returned.

Kony Studio API Developer's Guide

Version 3.1

Platform Availability

Available on all platforms except Windows and SPA.

JavaScript Example var request = new kony.net.HttpRequest() print(request.getAllResponseHeaders());

3.4.1.3 Constants

The constants used by HttpRequest APIs are: l constants.HTTP_RESPONSE_TYPE_TEXT

l constants.HTTP_RESPONSE_TYPE_JSON

l constants.HTTP_RESPONSE_TYPE_DOCUMENT

l constants.HTTP_RESPONSE_TYPE_RAWDATA

l constants.HTTP_READY_STATE_UNSENT = 0 l constants.HTTP_READY_STATE_OPENED = 1 l constants.HTTP_READY_STATE_HEADERS_RECEIVED = 2 l constants.HTTP_READY_STATE_LOADING = 3 l constants.HTTP_READY_STATE_DONE = 4 l constants.HTTP_METHOD_GET

l constants.HTTP_METHOD_POST

The delete quotes values are mapped to the corresponding http contentType as below:

ResponseType HTTP ContentType

Kony Studio API Developer's Guide

Version 3.1

constants.HTTP_RESPONSE_TYPE_

TEXT constants.HTTP_RESPONSE_TYPE_

JSON constants.HTTP_RESPONSE_TYPE_

DOCUMENT constants.HTTP_RESPONSE_TYPE_

RAWDATA application/text, text/plain application/json application/xml, text/xml, text/html, mime type that ends with +xml

Type except the above values

3.4.1.4 getResponseHeader

This API returns the header field value using the response for a given header, unless the header field name is Set-Cookie or Set-Cookie2.

Signature

JavaScript

:<<HttpRequestObject>>.getResponseHeader(

headerfield

)

Input Parameters headerfield [string] - Mandatory

The name of the header field.

Return Values string - header field value.

If the readyState is UNSENT, OPENED, or any of a failure case, null is returned.

Kony Studio API Developer's Guide

Version 3.1

Platform Availability

Available on all platforms except Windows and SPA.

JavaScript Example var request = new kony.net.HttpRequest() request.getResponseHeader("Date");

3.4.1.5 open

This method initializes the http request object with a request method type (GET or POST) and the url.

If this method is invoked after send(), it should terminate the current send() request.

Signature

JavaScript : <<HttpRequestobject>>.open(

requestMethod

url , async ,

username , password )

Input Parameters requestMethod [string]- Mandatory

For the http request method, the possible values are: l constants.HTTP_METHOD_GET

l constants.HTTP_METHOD_POST

l case-insensitive match to GET or POST string.

url [string] - Mandatory

The request URL string with character encoded UTF-8.

async [Boolean] - Optional

Sets request type as asynchronous or synchronous. Default value true that is asynchronous.

Kony Studio API Developer's Guide

Version 3.1

Note:

This parameter is ignored for SPA and only supports asynchronous.

username [string] - Optional

Configure the user credentials for basic authentication.

password [string] - Optional

Configure the user credentials for basic authentication.

Return Values

None.

Exceptions

SyntaxError - if the requestMethod is not valid or url cannot be resolved.

Platform Availability

Available on all platforms except Windows and SPA.

JavaScript Example var request = new kony.net.HttpRequest(); request.open(constants.HTTP_METHOD_GET,

"http://ws.geonames.org/weatherIcaoJSON?ICAO=KMCO");

3.4.1.6 send

This methods initiates a request.

Signature

JavaScript :<<HttpRequestObject>>.send(

data )

Kony Studio API Developer's Guide

Version 3.1

Input Parameters data [kony.net.FormData] - Optional

An optional argument specifying the input parameter data along with a request. This parameter is ignored if the request type is GET or HEAD.

Note: send() handles the redirection headers automatically, that is http status codes 301,

302, 303, or 307.

Return Values

None.

Exceptions

InvalidStateError - if this method is called before an open() API call and or after the send() API is called more than once.

Network or DNA errors generate an http status code such as 410 and raise the HEADERS_

RECEIVED state change event.

Platform Availability

Available on all platforms except Windows and SPA.

JavaScript Example var request = new kony.net.HttpRequest();

...

request.send();

3.4.1.7 setRequestHeader

This appends a header to the list of http request headers.

Kony Studio API Developer's Guide

Version 3.1

Note:

You must sanitize the data such as user input or http response before setting them as http header values. If the data is not sanitized it can lead to various types of header manipulation attacks such as an

HTTP response splitting attack, cross-site scripting, browser hijacking, cookie manipulation, and crossuser defacement.

Signature

JavaScript :<<HttpRequestObject>>.setRequestHeader(

header

value )

Input Parameters header [string]- Mandatory

The header name.

value [string] - Mandatory

The value of the header.

Return Values

None.

Exceptions

InvalidStateError - if this method is called before the open() API call and or after the send() API call.

Note: If this method is called twice on a header, then the values are appended by comma with a space delimiter.

Kony Studio API Developer's Guide

Version 3.1

Platform Availability

Available on all platforms except Windows and SPA.

JavaScript Example var request = new kony.net.HttpRequest();

...

request.setRequestHeader("From","[email protected]");

3.5 kony Namespace

The kony namespace provides the following API elements.

Functions

3.5.1 Functions

The kony namespace provides the following functions.

3.5.1.1 kony.convertToBase64

This API provides you the ability to convert rawbytes (returned by the camera or the encryption API) to a base64 encoded string.

Use Cases

The rawbytes returned by the camera or the encryption API are a set of junk characters that are not readable. When you want to display this data in a readable format to the user, you can use this API.

Signature

JavaScript

: kony.convertToBase64 ( rawbytes )

Kony Studio API Developer's Guide

Version 3.1

Input Parameters rawbytes [userData]: The datatype for the rawbytes differs per platform]- Mandatory

The rawbytes that you want to convert to an encoded base64 string. These rawbytes can be those that are returned from a camera or the encryption API.

Return Values mybase64String [String]

The encoded base64 string that was converted from the provided rawbytes. This converted encoded base64 string can be displayed on the screen to the user whenever required as this string is readable.

null/nil

JavaScript returns null null/nil is returned if the rawbytes cannot be converted to base64 string or the provided input is not of type rawbytes.

Exceptions

An error is thrown if the input type is invalid or follows an unexpected structure.

102-Invalid input error

Platform Availability

Available on all platforms except Desktop Web and Server Side Mobile Web.

JavaScript Example var base64

="MIICKTCCAZKgAwIBAgIESrI6bzANBgkqhkiG9w0BAQUFADBZMQswCQYDVQQGEwJp

Kony Studio API Developer's Guide

Version 3.1

bjELMAkGA1UECBMCYXAxDDAKBgNVBAcTA2h5ZDENMAsGA1UEChMEa29ueTENMAsGA1UE

CxMEa29ue

TERMA8GA1UEAxMIcGF0dGFiaGkwHhcNMDkwOTE3MTMzMjMxWhcNMDkxMjE2MTMzMjMxW jBZMQswCQ

YDVQQGEwJpbjELMAkGA1UECBMCYXAxDDAKBgNVBAcTA2h5ZDENMAsGA1UEChMEa29ueT

ENMAsGA1U

ECxMEa29ueTERMA8GA1UEAxMIcGF0dGFiaGkwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIG

JAoGBAIGP dqCQCtFgsy1sM494o1F07aN+UXgsilTuKsNRExOb03RGrg2WpAI8PqMXD1XzGZAg+qC9 iQexpWHUj

XgCYCbYrETvB3wNAToOrRE6mhZ0iaJij/0tLZACocLiTnvmzZU1B/xowvlioD3zsEs5N

5n0U0fIsv

W/22MZ6WtZuAZTAgMBAAEwDQYJKoZIhvcNAQEFBQADgYEAXfOB1Mhx2R9ameeZz0hvCz

YYSGcWsWN

ZaM7lMdBHFPzASYcVrmLj7JlLpuMm679A2p2JwXBsfetmhKse1ixqVeWdbe/FUfESU+8

Krdvkcknv

ZaDqXYFxQAaVjTwWOn+zcDHf7LjjDohgDsMOJWXHkVQj2jooXqiktrBrpccm864="; var rawBytes = kony.convertToRawBytes(base64); var newbase64 = kony.convertToBase64(rawBytes);

3.5.1.2 kony.convertToRawBytes

This API provides you the ability to read rawbytes from a base 64 encoded string.

Signature

JavaScript: kony.convertToRawBytes(

base64String

)

Kony Studio API Developer's Guide

Version 3.1

Input Parameters base64String [String]- Mandatory.

The base64 encoded string from which you want to read the rawbytes.

Return Values

This API returns the modified rawbytes of the image.

rawbytes - Userdata.

The datatype of the rawbytes varies per platform. In JavaScript, there is no specific type for rawbytes and every platform represent the rawbytes in a unique way.

null/nil null/nil is returned if the input is not a base64 encoded string

Exceptions

An error occurs if input type is invalid or does not follow the expected structure.

Platform Availability

Available on all platforms except Desktop Web and Server Side Mobile Web. On SPA, reading base64 from an image src is not supported, but you can read the base64 from an image which is displayed through base64.

JavaScript Example var base64

="MIICKTCCAZKgAwIBAgIESrI6bzANBgkqhkiG9w0BAQUFADBZMQswCQYDVQQGEwJpbj

ELMAkGA1UECBMCYXAxDDAKBgNVBAcTA2h5ZDENMAsGA1UEChMEa29ueTENMAsGA1UECx

MEa29ueTERMA8GA1UEAxMIcGF0dGFiaGkwHhcNMDkwOTE3MTMzMjMxWhcNMDkxMjE2MT

MzMjMxWjBZMQswCQYDVQQGEwJpbjELMAkGA1UECBMCYXAxDDAKBgNVBAcTA2h5ZDENMA sGA1UEChMEa29ueTENMAsGA1UECxMEa29ueTERMA8GA1UEAxMIcGF0dGFiaGkwgZ8wDQ

Kony Studio API Developer's Guide

Version 3.1

YJKoZIhvcNAQEBBQADgY0AMIGJAoGBAIGPdqCQCtFgsy1sM494o1F07aN+UXgsilTuKs

NRExOb03RGrg2WpAI8PqMXD1XzGZAg+qC9iQexpWHUjXgCYCbYrETvB3wNAToOrRE6mh

Z0iaJij/0tLZACocLiTnvmzZU1B/xowvlioD3zsEs5N5n0U0fIsv

W/22MZ6WtZuAZTAgMBAAEwDQYJKoZIhvcNAQEFBQADgYEAXfOB1Mhx2R9ameeZz0hvCz

YYSGcWsWNZaM7lMdBHFPzASYcVrmLj7JlLpuMm679A2p2JwXBsfetmhKse1ixqVeWdbe

/FUfESU+8Krdvkcknv

ZaDqXYFxQAaVjTwWOn+zcDHf7LjjDohgDsMOJWXHkVQj2jooXqiktrBrpccm864="; kony.convertToBase64(myVal) var rawBytes = kony.convertToRawBytes(base64);

3.5.1.3 kony.getError

This API uses the handle to the error object and returns the actual error object.

Signature

JavaScript : kony.getError(

error )

Input Parameters error-[Error] / [object/handle] - Mandatory

The input parameters of this API is either the Original Error object or a handle received in try/catch block.

Return Values

Returns the JavaScript error object.

Exceptions

If the input type is invalid or there is an unexpected structure.

Special considerations:

Use getError APIs for cross platform applications to handle exceptions consistently.

Kony Studio API Developer's Guide

Version 3.1

Platform Availability

Available on all platforms except BlackBerry 10, Windows 8 and Windows 7 / Kiosk.

JavaScript Example try

{

// Label to check UserData Type.

} catch ( e )

{ var err = kony.getError(e); if (err instanceof KonyError) alert("A Kony error"); else (err instanceof EvalError) alert("A JavaScript Eval Eror");

}

3.5.1.4 kony.props.getProperty

This API is used to access parameters from an external properties file. All the external properties files must be appended to the

<appID>.properties

file and be deployed at the following folder on the Kony Application Server:

Kony Studio API Developer's Guide

Version 3.1

<middlewarehome>\middleware\middlewarebootconfig\tc\<appID>.properties

Signature

JavaScript: kony.props.getProperty(

group , key

)

Input Parameters group - Mandatory

Current value is null for JavaScript, this parameter will be used and enhanced in the future.

key [String] - Mandatory

The key for which you want to access the value.

Return Values value [String]

The value that matches the given key null/nil null or nil is returned if there is no value matching the given input key in the

properties file

Platform Availability

Available on Mobile Web and SPA.

JavaScript Example frmhome.label103982946332169.text=kony.props.getProperty

(null,"key1");

Kony Studio API Developer's Guide

Version 3.1

3.5.1.5 kony.print

This API receives a string as an argument. If any other type of argument is passed a string representation of that input is passed. It prints the value to the Standard Output specific to the platform.

It prints their values to stdout, using the

tostring

function to convert them to strings. print is not intended for formatted output, but only as a quick way to show a value, typically for debugging. For formatted output, use

string.format

Note: To view the log in BlackBerry 10, see Viewing log for BlackBerry 10 section.

Signature

JavaScript

: kony.print(

myString )

Input Parameters myString[String] - Mandatory

Specifies the string to be printed

Return Values

None.

Platform Availability

Available on all platforms.

JavaScript Example kony.print ("This is a test message.");

3.5.1.6 kony.runOnMainThread

This API helps you run the JavaScript code on the main thread. It is an asynchronous API. It posts a message to the main thread to invoke a function f with parameters arguments.

Kony Studio API Developer's Guide

Version 3.1

Note:

If runonMainThread is invoked in a JavaScript function that is already running on the main thread, then the function is executed in synchronous mode.

Signature

JavaScript: kony.runOnMainThread (f, args)

Input Parameters f [Function] - Mandatory

Specifies the callback function that must be executed.

args [Array] - Mandatory

Specifies the JavaScript array that holds the parameters to be passed to function f.

Return Values

None

Platform Availability

Available on iOS platform

JavaScript Example

//Example to be added

3.5.1.7 kony.runOnWorkerThread

This API helps you run the JavaScript code on the worker thread. It is an asynchronous API. It posts a message to the worker thread that owns the current JavaScript context to invoke a function f with parameters arguments.

Kony Studio API Developer's Guide

Version 3.1

Note:

The assumption here is that main thread does not own any JavaScript context. The

VM/closure thread and worker threads own the JavaScript context. When the kony.runOnWorkerThread

is invoked from the main thread, a message is posted to the thread that originally invoked the kony.runOnMainThread. If the runonWorkerThread is invoked in a JavaScript function that is already running on the worker thread, then the function would be executed in synchronous mode.

Signature

JavaScript: kony.runOnWorkerThread (f, args)

Input Parameters f [Function] - Mandatory

Specifies the callback function that must be executed.

args [Array] - Mandatory

Specifies the JavaScript array that holds the parameters to be passed to f.

Return Values

None

Platform Availability

Available on iOS platform

3.5.1.8 kony.type

This API retrieves the data type of the specified input. The possible return values in JavaScript are: l string l number l boolean

Kony Studio API Developer's Guide

Version 3.1

l function l userdata - not JavaScript type but the platform specific type that platform returns and consumes like rawBytes.

In case of kony custom objects, this API returns the fully qualified name of the class from which object is instantiated. for e.g

kony.ui.Form2

l null

Use the typeof operator instead of kony.type to achieve the same result. If the typeof operator cannot be used, use kony.type instead.

Signature

JavaScript : kony.type(

variable )

Input Parameters variable [String] or [Number] or [Boolean] or [Function] - or [userdata] or nil/null - Mandatory

Specifies the value for which you want to retrieve the data type.

Return Values returnValue [String]

Returns a string that determines the data type of the specified input. Possible values are: l string this value is returned when you pass a string as the input parameter.

l number this value is returned when you pass a number as the input parameter.

l boolean this value is returned when you pass a boolean value as the input parameter.

l function this value is returned when you pass a function as the input parameter.

l userdata this value is returned when the input parameter is not a string, number, boolean or function.

Kony Studio API Developer's Guide

Version 3.1

Note:

Any data type which is not a string, number, boolean, or function is treated as userdata.

l null/nil this value is returned when the variable is assigned null/nil l

In case of kony custom objects, this API returns the fully qualified name of the class from which object is instantiated. for e.g

kony.ui.Form2

. When you pass any custom / built in

JSObject to this API, it should return the name of the custom JSObject.

Platform Availability

Available on all platforms.

JavaScript Example var myVal = 2000; var varType = kony.type(myVal);//Returns a number var myVal1= "hello"; var varType = kony.type(myVal1);//Returns a string

3.6 kony.accelerometer Namespace

The kony.accelerometer namespace provides both events and functions to manage and retrieve data from the device's accelerometer.

Events

Functions

Kony Studio API Developer's Guide

Version 3.1

3.6.1 Accelerometer Events

A developer can register and perform an appropriate action when a shake event occurs.

The shake event is generated by the platform.

Note: Currently, shake is the only event that is supported.

3.6.1.1 kony.accelerometer.registerAccelerationEvents

This API allows you to register for the acceleration events such as 'shake'. This event is triggered only at the end of the shake event indicating that device motion has occurred. The precision with which a shake event can be recognized may vary per platform and depends on the device capability. This is an asynchronous API.

Signature

JavaScript: kony.accelerometer.registerAccelerationEvents(

events )

Input Parameters events [Object] - Mandatory

Specifies a hash table with the type of events. This table has the following key-value pairs: l shake [Function] - Specifies a callback function with no arguments.

For example, {"shake":onshake} where function onshake ()

// write your logic here end;

Return Values

None.

Kony Studio API Developer's Guide

Version 3.1

Platform Availability

Available on all platforms except BlackBerry 10, SPA, Desktop Web, Windows 7/Kiosk, and Mobile

Web.

JavaScript Example

//Defining shake function function onshake()

{ kony.print("Shake called");

} function registerAccelerationEvents()

{

//register acceleration events

//Defining the event object var events = {shake:onshake};

//Registering Shake event kony.accelerometer.registerAccelerationEvents(events);

}

3.6.1.2 kony.accelerometer.unregisterAccelerationEvents

This API allows you to de-register for the specified acceleration event types. This is an asynchronous

API.

Kony Studio API Developer's Guide

Version 3.1

Signature

JavaScript : kony.accelerometer.unregisterAccelerationEvents(

eventTypes )

Input Parameters

JavaScript: eventTypes [Array] - Mandatory

Return Values

None.

Platform Availability

Available on all platforms except BlackBerry 10, SPA, Desktop Web, Windows 7/Kiosk, and Mobile

Web.

JavaScript Example function unregisteraccelerationevents()

{

//stop acceleration request kony.accelerometer.unregisteraccelerationevents({"shake"});

}

3.6.2 Accelerometer Functions

The kony.accelerometer namespace provides the following functions.

Kony Studio API Developer's Guide

Version 3.1

3.6.2.1 kony.accelerometer.retrieveCurrentAcceleration

This API allows you to retrieve the current device acceleration. The specified callback functions are invoked asynchronously and this API returns the value immediately without waiting for actual retrieval of the device acceleration data. This is an asynchronous API.

Signature

JavaScript: kony.accelerometer.retrieveCurrentAcceleration (

onSuccessCallback ,

onFailureCallback )

Input Parameters onSuccessCallback [Function] - Mandatory

Specifies the callback function that must be executed when retrieving the current device acceleration is successful.

The callback function has the following signature: onSuccessCallback(accelerometerdata) l accelerometerdata [Table] - This table has the following key-value pairs: o x [Number] - contains the x co-ordinate as a floating point value o y [Number] - contains the y co-ordinate as a floating point value o z [Number] - contains the z co-ordinate as a floating point value o timestamp [Number] - specifies the number of milli seconds elapsed since the start of the

Unix Epoch. The standard Unix Epoch is 00:00:00 UTC on 1 January 1970. The timestamp does not reflect the frequency at which the device can retrieve the accelerometer data, because the device capability (in terms of frequency) can vary from one platform to the other.

Kony Studio API Developer's Guide

Version 3.1

onFailureCallback [Function] - Mandatory

Specifies the callback function that must be executed when the API call fails in retrieving the current device location. This callback function does not have any input parameters.

You can define the logic that must be executed in this function.

Return Values

None.

Platform Availability

Available on all platforms except BlackBerry 10, SPA, Desktop Web, Windows 7/Kiosk, and Mobile

Web.

JavaScript Example

//retrieve current acceleration request

// onsuccesscallback

// This method accepts an 'accelerometerdata' object, which contains the current device acceleration values function onsuccesscallback(accelerometerdata)

{ kony.print("X: " + accelerometerdata.x +"Y: " + accelerometerdata.y

+"Z: " + accelerometerdata.z +"Timestamp: " + accelerometerdata.timestamp );

}

// onfailurecallback

Kony Studio API Developer's Guide

Version 3.1

function onfailurecallback(error)

{ kony.print("code: " + error.code +"message: " + error.message);

} function retrieveCurrentAcceleration()

{

// Current acceleration request.

kony.accelerometer.retrieveCurrentAcceleration (onsuccesscallback, onfailurecallback);

}

3.6.2.2 kony.accelerometer.startMonitoringAcceleration

This API allows you to start monitoring the device acceleration or motion. When there is a change in the device acceleration values when the device moves, the callback functions are invoked. The callback functions are invoked asynchronously and this API returns immediately without waiting for the device initialization for accelerometer. This is an asynchronous API.

Signature

JavaScript : kony.accelerometer.startMonitoringAcceleration

(

onSuccessCallback ,

onFailureCallback

configData )

Input Parameters onSuccessCallback [Function] - Mandatory

Specifies the callback function that must be executed when monitoring the device acceleration is successful.

The callback function has the following signature:

Kony Studio API Developer's Guide

Version 3.1

onSuccessCallback(accelerometerdata) l accelerometerdata [Table] - This table has the following key-value pairs: o x [Number] - contains the x co-ordinate as a floating point value o y [Number] - contains the y co-ordinate as a floating point value o z [Number] - contains the z co-ordinate as a floating point value o timestamp [Number] - specifies the number of milli seconds elapsed since the start of the

onFailureCallback [Function] - Mandatory

Specifies the callback function that must be executed when the API call fails. This callback function does not have any input parameters.

You can define the logic that must be executed in this function.

configData [Object] - Mandatory

Specifies the configuration parameters for the monitoring operation. This table has the following key-value pairs: l frequency [Number] - Specifies the time interval in which accelerometer data needs to be retrieved. The frequency is specified in milli seconds. For example, if the frequency is 2 milli seconds, the accelerometer data is retrieved after every 2 milli seconds.

The default value of frequency must be "200" milliseconds minimum. Any negative value specified in the frequency reverts to the default value i.e., 200ms.

l onchange [Boolean] - If this value is set to true, the number set in frequency is not respected and the onsucesscallback event is invoked whenever the device is in motion. If this value is set to false, the onsuccesscallback event is invoked in the

Kony Studio API Developer's Guide

Version 3.1

time interval specified in the frequency parameter is used. The Default value for onchange is false.

Note: If you set onchange as false, it is necessary to specify a frequency value or the onsuccesscallback function will never be invoked.

Return Values

None.

Platform Availability

Available on all platforms except BlackBerry 10, SPA, Desktop Web, Windows 7/Kiosk, and Mobile

Web.

JavaScript Example

//Start monitoring request

// onsuccesscallback

// This method accepts an 'accelerometerdata' object, which containsthe current device acceleration values function onsuccesscallback(accelerometerdata)

{ kony.print("X: " +accelerometerdata.x +"Y: " +accelerometerdata.y

+"Z:

" +accelerometerdata.z +"Timestamp: " +accelerometerdata.timestamp

);

}

Kony Studio API Developer's Guide

Version 3.1

//onfailure callback function onfailurecallback(error)

{ kony.print("code: " + error.code +"message: " + error.message);

} function startMonitoringAcceleration()

{

// Start monitor acceleration request.

kony.accelerometer.startMonitoringAcceleration(onsuccesscallback, onfailurecallback,{frequency:10, onchange:false});

}

3.6.2.3 kony.accelerometer.stopMonitoringAcceleration

This API allows you to stop the device monitoring activity if it is active. You can start monitoring the device motion using accelerometer.

startmonitoringacceleration API.

Signature

JavaScript: kony.accelerometer.stopMonitoringAcceleration()

Input Parameters

None.

Kony Studio API Developer's Guide

Version 3.1

Return Values

None

Platform Availability

Available on all platforms except BlackBerry 10, SPA, Desktop Web, Windows 7/Kiosk, and Mobile

Web.

JavaScript Example function stopMonitoringAcceleration()

{

//stop the device monitoring activity if it is active kony.accelerometer.stopMonitoringAcceleration();

}

Kony Studio API Developer's Guide

Version 3.1

3.7 kony.application Namespace

Functions

Objects

Kony Studio API Developer's Guide

Version 3.1

3.7.1 Functions

The kony.application namespace contains the following functions.

3.7.1.1 kony.application.addBMState

This API adds a specified key and value to the parameter list of the URL of the form.

Signature

JavaScript:

kony.application.addBMState ( formID

key

value )

Input Parameters formID [String] - Mandatory.

Identifier of the form to be bookmarked.

key [String] - Mandatory

Key string representing the LHS of the parameter.

value [String] - Mandatory

Value string representing the RHS of the key-value combination. The value can not be a nested structure.

Return Values

None.

Platform Availability

Supported for SPA and Desktop Web.

JavaScript Example

To set a bookmark for a URL, enter the following:

Kony Studio API Developer's Guide

Version 3.1

kony.application.addBMState ("form1", "About", "page2")

3.7.1.2 addGestureRecognizerForAllForms

This API allows the developers to set a gesture recognizer for the specified gesture of the specified widget.

Signature kony.application.addGestureRecognizerForAllForms (

gestureType

gestureConfigParams

onGestureClosure

)

Input Parameters gestureType [Number] - Mandatory

Indicates the type of gesture that needs to be detected on the widget. The following are possible values: l

1 – constants.GESTURE_TYPE_TAP

2 - constants.GESTURE_TYPE_SWIPE

3 – constants.GESTURE_TYPE_LONGPRESS

4 – constants.GESTURE_TYPE_PAN

5 – constants.GESTURE_TYPE_ROTATION

6 - constants.GESTURE_TYPE_PINCH

7 - constants.GESTURE_TYPE_RIGHTTAP

Note:

Kony Studio API Developer's Guide

Version 3.1

RIGHTTAP is applicable only to Windows 8.1 and Windows Desktop/Kiosk platforms.

ROTATION is not supported on Android.

gestureConfigParams [object] - Mandatory

Specifies a table that has the configuration parameters needed to setup a gesture recognizer. The configuration parameters vary based on the type of the gesture.

This parameter has the following key-value pairs:

Gesture Type:

TAP l fingers [Number] - specifies the maximum number of fingers that must be respected for a gesture. Possible values are: 1. Default value is 1.

l taps [Number] - specifies the maximum number of taps that must be respected for a gesture. Possible values are: 1 or 2. Default value is 1.

For example,{fingers:1,taps:1}

Gesture Type:

SWIPE l fingers [Number] - specifies the maximum number of fingers that must be respected for a gesture. Possible values are: 1. Default value is 1.

For example, {fingers: 1}.

Gesture Type : LONGPRESS l pressDuration [Number] - specifies the minimum time interval (in seconds) after which the gesture is recognized as a LONGPRESS. This is not applicable to

Windows.

For example, if the pressDuration is 2 seconds, any continued press is recognized as LONGPRESS only if it lasts for at least 2 seconds. Default value is 1.

For example, {pressDuration:1}.

Kony Studio API Developer's Guide

Version 3.1

Gesture Type :

PAN l fingers [number] specifies the minimum number of fingers needed to recognize this gesture. Default value is 1.

l continuousEvents [Boolean] indicates if callback should be called continuously for every change beginning from the time the gesture is recognized to the time it ends.

Gesture Type : ROTATION l

Rotation gesture involves only two fingers.

l continuousEvents [Boolean] indicates if callback must be called continuously for every change beginning from the time the gesture is recognized to the time it ends.

Gesture Type : PINCH l

Pinch gesture invloves two fingures.

l continuousEvents [Boolean] indicates if callback should be called continuously every change beginning from the time the gesture is recognized to the time it ends.

onGestureClosure [function] - Mandatory

Specifies the function that needs to be executed when a gesture is recognized. This function will be raised asynchronously and has the following signature: onGestureClosure(widgetRef, gestureInfo, context) l widgetRef - specifies the handle to the widget on which the gesture was recognized.

l gestureInfo - Table with information about the gesture. The contents of this table vary based on the gesture type.

l context - Table with SegmentedUI row details.

gestureInfo table has the following key-value pairs:

Kony Studio API Developer's Guide

Version 3.1

l gestureType [number] – indicates the gesture type; 1 for TAP, 2 for SWIPE, and 3 for

LONGPRESS,4 for PAN, 5 for ROTATION, 6 for PINCH and 7 for RIGHTTAP l gesturesetUpParams [object] – specifies the set up parameters passed while adding the gesture recognizer l gesturePosition [number] – indicates the position where the gesture was recognized.

Possible values are: 1 for TOPLEFT, 2 for TOPCENTER, 3 for TOPRIGHT, 4 for

MIDDLELEFT, 5 for MIDDLECENTER, 6 for MIDDLERIGHT, 7 for BOTTOMLEFT, 8 for

BOTTOMCENTER, 9 for BOTTOMRIGHT, 10 for CENTER l swipeDirection [number] –indicates the direction of swipe. This parameter is applicable only if the gesture type is SWIPE. Possible values are: 1 for LEFT, 2 for RIGHT, 3 for TOP, 4 for

BOTTOM. Direction is w.r.t the view and not device orientation.

l gestureX [number] – specifies the X coordinate of the point (in pixels) where the gesture has occurred. The coordinate is relative to the widget coordinate system.

l gestureY [number] – specifies the Y coordinate of the point (in pixels) where the gesture has occurred. The coordinate is relative to the widget coordinate system.

l widgetWidth [number] – specifies the width of the widget (in pixels) l widgetHeight [number] – specifies the height of the widget (in pixels) l gestureState[number] – indicates the gesture state as below l

1 – gesture state begin l

2 - gesture state changed l

3 – gesture state ended.

* gestureState is applicable only for continuous gestures like PAN, ROTATION and

PINCH.

l rotation [number] rotation of the gesture in degrees since its last change.( Applicable only when gesture type is ROTATION

Kony Studio API Developer's Guide

Version 3.1

l velocityX and velocityY : horizontal and vertical component of velocity expressed in points per second. (Applicable only for PAN gesture type) l velocity [number]: velocity of pinch in scale per second (Applicable for Pinch gesture) l scale [number]:scale factor relative to the points of the two touches in screen coordinates l touchType[number]:(windows only) l

0 - constants.TOUCHTYPE_FINGER

1 - constants.TOUCHTYPE_PEN

2 - constants.TOUCHTYPE_MOUSE

l translationX and translationY [number] : cumulative distance as number. (Applicable only for PAN gesture type) context table has the following key-value pairs: l rowIndex [number] : row index of the segui where gesture was recognised. (Applicable to gestures added to segUI rows) l sectionIndex [number] : section index of the segui where gesture was recognised.

(Applicable to gestures added to segUI rows)

Return Values

String - Reference to the gesture is returned.

JavaScript Example

//Defining a function function formGesture(widgetID,gestureInfo)

{ var y = kony.type(gestureInfo); //expected value of y = table var z = kony.type(gestureInfo.gesturesetUpParams); //expected values

Kony Studio API Developer's Guide

Version 3.1

of z = table var a = gestureInfo.gestureType; var b = gestureInfo.gesturesetUpParams; var c = gestureInfo.gesturePosition; var d = gestureInfo.gestureX; var e = gestureInfo.gestureY; var f = gestureInfo.widgetWidth; var g = gestureInfo.widgetHeight; kony.print("*******************************************"); if(kony.os.toNumber(gestureInfo.gestureType) == 2)

{ h = gestureInfo.swipeDirection; kony.print("swipe direction is: "+h);

} else{ h = ""

} if(kony.os.toNumber(a) == 1)

{ b1 = "fingers: "+gestureInfo.gesturesetUpParams.fingers; b2 = "taps: "+gestureInfo.gesturesetUpParams.taps; kony.print(""+b1+""+b2);

} else if(kony.os.toNumber(a) == 2)

{ b1 = "fingers :"+gestureInfo.gesturesetUpParams.fingers; b2 = ""; kony.print(""+b1+""+b2);

} else if(kony.os.toNumber(a) == 3)

{ b1 = "pressduration:"+gestureInfo.gesturesetUpParams

pressDuration;

Kony Studio API Developer's Guide

Version 3.1

b2 = ""; kony.print(""+b1+""+b2);

} kony.print("widget id is: "+widgetID[id]); //will print the widgetID.

To print widgetID use widgetID.id

kony.print("type of gestureInfo is: "+y); kony.print("type of gesturesetUpParams is: "+z); kony.print("gestureType is: "+a); //gestureType=1 or 2 or 3 kony.print("gesturesetUpParams is: "+b.fingers);

//gesturesetUpParams

= {fingers =1, taps =1} or {fingers =1, taps =2} or {fingers =1} or

{pressDuration = 1} kony.print("gesturePosition is: "+c); //gesturePosition=1 or 2 or 3 or .....9

kony.print("gestureX is: "+d); //ex: gestureX=30 kony.print("gestureY is: "+e); //ex: gestureY=100 kony.print("widgetWidth is: "+f); //ex: widgetWidth=320 kony.print("widgetHeight is: "+g); //ex: widgetHeight=28

//gesturePosition, gestureX, gestureY, widgetWidth, widgetHeight params are not applicable in android kony.print("*******************************************");

} function callbackSingleTapGesture()

{ var x ={fingers:1,taps:1}; try{ kony.application.setGestureRecognizerForAllForms(1, x, formGesture);

} catch(err){ alert(typeof err);

Kony Studio API Developer's Guide

Version 3.1

alert("error in function callbackSingleTapGesture:

"+err.message);

}

Platform Availability

Available on all platforms except Server Side Mobile Web, BlackBerry 10, Windows 7/Kiosk, and

Desktop Web.

3.7.1.3 kony.application.addSettingsMenuItemAt

This API enables you to add a menu item at a given index in the Charm settings menu.

Signature

JavaScript: kony.application.addSettingsMenuItemAt (

id , index

menuSettings

)

Input Parameters id [String] - Mandatory.

Identifier of the Charm setting menu created.

index [Number] - Mandatory.

The index at which the menu item must be added. The index value lies between 0 and n-1. If the index is beyond the current length of the Charm menu items then the item is added to the end.

menuSettings [Hash table] - Mandatory

The menuSettings hash table comprises the following key-value pairs l id: ID of the Charm menu item.

l text: Name of the menu item.

l onClick: onclick event to be executed for the menu item.

Kony Studio API Developer's Guide

Version 3.1

Return Values

None.

Platform Availability

Available on Windows 8.

JavaScript Example

To add a menu item at a given index, enter the following:

//The below function is the callback function for onClickClosure event of app menu item with id "appmenuitemid3".

function onClickClosure3()

{

//proceed with the logic

} var settingsMenuItem1 = {id : "about", text : "About", onClick : onClickClosure3};

//Adding the above app menu item at the index 3.

kony.application.addSettingsMenuItemAt("accountMenu", 3, settingsMenuItem1);

3.7.1.4 kony.application.beginBackgroundTask

In some scenarios apps are launched in the background to perform some long running task. A typical example, could be when a watch app requests its parent app (phone app) for some information, the phone app is launched in the background. If the phone app needs to run a long running task in order to serve the requirement of the watch app, it is recommended to start a background task. This API ensures iOS does not suspend the phone app when running in the background that take too much time or resources for execution.

Kony Studio API Developer's Guide

Version 3.1

This API is used when you want to run a long running or the asynchronous task in the background of the phone app. When the long running task is completed, you must end the background task using the

API kony.application.endBackgroundTask.

Signature

JavaScript: kony.application.beginBackgroundTask(taskID, callback)

Input Parameters taskID [String] - Mandatory

Specifies the unique identifier for the task.

callback [function] - Optional

Specifies the callback that gets executed in the background before iOS suspends the app. You can use this callback to save information or clean up resources before your app gets suspended.

Return Values

This API returns taskID as a number that is used as an input for kony.application.endBackgroundTask

API.

Platform Availability

Available on iPhone and iPad.

JavaScript Example function ExpirationHandlercallback(){

//your logic to clear resources or save data.

} function jsfunction(userInfo, replyObj)

{

Kony Studio API Developer's Guide

Version 3.1

var taskID = kony.application.beginBackgroundTask("TaskName",

ExpirationHandlercallback);

//Long running task.

kony.application.endbackgroundTask(taskID);

}

3.7.1.5 kony.application.createSettingsMenu

This API enables you to create a Charm settings menu for an application.

Signature

JavaScript: kony.application.createSettingsMenu (

menuSettings )

Input Parameters id [String] - Mandatory.

Identifier of the Charm setting menu created.

menuSettings [Hash table] - Mandatory

The menuSettings hash table comprises the following key-value pairs: l id: ID of the Charm menu item.

l text: Name of the menu item.

Return Values

None.

Kony Studio API Developer's Guide

Version 3.1

Special Considerations

If a Charm setting menu is already created with the identifier passed, a new Charm setting menu will be created and the old Charm setting menu will be replaced with the new one. The same holds true for menu items as well.

At least one menu item must be present in the Charm settings menu created. A Charm settings menu with no menu items is invalid.

Platform Availability

Available on Windows 8.

JavaScript Example

To create a Charm settings menu, enter the following: var settingsMenuItem1 = {id : "about", text : "About"}; var settingsMenuItem2 = {id : "help", text : "Help"}; var settingsMenu = [settingsMenuItem1, settingsMenuItem2]; kony.application.createSettingsMenu("mysettingsmenu", settingsMenu);

3.7.1.6 kony.application.dismissLoadingScreen

This API provides you the ability to dismiss the loading screen displayed earlier. If there is no loading screen, this API has no affect.

Signature

JavaScript: kony.application.dismissLoadingScreen()

Input Parameters

None

Kony Studio API Developer's Guide

Version 3.1

Return Values

None.

Platform Availability

Available on all platforms except Mobile Web.

JavaScript Example kony.application.dismissLoadingScreen();

3.7.1.7 kony.application.disableZoomedOutView

This API enables you to disable a zoomed out view set for an application using the previous API.

Signature

JavaScript: kony.application.disableZoomedOutView()

Input Parameters

None

Return Values

None.

Platform Availability

Windows 8

JavaScript Example

//Disabling zoomout on an application

Kony Studio API Developer's Guide

Version 3.1

function zoomout()

{ kony.application.disableZoomedOutView();

}

3.7.1.8 kony.application.endBackgroundTask

This API is invoked when you are done with an execution of long running tasks in the background. The return value of the API kony.application.beginBackgroundTask is used as the input parameter for this API.

Input Parameters taskID [Number] - Mandatory

Specifies the identifier returned by the kony.application.beginBackgroundTask API.

Return Values

None

Platform Availability

Available on iPhone and iPad.

JavaScript Example function ExpirationHandlercallback(){

//your logic to clear resources or save data.

} function jsfunction(userInfo, replyObj)

{

Kony Studio API Developer's Guide

Version 3.1

var taskID = kony.application.beginBackgroundTask("TaskName",

ExpirationHandlercallback);

//Long running task.

kony.application.endbackgroundTask(taskID);

}

3.7.1.9 kony.application.exit

This API terminates the application.

Signature

JavaScript: kony.application.exit()

Input Parameters

None

Return Values

None.

Platform Availability

Available on all platforms except for Server side Mobile Web and Desktop Web. SPA supports only iPhone, iPad, and Windows 8 Tablet.

JavaScript Example function exit()

{ try{

Kony Studio API Developer's Guide

Version 3.1

"+Error); alert("Exception While getting exiting the application :

}

} kony.application.exit();

} catch(Error)

{

3.7.1.10 kony.application.getApplicationBadgeValue

This API allows you to read the badge value (if any) attached to the given application icon. If the applications icon does not have any badge value attached to it, this API returns an empty string.

Signature

JavaScript : kony.application.getApplicationBadgeValue()

Input Parameters

None

Return Values badgeValue [String]

Returns the badge value applied to the application icon If the application icon has no badge value attached to it, it returns null/nil.

Platform Availability

Available only on iPhone and iPad.

Kony Studio API Developer's Guide

Version 3.1

JavaScript Example function getApplicationBadgeValue()

{

//Get the ApplicationBadgeValue from the application icon on the mobile desktop at the top-right corner of the application icon.

kony.application.getApplicationBadgeValue();

}

3.7.1.11 kony.application.getApplicationMode

This API enables you to get the application mode.

Signature

JavaScript: kony.application.getApplicationMode()

Input Parameters

None

Return Values

Integer Constant l

1: constants.APPLICATION_MODE_NATIVE

2: constants.APPLICATION_MODE_HYBRID

3: constants.APPLICATION_MODE_WRAPPER

Special Considerations

This API should be called only in preappinit or before the execution of preappinit. If this API is invoked elsewhere in the program, it is invalid and leads to undefined behavior.

Kony Studio API Developer's Guide

Version 3.1

Exceptions

Error

Platform Availability

Available on all platforms.

JavaScript Example function getApplicationMode()

{ kony.application.getApplicationMode();

}

3.7.1.12 kony.application.getApplicationState

iOS prohibits UI updates when the app is running in the background. Using this API you can check whether the app is running in the background or not to make UI updates. The possible application states are active, inactive, or background.

Signature

JavaScript: kony.application.getApplicationState()

Input Parameters

None

Return Values

This API returns the following constant values: l

APPLICATION_STATE_ACTIVE l

APPLICATION_STATE_INACTIVE

Kony Studio API Developer's Guide

Version 3.1

APPLICATION_STATE_BACKGROUND

Platform Availability

Available on iPhone and iPad.

JavaScript Example

//Sample code to get the application state function util() { var appState = kony.application.getApplicationState(); if (appState = constants.APPLICATION_STATE_BACKGROUND) { kony.print(appState);

}

} kony.application.getAppMenuBadgeValue

This API enables you to read the badge value (if any) attached to the specified app menu item. If the specified app menu item does not have any badge value attached to it, the API returns an empty string.

Signature

JavaScript

: kony.application.getAppMenuBadgeValue( appmenuID , menuItemID )

Kony Studio API Developer's Guide

Version 3.1

Input Parameters appMenuId [String] - Mandatory

If you are setting the badge for an app menu item that was created dynamically, use the same ID that was used to create the app menu item.If you are setting the badge for an app menu item that was created from the IDE, use the ID available in the generated script file.

menuItemId [String] - Mandatory

Identifier of the app menu item from which the badge value is to be read.

Return Values badgeValue [String]

Returns the badge value applied to the specified app menu. If the specified app menu has no badge value attached to it, it returns an empty string.

Platform Availability

Available only on iPhone and iPad.

JavaScript Example function getAppMenuBadgeValue()

{

//Get the AppMenuBadgeValue for the menu item with id :

:"appmenuitemid3" kony.application.getAppMenuBadgeValue

("accountMenu","appmenuitemid3");

}

3.7.1.13 kony.application.getBMState

This API retrieves the list of parameters attached to a URL using the above add, set APIs.

Kony Studio API Developer's Guide

Version 3.1

Signature

JavaScript: kony.application.getBMState (

formID )

Input Parameters formID [String] - Mandatory.

Identifier of the form for which the parameters of the URL have to be fetched.

Return Values

A json structure representing key-values of various parameters attached to the URL string of the given form.

Platform Availability

Supported for SPA and Desktop Web.

JavaScript Example

To fetch a list of parameters for a form, enter the following: kony.application.getBMState("form1")

3.7.1.14 kony.application.getCurrentForm

This API returns a handle to the current form. The form handle is useful when you are sending analytics to the analytic engine.

Note: For iOS, kony.application.getCurrentForm() returns the form id of current form. This rule does not apply for form used as cameraOverlay.

Use Case

You can use this API in the following scenarios:

Kony Studio API Developer's Guide

Version 3.1

1. When you want to send analytics to the analytic engine.

2. When you want to use the handle to the current form in any other function.

Modeled After

None

Signature

JavaScript : kony.application.getCurrentForm()

Input Parameters

None

Return Values currentForm - Object

This API returns the current form.

Rules and Restrictions

The following are the guidelines applicable for the API: l

If you invoke this API in the

preshow

method of the application, it does not have any affect.

If you invoke this API in the

appinit

method of the application, nil is returned.

UI Behavior

None

Platform Availability

Available on all platforms.

Kony Studio API Developer's Guide

Version 3.1

JavaScript Example function getCurrentForm()

{

//Get the current form var currentForm = kony.application.getCurrentForm();

//Alert the current form alert("currentForm is::"+currentForm);

}

3.7.1.15 kony.application.getCurrentSettingsMenu

This method returns the unique identifier of the current menu that is set through getCurrentSettingsMenu.

Signature

JavaScript: kony.application.getCurrentSettingsMenu ()

Input Parameters

None

Return Values

Returns the unique identifier of the current menu that is set through getCurrentSettingsMenu.

Platform Availability

Available on Windows 8.

JavaScript Example

To get the unique identifier a Charm settings menu, enter the following:

Kony Studio API Developer's Guide

Version 3.1

kony.application.getCurrentSettingsMenu ();

//Alert the Current Charm Settings menu alert("Current charm menu id is:: "+currCharmMenuId);

3.7.1.16 kony.application.getPreviousForm

This API returns a handle to the previous form.

Use Case

You can use this API in the following scenarios:

1. When you want to send analytics to the analytic engine.

2. When you want to use the handle to the current form in any other function.

Modeled After

None

Signature

JavaScript: kony.application.getPreviousForm()

Input Parameters

None

Return Values previousForm-Object

API returns the previous form handle.

Rules and Restrictions

The following are the guidelines applicable for the API:

Kony Studio API Developer's Guide

Version 3.1

If you invoke this API in

preshow

event of the application, you get unpredictable results.

If you invoke this API in the

appinit

method of the application, nil is returned.

If you use the Back button on the mobile web browser, this API does not return the handle to the previous form.

If you use this API on the first form of the application it returns null/nil.

UI Behavior

None

Platform Availability

Available on all platforms.

JavaScript Example function getPreviousForm()

{

//Get the Previous form var previousForm = kony.application.getPreviousForm();

//Alert the Previous form alert("previousForm is::"+previousForm);

}

3.7.1.17 kony.application.getPreviousSessionParams

This API retrieves the previous session parameters in the application life cycle.

Important: You must use the kony.application.invalidateSession("frmName", sessionParams)

API before using kony.application.getPreviousSessionParams API.

Kony Studio API Developer's Guide

Version 3.1

Signature

JavaScript: kony.application.getPreviousSessionParams()

Input Parameters

This API does not have any parameters.

Return Values listOfParams [Array]

Returns a table of the previous session parameters that is passed from the invalidateSession API.

Platform Availability

Available on Mobile Web

JavaScript Example

//The following function is for getPreviousSessionParams API

//You must use the invalidateSession("frmName", sessionParams) API before using getPreviousSessionParams API. function invalidateSession()

{

//invalidating the session var sessionParams = {}; sessionParams ["category"] = "news"; sessionParams ["country"] ="US"; kony.application.invalidateSession("frmName", sessionParams);

} function getPreviousSessionParams()

{

//Collecting all the params in to an object var mySessionParams = kony.application.getPreviousSessionParams();

Kony Studio API Developer's Guide

Version 3.1

kony.print("mySessionParams are"+mySessionParams);

}

3.7.1.18 kony.application.invalidateSession

This API explicitly invalidates a session on Mobile Web.

Important: This API is applicable only on Mobile Web platforms

Use Case

You can use this API for Financial applications where you want to completely invalidate the session on execution of specific functions. For example, logout function. When the user logs out from the application, you can invoke this API to invalidate the current session and initiate a new session before navigating to any other form. In this case, all the session data is cleared.

Signature

JavaScript: kony.application.invalidateSession(

formName

params

)

Input Parameters formName [Handle to the form] - Optional

Specifies the form to which the application must navigate after the session is invalidated params [Function] - Optional

Specifies a table of parameters that you want to pass to the new session

Return Values

This API navigates to the specified form or remains on the same form if there is no form specified.

Kony Studio API Developer's Guide

Version 3.1

Rules and Restrictions

When the current session is invalidated, the Mobile Web framework will start the application lifecycle again. This API invokes appinit and then navigates the user to the startup form or any form that is associated with the logout function.

Platform Availability

Available on Mobile Web.

JavaScript Example

//The following function is for invalidateSession API function invalidateSession()

{

//invalidating the session kony.application.invalidateSession();

}

3.7.1.19 kony.application.openMediaURL

This API launches the native media player and starts playing the media (audio or video) at the specified URL. The media server provides the appropriate media content depending upon the device

(for example, Blackberry, iPhone, etc). This API is not applicable on SPA.

Use Case

You can use this API when you want to access and use multimedia from an external URL or server.

Signature

JavaScript: kony.application.openMediaURL(

URL

)

Kony Studio API Developer's Guide

Version 3.1

Input Parameters

URL [String] - Mandatory

Specifies the URL that points to the audio/video file

Return Values

None.

Implementation Details

This API assumes that the media is available at the specified URL. The API does not check for the availability of the media at the specified location. The responsibility lies on the developer to ensure that appropriate media is available at the referred URL.

Any errors related to the type of media or the availability of the media are handled by the native media player. The errors are not propagated back to the application.

Note:

For more information on media formats, see: l

Android: http://developer.android.com/guide/appendix/media-formats.html

You have to provide an absolute path of the video file in the URL. For example, http://www.boisestatefootball.com/sites/default/files/videos/original/01%20-%20coach%20pet e%20bio_4.mp4

or the URL should be in 'rtsp' format if it is a YouTube video.

l iPhone: Apple Documentation l

Windows Phone (7.5 and 8.0): http://msdn.microsoft.com/enus/library/windowsphone/develop/ff462087(v=vs.105).aspx

Windows 8 tablet: Supported File Types

Platform Availability

Available on all platforms except BlackBerry 10 and Windows 7 / Kiosk.

Kony Studio API Developer's Guide

Version 3.1

JavaScript Example function openMediaURL()

{

//Launching the native media player and starts playing the media

(audio or video) at the

URL:"http://www.boisestatefootball.com/sites/default/files/videos/or iginal/01%20-%20coach%20pete%20bio_4.mp4" kony.application.openMediaURL

("http://www.boisestatefootball.com/sites/default/files/videos/origi nal/01%20-%20coach%20pete%20bio_4.mp4");

}

3.7.1.20 kony.application.openURL

This API opens the web page at the specified URL in the native browser of the mobile device.

Use Case

You can use this API when you want to access an external web page within the application. With this

API, you can open a web page without using a browser widget in your application.

Signature

JavaScript: kony.application.openURL(

URL

)

Input Parameters

URL [String] - Mandatory

Specifies the URL that points to the external web page

Return Values

None.

Kony Studio API Developer's Guide

Version 3.1

Implementation Details

When you use this API, the behavior of the application is as follows on different platforms: iPhone

Platform Behavior l

On 4.0 and above versions, the application opens the specified

URL in the native browser and the application goes into background l

On versions below 4.0, the application opens the specified URL in the native browser and the application exits l

For opening the maps application of iOS, please using following

URLs: l

For iOS 5 : http://maps.google.com/maps l

For iOS 6: http://maps.apple.com/maps

Android

BlackBerry

Windows

Phone/Windows

Kiosk/Mango

SPA

The application opens the specified URL in the native browser and the application goes into background

The application opens the specified URL in the native browser and the application exits

Symbian l

The URL opens in the browser l

The application redirects the existing browser instance to the new URL

The application opens the specified URL in the native browser and the application goes into background

Kony Studio API Developer's Guide

Version 3.1

Palm

Platform Behavior

The application opens the specified URL in the native browser and the application goes into background

Platform Availability

Available on all Rich Client platforms.

JavaScript Example

//The following function is for openURL API function openURL()

{

//Accessing an external web page : http://www.google.com

kony.application.openURL("http://www.google.com")

}

3.7.1.21 kony.application.registerForIdleTimeout

This API specifies if the application must timeout after a defined period of inactivity (time difference between the current device time and the last time you clicked on any user interface component) and also specifies the action after the timeout interval.

Important: l

You must enable the forms for idletimeout by setting the property for enabledForIdleTimeout as

True in the IDE. The idletimeout event is triggered only when the user is on a form that is enabled for idletimeout.

When the idletimeout event is triggered, the user is navigated to the home screen with an alert message.

Kony Studio API Developer's Guide

Version 3.1

In BJS devices, to validate registerForIdleTimeout, an event must be triggered once time out is occurred.

Use Case

You can use this API typically in financial applications when you want to log the user out automatically after a specific period of inactivity. This way, you can ensure that there is no un-authorized access to the application or to the sensitive information like account number, credit card numbers, and so on.

Signature

JavaScript: kony.application.registerForIdleTimeout(

timeoutValue

callback

)

Input Parameters timeoutValue [Number] - Mandatory.

The timeout value in minutes.

callback [Function] - Mandatory.

The function that must be executed after the timeout has occurred. The callback function has the logic to display the current form. The function can be changed during runtime.

Note:

Current form is the Form that was being displayed on the device screen when the timeout occurred.

Return Values

None.

Implementation Details

The idletimeout event is triggered only once for every call to

registerForIdleTimeout

API and this event is not fired again until the next call to the API. The idletimeout event unregisters itself automatically when the event is fired. When the event unregisters itself, the application can register again for idletimeout.

The following are a few scenarios:

Kony Studio API Developer's Guide

Version 3.1

Scenario 1 idletimeout event is triggered after the specified time interval, but the user is on a form that is not enabled for idletimeout. In this case, the function associated with the event is executed as soon as the user navigates to the form that is enabled for idletimeout.

Note: In this case, the form that the user is trying to navigate to is never shown as the idletimeout event takes precedence.

Scenario 2 idletimeout event is triggered and the user is on a form enabled for idletimeout. In this case, the associated function is executed immediately.

Scenario 3

The application is registered for idle time out and the user tries to register again for idletimeout. In this case, the latter call to the

registerForIdleTimeout

API has no affect and is ignored.

Scenario 4

The application is registered for idletimeout but none of the forms in the application are enabled for idletimeout. In this case, this API has no affect and the behavior of the application is undefined.

Each underlying platform handles the idletimeout event differently: iPhone l

When the application is running in the background, no logic is executed. However, the timers keep running and the idletimeout event is triggered in the background. But the function is executed immediately when the application comes to foreground.

Note: When the application comes to foreground, you will suddenly notice the function of the idletimeout event getting executed.

Kony Studio API Developer's Guide

Version 3.1

Android l

When you press the device Back button to go out of the application, the underlying OS destroys the UI activity. In such cases, the idletimeout event is fired only when the application comes to the foreground.

When you navigate out of the application using the device Home button, the underlying OS pauses the UI activity but does not destroy it. In such cases, the idletimeout event is fired immediately in the background.

BlackBerry l

The underlying OS triggers the idletimeout event when the application is in background. The associated function of the idletimeout event also gets executed when the application is in background.

Symbian l

The underlying platform runs the timer and triggers the idletimeout event even when the application is in background. The function associated with the event is executed as soon as the application comes to the foreground.

Mobile Web l

In Mobile Web applications, the timer is not active when the application goes into background or sleep mode. When the application comes into foreground, the timer starts running and the

idletimeout

triggers after the specified time interval.

Rules and Restrictions

This API is applicable only when the Form property

Enable Time Out is set to true. For more information about

Enable Time Out property, see Kony Widget User Guide.

Exceptions

An error is thrown if input is invalid or does not follow the expected structure.

102-Invalid input error

Kony Studio API Developer's Guide

Version 3.1

Platform Availability

Available on all platforms.

JavaScript Example function test()

{

//Logic for the callback function registerForIdleTimeout

} function registerForIdleTimeout()

{ kony.application.registerForIdleTimeout(1, test);

}

3.7.1.22 kony.application.registerOnKeyPress(values)

This API allows the user to hook any closure with key press event. It expects an object with key-value pair. This API is exposed for Windows 7 platform.

JavaScript Example function keyPress(keycode)

{ kony.print("DONE!!!" + keycode)

} function callRegisterOnKeyPress()

{ var values = {

"Ctrl+C": keyPress,

Kony Studio API Developer's Guide

Version 3.1

}

"Ctrl+X": keyPress,

"Ctrl+V": keyPress,

"Esc": keyPress

}; kony.application.registerOnKeyPress(values);

3.7.1.23 kony.application.removeBMState

This API removes a specified key from the parameter list of the URL of the form.

Signature

JavaScript: kony.application.removeBMState (

formID,key )

Input Parameters formID [String] - Mandatory.

Identifier of the form for which the parameters of the URL have to be removed.

key [String] - Mandatory

Key string representing the key to be removed.

Return Values

None.

Platform Availability

Supported for SPA and Desktop Web.

JavaScript Example

To remove a bookmark for a URL, enter the following:

Kony Studio API Developer's Guide

Version 3.1

kony.application.removeBMState ("form1", "About")

3.7.1.24 removeGestureRecognizerForAllForms

This method allows you to remove a specified gesture recognizer for all Forms.

Signature

JavaScript: kony.application.removeGestureRecognizerForAllForms(

uniqueIdentifier

)

JavaScript Parameters uniqueIdentifier - Mandatory

Reference to the gesture. The reference to the gesture is returned by the setGestureRecognizerForAllForms.

Example function callbackClearLongPressGesture()

{ try{ kony.application.removeGestureRecognizerForAllForms

(uniqueidentifier);

} catch(err){ alert(typeof err); alert("error in function callbackClearLongPressGesture:

"+err.message);

}

Kony Studio API Developer's Guide

Version 3.1

Platform Availability

Available on all platforms except Server Side Mobile Web, BlackBerry 10, Windows 7/Kiosk, and

Desktop Web.

3.7.1.25 kony.application.removeSecondaryTile

This API enables you to remove and unpin a specified secondary tile which was created earlier.

Signature

JavaScript: kony.application.removeSecondaryTile(

id )

Input Parameters id [String] - Mandatory

Unique identifier of the secondary tile

Return Values

None

Platform Availability

Available on Windows Mango, Windows Phone 8, and Windows 8.

JavaScript Example kony.application.removeSecondaryTile("12345")

3.7.1.26 kony.application.removeSettingsMenuItemAt

This API enables you to removes the specified App Menu item based on the index.

Signature

JavaScript:

kony.application.removeSettingsMenuItemAt ( id , index

)

Kony Studio API Developer's Guide

Version 3.1

Input Parameters id [String] - Mandatory.

Identifier of the Charm setting menu created.

index [Number] - Mandatory.

The index from which the menu item must be removed. The index value lies between 0 and n-1.

Return Values

None.

Platform Availability

Available on Windows 8.

JavaScript Example

To remove a menu item from a given index, enter the following:

//Removing a menu item from the index 3.

kony.application.removeSettingsMenuItemAt("charmmenu", 3);

3.7.1.27 kony.application.resetBMState

This API resets the state associated with the URL of a form. It removes all the parameters attached to the form URL

Signature

JavaScript: kony.application.resetBMState (

formID

)

Input Parameters formID [String] - Mandatory.

Identifier of the form for which the parameters of the URL have to be removed.

Kony Studio API Developer's Guide

Version 3.1

Return Values

None.

Platform Availability

Supported for SPA and Desktop Web.

JavaScript Example

To reset a bookmark for a URL, enter the following: kony.application.resetBMState ("form1")

3.7.1.28 kony.application.setApplicationBehaviors

This API enables you to specify if: l

The pre-show and post show events are invoked if you press Back option on a mobile device.

The pop-up is modal (requires interaction before it can return to the parent application).

The app menu needs to be updated when pre-show and post show events are invoked if you press the Back option on a mobile device.

App menu has to be configured in pre-show/post show of each form, if each form has separate app menu buttons/items. But on some Kony platforms, pre-show and post show events are triggered when user navigates back using Back option and on some other platforms, those events are not triggered. If pre-show/post show event is not triggered, form cannot update its app menu. In this scenario, ideally, form must retain its app menu which is set earlier.

To ensure consistency while porting application across platforms, the setapplicationbehavior API enables you to set the default behavior of pre-show and post show events, a pop-up, and app menu.

Note: This API can only be called in post-appinit() method.

Kony Studio API Developer's Guide

Version 3.1

Signature

JavaScript: kony.application.setApplicationBehaviors(

Objectbehaviors )

Input Parameters

Objectbehaviors [Object] - Mandatory

The object includes the following key-value pairs: l invokePreshowPostShowEventsOnDeviceBack [Boolean] : Specifies if the pre-show or postshow events are triggered if the user presses the Back option on a mobile device.

l isPopupModel

[Boolean]

: Specifies if the pop-up is modal (requires interaction before it can return to the parent application). The value set as the property for a pop-up takes precedence over the value set dynamically.

l retainSpaceOnHide [Boolean] : Specifies if the space allocated for a widget is retained when the widget is made invisible. Applicable on widgets placed in a percentage container.

Important: l

Limitation in Windows channel: when retainSpaceOnHide is true and widget isVisible property is false, top, and bottom margins will not be considered for invisible widget.

When visibility of widget is changed and when retainSpaceOnHide is True, there must not be any change in the width of HBox or % scrollBox. Height changes to the max height of the visible child widget.

When retainSpaceOnHide property is made False, inconsistency among platforms is observed. If any of the widgets placed inside a container are made invisible, then some platforms will retain the space and some platforms will not retain the space. To overcome this inconsistency or to retain the space in all platforms, retainSpaceOnHide property must be configured to True. The default value of retainSpaceOnHide property is True.

l restoreformstateondeviceback [

Boolean]: Specifies whether the default behavior of form app menu state is retained when the user presses the Back option.

Kony Studio API Developer's Guide

Version 3.1

l hideDefaultLoadingIndicator [ Boolean]: If enabled (true), it hides the default loading indicator that appears when background operation is performed. For example, executing onClick() callback function of Button widget if a button is clicked.

Important: The hideDefaultLoadingIndicator property is available only on Android Platform and it is supported from Kony Android plug-in GA 5.0.32 onwards.

l adherePercentageStrictly [

Boolean]: By default, this parameter is set to True.

Note: SPA and Desktop Web supports only adherePercentageStrictly property.

l defaultIndicatorColor [String]: Set color for the progress indicator. An Hex code or a word can be used to set the color. The words can only be used for two colors white and grey, and these words are not case sensitive.

Note: The defaultIndicatorColor property is only support for Android and Windows. Default color might vary for each platform as it picks from application theme, form color or predefined color.

l hideDefaultLoadingIndicator [Boolean]: Set as True to hide the loading indicator, and set as

False to show the loading indicator.

l hideStatusBar [Boolean]: Set as True to hide the status bar, and set as False to show the status bar. Default value is True. This is an optional parameter.

Important:

The hideStatusBar property is available only on Windows (8 and later versions)

Platform and it is supported in Kony Studio GA 5.6.4.11 and in GA 6.0.2.3.

l marginsIncludedInWidgetContainerWeight [Boolean]: Set to True to apply margin calculations.

Margins are calculated based on width of the parent box.

Note: The margin change is applicable only for percentage boxes.

Kony Studio API Developer's Guide

Version 3.1

l skinImageScaleMode [Constant]: Available on Windows Phone 8 or 8.1, Windows 8, and

Desktop Kiosk o skinImageScaleMode [Constant] – Optional o skinImageScaleMode accepts the following constants: o constants.SKIN_IMAGE_SCALE_MODE_DEFAULT

o constants.SKIN_IMAGE_SCALE_MODE_NONE

o constants.SKIN_IMAGE_SCALE_MODE_FILL

o constants.SKIN_IMAGE_SCALE_MODE_UNIFORM

o constants.SKIN_IMAGE_SCALE_MODE_UNIRFORMTOFILL

SKIN_IMAGE_SCALE_MODE_DEFAULT: This mode renders the

Images provided to the skin according to the existing, default behavior.

SKIN_IMAGE_SCALE_MODE_NONE: This mode does not scale the Images provided to the skin. In case the image is larger than the control, the widget expands to the size of the image, else, the image occupies it’s actual height within the control.

Kony Studio API Developer's Guide

Version 3.1

SKIN_IMAGE_SCALE_MODE_FILL: The image is scaled to fill the size of the widget in this mode. It’s aspect ratio is not preserved.

SKIN_IMAGE_SCALE_MODE_UNIFORM: The image is scaled to fill the size of the widget while ensuring it’s aspect ratio is preserved.

Kony Studio API Developer's Guide

Version 3.1

SKIN_IMAGE_SCALE_MODE_UNIFORMTOFILL: The image is resized to fill the widget dimensions while preserving the native aspect ratio. If the aspect ratio of the widget differs from that of the image, the image is clipped to fit in the destination.

Example: kony.application.setApplicationBehavior

s({skinImageScaleMode:constants.SKIN_IMAGE_

SCALE_MODE_DEFAULT}); l

Usage Guidelines or Restrictions or Examples: In Kony Platform, height cannot be fixed for most of the widgets. Hence, for the widgets, for which the height is not fixed, the image skin will expand and the widget’s size will grow for the modes: FILL, UNIFORM and

Kony Studio API Developer's Guide

Version 3.1

UNIFORMTOFILL. This flag is usually set in Pre-AppInit or Post-

Appinit before the widgets are rendered. In the scenario where the flag is modified after any of the widgets are rendered, there will be no change in the widgets which have already been rendered. The change will be reflected by the widgets which have not been rendered yet.

l isScrollEventsAsync [Boolean]: All scroll events are executed asynchronously. If visual changes and calculations are done based on scroll properties and events (such as content scroll offset). It is recommended to set isScrollEventsAsync to False and execute the scroll events synchronously.

Default Value: True o

Platform Availability: Windows Phone 8 and 8.1

l isLowLevelEventsAsync [Boolean]:

onTouchStart

onTouchMove

onTouchEnd

, and

onTouchCancel

are classified as low-level events. If these events are required to be executed synchronously, then isLowLevelEventsAsync must be set to False.

Default Value: True o

Platform Availability: Windows Phone 8 and 8.1

l enableRedrawRegions [Boolean]: All gesture events are executed asynchronously. By setting

isGestureEventsAsync

to False, the gesture events are executed synchronously.

Default Value: True o

Platform Availability: Windows Phone 8 and 8.1

l skipEscapeHTML [Boolean]: Set as true to allow HTML tags in label widget and for backward compatibility.

l useNativeMSG [Boolean]: Set to true to enable your app to use native multi-step gradients that are scaled relative to the size of the widget. Otherwise,set to false to disable this behavior.

Following are the Windows 7 specific properties available in setApplicationBehaviour API.

Kony Studio API Developer's Guide

Version 3.1

Note:

All the properties must be passed as a key value pairs under Windows 7 Key.

l backOnEsc: If set to True, allows the user to go back to previous form by pressing Escape key. If the user is on the first form, the operation is ignored. Default value is False.

Note: If you are using onDeviceBack property on the form, the app will override the backOnEsc property and gives priority to onDeviceBack property.

l minWidth: Allows to set minimum width of the main window.

l maxWidth: Allows to set maximum width of the main window.

l minHeight: Allows to set minimum height of the main window.

l maxHeight: Allows to set maximum height of the main window.

l popupAsDialog: If this property is set to True, all the pop-ups will be displayed outside the main window. If set to False, pop-up displays embedded in main window. Default value is False.

l saveState: If set to true, location and size of the main window will be saved between application session. Default is false.

Note: If the setApplicationBehaviour API is called multiple times, latest settings are considered and all old settings are overridden.

Following are the BlackBerry 10 specific properties available in setApplicationBehaviour API.

l contextMenuHandler [Boolean]: This enables or disables the appearance of Menu (with action items) from right side when you do a long press on the form. Set as true to enable this property and set as false to disable. By default, the value is true.

l defaultPaddingEnabled [Boolean]: This enables or disables the default padding for the button.

Set as true to enable this property and set as false to disable. By default, the value is true.

Kony Studio API Developer's Guide

Version 3.1

Note: The contextMenuHandler and defaultPaddingEnabled properties are available only on BlackBerry 10 platform and are supported from Kony Visualizer 5.6 onwards.

Return Values

None

Platform Availability

Available on all platforms

JavaScript Example

//The Application must to call kony.application.setApplicationBehaviors(appTable)

//in post-appinit() methods.

function setApplicationBehaviors()

{

//Controlling the behaviours by setting invokePreshowPostShow

//EventsOnDeviceBack as true,isPopupModel as true,and retainSpaceOnHide as true.

kony.application.setApplicationBehaviors

({invokePreshowPostShowEventsOnDeviceBack:true, isPopupModel:true, retainSpaceOnHide:true,

"hideDefaultLoadingIndicator":true});

}

Kony Studio API Developer's Guide

Version 3.1

var obj =

{ windows7:

{ backOnEsc:true, minWidth:300, maxWidth:1000, minHeight:400, maxHeight:800,

}

} popupAsDialog:true, saveState:true, kony.application.setApplicationBehaviors(obj); var inputParamTable = {}; inputParamTable["isScrollEventsAsync"] = false; inputParamTable["isLowLevelEventsAsync"] = false; inputParamTable["isGestureEventsAsync"] = false; kony.application.setApplicationBehaviors(inputParamTable);

3.7.1.29 kony.application.setApplicationBadgeValue

This API allows you to set a badge value to an application icon on the mobile desktop at the top-right corner of the application icon. If you pass an empty string as a parameter, the badge applied on the application icon is removed.

Signature

JavaScript : kony.application.setApplicationBadgeValue(

badgeValue

)

Kony Studio API Developer's Guide

Version 3.1

Input Parameters badgeValue [String] - Mandatory

Value of the badge. The value that you specify in the badgeValue parameter appears within the badge. Do not pass any other value except a numerical value. For example, to set a badge value for an appicon, specify the value as "2" instead of 2. If the length of the badge value is greater than

1 the badge is a rounded rectangle. For example, if you specify the value of the badge as 88, the number appears in a rounded rectangular badge. If the length of the badge value is 1, the badge is always a circle.

Return Values

None

UI Behavior

The badge appears with white font on a red background. The shape of the badge varies with its value: l

If the badge value is a single digit, the badge shape is a circle.

If the badge value contains multiple digits, the badge shape is a rectangle with rounded corners and borders.

Platform Availability

Available only on iPhone and iPad.

Kony Studio API Developer's Guide

Version 3.1

JavaScript Example function setApplicationBadgeValue()

{

//Set the ApplicationBadgeValue to the application icon on the mobile desktop at the top-right corner of the application icon.

kony.application.setApplicationBadgeValue("234567");

}

The badge appears as follows when you execute the code given above:

3.7.1.30 kony.application.setApplicationCallbacks

This API captures the callback events for various states of the application which include: l onactive - state which indicates that the mobile device is active and application is running l oninactive - state which indicates that the mobile device is inactive and application is running l onbackground - state which indicates that the application is active and running in the background.

For more information on iOS application behavior on background, click here l onforeground - state which indicates that the application is active and running in the foreground

Kony Studio API Developer's Guide

Version 3.1

l onappterminate - state which indicates that the application is terminated and not running.

l onkeyboardchange - state which indicates whether a keyboard is deployed for an application.

l onpowersourcechange - state which indicates whether if a power source is attached to a device.

l onnetworkchange - this is specific to Mango. This state occurs whenever there is a change in the following: o

Status - Indicates the status of the device. The different statuses are Connected,

Disconnected, Roaming or Unknown.

Network- Indicates the network available on the device. The network statuses are

Wireless80211, Ethernet, MobileBroadbandGSM, MobileBroadbandCDMA, or None.

Date - Indicates the date on which the event occurs.

Note:

Android supports only onbackground and onforeground states.

onapplicationopenurl -To support interprocess communication (IPC) message authentication, Kony provides an application callback

onapplicationopenurl

. The

onapplicationopenurl

callback is used if an application needs to authenticate another application. To use this callback, applications must register with it. The

onapplicationopenurl

callback takes

sourceApplication

url

, and

annotation (via

UIDocumentInteractionController)

as input parameters. If the developer chooses to process the commands/information, True must be returned. If the developer chooses to ignore the commands/information passed, then False must be returned.

Signature

JavaScript

: kony.application.setApplicationCallbacks(

callbacks

)

Kony Studio API Developer's Guide

Version 3.1

Input Parameters callbacks [Object] - Mandatory

Specifies an Object with key as appstate and value as the callback function for the corresponding appstate. The following are the different appstates possible: l onappterminate: This state which indicates that the application is terminated and not running.

Callbacks specific to Android l onbackground: This state which indicates that the application is active and running in the background.

l onforeground: This state which indicates that the application is active and running in the foreground.

Callbacks specific to Windows l onkeyboardchange - This state indicates whether a keyboard is deployed for an application.

l onpowersourcechange - This state indicates whether a power source is attached to a device.

l onnetworkchange - This state occurs whenever there is a change in the following: o

Status: Indicates the status of the device. The different statuses are Connected,

Disconnected, Roaming or Unknown.

Network: Indicates the network available on the device. The network statuses are

Wireless80211, Ethernet, MobileBroadbandGSM, MobileBroadbandCDMA, or None.

Date: Indicates the date of the event.

Callbacks specific to iOS

Kony Studio API Developer's Guide

Version 3.1

l onactive - This state occurs when there is an incoming SMS, phone call, or anything else that interrupts the automatic lock of the mobile device.

l oninactive - This state occurs when the application is idle for a specific time interval.

l shouldAllowExtensions - You can use extensions to enable a specific task beyond your app functionality and make available to users while they are using other apps or the system. This callback provides a mechanism to enable or disable the extensions in iOS framework. Following are the input parameter and return values of this callback: l string - [Mandatory - Specifies the entensionID that contains the identifier to identify the extension.

Return values - Returns a boolean value. If true is returned, the extension is enabled. If false is returned, the extension is disabled. By default, all the extensions are enabled.

Note: Extensions are available from iOS8 and above versions.

//Sample code function shouldAllowExtensions(extensionID)

{ if (extensionID == "com.apple.keyboard - service")

{ accessed return true; //will allow the keyboard extension to be

}

return false;

} l onlowmemory - This state indicates that the app received a memory warning from the system.

Kony Studio API Developer's Guide

Version 3.1

l onapplicationopenurl - To support interprocess communication (IPC) message authentication,

Kony provides an application callback

onapplicationopenurl

. The

onapplicationopenurl

callback helps a developer do some authentication when an app is opened from an already running app. To use this callback, applications must register with it. The

onapplicationopenurl

callback takes

sourceApplication

url

, and

annotation (via UIDocumentInteractionController)

as input parameters. If the developer processes the commands/information,

True

must be returned. If the developer ignores the commands/information passed, then

False

must be returned.

This callback accepts the following arguments: l sourceApplication - String – Mandatory - The application that requests to open a URL.

l url - String – Mandatory - The URL that is to be opened.

l annotation - Dictionary - Mandatory - If the URL refers to a file that is opened through a document interaction controller, then the source application can send information contained in this dictionary. Otherwise, this value is nil. The receiving app must know about the keys of the dictionary sent.

Return Value - True or False.

l onwatchrequest - This method is used to handle the requests coming from Apple WatchKit

Extension. The dictionary object is a dictionary of value pairs and represents the context for request to be processed.

This callback accepts the following arguments: l userInfo- [Dictionary] This parameter is mandatory. A dictionary of key value pairs.

l replyObject- [JSObject]- This parameter is mandatory. This object is used to send the response asynchronously. To send the response we should call a method

(executeWithReply) on this JSObject. The method accepts a key value pairs that form the response to be sent back.

Kony Studio API Developer's Guide

Version 3.1

//Sample code for onwatchrequest callback method.

function jsfunction(userInfo, replyObj)

{

if (userInfo["requestName"]=="getData"){

var responseDict={"key1":"value1","key2":"value2" };

replyObj.executeWithReply(responseDict);

}

Note:

It is possible to that execution of this call back might happen while the application is in the background. It is suggested to check the application state and perform UI updates in the phone application only when the application is running in the foreground.You may use getapplicationstate APIs.

l onactivityrequest - This method is used to handle the handoff activity request that are sent to the application.

This callback accepts the following arguments: l activityName - [String] This parameter is mandatory. A string that represents the name of the activity.

l activityInfo - [Dictionary] This parameter is mandatory. A dictionary containing custom user information.

This callback method returns a boolean (true/false) value that indicates the request handle status.

//Sample code for onactivityrequest callback method.

function jsfunction(activityName, activityInfo)

{

if (activityName =="continueActivity"){

// use activityInfo dictionary to continue the past activity on the iPhone

Kony Studio API Developer's Guide

Version 3.1

return true;

}

return false;

} l onpreactivityrequest - This method is used to ask the receiving application, whether it wants to continue the handed off activity. If this callback method returns true, then the onactivityrequest callback method gets invoked where the receiving app gets a chance to continue the handed off activity.

This callback accepts the following arguments: l activityName - [String] This parameter is mandatory. A string that represents the name of the activity.

If this callback method returns true, then the you notify the user that the receiving app wants to continue the activity on the device. If the callback method returns false, then iOS notifies the user to continue activity on the device.

//Sample code for onpreactivityrequest callback method.

function jsfunction(activityName)

{

if (activityName =="continueActivity"){

return true;

}

return false;

}

Return Values

None.

Kony Studio API Developer's Guide

Version 3.1

Exceptions

An error is thrown if input is invalid or does not follow the expected structure.

100 - Invalid type pf parameters.

101 - Invalid number of arguments.

102 - Invalid input error

Platform Availability

Available on all platforms except Desktop Web, SPA, and Mobile Web.

JavaScript Example

//onactive function function test()

{ alert("===============Test executed=======");

}

//oninactive function function test1()

{ alert("===============Test1 executed=======");

}

//onbackground function function test2()

{ alert("===============Test2 executed=======");

}

//onforeground function

Kony Studio API Developer's Guide

Version 3.1

function test3()

{ alert("===============Test3 executed=======");

}

//onappterminate function function test4()

{ alert("===============Test4 executed=======");

}

//setcallbackfunction function setCallBacks()

{ alert("===============setApplicationCallbacks executed======="); var callbacksObj =

{onactive:test,oninactive:test1,onbackground:test2,onforeground:test

3,onappterminate:test4}; kony.application.setApplicationCallbacks(callbacksObj);

}

//onapplicationopenurl kony.application.setApplicationCallbacks

({onapplicationopenurl:callbackFunction});

Example 1.

function callbackFunction (sourceApplicaion, url, annotation)

{v ar flag = false; if (sourceApplication == "AppOne" && url == "appTwo://….")

{f lag = true;

Kony Studio API Developer's Guide

Version 3.1

eturn flag;

}

Example 2.

function callbackFunction (sourceApplicaion, url, annotation)

{v ar flag = false; if (annotation) //annotation can be nil as well… refer parameter description…

{i f (annotation[key1] == 10)

{f lag = true;

}}r eturn flag;

}

//onWatchRequest sample code function jsfunction(requestObject){ return <returnValue>;

} kony.application.setApplicationCallbacks({onwatchrequest: jsfunction}) requestObject – is a dictionary of key value pairs.

Returnvalue – Any JS Object consisting of numbers, strings and boolean data types.

Kony Studio API Developer's Guide

Version 3.1

3.7.1.31 kony.application.setApplicationInitializationEvents

This API is used to configure all initialization events such as, preappinit, postappinit, init, appservice, showstartupform and so on. The application lifecycle is as follows:

Important: This API must be invoked only once during the application lifecycle. You should NOT invoke this API as part of the application lifecycle, because Kony Visualizer will generate the code that invokes the API automatically. Invoking this API multiple times will result in an undefined behavior.

Signature

JavaScript:

kony.application.setApplicationInitializationEvents( callbacks

)

Kony Studio API Developer's Guide

Version 3.1

Input Parameters callbacks [Object] - Mandatory

Is a Hash table which comprises of the following key value pairs: l preappinit[params]:This is an existing event that the developer registers in the IDE per application basis. This event consists of any logic that needs to be executed before the initialization of forms, skins, and any other application initialization activities. For e.g loading the i18n resource bundles dynamically etc.

l init[params]: init is generated by the code and consists of the form and skin initialization data.

l postappinit[params]: Is an existing event that the developer registers in the IDE per application basis. Developers use this function to define logic that needs to be executed before the first form is shown and after the application is initialized.

Note: postappinit can return a form handle. If postappinit returns a form handle, then the platform shows the form returned from the postappinit callback, otherwise the platform invokes the showstartupform function.

l appservice[params]:The closure provided against appservice will be invoked by the platform in a sequence. This function also returns the form handle.

Note: appservice can return a form handle. If appservice returns a form handle, then the platform shows the form returned from the appservice callback. If appservice does not return a form handle, the platform invokes the showstartupform function.

Note: If both postappinit and appservice return the form handle then, the form returned by app service is given priority by the platforms.

l showstartupform[params]: This is a method invoked by the platform to show the

Kony Studio API Developer's Guide

Version 3.1

startup form, as indicated in the IDE.

Note: This event is invoked only when postappinit returns a nil. If appservice returns a form handle, showstartupform is not invoked.

l deeplink[params]: This method is Thinclient/SPA specific and if appservice event is provided, then this event will be ignored.

Return Values

None.

Exceptions l

102 - InvalidInputError: An error is thrown if input is invalid.

100- TypeError: An error is thrown when the type is invalid.

Platform Availability

Available on all platforms.

JavaScript Example

//onactive function function test()

{ alert("===============Test excuted=======");

}

//oninactive function function test1()

{ alert("===============Test1 excuted=======");

}

Kony Studio API Developer's Guide

Version 3.1

//onbackground function function test2()

{ alert("===============Test2 excuted=======");

}

//onforeground function function test3()

{ alert("===============Test3 excuted=======");

}

//onappterminate function function test4()

{ alert("===============Test4 excuted=======");

}

//setAppInitialization function function setAppInitializationEvents()

{ kony.application.setApplicationInitializationEvents({init:test, preappinit:test1, postappinit:test2, appservice:test3, showstartupform:test4, deeplink:test5}); alert("===============setAppInitializationEvents excuted=======");

}

3.7.1.32 kony.application.setApplicationLayout

This API specifies if the application must have a layout from "left to right" or "right to left".

Kony Studio API Developer's Guide

Version 3.1

UseCase

To support Arabic kind of languages, all the widgets on a form must be layout from right to left. This

API impacts only horizontal layout.

Signature

JavaScript: kony.application.setApplicationLayout(

layoutDirection )

Input Parameters layoutDirection [Constant] - Mandatory

Specifies the layout direction for the content and the widgets of an application.

l constants.APPLICATION_LAYOUT_RIGHT2LEFT

l constants.APPLICATION_LAYOUT_LEFT2RIGHT

Return Values

None

Implementation Details

There is no direct API available to change the application layout to support both "Left2Right" and

"Right2Left" languages. App developers have to spend huge amount of time in redesigning the UI for both locales, setting the margins/paddings and in setting "contentAlignment" for all widgets on all forms. This API is simple solution to change the application layout based on locale.

This API can be called in appservice/preappinit/postappinit after checking the current locale or this should be called after the locale is changed successfully with "setCurrentLocaleAsync()".

Exceptions

An error is thrown if input is invalid or does not follow the expected structure.

102 - Invalid input error

101 - Insufficient arguments passed

Kony Studio API Developer's Guide

Version 3.1

Platform Availability

Available on Windows 8, Windows Phone 8, and Windows Phone 7.5 (Mango).

JavaScript Example

If an application supports English and Arabic languages, app developer can invoke below snippet anywhere in appservice or preappinit or postappinit.

function setApplicationLayoutBasedOnLocale()

{ if(kony.i18n.getCurrentLocale() == "en_US")

{ kony.application.setApplicationLayout(constants.APPLICATION_

LAYOUT_LEFT2RIGHT);

}else

{ kony.application.setApplicationLayout(constants.APPLICATION_

LAYOUT_RIGHT2LEFT);

}

3.7.1.33 kony.application.setApplicationMode

This API enables you to set the application mode to Native, Hybrid, or Wrapper.

Signature

JavaScript: kony.application.setApplicationMode(Integer constant)

Kony Studio API Developer's Guide

Version 3.1

Input Parameters

Integer Constant l

1: constants.APPLICATION_MODE_NATIVE

2: constants.APPLICATION_MODE_HYBRID

3: constants.APPLICATION_MODE_WRAPPER

Return Values

None

Special Considerations

This API should be called only in preappinit or before the execution of preappinit. If this API is invoked elsewhere in the program, it is invalid and leads to undefined behavior.

Exceptions

Error

Platform Availability

Available on all platforms.

JavaScript Example function setApplicationMode()

{ kony.application.setApplicationMode(APPLICATION_MODE_NATIVE);

}

Kony Studio API Developer's Guide

Version 3.1

3.7.1.34 kony.application.setAppMenuBadgeValue

This API allows you to set a badge value to the specified app menu item on the top-right corner of the app menu item. If you pass an empty string as the parameter, the badge value of the app menu item is cleared.

Signature

JavaScript

: kony.application.setAppMenuBadgeValue( appmenuID , menuItemId , badgeValue )

Input Parameters appMenuId [String] - Mandatory

menuItemId [String] - Mandatory

Id of the app menu item to which the badge value to be set.

badgeValue [String] - Mandatory

Value of the badge. The value you specify in the badge value appears within the badge. If the length of the badge value is greater than 1 the badge is a rounded rectangle. For example, if you specify the value of the badge as 88, the number appears in a rounded rectangular badge. If the length of the badge value is 1, the badge is always a circle. The maximum number of characters that can be specified in a badge value is 9. If the badge value id beyond 9 only the first 9 characters are displayed.

Return Values

None

UI Behavior

The following image depicts how a bade appears on an app menu item:

Kony Studio API Developer's Guide

Version 3.1

Platform Availability

Available only on iPhone and iPad.

JavaScript Example function setAppMenuBadgeValue()

{

//Set the AppMenuBadgeValue for the menu item with id ::

"appmenuitemid3" ,here the badge value is "3" kony.application.setAppMenuBadgeValue

("accountMenu","appmenuitemid3",

"3");

}

3.7.1.35 kony.application.setAppTile

This API enables you to set the data for an application tile. If the user chooses to pin the application tile, the data set is visible. For more information on pinning a tile, refer http://www.microsoft.com/windowsphone/en-us/howto/wp7/start/move-or-delete-tile-on-start.aspx

Signature

JavaScript: Mango: kony.application.setAppTile (

frontTileData ,

backTileData

)

Windows 8: kony.application.setAppTile(

tileTemplateType , tileTemplateData

)

Windows 8: setapptile(

tileTemplateType , tileTemplateData

))

Input Parameters for Mango frontTileData [Object] - Mandatory, If you do not set the front tile data, a default image and values will be used

Specifies the data to be displayed at the front of a tile. This hash table has the following inputs:

Kony Studio API Developer's Guide

Version 3.1

l title [String] - Specifies the title to be displayed at the front of a tile.The title appears at the bottom of the tile as white text.

l backgroundImage [String] - Specifies the background image to be displayed at the front of a tile.

Note: The backgroundImage will use the specified image to fill the entire space of the tile, regardless of its actual size.

l count [integer] - specifies a number to be displayed at the top - right corner of the tile. The count value is displayed in a small black circle in white text.

Note:

The colors, sizes, and layout of the count and the title do not ever change.

backTileData[Object] - Optional

Specifies the data to be displayed at the back of a tile. This table has the following key - value pairs: l title [String] - specifies the title to be displayed at the back of a tile.The title value appears at the bottom of the tile as white text.

l backBackgroundImage [String] - specifies the background image to be displayed at the back of a tile.

l backcontent

[String] - specifies the content to be displayed at the back of a tile. The back content appears at the top of the tile as white text.

Note: The colors, sizes, and layout of the back content and the title do not ever change.

You can also set the backTileData to be nil. In this case, no information will be set on the back of the tile and the tile will not flip.

Kony Studio API Developer's Guide

Version 3.1

Input Parameters for Windows 8 tileTemplateType [String] - Mandatory tileTemplateType is a string describing which tile template to use. Refer the tile template catalog for the list of supported tile templates: tileTemplateData [Array] - Optional tileTemplateData is an array of data for the tile, according to the tileTemplateType being used.

The tile template catalog . contains details of the data required for each tile template.

Return Values

None

UI Behavior - Mango

The Titles of both front and back tiles are displayed in white and this behavior cannot be changed even if the user sets a different theme or a background image. The count value for the front tile is displayed in a small black circle in white text at the top-right corner of the tile. The back content appears at the top-left corner of the tile as white text and is left justified.

Considering we have set values for both the frontTileData and the backTileData, the tiles might appear as follows:

Front Tile Back Tile

Kony Studio API Developer's Guide

Version 3.1

UI Behavior - Windows 8

The title and the display name of the tile will be displayed in white or black depending on the setting in

Kony Visualizer and this behavior cannot be changed even if the user sets a different theme or a background image. Unlike Mango. tiles cannot be flipped on Windows 8. The tile can be updated dynamically in Windows 8.

Platform Availability

Available on Windows Mango, Windows Phone 8, and Windows 8.

JavaScript Example

JavaScript Example1- Mango frontTileData:{"Front Tile Title", "test.png", 20} backTileData:{"Front Tile Title", "test.png", "This is the back tile content"} kony.application.setAppTile( frontTileData, backTileData );

JavaScript Example2 - Windows 8 kony.application.setAppTile( "TileSquareBlock", ["Hello", "World!"]

);

Kony Studio API Developer's Guide

Version 3.1

3.7.1.36 kony.application.setBMState

This API sets the bookmark state to the URL. This API accepts the formID and a json structure of key value pairs which will be added to the URL of the page.

Signature

JavaScript: kony.application.setBMState (

formID ,

State )

Input Parameters formID [String] - Mandatory.

Identifier of the form to be bookmarked.

state [JSON Object] - Mandatory

A JSON object comprising key value pairs. The key value pairs are user defined. You cannot specify this as a nested structure. i.e the value part can not be another JSON object.

Return Values

None.

Platform Availability

Supported for SPA and Desktop Web.

JavaScript Example

To set a bookmark for a URL, enter the following: var state = {Bookmark : "about", text : "About"}; kony.application.setBMState ("form1", state)

3.7.1.37 kony.application.setCheckBoxSelectionImageAlignment

This API is used to set the alignment of the checkBox selection image.

Kony Studio API Developer's Guide

Version 3.1

Signature

JavaScript: kony.application.setCheckBoxSelectionImageAlignment(

SelectionImageAlignment

)

Input Parameters

SelectionImageAlignment [String] - Mandatory

One of the following string can be provided: l constants.CHECKBOX_SELECTION_IMAGE_ALIGNMENT_LEFT - Image will be aligned to left.

l constants.CHECKBOX_SELECTION_IMAGE_ALIGNMENT_RIGHT - Image will be aligned to right.

Return Values

None

Exceptions

If input is invalid, an error is displayed.

Platform Availability

Available on iPhone and iPad.

JavaScript Example kony.application.setCheckBoxSelectionImageAlignment

(constants.CHECKBOX_SELECTION_IMAGE_ALIGNMENT_RIGHT);

Kony Studio API Developer's Guide

Version 3.1

3.7.1.38 kony.application.setCurrentSettingsMenu

This method uses the unique identifier which represents the Charm settings menu and sets it as current settings menu. There can be only one current settings menu that can be set any time. Calling this method multiple times, replaces the current Charm settings menu.

Signature

JavaScript:

kony.application.setCurrentSettingsMenu ( id )

Input Parameters id [String] - Mandatory.

Identifier of the Charm setting menu to be set.

Return Values

None.

Platform Availability

Available on Windows 8.

JavaScript Example

To create a Charm settings menu, enter the following: kony.application.setCurrentSettingsMenu ("myMenu")

3.7.1.39 kony.application.setDefaultTextboxPadding

This API customizes the default paddings applied for a Textbox. Generally, default padding is appended to padding applied through layout configurations of the widget.

Signature

JavaScript: kony.application.setDefaultTextboxPadding(

bool

)

Kony Studio API Developer's Guide

Version 3.1

Input Parameters bool [Boolean] - Mandatory

Indicates if the default padding is set.

True - Default padding is applied to textbox widgets.

False - No default padding is applied to textbox widgets.

Return Values

None

Platform Availability

Available on iPhone and iPad.

JavaScript Example kony.application.setDefaultTextboxPadding(false);

3.7.1.40 kony.application.setRespectImageSizeForImageWidgetAlignment

This API sets the ImageWidget width to minimum or maximum according to available width or image width in absence of reference width. If ImageWidget is smaller than the available width, it is aligned using the widget alignment rules.

Signature

JavaScript: kony.application.setRespectImageSizeForImageWidgetAlignment(

bool )

Input Parameters bool [Boolean] - Mandatory

Indicates if the default padding is set.

Kony Studio API Developer's Guide

Version 3.1

True - Sets the ImageWidget width to minimum.

False - Sets the ImageWidget width to maximum.

Return Values

None

Implementation Details

If this API is not used, the Image widget width is always the given width and image is center aligned.

Platform Availability

Available on iPhone and iPad.

JavaScript Example kony.application. setRespectImageSizeForImageWidgetAlignment (true);

3.7.1.41 kony.application.setSecondaryTile

This API enables you to create or update data for a secondary tile for an application. For more information about secondary tiles, refer Secondary tiles .

Signature

JavaScript:Mango kony.application.setSecondaryTile(

id ,

frontTileData

backTileData

)

Windows 8: kony.application.setSecondaryTile(

Windows 8: setsecondarytile(

shortname , displayname , imagename

)

Input Parameters for Mango id [String] - Mandatory

Unique identifier of the secondary tile.

Kony Studio API Developer's Guide

Version 3.1

frontTileData [Object] - Mandatory, If you do not set the front tile data, a default image and values will be used

Specifies the data to be displayed at the front of a tile. This hash table has the following inputs: l title [String] - Specifies the title to be displayed at the front of a tile.The title appears at the bottom of the tile as white text.

l backgroundImage [String] - Specifies the background image to be displayed at the front of a tile.

Note: The backgroundImage will use the specified image to fill the entire space of the tile, regardless of its actual size.

l count [integer] - specifies a number to be displayed at the top - right corner of the tile. The count value is displayed in a small black circle in white text.

Note:

The colors, sizes, and layout of the count and the title do not ever change.

backTileData[Object] - Optional

l backBackgroundImage [String] - specifies the background image to be displayed at the back of a tile.

l backcontent

[String] - specifies the content to be displayed at the back of a tile. The back content appears at the top of the tile as white text.

Note: The colors, sizes, and layout of the back content and the title do not ever change.

Kony Studio API Developer's Guide

Version 3.1

You can also set the backTileData to be nil. In this case, no information will be set on the back of the tile and the tile will not flip.

Input Parameters for Windows 8 id [String] - Mandatory

Unique identifier of the secondary tile.

shortname [String] - Mandatory

A short name displayed directly on the tile. Anything over 40 characters will be truncated. The user has the option to change this value as part of the pinning process.

displayname[String] - Optional

The text specified here is displayed when you hover over the tile. There is no restriction on the display name length or the characters that it can contain.

imagename [String] - Optional

Name of the image to be displayed on the tile.

Return Values

None

UI Behavior Mango

Considering we have set values for both the frontTileData and the backTileData, the tiles are rendered as follows:

Kony Studio API Developer's Guide

Version 3.1

Front Tile Back Tile

UI Behavior - Windows 8

The title and the display name of the tile will be displayed in white or black depending on the setting in

Platform Availability

Available on Windows Mango, Windows Phone 8, and Windows 8.

JavaScript Example

The usage of this API on Mango is shown in the code snippet below:

//Setting the front and back tile data frontTileData:{"Front Tile Title", "test.png", 20 backTileData:{"Front Tile Title", "test.png", "This is the back tile content"}

Kony Studio API Developer's Guide

Version 3.1

//Set the secondary tile with the front and back tile data witht ile id 1234 kony.application.setSecondaryTile("1234", frontTileData, backTileData );

The usage of this API on Windows 8 is shown in the code snippet below:

//Setting a secondary tile for an application with tile id myTile1.

kony.application.setSecondaryTile("myTile1", "title text", "display name", "orange.png");

3.7.1.42 kony.application.setZoomedOutView

You can design a user interface to be displayed to the end user when you zoom out of an application.

This API enables you to set a form to be shown to the user when a zoom out gesture is performed.

This API is introduced to support the Semantic Zoom feature introduced with Windows 8. For more information about Semantic zoom,zoomed in, and zoomed out views, refer http://msdn.microsoft.com/en-us/library/windows/apps/hh465319.aspx

Signature

JavaScript: kony.application.setZoomedOutView(

formid

)

Kony Studio API Developer's Guide

Version 3.1

Input Parameters formid [Widget Reference] - Mandatory

Specifies the id of the form to be displayed when the user zooms out of the application.

Return Values

None.

Platform Availability

Windows 8

JavaScript Example

//Zooming out of a an application and displaying a form with an id myForm1 on zoomout function zoomout()

{ kony.application.setZoomedOutView(myForm1);

}

3.7.1.43 kony.application.showLoadingScreen

This API allows you to display a loading screen (following a certain color schema) to the user while another action is in progress. The loading screen can be defined in such a way it can either block the

UI or does not block the UI. Typically, the loading screen is a semi-transparent screen over-laid on the current form.

Use Case

You can use this API to display a loading screen to the end user with a specific skin attached to it in the following scenarios:

Kony Studio API Developer's Guide

Version 3.1

l on invoking a service l on executing a user-defined function that takes some time for execution.

Signature

JavaScript: kony.application.showLoadingScreen(

skin

text

position , isBlocked ,

showProgressIndicator

properties )

Input Parameters skin [skin identifier] - Mandatory

The skin to be applied to the loading screen. All the skin attributes supported by different platforms are applicable. This is a reference to an existing skin. If it is nil, the native platform skin is applied.

text [String] - Mandatory

The text to be displayed when displaying the loading screen. For example, "Searching flights...". If it is nil, no text is displayed.

position [String] - Mandatory

Indicates the position of the loading screen, whether it should occupy the entire screen or just the center of the screen. The possible values for position are : l constants.LOADING_SCREEN_POSITION_FULL_SCREEN (default) l constants.LOADING_SCREEN_POSITION_ONLY_CENTER.

Note: Currently only center and fullscreen are supported.

isBlocked [Boolean] - Mandatory

Indicates if the UI should be blocked.

l true - no click and scroll is allowed on the UI. The Back button on the device also does not work. true is the default value.

Kony Studio API Developer's Guide

Version 3.1

l false - click and scroll is allowed(UI is not blocked) and back button of the device also works.

If nothing is specified, default value is used.

showProgressIndicator [Boolean] - Mandatory

Indicates if the progress indicator should be displayed.

l true - displays the progress indicator. true is the default value.

l false - does not display the progress indicator.

Note:

The progress indicator is a set of animating images.

properties [Object] - Mandatory

Indicates the platform specific properties to be applied to the loading screen.

Note: You must pass this parameter as nil on all platforms except BlackBerry and iPhone platform.

The following are the key-value pairs to be passed in the table for BlackBerry:

JavaScript enableMenuKey

(boolean) enableBackKey

(boolean)

Description if true the menu key is enabled and user is able to select the menu items.

If true the Back button on the device is enabled and user is able to execute the default back behavior as defined by the application.

Important: These key-value pairs are applicable only on

BlackBerry platform.

The following are the key-value pairs to be passed in the table for iPhone:

Kony Studio API Developer's Guide

Version 3.1

JavaScript shouldShowLabelInBottom

(boolean/string) separatorHeight(number)

Description

To display the text content at the bottom or the top side of the activity indicator.

Default value is false. If string "true" is passed to this property then it will display the content at the bottom of the activity indicator.

Height between the activity indicator and text to be displayed.

Default height is 30px. Should be greater than 0.

Important:

These key-value pairs are applicable only on iPhone platform.

progressIndicatorColor

(String) progressIndicatorType

(Constant)

Color is applied for progress indicator when it is shown. (Optional)

Note: Only "white" and "gray" colors are supported. Default is white. White and gray values are not case sensitive.

Set the type of progress indicator. The following types are provided: l constants.PROGRESS_INDICATOR_TYPE_SMALL

l constants.PROGRESS_INDICATOR_TYPE_BIG

l constants.PROGRESS__INDICATOR_TYPE_DEFAULT

(Default value)

Note: progressIndicatorType:constants.PROGRESS_

INDICATOR_TYPE_BIG with "progressIndicatorColor:GREY" is not supported in iOS platform.

The following are the key-value pairs to be passed in the table for all platforms except BlackBerry and iPhone:

Kony Studio API Developer's Guide

Version 3.1

JavaScript progressIndicatorColor

(String)

Description

Color is applied for progress indicator when it is shown. (Optional)

Note: All colors with RGBA (Hex code) are supported, but for

"white" and "gray" you can pass it as a string value. Color value should be similar to the value provided in the theme.

Return Values

None.

Platform Availability

Available on all platforms except Mobile Web.

JavaScript Example

//Invoking showLoadingScreen on BlackBerry platform.

kony.application.showLoadingScreen

("loadskin","LoadingScreen",constants.

LOADING_SCREEN_POSITION_ONLY_CENTER, false,true,

{enableMenuKey:true, enableBackKey:true});

//Invoking showLoadingScreen on iPhone platform.

kony.application.showLoadingScreen(null, "testf", constants.LOADING_SCREEN_POSITION_ONLY_CENTER, false, true, { shouldShowLabelInBottom: "true", separatorHeight: 200, progressIndicatorType : constants.PROGRESS_INDICATOR_TYPE_SMALL,

Kony Studio API Developer's Guide

Version 3.1

progressIndicatorColor : "Gray"} )

//Invoking showLoadingScreen on other platform.

kony.application.showLoadingScreen

("loadskin","LoadingScreen",constants.

LOADING_SCREEN_POSITION_ONLY_CENTER, false,true,

{enableMenuKey:true, enableBackKey:true, progressIndicatorColor : "ffffff77"})

3.7.1.44 kony.application.unregisterForIdleTimeout

This API specifies that the application must not timeout after a defined period of inactivity (time difference between the current device time and the last time you clicked on any user interface component). This API unregisters the application from idletimeout.

Use Case

This API must be used in case you do not want to track the idle time, i.e., do not want to logout even if the application is inactive for a specific time interval.

Signature

JavaScript: kony.application.unregisterForIdleTimeout()

Input Parameters

The API does not have any input parameters.

Return Values

None.

Kony Studio API Developer's Guide

Version 3.1

Rules and Restrictions

This API is applicable only when the Form property Enable Time Out is set to true. For more information about Enable Time Out property, see Widget User Guide.

Platform Availability

Available on all platforms.

JavaScript Example function unregisterForIdleTimeout()

{ kony.application.unregisterForIdleTimeout(); alert("====unRegister======");

}

3.7.1.45 kony.application.zoomIn

This API enables you to zoom in on an application programmatically. If the application is already zoomed in, this API has no effect.

UseCase

Suppose your application is in a zoomed out state where the contacts associated with that letter is displayed. You can use this API to view all the contacts alphabeticallyand present the data using the letters of the alphabet.

Signature

JavaScript: kony.application.zoomIn()

Input Parameters

None

Kony Studio API Developer's Guide

Version 3.1

Return Values

None.

Platform Availability

Windows 8

JavaScript Example

//Enabling zoomin on an application function zoomIn()

{ kony.application.zoomIn();

}

3.7.2 Objects

The kony.application namespace provides the following object.

AppWindow

3.7.2.1 AppWindow Object

Delete this text and replace it with your own content.

3.8 kony.application.settings Namespace

The kony.application.settings Namespace provides the following API elements.

Functions

Kony Studio API Developer's Guide

Version 3.1

3.8.1 Functions

3.8.1.1 kony.application.settings.read

This API allows you to read the configurations associated with a specified key. This is an asynchronous call.

Use Case

This API must be used in case you want to read the user-defined values such as preferred locations.

Signature

JavaScript

: kony.application.settings.read (

key , onsuccesscallback , onfailureback

)

Input Parameters key[String] - Mandatory

Specifies the key for which you want to read the settings. The settings are read from the application settings file that is bundled along with the application binary.

onsuccesscallback [Function] - Mandatory

Specifies the callback function that must be executed when a key-value is read successfully. The callback function has the following signature: onsuccess(key,value) - Mandatory

Value can be boolean, string, double, or an object.

An object is returned only when Display option is multi-select.

onfailurecallback [Function] - Mandatory

Specifies the callback function that must be executed when there is an error in fetching the app setting. This callback function receives the error code and the error message. The callback function has the following signature:

Kony Studio API Developer's Guide

Version 3.1

onfailure(errorcode,errormessage)

Return Values

This API asynchronously returns the settings for a key by invoking onsuccess callback and does not return any values directly.

Rules and Restrictions

This API is applicable only when the application settings are set.

Platform Availability

Available only on iPhone

JavaScript Example

//The below four functions are callback functions for kony.application.

settings.read API function onsuccesscallback(key,value)

{

//Write Your Logic here

} function onfailureback(errorcode,errormessage)

{ alert("err is :"+errormessage);

} function onsuccesscallbackR(key,value)

{

//Write Your Logic here

} function onfailurebackR(errorcode,errormessage)

{ alert("Err is :"+errormessage);

Kony Studio API Developer's Guide

Version 3.1

} function read()

{

//Read the settings kony.application.settings.read

("key1", onsuccesscallback, onfailureback) kony.application.settings.read

("key2", onsuccesscallbackR, onfailurebackR)

}

3.8.1.2 kony.application.settings.write

This API allows you to write the values to the specified key with the given value. New keys cannot be introduced with this API. When the value for the specified key is modified using this API, the changes should reflect in the application settings at the device level. This is an asynchronous call.

Signature

JavaScript:

kony.application.settings.write ( key

value, onsuccesscallback , onfailurecallback )

Input Parameters key[String] - Mandatory

Specifies the unique key. The key that you specify must exist. You cannot introduce a new key.

value [String] - Mandatory

Specifies the value to be set for a key. The existing value would be replaced with the new value.

Value can be boolean, string, double, or an object.

An object is returned only when "Display option" is multi-select.

Kony Studio API Developer's Guide

Version 3.1

onsuccesscallback [Function] - Mandatory

Specifies the callback function that must be executed when the new value is updated against the specified key. The callback function has the following signature: onsuccess(key,value)

Value can be boolean, string, double, or an object.

An object is returned only when " Display option" is multi-select.

onfailurecallback [Function] - Mandatory

Specifies the callback function that must be executed when there is an error in updating the configuration. This callback function receives the error code and the error message. The callback function has the following signature: onfailures(errorcode,errormessage)

Return Values

This API asynchronously returns the values by invoking on success and does not return any values directly.

Rules and Restrictions

This API is applicable only when the application settings are set.

Platform Availability

Available only on iPhone

JavaScript Example

//The below four functions are callback functions for kony.application.

settings.write API

Kony Studio API Developer's Guide

Version 3.1

function onsuccesscallbackw(key,value)

{

//Write Your Logic here

} function onfailurebackw(errorcode,errormessage)

{ alert("Error is :"+errormessage);

} function onsuccesscallbackWrite(key,value)

{

//Write Your Logic here

} function onfailurebackWrite(errorcode,errormessage)

{ alert("Error is :"+errormessage);

} function write()

{

//Write the settings kony.application.settings.write("key1","Message1", onsuccesscallbackw, onfailurebackw); kony.application.settings.write("key2","Message2", onsuccesscallbackWrite, onfailurebackWrite);

}

3.9 kony.camera Namespace

The kony.camera namespace contains the following API elements.

Functions

Kony Studio API Developer's Guide

Version 3.1

3.9.1 kony.camera Functions

The kony.camera namespace contains the following functions.

kony.camera.releaseRawBytes

This API enables you to delete rawbytes for the image. If you use this API, the captured image is deleted from the disk or in-memory.

The following are the important considerations for this API: l

Rawbytes once released using this API cannot be used or released again.

If multiple handles to the same rawbytes exist, and if you release the rawbytes using any of those handles, the other handles become obsolete.

Use Case

You can use this API to delete rawbytes of an image (captured from the camera) for memory management and better user experience so that the mobile application runs smoothly.

Signature

JavaScript: kony.camera.releaseRawBytes(

rawBytes

)

Input Parameters rawBytes [Object] - Mandatory

Specifies the rawbytes of the image (captured from the camera) you want to release when the camera widget accessMode property is set as: l

CAMERA_IMAGE_ACCESS_MODE_PUBLIC: The captured image is stored on the device as a Image and is accessible to all the applications on the device.

CAMERA_IMAGE_ACCESS_MODE_PRIVATE: This is the default option for

Windows platform. The captured image is stored as an Image on the device and

Kony Studio API Developer's Guide

Version 3.1

will not be accessible to any other application on the device and remain private to the application.

CAMERA_IMAGE_ACCESS_MODE_INMEMORY: The captured camera image is stored in memory and is never written to the disk.

Return Values

None

Best Practices

Scenario 1

If you try to release rawbytes that was already released, you will encounter an exception.

To avoid an exception, you must follow the following best practices to ensure that rawbytes are released properly:

1. Before releasing the rawbytes, ensure that the rawbytes handle is not null.

2. Assign null after releasing the rawbytes.

JavaScript Example if( null != RawBytesHandle){ kony.camera.releaseRawBytes(RawBytesHandle)

RawBytesHandle = null

} else

//RawBytesHandle already released (or rawbytes not assigned to it)

Scenario 2

If you assign a handle to new rawbytes without releasing the rawbytes that the handle is currently pointing to, the access to the previous rawbytes is lost and will be released only at the time of application termination.

Kony Studio API Developer's Guide

Version 3.1

To avoid such a scenario, you must do the following:

1. Initialize the rawbytes handle to null before use.

2. Before assigning the rawbytes, ensure that the rawbytes handle is null.

JavaScript Example if( null == RawBytesHandle)

RawBytesHandle = cameraWidget.rawBytes

else

// RawBytesHandle not empty, release it and then use.

The following best practices ensure that rawbytes are properly treated and released.

1. Check if the rawbytes handle is not null before releasing.

2. Make sure to assign null after releasing rawbytes.

3. Initialize RawBytesHandle to null before use.

4. Check if RawBytesHandle is not null, before assigning RawBytes.

Platform Availability

Available on all platforms except SPA.

JavaScript Example

//To delete the rawbytes captured by the camera widget cam1 in form

Frm1, enter the following: var imagetodel = frm1.cam1.rawBytes

kony.camera.releaseRawBytes(imagetodel) or kony.camera.releaseRawBytes(frm1.cam1.rawBytes)

Kony Studio API Developer's Guide

Version 3.1

3.10 kony.contact Namespace

The kony.contact namspace, part of the Phone API, provides the following API elements.

Functions

3.10.1 kony.contact_Functions

The kony.contact namespace contains the following functions.

3.10.1.1 kony.contact.add

This API adds a contact to the address book of the mobile device.

Important: On Windows Phone 7.5, you have to manually click the Save button to add the contact.

Signature

JavaScript: kony.contact.add(

contactDetails )

Parameters contactDetails [Table] - Mandatory

A table that has the following key-value pairs: l firstname - specifies the first name of the contact l lastname - specifies the last name of the contact

Kony Studio API Developer's Guide

Version 3.1

l phone - array of arrays containing

Label and number

Note: The phone number can contain a + (for country code), - (hyphen) (to separate country code, STD code, and the number), and space ((to separate country code, STD code, and the number). No other characters are allowed within a phone number.

Note: For example, +919999999999, +91 99999 99999, or +91-99999-99999.

l email - array of arrays containing

Label and emailID l postal - array of arrays containing

Label and address in a table with defined keys l company - array of arrays containing Label followed by table with company name and title keys

Note: firstname and phone fields are mandatory with at least one phone number in phone field

The following are the Labels for different fields in the table: phone email postal company

Keys in the Table Possible Labels

•Mobile •Home •Work •Other

•Home •Work •Other

•Work •Other

Return Values

The following are the return values for this API:

Kony Studio API Developer's Guide

Version 3.1

Reference [Table]

Table containing the information related to the newly created contact is returned.

nil

If the contact was not created.

Error Codes

If any of the field is not stored, the field is ignored. If no field is stored, an error is raised.

Implementation Details

The following are the implementation details: l firstname and phone field with empty string or nil does not create a contact and the API call is ignored.

Other fields with empty string or nil or invalid data type assignment are ignored.

l id field is read only property and must not be modified by the application.

API Usage

When you use this API with Android emulator that uses Android SDK 2.0 and above, you will be prompted to create an account to add contacts.

Creating an account (Google/GMail) is a mandate to add contacts. This is an Android platform limitation.

Ensure that the following permissions are set for Android: l

READ_CONTACTS l

WRITE_CONTACTS l

GET_ACCOUNTS.

Kony Studio API Developer's Guide

Version 3.1

You can set these permissions for Android under Manifest Properties in Project Properties ->

Native App -> Android. For more information about Android Manifest permissions, see Kony

Visualizer User Guide.

Platform Availability

Available on all platforms except SPA, Desktop Web, Mobile Web, Kiosk, Windows 8, and Win Mobile

6x.

3.10.1.2 kony.contact.details

This API displays the details of a given contact and returns a new instance of the contact structure.

The API is introduced to improve the performance and for effective utilization of memory. In platforms like Android, contact information is stored in multiple database tables, one table contains the contact id, first name, and lastname, and the another table contains the entire contact details. The contacts application displays only firstname, lastname in the initial screen, and when the user selects a particular contact, the details are shown in next screen.

When you to accommodate the contact details in one call to contact.find API, the memory is not sufficient when the contacts are numerous. This results in an out of memory issue and results in performance issues in many applications.

Signature

JavaScript:

kony.contact.details( ReferenceTable

)

Parameters

ReferenceTable - Mandatory

Specifies the reference table returned by the contact.find API

Kony Studio API Developer's Guide

Version 3.1

Return Values

Reference [Table]

Table of the contacts retrieved. The reference table retrieved contains a field photorawbytes. This is a new property in the existing contact structure that should be populated with raw bytes, just like camera or gallery raw bytes.

Example of the reference table returned:

{ firstname="John", lastname="Xyz",

//array of arrays containing "Label" and "number" phone={{name="mobile",number="99999999999"},

////array of arrays containing "Label" and "emailid"

{name="home",number="99999999999"},

{name="home",number="5555555555"},.....}, email={{name="home",id="[email protected]" },

{name="work",id="[email protected]"},....},

////array of arrays containing "Label" and address in a table with defined keys.

postal=

{name="home",street="ABC",city="hyderabad",state="AP",zipcode="50031

0"}

{name="work",street="XYZ",city="hyderabad",state="AP",zipcode="50001

0"}

,...},

Kony Studio API Developer's Guide

Version 3.1

//array of arrays containing "Label" followed by table with company name and title keys.

company={{name="work",company="kony",title="Tester"},

{name="other",company="abc",title="VP"},...}, id="platform specific identifier for the contact" photorawbytes=rawbytes

} nil

If no contact is retrieved.

Platform Availability

Available on all platforms except SPA, Desktop Web, BlackBerry 10, Mobile Web, Kiosk,Windows 8, and Windows Mobile 6x.

JavaScript Example function form1_button15681600315097_onClick_seq0(eventobject) { var array = kony.contact.find('John', false) var dict = array[0] kony.print(kony.contact.details(array[0]))

};

3.10.1.3 kony.contact.find

This API parses through the address book of the mobile device and looks for contacts that match the input string.

Signature

JavaScript: kony.contact.find(

firstName , needdetails

)

Kony Studio API Developer's Guide

Version 3.1

Parameters firstName [String] - Mandatory

A string that represents the firstname of the contact.

needdetails [boolean] - Optional

When the needdetails parameter is not passed, the default value set is true. When needdetails is set to true, this API returns the complete details of the contact. If needdetails is false, contact.find

returns a list of contacts with a new field called displayname in the existing contact structure. All other fields of contact structure are not populated.

displayname is a combination of firstname and lastname.

displayname is a platform specific Android property.

Return Values

Reference [Object]

Table containing the list of all the contacts that contain the input string nil

If there is no contact with the specified first name

Implementation Details

This API searches and matches only the contacts that have the firstname as the specified input string.

Platform Availability

Available on all platforms except SPA, Desktop Web, Mobile Web, Kiosk, and Win Mobile 6x.

3.10.1.4 kony.contact.remove

This API deletes the contact (s) that was returned by the contact.find operation.

Signature

JavaScript: kony.contact.remove(

ReferenceTable

)

Kony Studio API Developer's Guide

Version 3.1

Parameters

ReferenceTable - Mandatory

Specifies the reference table returned by the contact.find API

Return Values

Reference [Table]

Table of the contacts that is deleted nil

If no contact is deleted

Platform Availability

Available on all platforms except SPA, Desktop Web, Mobile Web, Kiosk, Windows 8, Windows

Phone 7.5, and Win Mobile 6x.

3.11 kony.crypto Namespace

The kony.crypto namespace provides the following API elements.

Functions

3.11.1 Functions

The kony.crypto namespace contains the following functions.

3.11.1.1 kony.crypto.createHash

Hash value is a unique and compact numerical representation of a chunk of data.

This API provides the ability to create a hash value in hexadecimal format for a given input string, using the specified algorithm.

Kony Studio API Developer's Guide

Version 3.1

Use Cases

You can use this API when you want to mask sensitive data with a numerical representation.

Signature

JavaScript:

kony.crypto.createHash( algo , inputstring )

Input Parameters algo [String] - Mandatory

Algorithm to be used for creating the hash value. Possible values are: l sha1 l sha224 l sha256 l sha384 l sha512 l md2 l md4 l md5

Important: l sha224, sha384,sha512, md2, md4,and md5 Algorithm are not supported in

Windows Platforms.

inputstring [String] - Mandatory

Input string for which the hash value needs to be created.

Kony Studio API Developer's Guide

Version 3.1

Return Values hashValue [String]

Hash value created using the specified algorithm for the given input string. This string is in hexadecimal format. Length of the hashValue string in bytes is as follows (for each algorithm):

1. sha1

2. sha224

3. sha256

4. sha384

5. sha512

6. md2

7. md4

8. md5

For details about the digest length and hexa decimal string length, see the table given below.

Hashing

Algorithm sha1 sha224 sha256 sha384 sha512

Digest Length (in bytes)

20 40

Hexa Decimal String Length (in characters)

28 56

128

Kony Studio API Developer's Guide

Version 3.1

Hashing

Algorithm md2 md4 md5

Digest Length (in bytes)

16 32

Hexa Decimal String Length (in characters)

Exceptions

CryptoError: Thrown by Crypto API.Various error conditions related to CryptoError will be covered through the following error codes.

2001 - unsupported algorithm.

2002 - invalid key strength specified.

2003 - insufficient buffer provided for specified operation.

2004 - memory allocation failure.

2005 - input data did not encode or encrypt properly.

2006 - specified name already exists.

2007 - key with the specified unique ID is not found.

Error

Platform Availability

Available on all platforms except J2ME and Windows Kiosk.

Kony Studio API Developer's Guide

Version 3.1

JavaScript Example var algo="md5"; var inputstr="pleasecreatehash"; var myHashValue = kony.crypto.createHash(algo,inputstr);

3.11.1.2 kony.crypto.createHMacHash()

HMAC (Hash-based Message Authentication Code) uses a cryptographic key along with a user selected hash function to generate a MAC (Message Authentication Code).

The purpose of this API is to return Hash value of a given message. The cryptographic strength of the

HMAC depends upon the cryptographic strength of the underlying hash function, the size of its hash output, and on the size and quality of the key.

Signature var myHash = kony.crypto.createHMacHash(algo, key, message);

Input Parameters algo [String] - Mandatory

Hashing algorithm used to create for creating the hash value. Refer to

Supported Algorithms

table for a list of supported algorithms in each platform.

key [String] - Mandatory

Input key to algorithm.

message [String] - Mandatory

Plain text for which hash needs to be generated.

Kony Studio API Developer's Guide

Version 3.1

Return Values hashValue [String]

Hash value created using the specified algorithm for the given input string. This string is in a hexadecimal format. For details about the digest length and hexadecimal string length, refer to the

Hash lengths table under the CreateHash API

return values

section.

Platform Availability

Available in iOS and Android

In Android, the Bundle OpenSSL Library option is available in Application Properties

> Native > Android section. If this option is selected, OpenSSL library is bundled along with the application.

If the Bundle OpenSSL Library option is selected in Kony Visualizer, the implementation in

OpenSSL library is invoked.

If the Bundle OpenSSL Library option is not selected in Kony Visualizer, the default Java implementation offered by native Android platform is invoked.

Note: Supported hashing algorithms for each case are listed in the

algorithms

table. If the device under testing does not support a user requested hashing algorithm, a corresponding error message will be thrown by the API.

Exceptions

Common error codes and their descriptions follow: l

100 - Invalid input parameters l

101 - Unsupported algorithm l

102 - Unknown error l

104 - Invalid key strength

Kony Studio API Developer's Guide

Version 3.1

105 - Sub algorithm parameter is mandatory l

109 - The specified item could not be found

JavaScript Example var myHash = kony.crypto.createHMacHash("SHA1","key1","test message to generate hash"); kony.print("myHash :" + myHash);

Supported Algorithms

The following table lists algorithms supported for a specific platform.

Platform Name

Android Default Implementation

Supported Algorithms

MD5, SHA1, SHA224, SHA256, SHA384, SHA512 (

SHA224 supported only on API level 21 and above)

MD5, SHA1, SHA224, SHA256, SHA384, SHA512 Android OpenSSL Implementation (Bundle

OpenSSL Library option is selected in Kony

Visualizer) iOS MD5,SHA1,SHA224,SHA256,SHA384,SHA512

3.11.1.3 kony.crypto.createPBKDF2Key()

Password-Based Key Derivation Function 2 (PBKDF2) is a key derivation function that generates encryption keys of different lengths to protect passwords.

PBKDF2 applies a hash function (chosen by algorithm input) to the input password or passphrase along with a salt value and repeats the process many times to produce a derived key, which is used as a cryptographic key in subsequent operations. The added computational work, or key stretching, makes it more difficult to crack a password.

Kony Studio API Developer's Guide

Version 3.1

This function uses a password in plain text, a salt value and iteration count, as inputs and generates a

PBKDF2 key using the supplied

hashing algorithm .

Signature var mySecureNewKey = kony.crypto.createPBKDF2Key

(algo, password, salt ,iteration, klen);

Input Parameters algo [String] - Mandatory

Hashing algorithm used for creating the key. Refer to

Supported Algorithms

table for a list of supported algorithms in each platform.

password [String] - Mandatory

Master password from which a derived key is generated.

salt [String] - Mandatory

A random salt input string from a programmer iteration [Number] - Mandatory

The desired number of iterations klen [Number] - Optional

The klen is the desired length of the derived key in bits. If the key length is not specified, this value defaults to 256-bits.

Note: If klen key is used for encryption or decryption, a developer needs to make sure that this key length (klen) is supported by a corresponding encryption or decryption algorithm.

aes - possible values are 128, 192, and 256.

tripledes - possible value is 192.

Return Values

The following are the return values for this API:

Kony Studio API Developer's Guide

Version 3.1

key [userdata] - object

The key created using the PBKDF2 algorithm.

Platform Availability

Available in iOS and Android

In Android, the Bundle OpenSSL Library option is available in Application Properties

> Native > Android section. If this option is selected, the OpenSSL library is bundled along with the application.

If the Bundle OpenSSL Library option is selected in Kony Visualizer, implementation in

OpenSSL library is invoked.

If the Bundle OpenSSL Library option is not selected in Kony Visualizer, default Java implementation offered by the native Android platform is invoked.

Note: Supported hashing algorithms for each case are listed in the

algorithms

table. If the device under testing does not support a user requested hashing algorithm, a corresponding error message is thrown by the API.

Exceptions

Common error codes and their descriptions follow: l

100 - Invalid Input parameters l

101 - Unsupported algorithm l

102 - Unknown error l

104 - Invalid key strength l

105 - Sub algorithm parameter is mandatory l

109 - The specified item could not be found

Kony Studio API Developer's Guide

Version 3.1

JavaScript Example var mySecureNewKey = kony.crypto.createPBKDF2Key

("SHA1","password","salt",1000,256); kony.print("mySecureNewKey :" + mySecureNewKey);

Supported Algorithms

The following table lists algorithms supported for a specific platform.

Platform Name

Android Default Implementation

Android OpenSSL Implementation (Bundle

Open SSL Library option is selected in Kony

Visualizer) iOS

Supported Algorithms

SHA1

MD5, SHA1, SHA224, SHA256, SHA384, SHA512

SHA1 , SHA224, SHA256, SHA384, SHA512

3.11.1.4 kony.crypto.decrypt

This API provides the ability to decrypt the encrypted text with the specified key and algorithm. The

API returns the decrypted text.

Use Cases

You can use this API to decrypt secured data like: l passwords l account information l credit card information, and so on.

Kony Studio API Developer's Guide

Version 3.1

Signature

JavaScript: kony.crypto.decrypt(

algo , generatedkey , encryptedRawbytes

propertiesTable )

Input Parameters algo [String] - Mandatory

Algorithm using which the encrypted text needs to be decrypted. Possible values are: l aes l tripledes

Important: l tripledes Algorithm is not supported in Windows Platforms.

generatedkey [Object] - Mandatory

The key to be used for decryption.

Note:

As we currently support only symmetric decryption, we use the same key used for encryption.

encryptedRawbytes [Object] - Mandatory

The rawbytes of the encrypted text that need to be decrypted.

propertiesTable [Table] - Mandatory

This Object contains the following key-value pairs: l padding - a string that denotes the padding that needs to be applied.

Note: If padding is none, and the text length is less than the block size, the underlying platform throws a Bad Padding error.

Kony Studio API Developer's Guide

Version 3.1

Block size for different algorithms is as follows: l aes - 128 bits l tripledes - 64 bits l rsa - 1024 or 2048 bits l mode - a string that denotes the encryption mode.

l initializationvector - a string that denotes the IV to be used.

Note: This parameter is applicable only if the algorithm is aes or tripledes.

Return Values clearText [String]

The clear text decrypted from the encrypted rawbytes.

Exceptions

CryptoError: Thrown by Crypto API.Various error conditions related to CryptoError will be covered through the following error codes.

2001 - unsupported algorithm.

2002 - invalid key strength specified.

2003 - insufficient buffer provided for specified operation.

2004 - memory allocation failure.

2005 - input data did not encode or encrypt properly.

2006 - specified name already exists.

2007 - key with the specified unique ID is not found.

Error

Kony Studio API Developer's Guide

Version 3.1

Platform Availability

Available on all platforms except J2ME.

JavaScript Example var algo="aes"; var encryptDecryptKey = kony.crypto.newKey("passphrase", 128,

{passphrasetext: ["inputstring1"], subalgo: "aes", passphrasehashalgo: "md5"}); var inputstr="pleaseencryptme"; var prptobj={padding:"pkcs5",mode:"cbc",initializationvector:

"1234567890123456"}; var myEncryptedText = kony.crypto.encrypt(algo,encryptDecryptKey, inputstr,prptobj); var myClearText = kony.crypto.decrypt(algo,encryptDecryptKey, myEncryptedText,prptobj);

3.11.1.5 kony.crypto.deleteKey

This API provides you the ability to delete a key from the device store.

Use Cases

You can delete the key from the device store if you are sure that you do not need that key anymore in the application.

Signature

JavaScript:kony.crypto.deleteKey(

uniqueID

)

Kony Studio API Developer's Guide

Version 3.1

Input Parameters uniqueID [String] - Mandatory

Unique ID represents the key on the device store (this is the ID returned by kony.crypto.saveKey

API).

Return Values

None.

API Usage

You can use this API only to delete the keys that you have saved earlier on the device store,which is keys that have a unique ID associated with it.

Exceptions

CryptoError: Thrown by Crypto API.Various error conditions related to CryptoError will be covered through the following error codes.

2001 - unsupported algorithm.

2002 - invalid key strength specified.

2003 - insufficient buffer provided for specified operation.

2004 - memory allocation failure.

2005 - input data did not encode or encrypt properly.

2006 - specified name already exists.

2007 - key with the specified unique ID is not found.

Error

Platform Availability

Available on all platforms except J2ME and Windows Kiosk.

Kony Studio API Developer's Guide

Version 3.1

JavaScript Example var encryptDecryptKey = kony.crypto.newKey("passphrase", 128,

{passphrasetext: ["inputstring1"], subalgo: "aes", passphrasehashalgo: "md5"}); var myUniqueIDKey = kony.crypto.saveKey("myKey",encryptDecryptKey); kony.crypto.deleteKey(myUniqueIDKey);

Note: You can use this API only to delete the keys that you have saved earlier on the device store, i.e., keys that have a unique ID associated with them.

3.11.1.6 kony.crypto.encrypt

Converting data into an encoded format using a key is known as encryption. Encryption of data is done through symmetric cryptography. We support both symmetric and asymmetric encryption.

This API provides the ability to encrypt the input text with the specified key and algorithm. The rawbytes of the encrypted text are returned.

Use Cases

You need to use encryption when you pass sensitive data like: l passwords l account numbers l account information l credit card information, and so on.

Signature

JavaScript: kony.crypto.encrypt(

algo , generatedkey , inputstring

propertiesTable

)

Kony Studio API Developer's Guide

Version 3.1

Input Parameters algo [String] - Mandatory

Specifies the algorithm using which the input string needs to be encrypted.

Possible values are:

1. aes

2. tripledes

3. rsa

Important: l tripledes algorithm is not supported in Windows Platforms.

generatedkey [Object] - Mandatory

The key to be used for encryption.

On Windows Phone and Kiosk, this parameter is the byte array that is returned in a call to kony.crypto.retrievePublicKey.

On Windows 8 this parameter is the name of the certificate that is included in the root directory of the Windows package, in “resources/common” in Kony Visualizer.

On all other platforms this API accepts the key generated using the kony.crypto.newKey API.

inputstring [String] - Mandatory

Data which needs to be encrypted.

propertiesTable [Table] - Mandatory

Note: This parameter is ignored in Windows 8.

Kony Studio API Developer's Guide

Version 3.1

This Object contains the following key-value pairs: l padding - a string that denotes the padding that needs to be applied.

Note: Windows Phone and Kiosk support pkcs and oeap padding.

l mode - a string that denotes the encryption mode.

Note: This value is ignored for the rsa algorithm.

l initializationvector - a string that denotes the Initialization Vector to be used.

Note: This parameter is applicable only if the subalgo is aes or tripledes.

Return Values rawbytes [Object] - userdata

The rawbytes for the encrypted version of the input text.

Exceptions

CryptoError: Thrown by Crypto API.Various error conditions related to CryptoError will be covered through the following error codes.

2001 - unsupported algorithm.

2002 - invalid key strength specified.

2003 - insufficient buffer provided for specified operation.

2004 - memory allocation failure.

2005 - input data did not encode or encrypt properly .

2006 - specified name already exists.

2007 - key with the specified unique ID is not found.

Kony Studio API Developer's Guide

Version 3.1

Error

Platform Availability

Available on all platforms except J2ME.

JavaScript Examples var algo="aes"; var encryptDecryptKey = kony.crypto.newKey("passphrase", 128,

{passphrasetext: ["inputstring1"], subalgo: "aes", passphrasehashalgo: "md5"}); var inputstr="pleaseencryptme"; var prptobj={padding:"pkcs5",mode:"cbc",initializationvector:

"1234567890123456"}; var myEncryptedText = kony.crypto.encrypt(algo,encryptDecryptKey, inputstr,prptobj);

Example for Windows Phone and Kiosk var algo="rsa"; var encryptDecryptKey = kony.crypto.retrievePublicKey

("rsa","sample.cer",true); var inputstr="pleaseencryptme"; var prptobj={padding:"pkcs1",mode:"ecb"}; var myEncryptedText = kony.crypto.encrypt

(algo,encryptDecryptKey,inputstr,prptobj); kony.print("********************************myEncryptedText

Kony Studio API Developer's Guide

Version 3.1

is::****************************"); kony.print(myEncryptedText); alert ("Encrypted Text : " + myEncryptedText);

Example for Windows 8 var algo="rsa"; var inputstr="pleaseencryptme"; var prptobj={padding:"",mode:""}; var myEncryptedText = kony.crypto.encrypt

(algo,"sample.cer",inputstr,prptobj); kony.print("********************************myEncryptedText is::****************************"); kony.print(myEncryptedText); alert ("Encrypted Text : " + myEncryptedText);

3.11.1.7 kony.crypto.newKey

This API allows you to create a key for cryptography using the specified algorithm. The key created using this API is used for encrypting clear text and decrypting the encrypted data.

Use Case

You can use this API to generate cryptographic keys when you want to transmit information in a secured manner over the private or public networks.

Signature

JavaScript: kony.crypto.newKey(

algo

keystrength ,

propertiesTable )

Kony Studio API Developer's Guide

Version 3.1

Input Parameters algo [String] - Mandatory

Scheme using which the key is to be created. Possible values are: l securerandom - uses a secure random number as the scheme to generate a key. This scheme always produces a unique key.

l random - uses a random number as the scheme to generate a key. This scheme always produces a unique key.

Note: random and securerandom are supported only on iPhone.

Note:

There is no differentiation between securerandom and random on Android and

BlackBerry platforms.

l passphrase - if this is the scheme, you need to pass the exact passphrase using which the key needs to be generated. The passphrasetext (an array of strings) is passed in the properties (JavaScript) parameter. The passphrase scheme always produces the same key for the same passphrase text.

Note: Only Passphrase is supported on SPA.

keystrength [Number] - Mandatory

Number of bits that indicate the key strength. If the subalgo is: aes - possible value is 128, 192, 256.

tripledes - possible value is 192.

Important:

Kony Studio API Developer's Guide

Version 3.1

l tripledes Algorithm is not supported in Windows Platforms.

On iPhone platform, keystrength of 192 is supported only if the algorithm is random or securerandom. You cannot apply a passphrasehashalgo to the key when the algorithm is random or securerandom.

l tripledes - In Android and iOS, if the supplied key length is not equal to 192 an exception will be thrown with error message

Invalid Keystrength and error code

104

Note:

On BlackBerry, the passphrasetext length should be greater than or equal to keystrength 16 else an illegal exception occurs.

propertiesTable [Table] - Mandatory l passphrasetext [Array of Strings ]- the exact passphrase using which the key needs to be generated if the scheme is passphrase .

Note:

This value in the table is mandatory only if the scheme is passphrase

If the subalgo is aes, it contains a single string, whereas if the subalgo is tripledes, it contains three strings.

For example: o for aes

, passphrasetext = {"inputstring1"} o for tripledes , passphrasetext = ["TestStr1","TestStr2","TestStr3"]

Note: passphrase should contain at least 3 characters (24 bytes), else the API throws an illegalargument exception.

Note: tripledes - in Android, if the passphrase length is less than 24 bytes or greater than 24 bytes an exception will be thrown with error message Invalid Keystrength and error code 104.

Kony Studio API Developer's Guide

Version 3.1

l subalgo - represents the key algorithm that is used to create the key. This is a mandatory parameter

(irrespective of the scheme). Possible values are: aes and tripledes .

l passphrasehashlogo

- hashing algorithm to be applied for the passphrase text. (applicable only on iPhone).

Note: This value in the table is applicable only if the scheme is passphrase .

Possible values for the hash algorithm are: o md2 (for key strength of 128) o md4

(for key strength of 128) o md5 (for key strength of 128) o sha2 (for key strength of 256)

Return Values

The following are the return values for this API: key [userdata] - object

The key that is created using the specified algorithm.

API Usage

The recommended key strengths are as follows for this API: l aes - 128 l tripledes - 192.

Platform Availability

Available on all platforms except J2ME.

Kony Studio API Developer's Guide

Version 3.1

Exceptions

CryptoError: Thrown by Crypto API.Various error conditions related to CryptoError will be covered through the following error codes.

2001 - unsupported algorithm.

2002 - invalid key strength specified.

2003 - insufficient buffer provided for specified operation.

2004 - memory allocation failure.

2005 - input data did not encode or encrypt properly .

2006 - specified name already exists.

2007 - key with the specified unique ID is not found.

Error

JavaScript Example var myEncryptionKey = kony.crypto.newKey("passphrase", 192 ,

{passphrasetext: ["TestStr1","TestStr2","TestStr3"],subalgo:

"tripledes"});

3.11.1.8 kony.crypto.readKey

This API provides you the ability to read the key from the device store.

Note:

Device store in case of iOS is Keychain. Keychain in iOS is the most secured place to store the crypto keys. saveKey and readKey APIs save and read from the Keychain. The Keychain can be shared between the applications provisioned and signed by the same certificate vendor.

Kony Studio API Developer's Guide

Version 3.1

Important:

To avoid accidental overwrite of one application content by the other application content, it is recommended to use the unique application specific identifier while saving and reading the crypto keys using saveKey and readKey APIs.

Use Cases

You can read the key from the device store if you want to use that key for encryption or decryption.

Signature

JavaScript : kony.crypto.readKey(

uniqueID

)

Input Parameters uniqueID [String] - Mandatory

Unique ID represents the key on the device store (this is the ID returned by kony.crypto.saveKey

API).

Return Values

The following are the return values for this API: key [rawbytes - object]

This key is generated using aes, tripledes, or RSA algorithms and saved on the device store.

API Usage

You can use this API only to read the keys that you have saved earlier on the device store, i.e., keys that have a unique ID associated with them.

Exceptions

CryptoError: Thrown by Crypto API.Various error conditions related to CryptoError will be covered through the following error codes.

Kony Studio API Developer's Guide

Version 3.1

2001 - unsupported algorithm.

2002 - invalid key strength specified.

2003 - insufficient buffer provided for specified operation.

2004 - memory allocation failure.

2005 - input data did not encode or encrypt properly.

2006 - specified name already exists.

2007 - key with the specified unique ID is not found.

Error

Platform Availability

Available on all platforms except J2ME and Windows Kiosk.

JavaScript Example var encryptDecryptKey = kony.crypto.newKey("passphrase", 128,

{passphrasetext: ["inputstring1"], subalgo: "aes", passphrasehashalgo: "md5"}); var myUniqueIDKey = kony.crypto.saveKey("myKey",encryptDecryptKey); var myCryptoKey = kony.crypto.readKey(myUniqueIDKey); alert(myCryptoKey);

3.11.1.9 kony.crypto.retrievePublicKey

Public Key Infrastructure (PKI) is the mechanism to secure the public networks (like Internet) to safely and securely transmit data with the use of keys. PKI assumes the use of public key cryptography

(

asymmetric cryptography ). PKI is the most common method to authenticate the message sender or

encrypt the message. PKI consists of a Certificate Authority (CA) that issues and verifies digital

Kony Studio API Developer's Guide

Version 3.1

certificates (trusted certificates). A certificate includes the public key or information about the public key.

Note: Due to security reasons, Thin Client or Mobile Web applications cannot access public/private keys or certificates that are on the server.

This API provides the ability to extract the public key from a base64 string of encoded X509 certificate or a locally packaged X509 certificate.

Signature

JavaScript:

kony.crypto.retrievePublicKey( algo , inputsource

islocalresource

)

Input Parameters algo [String] - Mandatory

The algorithm used for the public key. Possible values are: l

RSA l

AES - Supported only on Windows platforms.

inputsource [String] - Mandatory

This parameter indicates the name of the input source certificate from which the key needs to be retrieved.

Note: The certificate must be present in the resources folder.

islocalresource [Boolean] - Mandatory

This flag defines how the inputsource string needs to be interpreted.

l islocalresource is false - represents that the input source is base64 string of X509 certificate.

l islocalresource is true - represents that the input source is name of the local resource for the certificate. For example, public.cer.

Kony Studio API Developer's Guide

Version 3.1

Return Values publickey - userdata [Object]

The public key extracted from the certificate.

Rules and Restrictions l

Self-signed certificates are not supported on Android and BlackBerry platforms.

l iOS supports only Distinguished Encoding Rules (DER) representation of an X.509 certificate, when input source is certificate.

Exceptions

CryptoError: Thrown by Crypto API.Various error conditions related to CryptoError will be covered through the following error codes.

2001 - unsupported algorithm.

2002 - invalid key strength specified.

2003 - insufficient buffer provided for specified operation.

2004 - memory allocation failure.

2005 - input data did not encode or encrypt properly.

2006 - specified name already exists.

2007 - key with the specified unique ID is not found.

Error

Platform Availability

Available on all platforms except J2ME, Windows 8 Tablet, Windows Kiosk, Service Side Mobile Web,

Desktop Web, and SPA.

Kony Studio API Developer's Guide

Version 3.1

JavaScript Example var myKey = kony.crypto.retrievePublicKey("rsa","public.cer",true);

3.11.1.10 kony.crypto.saveKey

This API allows you to save the generated key on the device store. If a key does not exist with the given name, the API creates a key; if a key exists with the given name, the API updates the same. The key is saved and a unique identifier is returned.

Note:

Important: To avoid accidental overwrite of one application content by the other application content, it is recommended to use the unique application specific identifier while saving and reading the crypto keys using saveKey and readKey APIs.

Use Cases

To use the key at a later point of time for encryption and decryption.

Signature

JavaScript : kony.crypto.saveKey (

name

key

)

Input Parameters name [String] - Mandatory

Unique name with which you want to save the key on the device store.

key [Object] - Mandatory

The key that you want to save on the device.

Kony Studio API Developer's Guide

Version 3.1

Return Values uniqueID [String]

The unique ID represents the saved key on the device store. We can access the key from the device store using this unique ID.

Note: UniqueID is determined by the system. It might be the same as name in some platforms but not guaranteed.

Exceptions

CryptoError: Thrown by Crypto API.Various error conditions related to CryptoError will be covered through the following error codes.

2001 - unsupported algorithm.

2002 - invalid key strength specified.

2003 - insufficient buffer provided for specified operation.

2004 - memory allocation failure.

2005 - input data did not encode or encrypt properly.

2006 - specified name already exists.

2007 - key with the specified unique ID is not found.

Error

API Usage

You can use this API to save the generated symmetric keys.

Platform Availability

Available on all platforms except J2ME and Windows Kiosk.

Kony Studio API Developer's Guide

Version 3.1

JavaScript Example var myEncryptionKey = kony.crypto.newKey("securerandom",256,

{subalgo:

"aes"}); var myUniqueKey = kony.crypto.saveKey("myKey",myEncryptionKey);

3.12 kony.db Namespace

The kony.db namespace provides the following API elements.

Functions

3.12.1 Functions

The kony.db namespace contains the following functions.

3.12.1.1 kony.db.changeVersion

The changeVersion method allows scripts to automatically verify the version number and change it at the same time during a schema update. This method creates an SQLTransactionSync object

(executeSQL) for a read/write transaction. The database's actual version changes to newVersion only if the first argument (oldVersion) exactly matches the database's actual version, otherwise throws a

SQLException.

When you invoke this API, it returns immediately and asynchronously reads the transaction.

Signature

JavaScript

: kony.db.changeVersion( dbaseObjectId

oldVersion, newVersion,

SQLTransactionCallback ,SQLTransactionErrorCallback, SQLTransactionVoidCallback )

Parameters dbaseObjectId [String] - Mandatory

Specifies the unique ID of the database

Kony Studio API Developer's Guide

Version 3.1

oldVersion [String] - Mandatory

Specifies the older version of the database.

newVersion [String] - Mandatory

Specifies the newer version of the database.

SQLTransactionCallback [Function] - Mandatory

Specifies the callback function that contains the transactions.

For example, function callback(dbId)

{

//SQLTransaction contains implementation of executeSql method

// invoke database.executesql method for sql trasaction

};

SQLTransactionErrorCallback [Function] - Optional

Specifies the callback that must be executed if there is an error in executing the transaction. This callback function is used to roll back the updates to the database.

For example function errorCallback(SQLError)

{

//code

}

SQLVoidCallback [Function] - Optional

Specifies the callback that must be executed if the transaction is successful.

For example

Kony Studio API Developer's Guide

Version 3.1

function successCallback()

{

//code

}

Return Values

None.

Example kony.db.changeVersion

("1.0","1.1",transactioCall,errorCall,sucessCall); function transactioCall ()

{

//respective code

} function sucessCall()

{

//respective code

} function errorCall()

{

//respective code

}

Platform Availability

Available on all platforms* except BlackBerry 10 and SPA in Windows Phone 7.5 and windows Phone

8 browsers, for desktop IE8, IE9, IE10 browsers. *Dummy implementation on Mobile Web.

Kony Studio API Developer's Guide

Version 3.1

3.12.1.2 kony.db.executeSql

This API allows you to execute a specified SQL statement on the given database. This is an asynchronous API.

Important: The table names and column names are case sensitive.

Signature

JavaScript: kony.db.executeSql(

transactionId , SQLStatement

arguments

SQLStatementSuccessCallback

SQLStatementErrorCallback )

Parameters transactionId [String] - Mandatory

Specifies the unique ID of the transaction.

SQLStatement [String] - Mandatory

Specifies the SQL statement that must be executed.

arguments [Object] - Optional

Specifies the arguments for executing the SQL statement. If this parameter is not specified or is nil, then the statement is executed without any arguments.

The supported argument types are: l

NULL in JavaScript l

REAL l

TEXT l

BLOB.

No type affinity is performed.

Kony Studio API Developer's Guide

Version 3.1

SQLStatementSuccessCallback [Function] - Optional

Specifies the callback function that must be executed when the execution of the SQL statement is a success

SQLStatementErrorCallback [Function] - Optional

Specifies the callback function that must be executed when the execution of the SQL statement is a failure.

This callback returns a boolean value.

l true - ends the execution of the transaction. true is returned if there is no callback function specified as a parameter.

Important: When true is returned, the transaction is rolled back.

l false - continues executing the transaction.

The default return value is false for this callback.

Return Values

None.

Error Codes

The following table lists the error codes along with its corresponding error messages:

Error

Code

Error Message

1 UNKNOWN_

ERR

Description

The statement failed for database reasons not covered by any other error code.

Kony Studio API Developer's Guide

Version 3.1

Error

Code

Error Message

2 DATABASE_

ERR

Description

The operation failed because the actual database version was not what it should be. For example, a statement found that the actual database version no longer matched the expected version of the

Database

DatabaseSync

object, or the

Database.changeVersion()

DatabaseSync.changeVersion()

methods were passed a version that doesn't match the actual database version.

TOO_LARGE_

ERR

QUOTA_ERR

SYNTAX_ERR

CONSTRAINT_

ERR

The statement failed because the data returned from the database was too large. The SQL "LIMIT" modifier might be useful to reduce the size of the result set.

The statement failed because there was not enough remaining storage space, or the storage quota was reached and the user declined to give more space to the database.

The statement failed because of a syntax error, or the number of arguments did not match the number of ? placeholders in the statement, or the statement tried to use a statement that is not allowed, such as BEGIN, COMMIT, or ROLLBACK, or the statement tried to use a verb that could modify the database but the transaction was read-only.

An INSERT, UPDATE, or REPLACE statement failed due to a constraint failure. For example, because a row was being inserted and the value given for the primary key column duplicated the value of an existing row.

7 TIMEOUT_ERR A lock for the transaction could not be obtained in a reasonable time.

For more information, refer SQL Error Codes

Kony Studio API Developer's Guide

Version 3.1

Platform Availability

Available on all platforms* except for SPA in Windows Phone 7.5 and windows Phone 8 browsers, for desktop IE8, IE9, IE10 browsers.*Dummy Implementation on Mobile Web.

JavaScript Example

//The below function specifies the callback function that must be executed when the execution of the SQL statement is a success function sql_success(transactionId, resultset)

{

//logic to process the resultset

}

//The below function specifies the callback function that must be executed when the execution of the SQL statement is a failure.

{ function sql_errorCallBack(err) alert("Error processing sql statement error code=" + err["code"]);

}

//The below function specifies the callback function that contains the transactions also invokes executeSql

{ function myTransactionCallback(dbId)

//SQLTransaction contains implementation of executeSql method

// invokekony.db.executesql method for sql trasaction var sqlStatement = "SELECT * FROM employee"; kony.db.executeSql(transactionID, sqlStatement, null, sql_success, sql_errorCallBack);

}

Kony Studio API Developer's Guide

Version 3.1

3.12.1.3 kony.db.openDatabase

This API allows you to open the specified version of a database. This is an asynchronous API.

Important: This API is not available in 6.5 plugins.

Signature kony.db.openDatabase(

dbname , version

displayName , estimatedSize , passphrase

)

Parameters dbname [String] - Mandatory

Specifies the actual name of the database that you want to open.

version [String] - Mandatory

Specifies the version of the database that you want to open.

displayName [String] - Mandatory

Specifies the display name of the database that you want to open.

estimatedSize [Number] - Optional

Specifies the approximate size of the database in bytes.

Note: This parameter is applicable only on the SPA platform.

passphrase

This is applicable for

iOS

and

Android

iOS passphrase[Array] - Optional

In iOS, this argument is used to specify Pragma statements (Array) to encrypt database.

Kony Studio API Developer's Guide

Version 3.1

Usage l

To link the SQLCipher library, extract the KAR file with -sqlcipher option. After the extraction, pass the passphrase for the SQL engine to encrypt the database. perl extract.pl /Users/PLATFROM/Downloads/konyappipad.KAR – sqlcipher

Note: For more information on this parameter and Pragma statements, see https://www.zetetic.net/sqlcipher/sqlcipher-api/ .

Android passphrase [String] - Optional

In Android, this argument is used to specify password (String) to encrypt database.

The developer needs to enable Support SQL DB Encryption (FIPS) option in Kony Visualizer

> Application Properties > Native > Android section in order to support database encryption using passphrase.

Windows Phone 8/8.1

If a password is provided to the openDatabase API, the database will be encrypted.

For database encryption a set of licensed components must be obtained from Zetetic inc. for

Windows Phone 8 and Windows Phone 8.1. For more information, see https://www.zetetic.net/sqlcipher/buy/ .

The dll/class library is provided by Zenetic Inc as a zipped file. It contains the sqlcipher dlls built for arm and x86 architectures and should be copied to the windowsphone8 folder, as shown in the following figure.

Kony Studio API Developer's Guide

Version 3.1

During the build process these dlls are unzipped and added to the xap file used for application deployment. The name of the zip file for Windows Phone 8 must be sqlcipherwp8.zip. The zip file for Windows Phone 8.1 must be sqlcipherwp81.zip. The zip files should have folders for each architecture type, where the dlls for each architecture are placed.

Each architecture folder should contain the following 3 files: l

Sqlite.winmd

Sqlite.dll

l sqlite3.dll

Windows 8.1 and Windows Kiosk

A free version of the sqlite library is available to support encryption. Therefore a license is not needed and you do not need to copy the zip files.

Kony Studio API Developer's Guide

Version 3.1

Important:

The database will not be encrypted in the following conditions:

1. If Support SQL DB Encryption (FIPS) option is enabled and empty string is passed as passphrase.

2. If Support SQL DB Encryption (FIPS) option is not enabled ,passphrase will be ignored and database is non encrypted.

3. If passphrase is not passed.

Important: Encrypted and non-encrypted databases cannot be interchangeably opened using this

API.

Important: The other Web SQL APIs operate on encrypted DB seamlessly if the

databaseObjectId

passed to them is opened using

kony.db.openDatabase()

API with passphrase.

Important: The framework does not store the passphrase argument to

kony.db.openDatabase()

API, it is responsibility of application developer to secure the password.

Return Values databaseObjectId [userdata]

Returns the unique ID of the database. The identifier is userdata ( platform specific instance) and is not specifically String. Developers must not rely on the type of the identifier.

Platform Availability

Available on all platforms(dummy implementation on MobileWeb) except for SPA in Windows Phone

7.5 browser, and for desktop IE8, IE9, and IE10 browsers.

Kony Studio API Developer's Guide

Version 3.1

JavaScript Example

//The below function will invoke openDatabase function openDatabase()

{ var dbName="konytestDB"; var version="1.0"; var displayName="demo web SQL Database"; var estimatedSize=5*1024*1024; //5*1024*1024 indicates 5 MB

//Note: Use only one of the statements depending on platform is Android or iOS

//Passphrase is string in case of android.

var passphrase = "samplepassword";

//Passphrase is pragma array in case of android.

passphrase = ["PRAGMA key = 'old passphrase';"]; var databaseObjectId =kony.db.openDatabase(dbName,version, displayName, estimatedSize,passphrase);

//databaseObjectId contains the unique ID of the database

}

//Android Example using password parameter var databaseObjectId =kony.db.openDatabase("konytestDB",1.0,"demo web SQL Database",5*1024*1024,"samplepassword");

3.12.1.4 kony.db.readTransaction

This API allows you to read a specified transaction. This API creates a SQLTransaction object for read-only transactions.

When you invoke this API, it returns immediately and asynchronously reads the transaction.

Kony Studio API Developer's Guide

Version 3.1

Important:

You can only read queries using this API. The kony.db.readTransaction API results in a SYNTAX_ERR in case of DML commands in the SQL statement. DML commands are not supported in this API.

Important: The table names and column names are case sensitive.

Signature

JavaScript : kony.db.readTransaction

(

dbaseObjectId

TransactionCallback , TransactionErrorCallback

SuccessCallback

)

Parameters dbaseObjectId [String] - Mandatory

Specifies the unique ID of the database.

TransactionCallback [Function] - Mandatory

Specifies the callback function that contains the transactions.

For example, function callback(dbId)

{

//Code

}

TransactionErrorCallback [Function] - Optional

Specifies the callback that must be executed if there is an error in executing the transaction. This callback function is used to roll back the updates to the database.

For example,

Kony Studio API Developer's Guide

Version 3.1

function errorCallback(SQLError)

{

//Code

}

SuccessCallback [Function] - Optional

Specifies the callback that must be executed if the transaction is successful.

For example, function successCallback()

{

//code

}

Return Values

None.

Platform Availability

Available on all platforms* except for SPA in Windows Phone 7.5 and windows Phone 8 browsers, for desktop IE8, IE9, IE10 browsers.*Dummy Implementation on Mobile Web.

JavaScript Example

//The below function specifies the callback function that contains the transactions.

function myTransactionCallback(dbId)

{

//SQLTransaction contains implementation of executeSql method

// invokekony.db.executeSql method for sql trasaction

}

Kony Studio API Developer's Guide

Version 3.1

//The below function specifies the callback that must be executed if there is an error in executing the transaction. This callback function is used to roll back the updates to the database.

function myTransactionErrorCallback(SQLError)

{

// proceed with the logic

}

//The below function specifies the callback that must be executed if the transaction is successful.

function mySuccessCallback()

{

// proceed with the logic

}

//The below function will invoke readTransaction function readTransaction()

{ var dbName="konytestDB"; var version="1.0"; var displayName="demo web SQL Database"; var estimatedSize=5*1024*1024; //5*1024*1024 indicates 5 MB var databaseObjectId =kony.db.openDatabase(dbName,version, displayName, estimatedSize);

//databaseObjectId contains the unique ID of the database kony.db.readTransaction(databaseObjectId, myTransactionCallback, myTransactionErrorCallback, mySuccessCallback);

}

3.12.1.5 kony.db.sqlResultsetRowItem

This API returns the row available at the specified index. If there is no such row, then the API returns null for JavaScript.

Kony Studio API Developer's Guide

Version 3.1

Important:

The table names and column names are case sensitive.

Signature

JavaScript

: kony.db.sqlResultsetRowItem(

transactionID , SQLResultSet

index

)

Parameters transactionID [String] - Mandatory

Specifies the unique ID of the transaction

SQLResultSet [Array of JS Objects] - Mandatory

Specifies the name of the SQL result set index [Number] - Mandatory

Specifies the index from which the row is to be retrieved

Return Values rowitem [Array of Objects]

Returns the row item at the specified index null/nil

Returns null/nil if there is no row available at the specified index

Platform Availability

Available on all platforms* except for SPA in Windows Phone 7.5 and windows Phone 8 browsers, for desktop IE8, IE9, IE10 browsers.*Dummy Implementation on Mobile Web.

JavaScript Example

//The below function specifies the callback function that must be executed when the execution of the SQL statement is a success also invokes sqlResultsetRowItem.

function sql_success(transactionId, resultset)

Kony Studio API Developer's Guide

Version 3.1

{ var rowItem =kony.db.sqlResultsetRowItem

(transactionId,resultset,i); alert("empID:" + rowItem["empID"] + " empName:" + rowItem

["empName"] + " depID:" + rowItem["depName"]);

}

//logic to process the resultset for (var i=0; i<resultset.length;i++)

{

//The below function specifies the callback function that must be executed when the execution of the SQL statement is a failure.

{ function sql_errorCallBack(err) alert("Error processing sql statement error code=" + err["code"]);

}

3.12.1.6 kony.db.transaction

This API allows you to execute the specified transaction on the given database. When you invoke this

API, it returns immediately and asynchronously executes the transaction.

This is an asynchronous API. This API creates an

SQLTransaction

object.

Important: The table names and column names are case sensitive.

Signature

JavaScript

: kony.db.transaction(

dbaseObjectId

transactionCallback

transactionErrorCallback

successCallback )

Kony Studio API Developer's Guide

Version 3.1

Parameters dbaseObjectId [String] - Mandatory

Specifies the unique ID of the database transactionCallback [Function] - Mandatory

Specifies the callback function that contains the transactions.

For example, function callback(dbId)

{

//SQLTransaction contains implementation of executeSql method

// invoke database.executesql method for sql trasaction

}; transactionErrorCallback [Function] - Optional

Specifies the callback that must be executed if there is an error in executing the transaction. This callback function is used to roll back the updates to the database.

For example, function errorCallback(SQLError)

{

//write code here

} successCallback [Function] - Optional

Specifies the callback that must be executed if the transaction is successful.

For example,

Kony Studio API Developer's Guide

Version 3.1

function successCallback()

{

//code here

}

When the transaction is successful, this callback is executed along with the callback function of the kony.db.executeSql API.

Return Values

None.

Platform Availability

Available on all platforms* except for SPA in Windows Phone 7.5 and windows Phone 8 browsers, for desktop IE8, IE9, IE10 browsers.*Dummy Implementation on Mobile Web.

JavaScript Example

//The below function specifies the callback function that contains the transactions.

function myTransactionCallback(dbId)

{

//SQLTransaction contains implementation of executeSql method

// invokekony.db.executeSql method for sql trasaction

}

//The below function specifies the callback that must be executed if there is an error in executing the transaction. This callback function is used to roll back the updates to the database.

function myTransactionErrorCallback(SQLError)

{

// proceed with the logic

}

Kony Studio API Developer's Guide

Version 3.1

//The below function specifies the callback that must be executed if the transaction is successful.

function mySuccessCallback()

{

// proceed with the logic

}

//The below function will invoke transaction function transaction()

//databaseObjectId contains the unique ID of the database kony.db.transaction(databaseObjectId, myTransactionCallback, myTransactionErrorCallback, mySuccessCallback);

}

3.13 kony.ds Namespace

The kony.ds namespace provides data storage functionality. It contains the following API elements.

Functions

3.13.1 Functions

The kony.ds namespace holds the following functions.

Kony Studio API Developer's Guide

Version 3.1

kony.ds.read

This API provides you an ability to read the data stored on the data store of the mobile device using the given name identifier. A reference to the data table is returned.

Use Cases

You can use this API when you want to: l fetch the data stored on the mobile device and re-use it.

l know the data associated with a name identifier before you delete it.

Signature

JavaScript: kony.ds.read(

name,storeContext

)

Parameters name [String] - Mandatory

Specifies the unique name identifier that represents the data on the data store storeContext [String] - Optional

Specifies the unique identifier that of the data store if the data store is shared between apps. The storeContext parameter is a dictionary that holds the following keys.

Key storeAsUserPreference konyAppGroupID

Type

Boolean string

Description

Contains true to access the data in an app group.

Otherwise, set to false.

Holds a unique identifier that specifies the app group to be accessed.

Return Values

Reference [String]

A reference to the table is returned

Kony Studio API Developer's Guide

Version 3.1

nil [nil] nil is returned if no record is found

Error Codes

The following error codes are returned: l

704 Unknown error l

705 Invalid parameters l

706 Invalid parameter type. A non-string type specified as the name of the datastore

Implementation Details

If you use secure=true, while saving the data in ds.save, then the ds.read API fetches the correct values only if you are invoking the API on a form enabled for Secure Submit. Else, it will return nil.

Platform Availability

Available on all platforms.

kony.ds.remove

This API allows you to delete the data stored on the data store that corresponds to a specific name identifier.

Signature

JavaScript: kony.ds.remove (

name, storeContext )

Parameters name [String] - Mandatory

Specifies the name identifier using which the table was saved.

storeContext [String] - Optional

Specifies the unique identifier that of the data store if the data store is shared between apps. The storeContext parameter is a dictionary that holds the following keys.

Kony Studio API Developer's Guide

Version 3.1

Key storeAsUserPreference konyAppGroupID

Type

Boolean string

Description

Contains true to access the data in an app group.

Otherwise, set to false.

Holds a unique identifier that specifies the app group to be accessed.

Return Values status [Boolean] true - if the table is deleted successfully false - if the table is not deleted, or if no datastore exists with the key specified

Platform Availability

Available on all platforms.

kony.ds.save

This API allows you to save the given data using the specified name identifier in the data store of the mobile device. In case of Mobile Web applications, you have the option to specify where to store the data (cache/session/cookie).

Use Cases

You can use this API to store data on the mobile device that you may require even after quitting the application.

Signature

JavaScript: kony.ds.save(

inputtable ,

name

metainfo, storeContext

)

Parameters inputtable [Array] - Mandatory

Specifies the table that needs to be saved (array of values)

Kony Studio API Developer's Guide

Version 3.1

name [String] - Mandatory

Specifies the name identifier for the table. The data is stored on the data store with this name identifier. You must use this identifier if you want to retrieve data from the data store.

metainfo [Table] - Optional

Specifies a table with key-value pairs. These key-value pairs are useful for Mobile Web and indicate where to store the data. You have an option to store the data in the user session or cache or create a cookie to be placed on the device.

Important:

The following points are applicable only to metainfo [Table] parameter: l

The parameter is mandatory for Server Side Mobile Web.

Example code to use: kony.ds.save(["John","Joe","Jack"],"friends",

{dsmode:"session"}) secure means that the data stored on the device store is stored using a secure mode.

Note: secure is applicable only on Mobile Web and must be used in conjunction with dsmode="cookie". For example, {dsmode="cookie", secure="true"}.

You should provide a key value in the metainfo as key:

"dsmode" value:"cache/session/cookie" l cache: Data is stored in the application context and shared across all users of the Web

Application l session: Data is stored in the HTTP session created for a particular user l cookie: Data is stored in client browser's cookie store.

Kony Studio API Developer's Guide

Version 3.1

Based on the mode you specify here, the availability of the data after you quit the application varies.

For example, dsmode="session".

storeContext [String] - Optional

Specifies the unique identifier that of the data store if the data store is shared between apps. The storeContext parameter is a dictionary that holds the following keys.

Key storeAsUserPreference konyAppGroupID

Type

Boolean string

Description

Contains true to access the data in an app group.

Otherwise, set to false.

Holds a unique identifier that specifies the app group to be accessed.

Return Values

None.

Error Codes

The following error codes are returned: l

700 Unknown error l

701 Invalid parameters specified l

702 Invalid parameter type.

703 Invalid parameter type. A non-string type specified as input l

704 Unknown error l

705 Invalid parameters l

706 Invalid parameter type. A non-string type specified as the name of the datastore

Kony Studio API Developer's Guide

Version 3.1

Implementation Details

If you save some other data on the data store with the same name identifier used earlier, data is overridden.

API Usage

We recommend you not to store save sensitive data like passwords, account numbers, and so on using this API.

Platform Availability

Available on all platforms.

3.14 kony.filter Namespace

The kony.filter namespace provides your apps with the ability to create an manage filters for use with the Image widget. Information about the kony.filter namespace is presented in the following topics.

Functions

Objects

3.14.1 Constants

The kony.filter namespace contains the following constants.

Filter Type Constants

Filter Type Parameters Description

Kony Studio API Developer's Guide

Version 3.1

kony.filter.ADDITION_

COMPOSITING kony.filter.AFFINE_

TRANSFORM kony.filter.BLEND_WITH_

MASK filterName:kony.filter.ADDITION_

COMPOSITING inputImage:- Image widget inputBackgroundImage:- Image widget filterName :kony.filter.AFFINE_

TRANSFORM inputImage :- Image widget inputTransform:- transform object filterName :kony.filter.BLEND_WITH_

MASK inputImage :-Image widget inputBackgroundImage :- Image widget inputMaskImage :- Image widget

Adds color components to achieve a brightening effect. This filter is available from Android 3.0

and above. This filter is available in iOS 6 and above.

This filter is available in iOS 5 and above.

This filter is available in iOS 6 and above.

Kony Studio API Developer's Guide

Version 3.1

kony.filter.BLEND_WITH_

ALPHA_MASK kony.filter.BLOOM

kony.filter.BOX_BLUR

kony.filter.BRIGHTNESS

filterName :kony.filter.BLEND_WITH_

ALPHA_MASK inputImage :- Image widget, inputBackgroundImage :- Image widget inputMaskImage :- Image widget filterName :- kony.filter.BLOOM

inputImage :- Image widget inputRadius :- Number inputIntensity: Number filterName:- kony.filter.BOX_

BLUR inputImage:- Image widget inputRadius:- number(1 to 25) inputImage :- Image widget inputBrightness :- number (0.0 to infinite)

This filter is available in iOS 7 and above.

This filter is available in iOS 6 and above.

Increase or decreases the blurriness of image.

Available on Android.

This filter is available in iOS 9 and above.

Increases or decreases the brightness of an image. Available on

Android.

Kony Studio API Developer's Guide

Version 3.1

kony.filter.COLOR_BLEND_

MODE kony.filter.CLEAR_

COMPOSITING filterName :kony.filter.COLOR_BLEND_

MODE inputImage :- Image widget inputBackgroundImage :- Image widget filterName:- kony.filter.CLEAR_

COMPOSITING inputImage:- Image widget inputBackgroundImage:- Image widget

Uses the luminance values of the background with the hue and saturation values of the source image. This filter is available in iOS 6 and above.

This filter is available from Android 3.0 and above.

Kony Studio API Developer's Guide

Version 3.1

kony.filter.COLOR_CLAMP

kony.filter.COLOR_

CONTROLS filterName:- kony.filter.COLOR_

CLAMP inputImage:- Image widget inputMinComponents:- array of four floats representing

[R,G,B,A] in that order where each float ranges between 0.0 to

1.0.

inputMaxComponents:- array of four floats representing

[R,G,B,A] in that order where each float ranges between 0.0 to

1.00

filterName :kony.filter.COLOR_

CONTROLS inputImage :- Image widget inputSaturation:- number (0.0 -

1.0) inputBrightness:- number (0.0 -

1.0) inputContrast:- number (0.0 -

1.0)

This filter clamps the colors of the input image within the given range specified by inputMinComponents and inputMaxComponents. At each pixel, color component values less than those in inputMinComponents will be increased to match those in inputMinComponents, and color component values greater than those in inputMaxComponents will be decreased to match those in inputMaxComponents.

Available on Android.

This filter is available in iOS 7 and above.

Adjusts saturation, brightness, and contrast values. This filter is available in iOS 5 and above.

Kony Studio API Developer's Guide

Version 3.1

kony.filter.COLOR_CROSS_

POLYNOMIAL kony.filter.COLOR_DODGE_

BLEND_MODE kony.filter.COLOR_

INVERSION filterName :kony.filter.COLOR_CROSS_

POLYNOMIAL inputImage :- Image widget inputRedCoefficients:- Array of

10 numbers [x,y,z,w,...] (0.0 -

1.0) inputGreenCoefficients:- Array of 10 numbers [x,y,z,w,….] (0.0 -

1.0) inputBlueCoefficients:- Array of

10 numbers [x,y,z,w,…..] (0.0 -

1.0) filterName :kony.filter.COLOR_DODGE_

BLEND_MODE inputImage :- Image widget inputBackgroundImage :- Image widget filterName:- kony.filter.COLOR_

INVERSION inputImage:- Image widget

Modifies the pixel values in an image by applying a set of polynomial crossproducts. This filter is available in iOS 6 and above.

Brightens the background image samples to reflect the source image samples. This filter is available in iOS 6 and above.

Inverts the colors of given image. Available on

Android. Available on iOS

6 and above.

Kony Studio API Developer's Guide

Version 3.1

kony.filter.COLOR_MAP

filterName :kony.filter.COLOR_MAP

inputImage :- Image widget inputGradientImage :- Image widget kony.filter.COLOR_MATRIX

filterName :kony.filter.COLOR_MATRIX

inputImage :- Image widget inputRVector:- Array of four numbers [x,y,z,w] (0.0 - 1.0) inputGVector:- Array of four numbers [x,y,z,w] (0.0 - 1.0) inputBVector:- Array of four numbers [x,y,z,w] (0.0 - 1.0) inputAVector:- Array of four numbers [x,y,z,w] (0.0 - 1.0) inputBiasVector:- Array of four numbers [x,y,z,w] (0.0 - 1.0)

Performs a nonlinear transformation of source color values using mapping values provided in a table.

inputGradientImage is an nx1 or nxn gradient image used to describe a color ramp. This filter is available in iOS 6 and above.

Multiplies source color values and adds a bias factor to each color component. Available on iOS 5 and above.

Kony Studio API Developer's Guide

Version 3.1

kony.filter.COLOR_MATRIX

filterName:- kony.filter.COLOR_

MATRIX inputImage:- Image widget inputRVector:- array of four numbers representing [R,G,B,A] in that order.

inputGVector:- array of four numbers representing [R,G,B,A] in that order.

inputBVector:- array of four numbers representing [R,G,B,A] in that order.

inputAVector:- array of four numbers representing [R,G,B,A] in that order.

inputBiasVector:- array of four values where each value should be added to each channel of

RGBA in that order.

This filter transforms the colors of given image as per the input parameters.

For a given color

[R,G,B,A] of a pixel in the input image, the resulting color [rR, rG, rB, rA] is computed as follows: rR = R*Rv[0] + G*Rv[1] +

B*Rv[2] + A*Rv[3] + bias

[0] rG = R*Gv[0] + G*Gv[1] +

B*Gv[2] + A*Gv[3] + bias

[1] rB = R*Bv[0] + G*Bv[1] +

B*Bv[2] + A*Bv[3] + bias

[2] rA = R*Av[0] + G*Av[1] +

B*Av[2] + A*Av[3] + bias

[3] where Rv is inputRVector, Gv is inputGVector, Bv is inputBVector, Av is inputAVector and bias is inputBiasVector. The resulting color values [rR, rG, rB, rA] are clamped to

255 if exceeded beyond

255. Available on

Android.

kony.filter.COLOR_

MONOCHROME kony.filter.COLOR_

POLYNOMIAL

Kony Studio API Developer's Guide

Version 3.1

filterName :kony.filter.COLOR_

MONOCHROME inputImage :- Image widget inputColor :- Array of three numbers [r,g,b] (0.0 - 1.0) inputIntensity:- Number filterName :kony.filter.COLOR_

POLYNOMIAL inputImage :- Image widget inputRedCoefficients:- Array of four numbers [x,y,z,w] (0.0 - 1.0)

Remaps colors so they fall within shades of a single color. As inputColor only opaque color needs to be passed, ie, only red, blue, green components and no alpha. inputColor values should be in the range of

0.0 - 1.0. inputIntensity accepts the values in range 0.0 - 1.0. This filter is available on iOS 6 and above.

Modifies the pixel values in an image by applying a set of cubic polynomials.

This filter is available in iOS 7 and above.

inputGreenCoefficients:- Array of four numbers [x,y,z,w] (0.0 -

1.0) inputBlueCoefficients:- Array of four numbers [x,y,z,w] (0.0 - 1.0) inputAlphaCoefficients:- Array of four numbers [x,y,z,w] (0.0 -

1.0)

Kony Studio API Developer's Guide

Version 3.1

kony.filter.COLOR_

POSTERIZE kony.filter.COMIC_EFFECT

kony.filter.CONVOLUTION_

3X3 kony.filter.CONVOLUTION_

5X5 filterName :kony.filter.COLOR_

POSTERIZE inputImage :- Image widget inputLevels :- Number filterName :kony.filter.COMIC_EFFECT

inputImage :- Image widget filterName :kony.filter.CONVOLUTION_

3X3 inputImage :- Image widget inputWeights :- Array of 9 numbers (0.0 - 1.0) inputBias :- number (0.0 - 1.0) filterName :kony.filter.CONVOLUTION_

5X5 inputImage :- Image widget inputWeights :- Array of 25 numbers (0.0 - 1.0) inputBias :- number (0.0 - 1.0)

Remaps red, green, and blue color components to the number of brightness values you specify for each color component.

This filter is available on iOS 6 and above.

This filter is available on iOS 9 and above.

This filter is available on iOS 7 and above.

Kony Studio API Developer's Guide

Version 3.1

kony.filter.CONVOLUTION_

7X7 kony.filter.CONVOLUTION_9_

HORIZONTAL filterName :kony.filter.CONVOLUTION_

7X7 inputImage :- Image widget, inputWeights :- Array of 7x7 =

49 numbers (0.0 - 1.0) inputBias :- number (0.0 - 1.0) filterName :kony.filter.CONVOLUTION_9_

HORIZONTAL inputImage :- Image widget, inputWeights :- Array of 9 numbers (0.0 - 1.0) inputBias :- number (0.0 - 1.0) kony.filter.CONVOLUTION_9_

VERTICAL filterName :kony.filter.CONVOLUTION_9_

VERTICAL inputImage :- Image widget, inputWeights :- Array of 9 numbers (0.0 - 1.0) inputBias :- number (0.0 - 1.0)

This filter is available on iOS 9 and above.

This filter is available on iOS 7 and above.

Kony Studio API Developer's Guide

Version 3.1

kony.filter.CRYSTALLIZE

kony.filter.DARKEN_BLEND_

MODE kony.filter.DARKEN_

COMPOSITING kony.filter.DIFFERENCE_

BLEND_MODE filterName :kony.filter.CRYSTALLIZE

inputImage :- Image widget, inputRadius:- number inputCenter :- Array of two numbers [x,y] filterName :kony.filter.DARKEN_BLEND_

MODE inputImage :- Image widget inputBackgroundImage :- Image widget filterName:kony.filter.DARKEN_

COMPOSITING inputImage:- Image widget inputBackgroundImage:- Image widget filterName :kony.filter.DIFFERENCE_

BLEND_MODE inputImage :- Image widget inputBackgroundImage :- Image widget

This filter is available on iOS 9 and above.

Creates composite image samples by choosing the darker samples. This filter is available on iOS 6 and above.

This filter is available from Android 3.0 and above.

Subtracts the greater brightness values from lower. This filter is available on iOS 6 and above.

Kony Studio API Developer's Guide

Version 3.1

kony.filter.DISC_BLUR

kony.filter.DIVIDE_BLEND_

MODE kony.filter.EDGES

kony.filter.EDGE_WORK

kony.filter.EXCLUSION_

BLEND_MODE filterName :- kony.filter.DISC_

BLUR inputImage :- Image widget inputRadius:- number filterName :kony.filter.DIVIDE_BLEND_

MODE inputImage :- Image widget inputBackgroundImage :- Image widget filterName :- kony.filter.EDGES

inputImage :- Image widget, inputIntensity :- number filterName :- kony.filter.EDGE_

WORK inputImage :- Image widget, inputRadius :- number filterName :kony.filter.EXCLUSION_

BLEND_MODE inputImage :- Image widget inputBackgroundImage :- Image widget

This filter is available on iOS 9 and above.

Divides the backgroundImage color from source image color.

This filter is available on iOS 8 and above.

This filter is available on iOS 9 and above.

Producess the similar effect as

CIDifferenceBlend mode but has lower contrast.This filter is available on iOS 6 and above.

Kony Studio API Developer's Guide

Version 3.1

kony.filter.EXPOSURE_

ADJUST kony.filter.EDGE_

DETECTION kony.filter.EMBOSS

kony.filter.FALSE_COLOR

filterName :kony.filter.EXPOSURE_

ADJUST inputImage :- Image widget inputEV:- number (0.0 - 1.0) filterName:- kony.filter.EDGE_

DETECTION inputImage:- Image widget inputRadius:- number(1 or 2) filterName:kony.filter.EMBOSS

inputImage:- Image widget inputRadius:- number(1 or 2) filterName :- kony.filter.FALSE_

COLOR inputImage :- Image widget inputColor0 :- Array of four numbers of 0.0 - 1.0 [r,g,b,a] inputColor1 :- Array of four numbers of 0.0 - 1.0 [r,g,b,a]

Adjusts the exposure setting for an image similar to the way you control exposure for a camera when you change the F-stop. This filter is available on iOS 5 and above.

Detects or Highlight the edges of given image.

Available on Android.

Applies an embossing effect for a given image.

Available on Android.

Maps luminance to a color ramp of two colors.

This filter is available in iOS 6 and above.

Kony Studio API Developer's Guide

Version 3.1

kony.filter.GAMMA_ADJUST

kony.filter.GAUSSIAN_BLUR

kony.filter.GLOOM

kony.filter.GREYSCALE

filterName :kony.filter.GAMMA_ADJUST

inputImage :- Image widget inputPower:- number (0.0 - 1.0) filterName:kony.filter.GAUSSIAN_BLUR

inputImage:- Image widget inputRadius:- number(1 to 25)

This filter is available in iOS 5 and above.

Spreads source pixels by an amount specified by a

Gaussian distribution to increase the blurriness.

The blurriness of this filter is smooth compared to

BoxBlur. Available on

Android. Available on iOS

6 and above.

This filter is available in iOS 6 and above.

filterName :- kony.filter.GLOOM

inputImage :- Image widget inputRadius :- Number inputIntensity: Number filterName:kony.filter.GREYSCALE

inputImage:- Image widget

Converts given image to black & white or monochrome image.

Available on Android.

Kony Studio API Developer's Guide

Version 3.1

kony.filter.HARD_LIGHT_

BLEND_MODE kony.filter.HUE_ADJUST

kony.filter.HUE_BLEND_

MODE kony.filter.LIGHTEN_BLEND_

MODE filterName :- kony.filter.HARD_

LIGHT_BLEND_MODE inputImage :- Image widget inputBackgroundImage :- Image widget filterName :- kony.filter.HUE_

ADJUST inputImage :- Image widget inputAngle:- number (angle in

Radians) filterName :- kony.filter.HUE_

BLEND_MODE inputImage :- Image widget inputBackgroundImage :- Image widget filterName :kony.filter.LIGHTEN_BLEND_

MODE inputImage :- Image widget inputBackgroundImage :- Image widget

If input image sample is lighter than 50% grey then backgroundImage sample is lightened. If input image sample is greater that 50% grey then backgroundImage sample is darkened. This filter is available in iOS 6 and above.

Changes the overall hue, or tint, of the source pixels. This filter is available in iOS 5 and above.

Uses luminance and saturation values from backgroundImage with the hue values on input image. This filter is available in iOS 6 and above.

The lighter samples are taken from both the images and will be used in resultant image. This filter is available in iOS 6 and above.

Kony Studio API Developer's Guide

Version 3.1

kony.filter.LIGHTEN_

COMPOSITING kony.filter.LINEAR_BURN_

BLEND_MODE kony.filter.LINEAR_DODGE_

BLEND_MODE kony.filter.LINEAR_TO_

SRGB_TONE_CURVE filterName:kony.filter.LIGHTEN_

COMPOSITING inputImage:- Image widget inputBackgroundImage:- Image widget filterName :kony.filter.LINEAR_BURN_

BLEND_MODE inputImage :- Image widget inputBackgroundImage :- Image widget filterName :kony.filter.LINEAR_DODGE_

BLEND_MODE inputImage :- Image widget inputBackgroundImage :- Image widget filterName :kony.filter.LINEAR_TO_

SRGB_TONE_CURVE inputImage :- Image widget

This filter is available from Android 3.0 and above.

This filter is available in iOS 8 and above.

This filter is available in iOS 7 and above.

Kony Studio API Developer's Guide

Version 3.1

kony.filter.LUMINOSITY_

BLEND_MODE kony.filter.MASK_TO_ALPHA

kony.filter.MAXIMUM_

COMPONENT kony.filter.MAXIMUM_

COMPOSITING kony.filter.MEDIAN_FILTER

filterName :kony.filter.LUMINOSITY_

BLEND_MODE inputImage :- Image widget inputBackgroundImage :- Image widget filterName :- kony.filter.MASK_

TO_ALPHA inputImage :- Image widget

This filter is available in iOS 6 and above.

filterName :kony.filter.MAXIMUM_

COMPONENT inputImage :- Image widget filterName :kony.filter.MAXIMUM_

COMPOSITING inputImage :- Image widget inputBackgroundImage :- Image widget filterName :kony.filter.MEDIAN_FILTER

inputImage :- Image widget

Converts a grayscale image to a white image that is masked by alpha.

This filter is available in iOS 6 and above.

Returns a grayscale image from max(r,g,b).

This filter is available in iOS 6 and above.

This filter is available in iOS 9 and above.

Kony Studio API Developer's Guide

Version 3.1

kony.filter.MINIMUM_

COMPONENT kony.filter.MINIMUM_

COMPOSITING kony.filter.MOTION_BLUR

kony.filter.MULTIPLY_

BLEND_MODE filterName :kony.filter.MINIMUM_

COMPONENT inputImage :- Image widget filterName :kony.filter.MINIMUM_

COMPOSITING inputImage :- Image widget inputBackgroundImage :- Image widget filterName :kony.filter.MOTION_BLUR

inputImage :- Image widget inputRadius:- number inputAngle:- number (angle in radians) filterName :kony.filter.MULTIPLY_BLEND_

MODE inputImage :- Image widget inputBackgroundImage :- Image widget

This filter is available in iOS 5 and above.

This filter is available in iOS 6 and above.

This filter is available in iOS 9 and above.

This filter is available in iOS 6 and above.

Kony Studio API Developer's Guide

Version 3.1

kony.filter.MULTIPLY_

COMPOSITING kony.filter.NOISE_

REDUCTION kony.filter.OVERLAY_

BLEND_MODE kony.filter.OVERLAY_

COMPOSITING filterName:kony.filter.MULTIPLY_

COMPOSITING inputImage:- Image widget inputBackgroundImage:- Image widget filterName :- kony.filter.NOISE_

REDUCTION inputImage :- Image widget inputNoiseLevel:- number (0.0 -

1.0) inputSharpness:- number (0.0 -

1.0) filterName :kony.filter.OVERLAY_BLEND_

MODE inputImage :- Image widget inputBackgroundImage :- Image widget filterName:kony.filter.OVERLAY_

COMPOSITING inputImage:- Image widget inputBackgroundImage:- Image widget

This filter is available from Android 3.0 and above. This filter is available in iOS 6 and above.

This filter is available in iOS 9 and above.

This filter is available in iOS 6 and above.

This filter is available from Android 3.0 and above.

Kony Studio API Developer's Guide

Version 3.1

kony.filter.PHOTO_EFFECT_

CHROME kony.filter.PHOTO_EFFECT_

FADE kony.filter.PHOTO_EFFECT_

INSTANT filterName :kony.filter.PHOTO_EFFECT_

INSTANT inputImage :- Image widget kony.filter.PHOTO_EFFECT_

MONO filterName :kony.filter.PHOTO_EFFECT_

CHROME inputImage :- Image widget filterName :kony.filter.PHOTO_EFFECT_

FADE inputImage :- Image widget filterName :kony.filter.PHOTO_EFFECT_

MONO inputImage :- Image widget

Applies a preconfigured set of effects that imitate vintage photography film with exaggerated color.This filter is available in iOS 6 and above.

Applies a preconfigured set of effects that imitate vintage photography film with diminished color.

This filter is available in iOS 7 and above.

Applies a preconfigured set of effects that imitate vintage photography film with distorted colors. This filter is available in iOS 7 and above.

Applies a preconfigured set of effects that imitate black-and-white photography film with low contrast. This filter is available in iOS 7 and above.

Kony Studio API Developer's Guide

Version 3.1

kony.filter.PHOTO_EFFECT_

PROCESS kony.filter.PHOTO_EFFECT_

TONAL kony.filter.PHOTO_EFFECT_

TRANSFER kony.filter.PIN_LIGHT_

BLEND_MODE filterName :kony.filter.PHOTO_EFFECT_

PROCESS inputImage :- Image widget filterName :kony.filter.PHOTO_EFFECT_

TONAL inputImage :- Image widget filterName :kony.filter.PHOTO_EFFECT_

TRANSFER inputImage :- Image widget filterName :- kony.filter.PIN_

LIGHT_BLEND_MODE inputImage :- Image widget inputBackgroundImage :- Image widget

Applies a preconfigured set of effects that imitate vintage photography film with emphasized cool colors. This filter is available in iOS 7 and above.

Applies a preconfigured set of effects that imitate black-and-white photography film without significantly altering contrast.This filter is available in iOS 7 and above.

Applies a preconfigured set of effects that imitate vintage photography film with emphasized warm colors. This filter is available in iOS 7 and above.

This filter is available in iOS 8 and above.

Kony Studio API Developer's Guide

Version 3.1

kony.filter.SATURATION_

BLEND_MODE kony.filter.SCREEN_BLEND_

MODE kony.filter.SCREEN_

COMPOSITING kony.filter.SEPIA_TONE

filterName :kony.filter.SATURATION_

BLEND_MODE inputImage :- Image widget inputBackgroundImage :- Image widget filterName :kony.filter.SCREEN_BLEND_

MODE inputImage :- Image widget inputBackgroundImage :- Image widget filterName:kony.filter.SCREEN_

COMPOSITING inputImage:- Image widget inputBackgroundImage:- Image widget filterName :- kony.filter.SEPIA_

TONE inputImage :- Image widget inputInternsity:- number

This filter is available in iOS 6 and above.

This filter is available from Android 3.0 and above.

Maps the colors of an image to various shades of brown. This filter is available in iOS 5 and above.

Kony Studio API Developer's Guide

Version 3.1

kony.filter.SHARPEN

kony.filter.SOFT_LIGHT_

BLEND_MODE kony.filter.SOURCE_ATOP_

COMPOSITING kony.filter.SOURCE_IN_

COMPOSITING filterName:kony.filter.SHARPEN

inputImage:- Image widget inputRadius:- number(1 or 2) filterName :- kony.filter.SOFT_

LIGHT_BLEND_MODE inputImage :- Image widget inputBackgroundImage :- Image widget filterName:kony.filter.SOURCE_ATOP_

COMPOSITING inputImage:- Image widget inputBackgroundImage:- Image widget filterName:kony.filter.SOURCE_IN_

COMPOSITING inputImage:- Image widget inputBackgroundImage:- Image widget

Increases the sharpness of image. Available on

Android.

This filter is available in iOS 6 and above.

This filter is available from Android 3.0 and above. This filter is available in iOS 6 and above.

Kony Studio API Developer's Guide

Version 3.1

kony.filter.SOURCE_OUT_

COMPOSITING kony.filter.SOURCE_OVER_

COMPOSITING kony.filter.SRGB_TONE_

CURVE_TO_LINEAR kony.filter.SUBTRACT_

BLEND_MODE filterName:kony.filter.SOURCE_OUT_

COMPOSITING inputImage:- Image widget inputBackgroundImage:- Image widget filterName:kony.filter.SOURCE_OVER_

COMPOSITING inputImage:- Image widget inputBackgroundImage:- Image widget filterName :- kony.filter.SRGB_

TONE_CURVE_TO_LINEAR inputImage :- Image widget filterName :kony.filter.SUBTRACT_

BLEND_MODE inputImage :- Image widget inputBackgroundImage :- Image widget

This filter is available from Android 3.0 and above. This filter is available in iOS 6 and above.

This filter is available from Android 3.0 and above. This filter is available in iOS 5 and above.

This filter is available in iOS 7 and above.

This filter is available in iOS 8 and above.

Kony Studio API Developer's Guide

Version 3.1

kony.filter.TEMPERATURE_

AND_TINT kony.filter.TONE_CURVE

filterName :kony.filter.TEMPERATURE_

AND_TINT inputImage :- Image widget inputNeutral:- Array of two numbers [x,y] inputTargetNeutral:- Array of two numbers [x,y] filterName :- kony.filter.TONE_

CURVE inputImage :- Image widget inputPoint0:- Array of two numbers [x,y](0.0 - 1.0) inputPoint1:- Array of two numbers [x,y](0.0 - 1.0) inputPoint2:- Array of two numbers [x,y](0.0 - 1.0) inputPoint3:- Array of two numbers [x,y](0.0 - 1.0) inputPoint4:- Array of two numbers [x,y](0.0 - 1.0)

Adapts the reference white point for an image.

This filter is available in iOS 5 and above.

Adjusts tone response of the R, G, and B channels of an image. This filter is available in iOS 5 and above.

Kony Studio API Developer's Guide

Version 3.1

kony.filter.VIGNETTE

kony.filter.VIGNETTE_

EFFECT kony.filter.WHITE_POINT_

ADJUST kony.filter.XOR_

COMPOSITING filterName :kony.filter.VIGNETTE

inputImage :- Image widget inputRadius :- number inputInternsity:- number (0.0 -

1.0) filterName :kony.filter.VIGNETTE_

EFFECT inputImage :- Image widget inputCenter :- Array of two numbers [x,y] inputIntensity :- number (0.0 -

1.0) inputRadius:- number filterName :- kony.filter.WHITE_

POINT_ADJUST inputImage :- Image widget inputColor:- Array of four numbers [0.0 - 1.0] filterName:- kony.filter.XOR_

COMPOSITING inputImage:- Image widget inputBackgroundImage:- Image widget

Reduces the brightness of an image at the periphery. This filter is available in iOS 5 and above.

Modifies the brightness of an image around the periphery of a specified region. This filter is available in iOS 7 and above.

Adjusts the reference white point for an image and maps all colors in the source using the new reference. This filter is available in iOS 5 and above.

This filter is available from Android 3.0 and above.

Kony Studio API Developer's Guide

Version 3.1

kony.filter.ZOOM_BLUR

filterName :- kony.filter.ZOOM_

BLUR inputImage :- Image widget inputCenter:- Array of two numbers [x,y] inputAmount:- number (default :

20.0)

This filter is available in iOS 9 and above.

3.14.2 Functions

The kony.filter namespace provides the following function.

kony.filter.createFilter Function

Creates a new filter object for use with the Image widget.

Syntax kony.filter.createFilter();

Parameters

None.

Return Values

A new filter object.

Platform Availability

All platforms.

3.14.3 Objects

The kony.filter namespace provides the following object.

filter Object

Kony Studio API Developer's Guide

Version 3.1

3.14.3.1 Filter Object

The filter object enables your app to apply filters to the bitmaps contained in Image widgets. This section discusses the filter object in the following topics.

Overview

Methods

Overview

This section presents information about the filter object in the following topics.

Filter Input Parameters

Adroid Filters

Filter Input Parameters

The filter object uses the following input parameters.

inputImage

Parameter inputRadius inputMask inputAngle inputNoiseLevel inputCenter

Description

Image object

Floating point number

Masking image

Floating point number

Array of two values defining the

(x,y) location of the center

inputScale inputAmount inputSharpness inputMinComponents inputMaxComponents inputSaturation inputBrightness inputIntensity inputContrast inputRVector inputGVector inputBVector inputAVector inputBiasVector inputRedCoefficients inputGreenCoefficients inputBlueCoefficients inputAlphaCoefficients

Kony Studio API Developer's Guide

Version 3.1

Floating point number

Array of four floating values

Floating point number

Array of four floats

535 of 838

inputEV inputPower inputNeutral inputTargetNeutral inputPoint0 inputPoint1 inputPoint2 inputPoint3 inputPoint4 inputColor inputRedCoefficients inputGreenCoefficients inputBlueCoefficients inputGradientImage inputBackgroundImage inputLevels inputColor0

Kony Studio API Developer's Guide

Version 3.1

Floating point number

Array of two floating point numbers

Array of four numbers representing the color

Array of ten floating point numbers

Gradient Image

Background Image

Floating point number

Array of four hex numbers representing the color

536 of 838

inputColor1 inputInsetPoint0 inputInsetPoint1 inputStrands inputPeriodicity inputRotation inputZoom inputDisplacementImage inputTexture inputRefraction inputCropAmount inputCenterStretchAmount inputWidth inputTransform inputRectangle inputAspectRatio inputTopLeft

Kony Studio API Developer's Guide

Version 3.1

Array of four hex numbers representing the color

Array of two floating point numbers

Floating point number

Image object

Floating point number

Array of nine floats representing the transform

Array of four floating point numbers

Floating point number

Array of two floating point numbers

Kony Studio API Developer's Guide

Version 3.1

inputTopRight inputBottomRight inputBottomLeft inputExtent inputRadius0 inputRadius1 inputGCR inputUCR inputCount inputHeight inputHighLimit inputLowLimit inputMaskImage inputWeights inputBias inputUnsharpMaskRadius inputUnsharpMaskIntensity inputHighlightAmount

Array of two floating point numbers

Array of four floating point numbers

Floating point number

Integer

Floating point number

Masking image

Array of floating point numbers

Floating point number

Kony Studio API Developer's Guide

Version 3.1

inputShadowAmount inputNRNoiseLevel inputNRSharpness inputEdgeIntensity inputThreshold inputContrast inputShadingImage inputLightPosition inputLightPointsAt inputConcentration

Floating point number

Image object

Array of three floating point numbers

Floating point number

Android Filters

The following filters are available on Android devices. For detailed information on the filter types, please see

Filter Type Constants

Filter Name

AdditionCompositing

BoxBlur

Filter Type kony.filter.ADDITION_

COMPOSITING kony.filter.BOX_BLUR

Description

This filter is available from

Android 3.0 and above.

Increase or decreases the blurriness of image.

Kony Studio API Developer's Guide

Version 3.1

Brightness

ClearCompositing

ColorClamp

ColorInversion

ColorMatrix

DarkenCompositing

EdgeDetection

Emboss kony.filter.BRIGHTNESS

kony.filter.CLEAR_COMPOSITING

kony.filter.COLOR_CLAMP

kony.filter.COLOR_INVERSION

kony.filter.COLOR_MATRIX

kony.filter.DARKEN_

COMPOSITING kony.filter.EDGE_DETECTION

kony.filter.EMBOSS

Increases or decreases the brightness of an image.

This filter is available from

Android 3.0 and above.

This filter clamps the colors of input image within the given range.

Inverts the colors of given image. When this filter is applied, for each pixel having [R,G,B] components in given image, this filter inverts the color components of those pixels to [255-R,

255-G, 255-B].

Transparency or Alpha component is untouched

This filter transforms the colors of given image as per the input parameters

This filter is available from

Android 3.0 and above.

Detects or Highlight the edges of given image.

Applies an embossing effect for a given image.

Kony Studio API Developer's Guide

Version 3.1

GaussianBlur

Greyscale

MultiplyCompositing

LightenCompositing

OverlayCompositing

SourceAtopCompositing

ScreenCompositing

Sharpen

SourceInCompositing

SourceOutCompositing kony.filter.GAUSSIAN_BLUR

kony.filter.GREYSCALE

kony.filter.MULTIPLY_

COMPOSITING kony.filter.LIGHTEN_

COMPOSITING kony.filter.OVERLAY_

COMPOSITING kony.filter.SOURCE_ATOP_

COMPOSITING kony.filter.SCREEN_

COMPOSITING kony.filter.SHARPEN

kony.filter.SOURCE_IN_

COMPOSITING kony.filter.SOURCE_OUT_

COMPOSITING

Spreads source pixels by an amount specified by a

Gaussian distribution to increase the blurriness.

Blurriness of this filter is smooth compared to

BoxBlur.

Converts given image to black & white or monochrome image.

This filter is available from

Android 3.0 and above.

This filter is available from

Android 3.0 and above.

This filter is available from

Android 3.0 and above.

This filter is available from

Android 3.0 and above.

This filter is available from

Android 3.0 and above.

Increases the sharpness of image.

This filter is available from

Android 3.0 and above.

This filter is available from

Android 3.0 and above.

Kony Studio API Developer's Guide

Version 3.1

SourceOverCompositing

XorCompositing kony.filter.SOURCE_OVER_

COMPOSITING kony.filter.XOR_COMPOSITING

This filter is available from

Android 3.0 and above.

This filter is available from

Android 3.0 and above.

iOS Filters

The following filters are available on Android devices. For detailed information on the filter types, please see

Filter Type Constants

Filter Name

CIAdditionCompositing

CIAffineTransform

CIBlendWithMask

CIBlendWithAlphaMask

CIBloom

CIBoxBlur

Filter Type kony.filter.ADDITION_

COMPOSITING kony.filter.AFFINE_TRANSFORM

kony.filter.BLEND_WITH_MASK

kony.filter.BLEND_WITH_

ALPHA_MASK kony.filter.BLOOM

kony.filter.BOX_BLUR

Description

Adds color components to achieve a brightening effect. This filter is available in iOS 6 and above.

This filter is available in iOS 5 and above.

This filter is available in iOS 6 and above.

This filter is available in iOS 7 and above.

This filter is available in iOS 6 and above.

This filter is available in iOS 9 and above.

Kony Studio API Developer's Guide

Version 3.1

CIColorBlendMode

CIColorClamp

CIColorControls

CIColorCrossPolynomial

CIColorDodgeBlendMode

CIColorInvert kony.filter.COLOR_BLEND_

MODE kony.filter.COLOR_CLAMP

kony.filter.COLOR_CONTROLS

kony.filter.COLOR_CROSS_

POLYNOMIAL kony.filter.COLOR_DODGE_

BLEND_MODE kony.filter.COLOR_INVERSION

Uses the luminance values of the background with the hue and saturation values of the source image. This filter is available in iOS 6 and above.

This filter is available in iOS 7 and above.

Adjusts saturation, brightness, and contrast values. This filter is available in iOS 5 and above.

Modifies the pixel values in an image by applying a set of polynomial crossproducts. This filter is available in iOS 7 and above.

Brightens the background image samples to reflect the source image samples.

This filter is available in iOS 6 and above.

Inverts the colors in an image. This filter is available in iOS 6 and above.

Kony Studio API Developer's Guide

Version 3.1

CIColorMap

CIColorMatrix

CIColorMonochrome

CIColorPolynomial kony.filter.COLOR_MAP

kony.filter.COLOR_MATRIX

kony.filter.COLOR_

MONOCHROME kony.filter.COLOR_POLYNOMIAL

Performs a nonlinear transformation of source color values using mapping values provided in a table.

inputGradientImage is an nx1 or nxn gradient image used to describe a color ramp. This filter is available in iOS 6 and above.

Multiplies source color values and adds a bias factor to each color component. This filter is available in iOS 5 and above.

Remaps colors so they fall within shades of a single color. This filter is available in iOS 6 and above.

Modifies the pixel values in an image by applying a set of cubic polynomials.

This filter is available in iOS 6 and above.

Kony Studio API Developer's Guide

Version 3.1

CIColorPosterize

CIComicEffect

CIConvolution3X3

CIConvolution5X5

CIConvolution7X7

CIConvolution9Horizontal

CIConvolution9Vertical

CICrystallize

CIDarkenBlendMode kony.filter.COLOR_POSTERIZE

kony.filter.COMIC_EFFECT

kony.filter.CONVOLUTION_3X3

kony.filter.CONVOLUTION_5X5

kony.filter.CONVOLUTION_7X7

kony.filter.CONVOLUTION_9_

HORIZONTAL kony.filter.CONVOLUTION_9_

VERTICAL kony.filter.CRYSTALLIZE

kony.filter.DARKEN_BLEND_

MODE

Remaps red, green, and blue color components to the number of brightness values you specify for each color component.

This filter is available on iOS 6 and above.

This filter is available on iOS 9 and above.

This filter is available on iOS 7 and above.

This filter is available on iOS 9 and above.

This filter is available on iOS 7 and above.

This filter is available on iOS 9 and above.

Creates composite image samples by choosing the darker samples. This filter is available on iOS 6 and above.

Kony Studio API Developer's Guide

Version 3.1

CIDifferenceBlendMode

CIDiscBlur

CIDivideBlendMode

CIEdges

CIEdgeWork

CIExclusionBlendMode

CIExposureAdjust kony.filter.DIFFERENCE_

BLEND_MODE kony.filter.DISC_BLUR

kony.filter.DIVIDE_BLEND_

MODE kony.filter.EDGES

kony.filter.EDGE_WORK

kony.filter.EXCLUSION_BLEND_

MODE kony.filter.EXPOSURE_ADJUST

Subtracts the greater brightness values from lower. This filter is available on iOS 6 and above.

This filter is available on iOS 9 and above.

Divides the backgroundImage color from source image color.

This filter is available on iOS 8 and above.

This filter is available on iOS 9 and above.

Produces an effect similar to

CIDifferenceBlend mode but has lower contrast.

This filter is available on iOS 6 and above.

Adjusts the exposure setting for an image similar to the way you control exposure for a camera when you change the F-stop. This filter is available in iOS 5 and above.

Kony Studio API Developer's Guide

Version 3.1

CIFalseColor

CIGammaAdjust

CIGaussianBlur

CIGloom

CIHardLightBlendMode

CIHueAdjust kony.filter.FALSE_COLOR

kony.filter.GAMMA_ADJUST

kony.filter.GAUSSIAN_BLUR

kony.filter.GLOOM

kony.filter.HARD_LIGHT_

BLEND_MODE kony.filter.HUE_ADJUST

Maps luminance to a color ramp of two colors.

This filter is available in iOS 6 and above.

This filter is available in iOS 5 and above.

Spreads source pixels by an amount specified by a

Gaussian distribution to increase the blurriness.

This filter is available in iOS 6 and above.

Changes the overall hue, or tint, of the source pixels. This filter is available in iOS 5 and above.

Kony Studio API Developer's Guide

Version 3.1

CIHueBlendMode

CILightenBlendMode kony.filter.HUE_BLEND_MODE

kony.filter.LIGHTEN_BLEND_

MODE

CILinearBurnBlendMode

CILinearDodgeBlendMode

CILinearToSRGBToneCurve kony.filter.LINEAR_TO_SRGB_

TONE_CURVE

CILuminosityBlendMode

CIMaskToAlpha kony.filter.LINEAR_BURN_

BLEND_MODE kony.filter.LINEAR_DODGE_

BLEND_MODE kony.filter.LUMINOSITY_BLEND_

MODE kony.filter.MASK_TO_ALPHA

Uses luminance and saturation values from backgroundImage with the hue values on input image. This filter is available in iOS 6 and above.

The lighter samples are taken from both the images and will be used in resultant image. This filter is available in iOS 7 and above.

This filter is available in iOS 8 and above.

This filter is available in iOS 6 and above.

Converts a grayscale image to a white image that is masked by alpha.

This filter is available in iOS 6 and above.

Kony Studio API Developer's Guide

Version 3.1

CIMaximumComponent

CIMaximumCompositing

CIMedianFilter

CIMinimumComponent

CIMinimumCompositing

CIMotionBlur

CIMultiplyBlendMode

CIMultiplyCompositing

CINoiseReduction

CIOverlayBlendMode kony.filter.MAXIMUM_

COMPONENT kony.filter.MAXIMUM_

COMPOSITING kony.filter.MEDIAN_FILTER

kony.filter.MINIMUM_

COMPONENT kony.filter.MINIMUM_

COMPOSITING kony.filter.MOTION_BLUR

kony.filter.MULTIPLY_BLEND_

MODE kony.filter.MULTIPLY_

COMPOSITING kony.filter.NOISE_REDUCTION

kony.filter.OVERLAY_BLEND_

MODE

Returns a grayscale image from max(r,g,b).

This filter is available in iOS 6 and above.

This filter is available in iOS 9 and above.

Returns a grayscale image from min(r,g,b).

This filter is available in iOS 6 and above.

This filter is available in iOS 9 and above.

This filter is available in iOS 6 and above.

This filter is available in iOS 9 and above.

This filter is available in iOS 6 and above.

Kony Studio API Developer's Guide

Version 3.1

CIPhotoEffectChrome

CIPhotoEffectFade

CIPhotoEffectInstant

CIPhotoEffectMono kony.filter.PHOTO_EFFECT_

CHROME kony.filter.PHOTO_EFFECT_

FADE kony.filter.PHOTO_EFFECT_

INSTANT kony.filter.PHOTO_EFFECT_

MONO

Applies a preconfigured set of effects that imitate vintage photography film with exaggerated color.This filter is available in iOS 6 and above.

Applies a preconfigured set of effects that imitate vintage photography film with diminished color.

This filter is available in iOS 7 and above.

Applies a preconfigured set of effects that imitate vintage photography film with distorted colors.

This filter is available in iOS 7 and above.

Applies a preconfigured set of effects that imitate black-and-white photography film with low contrast. This filter is available in iOS 7 and above.

Kony Studio API Developer's Guide

Version 3.1

CIPhotoEffectNoir

CIPhotoEffectProcess

CIPhotoEffectTonal

CIPhotoEffectTransfer

CIPinLightBlendMode kony.filter.PHOTO_EFFECT_

NOIR kony.filter.PHOTO_EFFECT_

PROCESS kony.filter.PHOTO_EFFECT_

TONAL kony.filter.PHOTO_EFFECT_

TRANSFER kony.filter.PIN_LIGHT_BLEND_

MODE

Applies a preconfigured set of effects that imitate black-and-white photography film with exaggerated contrast.

This filter is available in iOS 7 and above.

Applies a preconfigured set of effects that imitate vintage photography film with emphasized cool colors. This filter is available in iOS 7 and above.

Applies a preconfigured set of effects that imitate black-and-white photography film without significantly altering contrast. This filter is available in iOS 7 and above.

Applies a preconfigured set of effects that imitate vintage photography film with emphasized warm colors. This filter is available in iOS 7 and above.

This filter is available in iOS 8 and above.

Kony Studio API Developer's Guide

Version 3.1

CISaturationBlendMode

CIScreenBlendMode

CISoftLightBlendMode

CISourceAtopCompositing kony.filter.SATURATION_

BLEND_MODE kony.filter.SCREEN_BLEND_

MODE kony.filter.SOFT_LIGHT_BLEND_

MODE kony.filter.SOURCE_ATOP_

COMPOSITING

CISourceInCompositing

CISourceOutCompositing

CISRGBToneCurveToLinear kony.filter.SOURCE_IN_

COMPOSITING kony.filter.SOURCE_OUT_

COMPOSITING kony.filter.SRGB_TONE_

CURVE_TO_LINEAR

CISubtractBlendMode

CITemperatureAndTint kony.filter.SUBTRACT_BLEND_

MODE kony.filter.TEMPERATURE_

AND_TINT

This filter is available in iOS 6 and above.

Maps color intensity from the sRGB color space to a linear gamma curve.

This filter is available in iOS 7 and above.

This filter is available in iOS 8 and above.

Adapts the reference white point for an image.

This filter is available in iOS 5 and above.

Kony Studio API Developer's Guide

Version 3.1

CIToneCurve

CIVibrance

CIVignette

CIVignetteEffect

CIZoomBlur

Methods

The filter object contains the following methods.

applyFilter Method

This method applies a filter to an Image object.

Syntax filter.applyFilter(

dictionary)

kony.filter.VIBRANCE

kony.filter.VIGNETTE

kony.filter.VIGNETTE_EFFECT

kony.filter.ZOOM_BLUR

Adjusts tone response of the R, G, and B channels of an image. This filter is available in iOS 5 and above.

Adjusts the saturation of an image while keeping pleasing skin tones. This filter is available in iOS 5 and above.

Reduces the brightness of an image at the periphery. This filter is available in iOS 5 and above.

Modifies the brightness of an image around the periphery of a specified region.

This filter is available in iOS 9 and above.

553 of 838

Kony Studio API Developer's Guide

Version 3.1

Parameters dictionary

A dictionary of attributes that contains the name of the filter and the filter's supporting data.

Return Values

None.

Remarks

For information about the available filters and their required supporting data, please see the

Overview

section of the filter Object documentation.

Platform Availability

Available on all platforms.

clearFilterData Method

Clears all of the data stored in a filter.

Syntax filter.clearFilterData()

Parameters

None.

Return Values

None.

Platform Availability

Available on all platforms.

getOutputImage Method

Gets the image that results from applying the filter.

Syntax filter.getOutputImage()

Parameters

None.

Return Values

The image that results from applying the filter.

Platform Availability

Available on all platforms.

3.15 kony.hybrid Namespace

The kony.hybrid namespace provides the following API elements.

Functions

3.15.1 Functions

The kony.hybrid namespace provides the following functions.

Kony Studio API Developer's Guide

Version 3.1

3.15.1.1 kony.hybrid.executeFunctionInNativeContext

This API provides the ability to send data from the browser widget execution context to native context.

Signature

JavaScript: kony.hybrid.executeFunctionInNativeContext(

Function

paramsTable

)

Input Parameters

Function [String] - Mandatory

Specifies the function that needs to be executed.

Kony Studio API Developer's Guide

Version 3.1

paramsTable [Object] - Mandatory

Specifies the list of parameters that the user defined function expects as input parameters. It is mandatory only if the invoked function accepts arguments.The paramsTable is the list of params that are passed to that function.

Note:

For the first parameter, the function name has to be passed as a string, for example, if the function is test() , then parameter must be passed as "test".

Return Values

None.

Platform Availability l iPhone l

Android

Example

//Defining executeFunctionInNativeContext function executeFunctionInNativeContext()

{ kony.hybrid.executeFunctionInNativeContext("JSFunThree",

{"KonySolutions",false,{"abc","xyz"}});

}

3.15.1.2 kony.hybrid.executeFunctionInSPAContext

This API provides the ability to send data from the native execution context to browser widget context.

Signature

JavaScript: hybrid.executeFunctionInSPAContext(

Function , paramsTable

)

Kony Studio API Developer's Guide

Version 3.1

Input Parameters

Function [String] - Mandatory

Specifies the function that needs to be executed paramsTable [Object] - Mandatory

Specifies the list of parameters that the user defined function expects as input parameters.

Return Values

None.

Platform Availability l iPhone l

Android

Example function executeFunctionInSPAContext()

{ kony.hybrid.executeFunctionInSPAContext("JSFunThree",

["KonyLabs",2012,false]);

}

3.15.1.3 kony.hybrid.executeFunctionInTCContext

This API is used to exchange data with the server-side context.

Signature

JavaScript:

hybrid.executeFunctionInTCContext( Function , paramsTable)

Kony Studio API Developer's Guide

Version 3.1

Input Parameters

Function [String] - Mandatory

Specifies the function that needs to be executed paramsTable [Object] - Mandatory

Specifies the list of parameters that the user defined function expects as input parameters.

Return Values

None.

Platform Availability l iPhone l

Android

Example function executeFunctionInTCContext()

{ kony.hybrid.executeFunctionInTCContext("JSFunThree",

{"KonySolutions", false,{"abc","xyz"}});

}

3.16 kony.image Namespace

The kony.image namespace provides the following API elements.

Constants

Functions

Kony Studio API Developer's Guide

Version 3.1

3.16.1 Constants

The kony.image namespace provides the following constants.

Image Format Constants

The following constants are used to specify the format of an Image widget's bitmap.

Constant kony.image.ENCODE_JPEG

kony.image.ENCODE_PNG

Description

The bitmap is in JPEG format.

The bitmap is in PNG format.

3.16.2 Functions

The kony.image namespace provides the following functions.

kony.image.createImage Function

Creates an Image. This function has three overloads.

Syntax kony.image.createImage(

rawBytes);

Parameters rawBytes

A RawBytes object containing the image's bitmap.

Syntax kony.image.createImage(

bundledImageFileName);

Kony Studio API Developer's Guide

Version 3.1

Parameters bundledImageFileName

A string containing the file name of the bitmap to use for the image.

Syntax kony.image.createImage(

Image);

Parameters

Image

An Image widget containing the bitmap to use for the Image being created.

Return Values

This function returns an image object with its associated bitmap.

Remarks

If your app creates an Image from a RawBytes object, it should not make copies of the Image by creating it again from the initial RawBytes object. Creating multiple Image objects from the same RawBytes object results in undefined behavior. Rather than copying the RawBytes object into multiple Image objects, your app can make further copies by calling this function and passing it the Image object created in the first call to this function.

Platform Availability

Available on all platforms.

kony.image.createImageFromSnapShot Function

Creates an Image by taking a snapshot of a widget.

Syntax kony.image.createImageFromSnapShot(

widget);

Kony Studio API Developer's Guide

Version 3.1

Parameters widget

The widget that this function takes a snapshot of. The snapshot is used for the bitmap of the Image created by the function.

Return Values

This function returns an Image that contains a snapshot of the widget passed in through the widget parameter.

Platform Availability

Available on all platforms.

cropImageInTiles Function

Crops the bitmap in an Image object and returns it as an array of tiles.

Syntax kony.image.cropImageInTiles(

image,

xTiles,

yTiles)

Parameters image

The Image widget containing the bitmap to be cropped.

xTiles

The number of equally-sized tiles that can be created in the x direction.

yTiles

The number of equally-sized tiles that can be created in the x direction.

Kony Studio API Developer's Guide

Version 3.1

Return Values

This function returns an array of Image widgets that were created from tiles of the bitmap in the Image widget in the image parameter.

Platform Availability

Available on all platforms.

cropImageInTilesForRects Function

Crops portions of an Image widget's bitmap to a set of rectangles and returns an array of Image widgets containg the cropped bitmaps.

Syntax kony.image.cropImageInTilesForRects(

image,

[ [x,y,w,h],[x1,y1,w1,h1],... ])

Parameters image

An Image widget containing the bitmap to be cropped.

[ [x,y,w,h],[x1,y1,w1,h1],... ]

An array of rectangles specified as the (x,y) coordinates of the upper left corner and the height and width of the rectangle.

Return Values

This function returns an array of Image widgets that contain the bitmap information from the bitmap in the

Image widget passed through the image parameter.

Remarks

This method iterates through an array of rectangles and uses each rectangle to obtain a cropped version of the bitmap associated with the Image widget in the image parameter. The original bitmap is not changed. It then creates an Image widget from each cropped bitmap and collects then into an array of Image widgets. It then returns the array of Image widgets.

Kony Studio API Developer's Guide

Version 3.1

Platform Availability

Available on all platforms.

3.17 kony.io.File Namespace

The kony,io.File namespace includes APIs to do various tasks related with files, such as copying, renaming, deleting and so on.

Creating a File object instance: Use the kony.io.FileSystem.getFile() api to get an instance of a File or create it with a new operator. Here, an abject represents a path to a file or directory in the device file system.

var myfile = new kony.io.File("myfile.txt"); or var myfile = kony.io.FileSystem.getFile("myfile.txt")

Description File

Properties:Name name: [type:

String, ReadOnly]

Name of the file or directory fullPath: [type:

String, ReadOnly]

Full absolute path of the file or directory parent:

[type:kony.io.File,

ReadOnly]

Returns the parent directory of this file.

This property may return nil or a File object which can neither Readable or

Writable, especially in case of Folders which are not accessible by the given

Application context

Returns true if this file is readable readable: [type:

Boolean,

ReadOnly]

Kony Studio API Developer's Guide

Version 3.1

File

Properties:Name writable: [type:

Boolean,

ReadOnly]

Returns true if this file is writable

Description

Returns the last modification time of the file in UTC modificationTime:

[type:Number,

ReadOnly] size:

[type:Number,

ReadOnly

Returns the size of a file in number of bytes.

The File library comprises the following APIs:

10.

11.

Kony Studio API Developer's Guide

Version 3.1

12.

write

3.17.1 Functions

The kony.io.File namespace contains the following functions.

3.17.1.1 kony.io.File.copyTo

copyTo API copies a file to the given destination path.

Signature

JavaScript: kony.io.File.copyTo(String path, String newName)

Input Parameters l

Path – path to the destination directory.

l newName (optional) – New name of the file/directory. Defaults to current name if unspecified.

Return Values

Kony.io.File returns a handle to the File object pointing to the destination file, if successful. If failure, then returns null.

Exceptions

None

Platform Availability

Available for iOS, Android, and Windows platforms.

3.17.1.2 kony.io.File.createDirectory

The createDirectory API creates a directory on the file system represented by this file object.

Signature

JavaScript: kony.io.File.createDirectory()

Kony Studio API Developer's Guide

Version 3.1

Input Parameters

None

Return Values

Boolean – true if the creation of directory is successful. False if directory already exists or could not be created.

Exceptions

None

Platform Availability

Available for iOS, Android, and Windows platforms.

3.17.1.3 kony.io.File.createFile

The createFile API creates a file on the file system represented by this file object.

Signature

JavaScript: kony.io.File.createFile()

Input Parameters

None

Return Values

Boolean – true if the creation of file is successful. False if file already exists or could not be created.

Exceptions

None

Platform Availability

Available for iOS, Android, and Windows platforms.

3.17.1.4 kony.io.File.exists

The exist API checks, if the file or directory exists on the file system represented by this file object.

Kony Studio API Developer's Guide

Version 3.1

Signature

JavaScript: kony.io.File.exists()

Input Parameters

None

Return Values

Boolean – true if the file or directory exists on file system.

Exceptions

None

Platform Availability

Available for iOS, Android, and Windows platforms.

3.17.1.5 kony.io.File.getFilesList

The getFilesList API returns kony.io.FileList object representing the files and directories available under this file object directory.

Signature

JavaScript: kony.io.File.getFilesList()

Input Parameters

None

Return Values kony.io.FileList – FileList object or null if this File is not identified as a directory.

Exceptions

None

Platform Availability

Available for iOS, Android, and Windows platforms.

Kony Studio API Developer's Guide

Version 3.1

3.17.1.6 kony.io.File.isDirectory

The isDirectory API checks, if this object represents a directory file on the file system.

Signature

JavaScript: kony.io.File.isDirectory()

Input Parameters

None

Return Values

Boolean – true, if this file object represents a directory, false otherwise.

Exceptions

None

Platform Availability

Available for iOS, Android, and Windows platforms.

3.17.1.7 kony.io.File.isFile

The isFile API checks, if this object represents a typical file on the file system but not a directory.

Signature

JavaScript: kony.io.File.isFile()

Input Parameters

None

Return Values

Boolean – true if this file object represents a file, false otherwise.

Exceptions

None

Kony Studio API Developer's Guide

Version 3.1

Platform Availability

Available for iOS, Android, and Windows platforms.

3.17.1.8 kony.io.File.moveTo

The moveTo API moves a file to the given destination path.

Signature

JavaScript: kony.io.File.moveTo(String path, String newname)

Input Parameters l

Path – path to the destination directory.

l newName (optional) – New name of the file/directory. Defaults to current name, if unspecified.

Return Values

Kony.io.File – returns a handle to File object pointing to destination file on success. Returns null on failure.

Exceptions

None

Platform Availability

Available to iOS, Android, and Windows platforms.

3.17.1.9 kony.io.File.read

The read API returns the kony.types.RawBytes of this file.

Signature

JavaScript: kony.io.File.read()

Input Parameters

None

Kony Studio API Developer's Guide

Version 3.1

Return Values kony.types.RawBytes – rawbytes representing the content of the file.Returns null in case of non existent file.

Exceptions

None

Platform Availability

Available for iOS, Android, and Windows platforms.

Note: RawBytes will hold a handle of File object that it represents. The file content is not actually loaded into memory.

3.17.1.10 readAsText

The readAsText API returns the data as text represented by this rawBytes . Returns null if this represents a binary.

Signature

JavaScript: kony.io.File.readAsText()

Input Parameters

None

Return Values

String - text available in this rawbytes.

Exceptions

None

Platform Availability

Available for iOS, Android, and Windows platforms.

3.17.1.11 kony.io.File.remove

The remove API deletes a file or a directory.

Signature

JavaScript: remove(boolean, deleteRecursive)

Input Parameters l boolean: By default, this is false.

True - deletes the folder and all its content recursively.

False - if the directory is empty it shall be removed.

l deleteRecursive (optional) – Ignored in case of a file.

Return Values

None

Exceptions

None

Platform Availability

Available for iOS, Android, and Windows platforms.

3.17.1.12 kony.io.File.rename

The rename API renames a file or a directory.

Signature

JavaScript: kony.io.File.rename(String newname)

Input Parameters newname – new name for a file or a directory.

Kony Studio API Developer's Guide

Version 3.1

Kony Studio API Developer's Guide

Version 3.1

Return Values

Boolean – If successful, then boolean value is true,. Boolean value is false, if invalid file name or if the destination is a different directory than the current file.

Exceptions

None

Platform Availability

Available for iOS, Android, and Windows platforms.

3.17.1.13 kony.io.File.write

The write API writes the given content into the file.

Signature

JavaScript: kony.io.File.write(rawbytes/string, append)

Input Parameters l

Rawbytes/string – data to write of type text string or kony.types.RawBytes

Append (optional) – true to append the data. Default is false, that means overrides the content.

Return Values

Boolean – true if success, false otherwise.

Exceptions

None

Platform Availability

Available for iOS, Android, and Windows platforms.

3.18 kony.io.FileList Namespace

FileList namespace represents the list of file objects.

Kony Studio API Developer's Guide

Version 3.1

FileList Properties:Name length: [type: Number, ReadOnly]

Description

Returns the number of files in the FileList object.

The FileList library comprises the following API: l item

3.18.1 Functions

The kony.io.FileList namespace contains the following functions.

3.18.1.1 item

The item API returns the File object at the specified index in the FileList.

Signature

JavaScript: kony.io.File.item(index)

Input Parameters

Index – index in the FileList.

Return Values

File - File object at specified index. Null if there is no File at specified index or if index is not in FileList range.

Exceptions

None

Platform Availability

Available for iOS, Android, and Windows platforms.

Kony Studio API Developer's Guide

Version 3.1

3.19 kony.io.FileSystem Namespace

The kony.io.FileSystem namespace includes APIs to create, read and navigate through the device file system.

The File System APIs library comprises the following APIs: l

getFile

getCacheDirectoryPath

getDataDirectoryPath

getApplicationDirectoryPath

getExternalStorageDirectoryPath

getRawDirectoryPath

getSupportDirectoryPath

isExternalStorageAvailable

kony.io.FileSystem.browse

kony.io.FileSystem.uploadFiles

3.19.1 Functions

The kony.io.FileSystem namespace contains the following functions.

3.19.1.1 kony.io.FileSystem.browse

This API provides the ability to browse and select files from your local system.

Signature

JavaScript:

kony.io.FileSystem.browse( browseConfig

browseCallBack

)

Kony Studio API Developer's Guide

Version 3.1

Input Parameters browseConfig [String] - Mandatory

Configuration params which is a simple JSON object of key value pairs, that drive the possible options during the browse. Currently the following keys are supported in the configuration: l selectMultipleFiles: (Boolean) - Default (true) l filter: An array indicates what file Filters should be applied to the file selection dialog. The file

Filters need to follow the conventions specified in the IANAMediaTypes specification. For more information, see http://www.iana.org/assignments/media-types/media-types.xhtml

browseCallBack [Object] - Mandatory

The callback is executed once the user closes the browse dialog. As part of call back, the platform provides the list of files that have been selected as an array of kony.io.FileSystem objects. The call back signature is as follows: browseCallBack (event, FileList[]).

Return Values

None.

Platform Availability

Applicable only on Desktop web.

Example function selectBtn_onClick_seq0() { // Event on button click var config = { selectMultipleFiles: true, filter: ["image/png", "image/jpeg"]

}; kony.io.FileSystem.browse(config, selectedFileCallback);

};

3.19.1.2 kony.io.FileSystem.getAppGroupDirectoryPath

Kony Studio API Developer's Guide

Version 3.1

Retrieves the root path of an app group.

Syntax kony.io.FileSystem.getAppGroupDirectoryPath(

appGroupID)

Parameters appGroupID

Holds a string containing the unique ID of the app group.

Return Values

A string containing the fully-qualified path to the root directory of the app group.

Platform Availability iOS only.

3.19.1.3 kony.io.FileSystem.getApplicationDirectoryPath

getApplicationDirectoryPath API returns the application directory path.

Signature

JavaScript: kony.io.FileSystem.getApplicationDirectoryPath()

Input Parameters

None

Return Values

String

Exceptions

None

Platform Availability

Applicable to the iOS platforms.

Kony Studio API Developer's Guide

Version 3.1

3.19.1.4 kony.io.FileSystem.getCacheDirectoryPath

getCacheDirectoryPath API returns the application's cache directory path.

Signature

JavaScript: kony.io.FileSystem.getCacheDirectoryPath()

Input Parameters

None

Return Values

String

Exceptions

None

Platform Availability

Applicable to all native Platforms and DesktopWeb.

3.19.1.5 kony.io.FileSystem.getDataDirectoryPath

getDataDirectoryPath API returns the application’s data directory path.

Signature

JavaScript: kony.io.FileSystem.getDataDirectoryPath()

Input Parameters

None

Return Values

String

Exceptions

None

Kony Studio API Developer's Guide

Version 3.1

Platform Availability

Applicable to all the native platforms and DesktopWeb.

3.19.1.6 kony.io.FileSystem.getExternalStorageDirectoryPath

getExternalStorageDirectoryPath API returns the path to the external storage, typically sdcard.

Signature

JavaScript: kony.io.FileSystem.getExternalStorageDirectoryPath()

Input Parameters

None

Return Values

String

Exceptions

None

Platform Availability

Applicable to the Android platform.

3.19.1.7 kony.io.FileSystem.getFile

getFile API returns a kony.io.File object representing the file for the given path. It returns a kony.io.File

object for the specified file path. getFile API does not create a File.

Signature

JavaScript: kony.io.FileSystem.getFile(string path)

Input Parameters

Path – path to the file or directory.

Return Values

Kony.io.File

Kony Studio API Developer's Guide

Version 3.1

Platform Availability

Applicable to all native Platforms and Desktop Web.

3.19.1.8 kony.io.FileSystem.getRawDirectoryPath

getRawDirectoryPath API returns the application’s “raw” directory path. getRawDirectoryPath API

API is applicable only on Android.

Signature

JavaScript: kony.io.FileSystem.getRawDirectoryPath()

Input Parameters

None

Return Values

String

Exceptions

None

Platform Availability

Applicable to the Android platform.

3.19.1.9 kony.io.FileSystem.getSupportDirectoryPath

getSupportDirectoryPath API returns the application’s support directory path. This is applicable to iOS platform only.

Signature

JavaScript: kony.io.FileSystem.getSupportDirectoryPath()

Input Parameters

None

Kony Studio API Developer's Guide

Version 3.1

Return Values

String

Exceptions

None

Platform Availability

Applicable to the iOS platform.

3.19.1.10 kony.io.FileSystem.isExternalStorageAvailable

isExternalStorageAvailable API is used to check, if the external storage is available and accessible on the device. isExternalStorageAvailable API returns boolean value as true/false accordingly on Android platform.

Signature

JavaScript: kony.io.FileSystem.isExternalStorageAvailable()

Input Parameters

None

Return Values

Boolean

Exceptions

None

Platform Availability

Applicable to iOS, Android, and Windows platforms.

Kony Studio API Developer's Guide

Version 3.1

3.19.1.11 kony.io.FileSystem.uploadFiles

When the developer invokes this API with the list of files, the API Developer's Guide internally iterates through the fileList and makes the network call to the URL mentioned and uploads the files. The

API Developer's Guide assumes that the application using this API has the necessary server side infrastructure to handle the upload.

Internally, API Developer's Guide uses AJAX-based multi-part upload of the files to the URL mentioned in all browsers except IE 8 and 9. In the case of IE 8 and 9, we provide frame-based submit as the multi-part through AJAX (as it is not handled by the browser).

Note: The API kony.io.FileSystem.uploadFiles cannot be tested in local jetty server included in the Kony Visualizer. Use Tomcat to test the API. The uploadURL must have code to receive and store the files sent via kony app. The sample war file uploadServlet30.war

, contains code to handle uploading or storing files at server end. Both kony app and UploadURL needs to be on the same domain.

Signature

JavaScript: kony.io.FileSystem.uploadFiles(

URL , fileList

upLoadCallBack ,

upLoadConfig

)

Input Parameters

URL [String] - Mandatory

Provide target location to upload the file.

fileList [Object] - Mandatory

Specifies the list of files to be uploaded. This is as an array of kony.io.FileSystem.file objects.

uploadCallBack [Object] - Mandatory

The callback is invoked each time when the file is getting uploaded. The signature of the call back is expected to be as follows: uploadCallBack(URL, upLoadStates).

Kony Studio API Developer's Guide

Version 3.1

l upLoadState [Object] - Mandatory

This is an array of key value map states of the individual files that are uploaded. The key value map currently consists of the following keys: o file: File (kony.io.FileSystem.file) object o status: One of the following four status are possible : n

FILE_UPLOAD_START_STATE = 0 n

FILE_UPLOAD_PROGRESS_STATE = 1 n

FILE_UPLOAD_COMPLETE_STATE = 2 n

FILE_UPLOAD_ERROR_STATE = 3 o uploadBytes: Number of bytes that are uploaded.

uploadConfig [Object]

Configuration parameters, which is a simple JSON object of key value pairs, that provides the possible options during the upload. Currently there are no keys.

Return Values

None.

Platform Availability

Available only on Desktop Web.

Example function UploadBtn_onClick_seq0() { // Event on upload button click var uploadURL = "http://10.10.4.17:8080/fileupload/upload"; var filesQueue = [{File object},{File Object}]; //Array of File objects got in browseCallBack() kony.io.FileSystem.uploadFiles(uploadURL, filesQueue,

Kony Studio API Developer's Guide

Version 3.1

upLoadCallBack);

};

Limitations for File Browse and Upload APIs

1. API cannot be used in pre-show, post-show, appService, pre-appinit, or post-app init.

2. For details on filter types for Browse API, follow the specification provided in the

IANAMediaTypes. The Kony Visualizer depends on the browsers respecting the given filter type and enable appropriate file selection for the end user.

3. File Upload API does not work in the cross origin request scenarios. That is, the file can be uploaded only to the site from which the original app has been accessed. For more information, check CORS documentation.

4. For security reasons all browsers just give name or size of the file and not parent or full path. So, file parent and full path are not available in File object in browse or upload APIs. For more information, see http://stackoverflow.com/questions/15201071/how-to-get-full-path-ofselected-file-on-change-of-input-type-file-using-jav .

5. IE 8 and 9 Limitations: a. Multiple file selection will not work. As multiple attribute is not supported for input type= file, it allows the user to select only one file from the browse window even when

‘selectMultipleFiles’ is passed as true. For more information, see http://www.w3schools.com/tags/att_input_multiple.asp

b. Filters in the Browse API do not work. As accept attribute is not supported for input type= file, even through the filter is passed, it does not have any effect on browse window. User can select any file of any type. Hence, server side file validation is recommended. For more information, see http://www.w3schools.com/tags/att_input_accept.asp

c. The file object in Browse API callback method will not have file size in IE 8. IE 8 browsers do provide file path, but it is inconsistent and depends on IE 8 security configuration (IE 9

Kony Studio API Developer's Guide

Version 3.1

provide fakepath). We recommend to avoid accessing file parent, path and size in IE 8 and 9. File size is provided in IE 10, Firefox, and Chrome.

d. IE 8 and 9 uses iframe for file upload. The uploadprogress event is not triggered and bytes uploaded information is not provided in Upload API callback. So, callback is fired only twice.

i. When you submit form to iframe with FILE_UPLOAD_PROGRESS_STATE.

ii. When you get error or success onload event of iframe with respective state constants.

e. Multiple Upload. If a widget onclick action invokes the Browse API and user selects the file multiple times from the browse window, in browse API callback, you must handle all the files (selected by the user one by one). When Upload API is called, all the files user selected is uploaded to the specified URL. If you want to upload different files on different servers or URLs, then they need to call Browse API and Upload API subsequently one after the other. That is, you need to upload the selected file before letting the user select an other file (in case user wants to upload files on different URLs).

f. Empty files cannot be uploaded in case of IE browsers.

6. IE 8 and 9 Limitations: a. Multiple file selection will not work. As multiple attribute is not supported for input type= file, it allows the user to select only one file from the browse window even when

‘selectMultipleFiles’ is passed as true. For more information, see http://www.w3schools.com/tags/att_input_multiple.asp

Kony Studio API Developer's Guide

Version 3.1

c. The file object in Browse API callback method will not have file size in IE 8. IE 8 browsers do provide file path, but it is inconsistent and depends on IE 8 security configuration (IE 9 provide fakepath). We recommend to avoid accessing file parent, path and size in IE 8 and 9. File size is provided in IE 10, Firefox, and Chrome.

d. IE 8 and 9 uses iframe for file upload. The uploadprogress event is not triggered and bytes uploaded information is not provided in Upload API callback. So, callback is fired only twice.

i. When you submit form to iframe with FILE_UPLOAD_PROGRESS_STATE.

ii. When you get error or success onload event of iframe with respective state constants.

f. Empty files cannot be uploaded in case of IE browsers.

7. When the user uploads a file that has special characters in its file name, the special characters in the file name are replaced with other special characters on the server.

8. Check if the user is selecting the same file again and create appropriate conditions for browseCallBack. The check will help identify same files if selected earlier and eliminate duplicate files from getting uploaded.

9. Firefox Limitation. Filters with specific Mimetype might not work properly. It is a known bug in

Firefox, for more information, see: l http://techblog.procurios.nl/k/618/news/view/15872/14863/mimetype-corruption-infirefox.html

Kony Studio API Developer's Guide

Version 3.1

l http://support.mozilla.org/en-US/questions/953914 l https://bugzilla.mozilla.org/show_bug.cgi?id=826176 l https://bugzilla.mozilla.org/show_bug.cgi?id=373621

Note: Constants: Constants.FILE_PATH_SEPARATOR: Platform specific File path separator

3.20 kony.i18n Namespace

The kony,i18n namespace, which forms the

Internationalization API

, provides the following API elements.

Functions

3.20.1 kony.i18n_Functions

The kony.i18n namespace, which is used for internationalization, provides the following functions.

3.20.1.1 kony.i18n.deleteResourceBundle

This API allows you to delete an existing resource bundle. If a resource bundle does not exist, the API will return without performing any operation. Only resource bundles which are newly created using the setResourceBundle API will be deleted. The bundle which are created by IDE, cannot be deleted, but they can only be updated.

Signature

JavaScript: kony.i18n.deleteResourceBundle(

locale

)

Input Parameters locale [String] - Mandatory

Specifies the locale for which the resource bundle needs to be deleted.

Kony Studio API Developer's Guide

Version 3.1

Return Values

None

Exceptions

1300 - i18n error or Locale not supported error

Platform Availability

Available on all platforms.

JavaScript Example

// Method for delete the resource bundle --> function deleteResourceBundle()

{ try{ kony.i18n.deleteResourceBundle("en_US"); alert(" Resources bundle has been deleted.");

} catch(i18nError)

{ alert("Exception While getting deleteResourceBundle : "+i18nError

);

}

3.20.1.2 kony.i18n.getCurrentLocale

This API returns the locale (string) that is currently being used by the application to populate the localized data. This locale might be different than the system locale. The locale follows the format language_Country.For example,

en_US

Country

is not mandatory.

Kony Studio API Developer's Guide

Version 3.1

Use Cases

You can use this API to know the current locale of the application before: l changing the locale.

l deleting the resource bundle of the locale.

Signature

JavaScript: kony.i18n.getCurrentLocale()

Input Parameters

None.

Return Values

Current locale [String]

The current locale that is being used by the application is returned.

Exceptions

1300 - i18n error or Locale not supported error

Implementation Details

The current locale of the application is identified using the following rules:

Device

Locale

Locales

Supported by the application

Default

Locale en_GB en_US, zh_TW en_TW

Locale returned by getCurrentLocale

API en_TW (Since the device locale is not supported by the application, the API falls back to default locale)

Kony Studio API Developer's Guide

Version 3.1

Device

Locale

Locales

Supported by the application

Default

Locale en_US en_US, en , zh_TW en_TW

Locale returned by getCurrentLocale

API en_US

(Since the device locale is supported by the application, the API returns it as the current locale) en_US en, zh_TW en_TW en

(Since the device locale is supported by the application, the API falls back to the country)

This API follows the rules given below to identify the current locale:

1. When the device locale is not supported by the application:

For example, if the l application supports fr_GR, nl_NL.

l default locale is (set from IDE) nl_NL.

l device locale is en_GB.

The kony.i18n.getCurrentLocale() API returns nl_NL.

2. When the device locale supports just the language part and not the region part

For example, l application supports fr_GR, en_US, en_GB, nl_NL.

l default locale is (set from IDE) nl_NL.

l device locale is en..

Kony Studio API Developer's Guide

Version 3.1

Note: On iPhone and Android, the device settings mandate that a region must also be associated with a language. For devices like BlackBerry, the region is not mandatory.

The kony.i18n.getCurrentLocale() API picks up the first locale that matches the language. In this example, the API returns en_US as it is the first locale that matches the language as specified in the device system settings.

3. When appropriate fonts are not installed on the device for a given locale

For example, l application supports fr_FR and nl_NL l default locale is (set from IDE) nl_NL l device locale is en_GB.

The kony.i18n.getCurrentLocale() API returns nl_NL. If the device does not have Dutch fonts installed, the application UI displays junk characters.

Platform Availability

Available on all platforms.

JavaScript Example

// Method for getting current locale --> function getCurrentLocale()

{ try{ var currentLocales = kony.i18n.getCurrentLocale(); alert("CurrentLocale :"+currentLocales);

}

Kony Studio API Developer's Guide

Version 3.1

catch(i18nError)

{ alert("Exception While getting currentLocale : "+i18nError );

}

3.20.1.3 kony.i18n.getCurrentDeviceLocale

This API provides you the ability to fetch the current locale of the device.

Signature

JavaScript: kony.i18n.getCurrentDeviceLocale()

Input Parameters

None

Return Values listOfLocales [Table]

A table with the following key-value pairs is returned: l language l country l name

For example, local myLocaleDetails = kony.i18n.getCurrentDeviceLocale()

Where myLocaleDetails={language="en", country="US", name="English US"}

Note: In iOS platform this API returns a string value.

Kony Studio API Developer's Guide

Version 3.1

Exceptions

1300 - i18n error or Locale not supported error

Platform Availability

Available on iOS, Android, Windows Mango, Windows 8, and BlackBerry 10.

JavaScript Example function getCurrentDeviceLocale()

{ try

{

} catch(i18nerr)

{ var locale =kony.i18n.getCurrentDeviceLocale(); alert("current device locale is "+locale[0]); alert("Exception in getCurrentDeviceLocale : "+err );

}

3.20.1.4 kony.i18n.getLocalizedString

This API returns the localized string that corresponds to the specified i18n Key.

Signature

JavaScript:

kony.i18n.getLocalizedString( i18nkey )

Input Parameters i18nkey [String]- Mandatory

Specifies the internationalization key for which the localized string needs to be returned.

Kony Studio API Developer's Guide

Version 3.1

Return Type

Localizedstring [String]

Returns the localized string corresponding to the key value.

Exceptions

1300 - i18n error or Locale not supported error

Platform Availability

Available on all platforms.

JavaScript Example

// Method for getLocalizedString --> function getLocalizedString()

{ try{ var currentLocales = kony.i18n.getLocalizedString("1"); var currentLocales1 = kony.i18n.getLocalizedString("2"); alert(" LocalizedString Method called :"+currentLocales+"

"+currentLocales1);

} catch(i18nError)

{ alert("Exception While getting localizedString : "+i18nError );

}

3.20.1.5 kony.i18n.getSupportedLocales

This API retrieves a list of all the locales supported by the device.

Kony Studio API Developer's Guide

Version 3.1

Signature

JavaScript: kony.i18n.getSupportedLocales()

Input Parameters

None

Return Values listOfLocales [Table]

A table with the following key-value pairs is returned: l language l country l name

Note: In Windows platform, Country and Name are not supported.

For example, local list = kony.i18n.getSupportedLocales()

Where list={{language:"en", country:"US", name:"English US"},

{language:"en", country:"UK", name:"English UK"}}

Exceptions

1300 - i18n error or Locale not supported error

Platform Availability

Available on all platforms except Server Side Mobile Web, Desktop Web and SPA. *SPA and Desktop

Web returns only current locale instead of all locales supported by the browser.

Kony Studio API Developer's Guide

Version 3.1

JavaScript Example function getSupportedLocales()

{ try

{ var locales =kony.i18n.getSupportedLocales(); for(var i=1;i<locales.length;i++)

{ alert("locale is "+locales[i].name);

}

} catch(i18nerr)

{ alert("Exception in getSupportedLocales : "+err );

}

3.20.1.6 kony.i18n.isLocaleSupportedByDevice

This API provides you the ability to view whether a locale is supported by a device.

Signature

JavaScript: kony.i18n.isLocaleSupportedByDevice(

locale )

Input Parameters locale [String] - Mandatory

Specifies the locale that must be verified if it is supported by the device.

locale must be in one of the following formats:

Kony Studio API Developer's Guide

Version 3.1

l language_countryCode l language

For example, kony.i18n.isLocaleSupportedByDevice("en_US") kony.i18n.isLocaleSupportedByDevice("fr")

Return Values status [Boolean]

Indicates the status if the specified locale is supported by the device.

l true - if the specified locale is supported by the device.

l false - if the specified locale is not supported by the device.

Exceptions

1300 - i18n error or Locale not supported error

Platform Availability

Available on all platforms except SPA and Desktop Web.

JavaScript Example function isLocaleSupportedByDevice()

{ try

{ var isPresent =kony.i18n.isLocaleSupportedByDevice("zh_CN"); alert("locale supported by device "+isPresent);

}

Kony Studio API Developer's Guide

Version 3.1

catch(i18nerr)

{ alert("Exception in isLocaleSupportedByDevice : "+err );

}

} var isPresent =kony.i18n.isLocaleSupportedByDevice("en_us"); kony.print (isPresent);

3.20.1.7 kony.i18n.isResourceBundlePresent

This API checks if a resource bundle exists for a given locale and returns a boolean value.

Signature

JavaScript:

kony.i18n.isResourceBundlePresent ( locale

)

Input Parameters locale [String] - Mandatory

Specifies the locale for which the resource bundle is checked.

Return Values status [Boolean] true - if the resource bundle exists for the given locale.

false - if no resource bundle exists for the given locale.

Exceptions

1300 - i18n error or Locale not supported error

Platform Availability

Available on all platforms except SPA and Desktop Web.

Kony Studio API Developer's Guide

Version 3.1

JavaScript Example

// Method for checking the resources bundle present or not--> function isResourceBundlePresent()

{ try{ var exists = kony.i18n.isResourceBundlePresent("en_US"); alert("isResourceBundlePresent :"+exists);

} catch(i18nError)

{ alert("Exception While getting isResourceBundlePresent :

"+i18nError );

}

3.20.1.8 kony.i18n.setDefaultLocaleAsync

Every application that has support for internationalization needs a locale to be set as a default locale.

Use Cases

You must set the resource bundle for a given locale to have internationalization support for that locale.

Signature

JavaScript:

kony.i18n.setDefaultLocaleAsync( localename

onsuccesscallback

onfailurecallback , info )

Input Parameters localename [String] - Mandatory

Specifies the locale that must be set as the default locale of the application.

Kony Studio API Developer's Guide

Version 3.1

onsuccesscallback [Function] - Mandatory onsuccess callback is called by the platform after successfully setting the specified locale as default.

onsucess(oldlocalename, newlocalename)

{

\\code

} onfailurecallback [Function] - Mandatory onfailure callback will be called by the platform if the locale is not set successfully.

onfailure (errCode, errMsg)

{

\\code

} info [Object] - Optional

A JavaScript object consisting of key value pairs. If info parameter is specified, it is passed to the callback function as a last parameter. If the info parameter is not specified, the callback function receives the info as null/nil. "Info" is basically a user data where in the application developers will pass it to the async API's and the platform returns this info object to the corresponding async callback.This parameter is helpful for developers to remember the context when the methods are called in asynchronous fashion.Developers can define any custom keys and values within the info

Object based on the needs. These are not predefined keys with values.

Return Values

None

Kony Studio API Developer's Guide

Version 3.1

Exceptions

1300 - i18n error or Locale not supported error

Platform Availability

Available on all platforms.

JavaScript Example function setDefaultLocaleAsync()

{ try

{ kony.i18n.setDefaultLocaleAsync("en_US", onsuccesscallback, onfailurecallback); alert("current locale is set to "+kony.i18n.getCurrentLocale());

} catch(i18nerr)

{ alert("Exception in setDefaultLocaleAsync : "+err );

}

3.20.1.9 kony.i18n.setCurrentLocaleAsync

This API provides you the ability to set the specified locale as the current locale of the application. If the locale is not supported by the device, junk characters are displayed on the screen for the locale specific string.

Use Cases

You must set the resource bundle for a given locale to have internationalization support for that locale.

Kony Studio API Developer's Guide

Version 3.1

Signature

JavaScript: kony.i18n.setCurrentLocaleAsync(

localename

onsuccesscallback

onfailurecallback , info )

Input Parameters localename [String] - Mandatory

Specifies the locale that must be set as the current locale of the application.

onsuccesscallback [Function] - Mandatory onsuccess callback will be called by the platform after a locale is set successfully as the current locale.

onsucess(oldlocalename, newlocalename)

{

\\code

} onfailurecallback [Function] - Mandatory onfailure callback will be called by the platform if the locale is not set successfully.

onfailure (errCode, errMsg)

{

\\code

} info [Object] - Optional

Kony Studio API Developer's Guide

Version 3.1

pass it to the async API's and the platform returns this info object to the corresponding async callback.This parameter is helpful for developers to remember the context when the methods are called in asynchronous fashion.Developers can define any custom keys and values within the info

Object based on the needs. These are not predefined keys with values.

Return Values

None

Exceptions

1300 - i18n error or Locale not supported error

Platform Availability

Available on all platforms.

JavaScript Example function setCurrentLocaleAsync()

{ try

{ kony.i18n.setCurrentLocaleAsync("en_GB", onsuccesscallback, onfailurecallback); alert("current locale is set to "+kony.i18n.getCurrentLocale());

} catch(i18nerr)

{ alert("Exception in setCurrentLocaleAsync : "+err );

}

Kony Studio API Developer's Guide

Version 3.1

3.20.1.10 kony.i18n.setResourceBundle

This API allows you to set the specified resource bundle for a given locale. If the specified locale has a resource bundle already set, it is overridden with the given resource bundle.

If no resource bundle has been set previously, this API will create a new resource bundle.

Use Cases

You must set the resource bundle for a given locale to have internationalization support for that locale.

Signature

JavaScript: kony.i18n.setResourceBundle(

inputtable

locale

)

Input Parameters inputtable [Table] - Mandatory

Specifies the resource bundle that needs to be set for the given locale.

locale [String] - Mandatory

Specifies the locale for which the resource bundle needs to be set.

Return Values

None

Exceptions

1300 - i18n error or Locale not supported error, Locale not supported.

Platform Availability

Available on all platforms.

Kony Studio API Developer's Guide

Version 3.1

JavaScript Example function setResourceBundle()

{ try{ kony.i18n.setResourceBundle

({btn1:"FirstName",btn2:"LastName"}, "en_US") alert(" Set ");

} catch(i18nError)

{ alert("Exception While getting setResourceBundle :

"+i18nError );

}

3.20.1.11 kony.i18n.updateResourceBundle

This API allows you to append new key-value pairs to the given resource bundle for a specified locale.

The key-value pairs you provide will be appended at the end of the resource bundle.

If no resource bundle exists for the specified locale, a new resource bundle is created.

Signature

JavaScript: kony.i18n.updateResourceBundle(

inputtable , locale )

Input Parameters inputtable [Table] - Mandatory

Specifies the set of key-value pairs that needs to be added to the resource bundle.

locale [String] - Mandatory

Specifies the locale for which the resource bundle needs to be updated with the given values.

Kony Studio API Developer's Guide

Version 3.1

Return Values

None

Exceptions

1300 - i18n error or Locale not supported error

Platform Availability

Available on all platforms.

JavaScript Example function updateResourceBundle()

{ try{ kony.i18n.updateResourceBundle({1:"John",2:"Jack",3:"Tom"}, "en_

US") alert(" Updated ");

} catch(i18nError)

{ alert("Exception While getting updateResourceBundle : "+i18nError

);

}

3.21 kony.lang Namespace

In JavaScript, exceptions that occur during runtime are usually handled using try/catch blocks.

Language APIs are implemented for exceptions that are not handled using try/catch blocks.

The kony.lang namespace provides the following API elements.

Functions

Kony Studio API Developer's Guide

Version 3.1

3.21.1 Functions

3.21.1.1 kony.lang.getUncaughtExceptionHandler

The kony.lang.getUncaughtExceptionHandler API retrieves the reference to a JavaScript function that is currently set as an exception handler for all uncaught exceptions.

Signature kony.lang.getUncaughtExceptionHandler()

Return Values

JavaScript value containing the function reference.

Platform Availability

Available in iOS and Android platforms.

JavaScript Example var funtionObject = kony.lang.getUncaughtExceptionHandler();

3.21.1.2 kony.lang.setUncaughtExceptionHandler

The kony.lang.setUncaughtExceptionHandler API sets a JavaScript function as an exception handler for all uncaught exceptions. The JavaScript function takes one argument that is the JavaScript exception object. A developer can query the properties of this object like any other JavaScript object.

Signature kony.lang.setUncaughtExceptionHandler(

JavaScript Function Object)

Arguments

JavaScript Function object [Function] - Mandatory

Call back function that is called when an uncaught exception is raised by JavaScript engine.

Kony Studio API Developer's Guide

Version 3.1

Following is the signature of the function object:

Function <FuncName> ( exceptionObject)

End

Return Values

None

Platform Availability

Available in iOS and Android platforms.

JavaScript Example function uncaughtExceptionHandler(exceptionObject) {

// Converting exception object into a readable string var exceptionString = ""; if("sourceURL" in exceptionObject){ exceptionString += exceptionObject.sourceURL;

} if("line" in exceptionObject){ exceptionString += " line # " + exceptionObject.line;

} if("message" in exceptionObject){ exceptionString += " : " + exceptionObject.message;

}

//Logging the exception string to console kony.print("Unhandled Exception:" + exceptionString);

} kony.lang.setUncaughtExceptionHandler(uncaughtExceptionHandler);

Kony Studio API Developer's Guide

Version 3.1

3.22 kony.localAuthentication Namespace

Touch ID is an authenticating mechanism introduced mainly for local authentication in iOS devices.

Touch ID is a biometric fingerprint reader that takes the place of the traditional Home button on iPhone

The Touch ID feature is specific to the iOS platform and available from iOS 8 onward.

Note: The applications using the kony.localAuthentication APIs must be in the foreground. If an application uses kony.localAuthentication APIs, the application handle errors and respond properly with UI to ensure an alternative method for logging into the application.

Kony Studio API Developer's Guide

Version 3.1

Following are the kony.localAuthentication APIs: l

kony.localAuthentication.authenticate

kony.localAuthentication.getStatusForAuthenticationMode

3.22.1 Functions

The kony.localAuthentication namespace provides the following functions.

kony.localAuthentication.authenticate

The API is used to authenticate the user.

Kony Studio API Developer's Guide

Version 3.1

Syntax kony.localAuthentication.authenticate (

authenticationMode,

statusCallback,

configMap);

Parameters authenticationMode

Specifies the authentication mode for which the status is requested. The data type is constant. For the authentication modes, see

Authentication Modes .

statusCallBack (status, message)

A callback conveys the status of the authentication with appropriate status and message. The default value is "nil." For status code, see the

Status Codes

section.

configMap

Specifies the configuration dictionary for the specified authentication mode. The configMap parameter uses a key listed in the table below.

Key Description promptMessage

Return Values

Remarks

Message to be displayed on the screen.

The authentication mode with the Touch ID (LOCAL_AUTHENTICATION_MODE_TOUCH_ID) requires a message to displayed that prompts a user to provide authentication. The key to be used is

“promptMessage”. Below is a sample configMap: var configMap = {"promptMessage" : "PLEASE AUTHENTICATE USING YOUR TOUCH

ID"};

Kony Studio API Developer's Guide

Version 3.1

Example function statusCB(status,message)

{

If(status == 5000)

{

kony.ui.Alert({message: "AUTHENTICATION SUCCESSFULL", alertType: constants.ALERT_TYPE_INFO, yesLabel:"Close"}, {});

}

else

{

var messg = status+message;

kony.ui.Alert({message: messg, alertType: constants.ALERT_TYPE_INFO, yesLabel:"Close"}, {});

}

} function authUsingTouchID()

{

var config = {"promptMessage" : "PLEASE AUTHENTICATE USING YOUR TOUCH

ID"};

kony.localAuthentication.authenticate(constants.LOCAL_AUTHENTICATION_MODE_

TOUCH_ID,statusCB,config);

}

Platform Availability

Available only on iOS kony.localAuthentication.getStatusForAuthenticationMode

The API returns the status of the authentication mode.

Syntax kony.localAuthentication.getStatusForAuthenticationMode(

authenticationMode)

Parameters authenticationMode

Kony Studio API Developer's Guide

Version 3.1

Specifies the authentication mode for which the status is requested. The data type is constant. For the authentication modes, see

Authentication Modes .

Return Values status

A status code is returned indicating the support for local authentication using Touch ID.

Remarks

Using the API, you can verify whether local authentication is supported on the device.

The API also returns different status codes based on the state of the device. For status codes, see the

Status Codes

section.

Example function isAuthUsingTouchSupported()

{

var status = kony.localAuthentication.getStatusForAuthenticationMode

(constants.LOCAL_AUTHENTICATION_ODE_TOUCH_ID);

if(status == 5000)

{

kony.ui.Alert({message: "AUTHENTICATION BY TOUCHID SUPPORTED", alertType: constants.ALERT_TYPE_INFO, yesLabel:"Close"}, {});

}

else

{

var msg = "TOUCHID AUTHENTICATION RETURNED THE STATUS ::"+status;

kony.ui.Alert({message: status, alertType: constants.ALERT_TYPE_INFO, yesLabel:"Close"}, {});

}

Platform Availability

Available only on iOS

Kony Studio API Developer's Guide

Version 3.1

3.22.1.1 Authentication Modes

The following table provides a list of authentication modes.

Modes constants.LOCAL_AUTHENTICATION_MODE_

TOUCH_ID

Description

For authentication, the Touch ID is used.

3.22.1.2 Status Codes

The following table provides a list of status codes and their descriptions.

Status Codes

5000 No Error

5005

5006

5007

5008

5001

5002

5003

5004

Description

Authentication is not successful because a user fails to provide valid credentials.

Authentication is canceled by a user. For example, a user taps Cancel in the dialog box.

Authentication is canceled because a user taps the fallback button (Enter Password).

Authentication is canceled by system.

Authentication does not start because the passcode is not set on the device.

Authentication does not start because Touch ID is not available on the device.

Authentication does not start because Touch ID has no enrolled fingers.

Authentication does not start because Target device's OS does not support local authentication with Touch ID.

3.23 kony.localnotifications Namespace

The kony.localnotifications namespace provides the following API elements.

Functions

Kony Studio API Developer's Guide

Version 3.1

3.23.1 Functions

The kony.localnotifications namespace contains the following functions.

3.23.1.1 kony.localnotifications.cancel

This API helps you cancel the notification.

Signature

JavaScript: kony.localnotifications.cancel (["notificationId"])

Input Parameters notificationId [array] - Mandatory

Specifies an array of notificationids to cancel the notifications.

Return Values

None

Platform Availability

Available on iOS and Android platforms.

JavaScript Example

//Cancelling the notification notificationIdArray = []; notificationIdArray.push("01"); kony.localnotifications.cancel(notificationIdArray);

3.23.1.2 kony.localnotifications.create

This API helps you create local notification.

Kony Studio API Developer's Guide

Version 3.1

Signature

JavaScript : kony.localnotifications.create (notificationId, datetime, message, title, categoryId, pspConfig)

Input Parameters notificationId [String] - Mandatory

Specifies a unique ID for the notification.

datetime [String] - Mandatory

Specifies the date and time when the notification must be triggered. It accepts unicode date, time, and Timezone pattern.

message [String] - Mandatory

Specifies the message for the notification.

title [String] - Mandatory

Specifies the title for the notification.

categoryId [String] - Mandatory

Specifies the categoryId to associate this local notification or null in case no actions to be displayed.

pspConfig [JSObject] - Optional

Specifies the platform specific options. This is applicable to iOS platform only. Following are the parameters: l badge [Number] - Optional: It displays the number on the app icon.

l sound [String] - Optional: To play a sound, assign a sound file from the app's main bundle. If the sound file is not available or the provided file name is incorrect, it will play a default sound from the system (kony.localnotifications.DEFAULT_

SOUND). To know the supported file formats, click here .

Kony Studio API Developer's Guide

Version 3.1

Return Values

None

Platform Availability

Available on iOS and Android platforms.

JavaScript Example

//Sample code to create notification.

var notificationId = "01"; var date = "27 Mar 2015 15:00:00 +0530"; var format = "dd MMM yyyy HH:mm:ss Z"; var message = "Local notification Received"; var title = "Title"; var categoryId ="calendar"; kony.localnotifications.create({

"id": notificationId,

"dateTime": {

"date": date,

"format": format

"message": message,

"title": title,

"categoryId": categoryId,

"pspConfig":{

"badge":1,

"sound": kony.localnotifications.DEFAULT_SOUND or

"sound.wav"

}

});

Kony Studio API Developer's Guide

Version 3.1

3.23.1.3 kony.localnotifications.setCallbacks

This API helps you associate online and offline callbacks for local notifications. These callbacks are invoked when local notifications are raised by the underlying system. The online notification callback is involved when the application is running. The offline callbacks are invoked when the application is not running. This API should be called on post app init on the application.

Signature

JavaScript:

kony.localnotifications.setCallbacks ( onlinenotification

offlinenotification

)

Input Parameters onlinenotification [Function] - Mandatory

Specifies the callback to be associated with online notification. The arguments are: l actionId [String] - Mandatory: A unique ID to identify the action.

l notificationobject [JSObject] - Mandatory: Specifies the platform-specific notification object.

offlineNotification [Function] - Mandatory

Specifies the callback to be associated with offline notification. The arguments are: l actionId [String] - Mandatory: A unique ID to identify the action.

l notificationobject [JSObject] - Mandatory: Specifies the platform-specific notification object.

Return Values

None

Platform Availability

Available on iOS and Android platforms.

Kony Studio API Developer's Guide

Version 3.1

JavaScript Example

//Register localnotifications setCallbacks in post app init function online_callback(notificationobject, actionid){

//your logic

} function offline_callback(notificationobject, actionid){

//your logic

}

Kony.localnotifications.setCallbacks({onlinenotification:online_ callback, offlinenotification: offline_callback});

3.24 kony.location Namespace

The kony.location namespace defines a high-level interface to location information. It contains the following API elements.

Functions

3.24.1 Functions

The kony.location namespace provides the following functions.

kony.location.clearWatch

This API takes one argument. When invoked, it must first check the value of the given watchID argument. If this value does not correspond to any previously started watch process, then the method must return immediately without performing any further action. Otherwise, the watch process identified by the watchID argument must be immediately stopped and no further callbacks must be invoked.

Kony Studio API Developer's Guide

Version 3.1

Signature

JavaScript: kony.location.clearWatch(

watchID

)

Input Parameters watchID [Number] - Mandatory

Specifies the number that uniquely identifies the watch.

Return Values

None.

Exceptions

LocationError

Error

JavaScript Example kony.location.clearWatch(watchID);

Platform Availability

Available on all platforms except Desktop Web and Windows 7 Kiosk. *Dummy Implementation on

Mobile Web.

3.24.1.1 kony.location.getCurrentPosition

This API takes one, two, or three arguments. When invoked, it must immediately return and then asynchronously attempt to obtain the current location of the device. If the attempt is successful, the successCallback is invoked (i.e. the handleEvent operation must be called on the callback object) with a new Position object, reflecting the current location of the device. If the attempt fails, the errorCallback is invoked with a new PositionError object, reflecting the reason for the failure.

Kony Studio API Developer's Guide

Version 3.1

Signature

JavaScript: kony.location.getCurrentPosition(

successcallback ,

errorcallback , positionoptions

)

Input Parameters successcallback [Function] - Mandatory

Specifies the callback function that must be executed when the API call is successful. The signature of the callback function is successcallback(position) where position contains the coordinates of the geo-location that are created and returned by the API. It is an object that has the following key-value pairs: l coords [Object] - coordinates that has the following key-value pairs: o latitude [Number] - latitude in decimal degrees.

o longitude [Number] - longitude in decimal degrees.

o altitude [Number] - height of the location in meters above the ellipsoid.

o accuracy [Number] - Accuracy level of the latitude and longitude coordinates in meters.

o altitudeaccuracy [Number] - Accuracy level of the altitude coordinate in meters.

o heading [Number] - Direction of travel, specified in degrees counting clockwise relative to the true north.

o speeding [Number] - Current ground speed of the device, specified in meters per second.

o timestamp [Number] - represents the time when the Position object was acquired.

Kony Studio API Developer's Guide

Version 3.1

errorcallback [Function] - Optional

Specifies the callback function that must be executed when the API call fails. The callback function has the following signature: errorcallback(positionerror)- positionerror is an object that has the following key-value pairs: l code [Number] - the error code.

l message [String] - the error message. The following are the pre-defined messages: o

PERMISSION_DENIED o

POSITION_UNAVAILABLE o

TIMEOUT positionoptions [Object] - Optional

Using this parameter, the user can customize the retrieval of the geolocation. It is an object that has the following key-value pairs: enableHighAccuracy [Boolean] - provides a hint to the implementation in order to receive the best possible result.

timeout [Number] - denotes the maximum length of time in milliseconds that is allowed to pass from the call.

maximumAge [Number] - indicates the application to accept a cached position whose age is no greater than the specified time in milliseconds.

Return Values:

None.

Kony Studio API Developer's Guide

Version 3.1

Exceptions

LocationError

Error

JavaScript Example function successcallback(position)

{ var geoPosition = "Latitude: " + position.coords.latitude; geoPosition = geoPosition + " Longitude: " + position.coords.longitude; geoPosition = geoPosition + " Altitude: " + position.coords.altitude; geoPosition = geoPosition + " Accuracy: " + position.coords.accuracy; geoPosition = geoPosition + " Altitude Accuracy: "

+ position.coords.altitudeAccuracy; geoPosition = geoPosition + " Heading: " + position.coords.heading; geoPosition = geoPosition + " Speeding: " + position.coords.speeding; geoPosition = geoPosition + " Timestamp: " + position.timestamp; alert(geoPosition);

} function errorcallback(positionerror)

{ var errorMesg = "Error code: " + positionerror.code; errorMesg = errorMesg + " message: " + positionerror.message

alert(errorMesg);

} var positionoptions = {timeout: 15000}; // 15 secs kony.location.getCurrentPosition(successcallback, errorcallback, positionoptions );

Kony Studio API Developer's Guide

Version 3.1

Platform Availability

Available on all platforms except Windows 7 Kiosk and prior to IE8 releases.

3.24.1.2 kony.location.watchPosition

This API takes one, two, or three arguments. When invoked, it must immediately return a number that uniquely identifies a watch operation and then asynchronously start the watch operation. This operation first attempts to obtain the current location of the device. If the attempt is successful, the succesCallback is invoked (i.e. the handleEvent operation must be called on the callback object) with a new Position object, reflecting the current location of the device. If the attempt fails, the errorCallback is invoked with a new PositionError object, reflecting the reason for the failure.

The watch operation continues to monitor the position of the device and invokes the appropriate callback every time this position changes. The watch operation continues until the clearwatch method is called with the corresponding identifier.

Signature

JavaScript: kony.location.watchPosition(

successcallback ,

errorcallback , positionoptions

)

Input Parameters successcallback [Function] - Mandatory

Specifies the callback function that must be executed when the API call is successful. The signature of the callback function is successcallback(position) where position contains the coordinates of the geolocation that are created and returned by the API. It is an object that has the following key-value pairs: l coords [Object] - coordinates that has the following key-value pairs: o latitude [Number] - latitude in decimal degrees.

o longitude [Number] - longitude in decimal degrees.

o altitude [Number] - height of the location in meters above the ellipsoid.

Kony Studio API Developer's Guide

Version 3.1

o accuracy [Number] - Accuracy level of the latitude and longitude coordinates in meters.

o altitudeaccuracy [Number] - Accuracy level of the altitude coordinate in meters.

o heading [Number] - Direction of travel, specified in degrees counting clockwise relative to the true north.

o speeding [Number] - Current ground speed of the device, specified in meters per second.

o timestamp [Number] - represents the time when the Position object was acquired.

l timestamp [Number] - represents the time when the Position object was acquired.

errorcallback [Function] - Optional

Specifies the callback function that must be executed when the API call fails. The callback function has the following signature: errorcallback(positionerror): Positionerror is an Object that has the following key-value pairs: l code [Number] - the error code. //TBD.

l message [String] - the error message. The following are pre-defined messages: o

PERMISSION_DENIED o

POSITION_UNAVAILABLE o

TIMEOUT positionoptions [Object] - Optional

Using this parameter, the user can customize the retrieval of the geolocation. It is an Object that has the following key-value pairs: l enableHighAccuracy [Boolean] - provides a hint to the implementation in order to

Kony Studio API Developer's Guide

Version 3.1

receive the best possible result.

l timeout [Number] - denotes the maximum length of time in milliseconds that is allowed to pass from the call.

l maximumAge [Number] - indicates the application to accept a cached position whose age is no greater than the specified time in milliseconds.

Return Values watchID [Number]

Returns a number that denotes the unique ID of the watch operation.

Exceptions:

LocationError

Error

JavaScript Example function successcallback1(position)

{ lblTest.text = "working with watchPosition success full call back"; var geoPosition = "Latitude: " + position.coords.latitude; geoPosition = geoPosition + " Longitude: " + position.coords.longitude; geoPosition = geoPosition + " Altitude: " + position.coords.altitude; geoPosition = geoPosition + " Accuracy: " + position.coords.accuracy; geoPosition = geoPosition + " Altitude Accuracy: " + position.coords.altitudeAccuracy; geoPosition = geoPosition + " Heading: " + position.coords.heading; geoPosition = geoPosition + " Speed: " + position.coords.speed; geoPosition = geoPosition + " Timestamp: " + position.timestamp;

Kony Studio API Developer's Guide

Version 3.1

alert(geoPosition);

} function errorcallback1(positionerror)

{ lblTest.text = "working with watchPosition err call back"; var errorMesg = "Error code: " + positionerror.code; errorMesg = errorMesg + " message: " + positionerror.message

alert(errorMesg);

} var positionoptions = {maximumAge: 3000}; watchID = kony.location.watchPosition (successcallback1, errorcallback1, positionoptions)

Platform Availability

Available on all platforms except Desktop Web, Windows 7 Kiosk, IE8 and prior to IE8 releases.

*Dummy Implementation on Mobile Web.

3.25 kony.map Namespace

The kony.map namespace provides support functions for use with the Map widget. This section contains reference information about the kony.map namespace in the following topics.

Constants

Functions

3.25.1 kony.map Namespace Constants

The kony.map namespace defines the following constants.

Map Provider Constants

Kony Studio API Developer's Guide

Version 3.1

The Map Provider Constants enable your app to select which map provider to use.

Constant kony.map.MAP_PROVIDER_BING

kony.map.MAP_PROVIDER_GOOGLE

Description

Select Bing as the map provider.

Select Google as the map provider.

Map View Mode Constants

Use the Map View Mode Constants to configure which map view your app selects.

Constant kony.map.MAP_VIEW_MODE_NORMAL

kony.map.MAP_VIEW_MODE_SATELLITE

kony.map.MAP_VIEW_MODE_STREET

kony.map.MAP_VIEW_MODE_TRAFFIC

Description

View the map in whatever mode is the default for the map provider.

View the map as a satellite image.

View the map as a street map.

View traffic information on the map.

Map Widget Error Codes

The following table lists the error codes that the Map widget generates.

Constant kony.map.ROUTE_SEARCH_INVALID_REQUEST

Description

The format of the route search request was invalid.

Kony Studio API Developer's Guide

Version 3.1

Constant kony.map.ROUTE_SEARCH_LIMIT_EXCEEDED

kony.map.ROUTE_SEARCH_NETWORK_FAILURE

kony.map.ROUTE_SEARCH_PLACE_NOT_FOUND

Description

The service has received too many requests from your application within the allowed time period. For Android, below are the usage limits imposed by

Google Map Service.

Up to 8 waypoints for

Google Map free API and

23 waypoints for Google

Map for Work in each request l

2500 & 100000 direction requests per 24 hour period for free API and work api respectively.

2 and 10 requests per second for free API and work API respectively.

The request failed due to network failure.

At least one of the locations specified in the request's source, destination, or waypoints could not be found.

An unknown error occurred.

kony.map.ROUTE_SEARCH_UNKNOWN_ERROR

Pin Image Anchor Constants

Kony Studio API Developer's Guide

Version 3.1

The Pin Image Anchor Constants define the positions that your app can anchor a pin image to on a map. The image positions are illustrated in the image below.

Constant kony.map.PIN_IMG_ANCHOR_BOTTOM_CENTER

kony.map.PIN_IMG_ANCHOR_BOTTOM_LEFT

kony.map.PIN_IMG_ANCHOR_BOTTOM_RIGHT

kony.map.PIN_IMG_ANCHOR_CENTER

kony.map.PIN_IMG_ANCHOR_MIDDLE_LEFT

kony.map.PIN_IMG_ANCHOR_MIDDLE_RIGHT

Description

Anchors the pin image at the bottom center position.

Anchors the pin image by its lower left corner.

Anchors the pin image by its lower right corner.

Anchors the pin image at the center position.

Anchors the pin image at the middle left position of the image.

Anchors the pin image at the middle right position of the image.

Kony Studio API Developer's Guide

Version 3.1

Constant kony.map.PIN_IMG_ANCHOR_TOP_CENTER

kony.map.PIN_IMG_ANCHOR_TOP_LEFT

kony.map.PIN_IMG_ANCHOR_TOP_RIGHT

Description

Anchors the pin image at the top center position.

Anchors the pin image by its upper left corner.

Anchors the pin image by its upper right corner.

Pin Image Type Constants

These constants define the types of images that can be used with maps.

Constant kony.map.PIN_IMG_SRC_TYPE_BASE64

kony.map.PIN_IMG_SRC_TYPE_FILE_PATH

kony.map.PIN_IMG_SRC_TYPE_IMAGE

kony.map.PIN_IMG_SRC_TYPE_RAWBYTES

kony.map.PIN_IMG_SRC_TYPE_RESOURCES

Description

Indicates that the pin image should be created out of given a base64 string.

Indicates that the pin image is available in internal file system.

The specified value can be either an absolute path or a File object.

Indicates that the pin image is of type Image object

Indicates that the pin image needs to be created from a

RawBytes object.

Indicates that the pin image is available in bundled resources.

Kony Studio API Developer's Guide

Version 3.1

Shape Type Constants

The following constants identify the shapes that can be drawn on maps.

Constant kony.map.SHAPE_TYPE_POLYGON

kony.map.SHAPE_TYPE_POLYLINE

kony.map.SHAPE_TYPE_CIRCLE

Description

The shape is a polygon.

The shape is a polyline.

The shape is a circle.

3.25.2 kony.map Namespace Functions

The kony.map namespaces contains the following functions.

kony.map.containsLocation

This function tests to see whether a specified location is within a circle or polygon on a map or whether it lies along a polyline on a map.

Syntax boolean kony.map.containsLocation(

shapeType,

location,

shapeData);

Parameters shapeType

Contains a

Shape Type Constant

that defines which kind of shape the location is being tested against.

location

Holds a location object which contains lat and lon values.

Kony Studio API Developer's Guide

Version 3.1

shapeData

A key-value pair object that defines the shape using the following keys: l radius [Number]: Radius that is needed to define circle shape. This key is only valid of shapeType is Circle and ignored for other shapes.

l tolerance [Number] [Android]: Specify tolerance in meters when user is interacting with Polyline or Polygon. Not applicable for other shapes.

Return Values

True if the location is within the circle or polygon, or if it lies along the polyline. Otherwise, false.

Examples

Example 1: Polyline var shapeData = { locations : [{lat:“17.451759”, lon:“78.380806”},{lat: “17.473305”, lon:”78.425191”}]; tolerance : 200;

}; var location = {lat: “17.427789”, lon:”78.451751”}; kony.map.containsLocation(kony.map.SHAPE_TYPE_POLYLINE,location, shapeData);

Example 2: Circle var shapeData = { locations : [{lat:“17.451759”, lon:“78.380806”}]; radius : 1000;

}; kony.map.containsLocation(kony.map.SHAPE_TYPE_CIRCLE,location, shapeData);

Platform Availability

Available on Android and iOS.

Kony Studio API Developer's Guide

Version 3.1

kony.map.distanceBetween

This function finds the linear distance between two locations on a map.

Syntax boolean kony.map.distanceBetween(

location1,

location2);

Parameters location1

Contains the first location to use.

location2

Contains the second location to use.

Return Values

A number that specifies the distance between the two input locations.

Examples location1 = {lat:“17.451759”, lon:“78.380806”}; location2 = {lat: “17.427789”, lon:”78.451751”}; var distanceInMeters = kony.map.distanceBetween(location1, location2);

Platform Availability

Available on Android and iOS.

kony.map.decode

Kony Studio API Developer's Guide

Version 3.1

This function enables apps to to decode the encoded polyline points which are provided in search route results.

In Android, each step in the search results contains a key.

Syntax boolean kony.map.decode(

encodedPolylinePoints);

Parameters encodedPolylinePoints

Hold a string containing the encoded polyline points.

Return Values

An array containing only the lat/lon values.

Platform Availability

Available on Android only.

kony.map.searchRoutes

This function searches for routes between the start and destination locations.

Syntax kony.map.searchRoutes(

searchCriteria

successCallback,

errorCallback)

Parameters searchCriteria

A JSObject with set of search request configuration parameters that defines the search criteria for routes request.

Kony Studio API Developer's Guide

Version 3.1

successCallback

A callback function that receives the search results when search request succeeds. The callback function must have the following syntax.

function successCallback( routes );

The callback function's routes parameter is an array with one or more routes indicating possible directions between source and destination.

errorCallback

An optional callback function that gets called when search request fails. The callback function must have the following syntax.

function errorCallback( errorCode[Number], errorMessage[String]

)

The errorCode parameter indicates the category of error. This carries the one of the Map Error

Codes defined in the kony.map namespace. The errorMessage parameter contains a detailed error message describes the reason for failure. These error messages are platform specific.

Return Values

None.

Remarks

Applications which use the apiKey in search criteria must enable the “Directions API” in Google Developer

Console. Google API’s usage quota is counted against the apiKey. For activating and deactivating Google

API’s, please follow the below link for detailed procedure.

Platform Availability

Available on Android and iOS.

3.26 kony.modules Namespace

The kony.modules namespace enables your apps to load functional modules through synchronous and asynchronous operations on demand. It provides the following API elements.

Kony Studio API Developer's Guide

Version 3.1

Functions

3.26.1 Functions

The kony.module namespace contains the following functions.

3.26.1.1 loadFunctionalModule loadFunctionalModule is a synchronous API used to load functional module (views and jsModules) in scope of JavaScript. Until loading of module is complete, further executions will be stopped.

Signature

JavaScript: kony.modules.loadFunctionalModule (

modulename )

Parameters modulename [String] - Mandatory

Unique module name that is defined in the

functionalModules.xml

file.

Note:

If the module is already loaded, then it returns true without reloading the same module.

Return Values

Boolean true: When module is loaded.

false: When any issue found while loading.

Platform Availability

Available on iOS, Android, Windows, SPA and Desktop Web

Kony Studio API Developer's Guide

Version 3.1

JavaScript Example

//In module1 you can load module2 as below when required.

function buttonClick() { kony.modules.loadFunctionalModule("module2");

//Now we cn access objects defined in module2 frmLogin.show();

}

3.26.1.2 loadFunctionalModuleAsync

The loadFunctionalModuleAsync is an asynchronous API used to load functional module (views and jsModules) in scope of JavaScript. A success callback is invoked after successful completions of load, else error callback will be invoked.

Note:

If the module is already loaded, then it will call successcallback without loading the same module.

Signature

JavaScript: kony.modules.loadFunctionalModuleAsync (

modulename

successcallback

errorcallback )

Parameters modulename [String] - Mandatory

Unique name of the module that is defined in the

functionalModules.xml

file.

successcallback [Function] - Mandatory

The callback will be invoked after successful load of module files and after calling corresponding init function, if defined.

l successcallback (modulename)

Kony Studio API Developer's Guide

Version 3.1

errorcallback [Function] - Mandatory

The callback which will be invoked if there are any issue while loading module files.

l errorcallback (modulename, errorcode)

Error Codes

1250 – Invalid module name is specified.

1251 – Unable to load module.

Platform Availability

Available on iOS, Android, Windows, SPA and Desktop Web.

JavaScript Example

//In module1 you can load module2 as below when required.

var successcalback = function (modulename) {

//Now we cn access objects defined in module2 frmLogin.show();

} var errorcalback = function (modulename, errorcode) { kony.print("error : " + errorcode + " in module - " + modulename);

} function buttonClick() { kony.modules.loadFunctionalModuleAsync("module2", successcalback, errorcalback);

}

3.27 kony.net Namespace

The kony.net namespace, part of the Network API, contains the following functions API elements

Kony Studio API Developer's Guide

Version 3.1

Functions

3.27.1 Functions

The kony.net namespace contains the following functions.

3.27.1.1 kony.net.cancel

This API cancels only async network calls. Synchronous calls have a platform-specific cancellation mechanism provided by the platform (mechanism may vary from platform to platform).

Signature

JavaScript: kony.net.cancel(

connHandle )

Invalid parameters to this API will be ignored.

Input Parameters connHandle - Mandatory

The handle to the asynchronous service.

connHandle is returned by invokeserviceasync.

Return Values

None.

Exceptions

1200 - Network Error.

Kony Studio API Developer's Guide

Version 3.1

Platform Availability

Available on all platforms except Server-Side Mobile Web, Windows 8, and Windows Phone 8 channels.

JavaScript Example function cancelService()

{ kony.net.cancel(connHandle);

}

3.27.1.2 kony.net.clearCookies

In an application where service calls are made through Browser Widget or through native service calls, cookies are sent from the servers to maintain the session. These cookies are stored in the cookie store on the client side. Using this API you can remove the cookies of a particular domain obtained through all of HttpRequest, invokeServiceAsync and browser widget.

If you specify the optional parameters url and cookieName, then all the cookies with the specified name related to that URL are removed from your application. The parameter url should be the complete URL. For example, http://www.gooogle.com

. If the URL is not valid, then this API will not remove the cookies. An exception is shown of type KonyError with the error code as 1005 and error name/message as "invalid input url".

If the scheme of the URL is "https" then all the cookies of https as well as http will be removed. If the scheme of the URL is "http" then only the cookies stored for http will be removed. If the cookies are not present in the application cookie store in the provided array of cookieNames, then this API will not perform any action and does not raise an exception.

Signature kony.net.clearCookies(url, cookieName [] )

Kony Studio API Developer's Guide

Version 3.1

Input Parameters url [String] - Optional

A valid URL of a domain from where the cookies were obtained.

cookieName [Array] - Optional

Specifies the cookie names that are to be removed from the current application.

Return Values

None

Platform Availability

Available on iOS, Android, Windows, and SPA platforms.

JavaScript Example kony.net.clearCookies("http://www.google.com");

Limitations on SPA Platform l

You can remove the cookies related to a currently loaded domain in a web page.

Cookies with the

httpOnly

flag cannot be removed. The secured cookies (https) cannot be removed when application is accessed with non-secured protocol.

3.27.1.3 kony.net.FormData

The FormData object represents an ordered collection of entries with name-value pairs. Call this function to create a FormData object.

Signature kony.net.FormData()

Kony Studio API Developer's Guide

Version 3.1

Input Parameters

None.

Return Values

Returns an object of type FormData.

Platform Availability

Android, iOS, Windows, and SPA

JavaScript Example var httpinputparams1 = new kony.net.FormData()

3.27.1.4 kony.net.getActiveNetworkType

This API returns the currently active network type. If the device is offline, it will return null. Otherwise, it will return the appropriate connection type.

For SPA , Mobile Web, and Desktop Web, it will always return constants.NETWORK_TYPE_ANY.

SPA and Desktop Web depend upon the navigator.onLine property to detect if the device is offline or online. The implementation of this property across browsers is uneven. For more information, refer to

Mozilla documentation for browser support .

Signature

JavaScript

: kony.net.getActiveNetworkType()

Input Parameters

None

Return Values

Returns one of the following constants:

Kony Studio API Developer's Guide

Version 3.1

l constants.NETWORK_TYPE_3G - when 3G network is used.

l constants.NETWORK_TYPE_WIFI - when Wi-Fi is used.

l constants.NETWORK_TYPE_ANY - only when SPA , Mobile Web, and Desktop Web applications are used.

Platform Availability

Available on all platforms except BlackBerry 10.

JavaScript Example function checkActiveNetwork()

{ return kony.net.getActiveNetworkType() ;

}

3.27.1.5 kony.net.getCookies

In an application where service calls are made through Browser Widget or through native service calls, cookies are sent from the servers to maintain the session. These cookies are stored in cookie store on the client side. The kony.net.getCookies API enables access to the cookies for a particular domain.

The URL is given as an input parameter to kony.net.getCookies API, then all cookies related to that domain are returned.

In the current application context, you can also access cookies for a particular domain stored in cookie store on the client side or device.

Kony.net.getCookies() API returns all the cookies stored in local cookie store on the client side or device for that particular domain. The returned cookies can vary based on the domain (partial or full domain) and as well as the path.

Signature kony.net.getCookies(URL)

Kony Studio API Developer's Guide

Version 3.1

Input Parameters

The URL is passed as input and must be a fully formed, valid URL like

http://www.google.com

If the URL is invalid or not formed properly,

Null

is returned.

Return Values

The return values are an array of cookie. Each cookie follows the format

key=value

string.

Each cookie string can also contain additional information following the Standard HTTP Cookie

Format, such as Domain, Path, Expires, Secure, and HttpOnly.

Null

is returned if no cookies are present for the domain.

If the scheme of the URL is

https

, then all the cookies of

https

as well as

http

are returned.

If the scheme of the URL is

http

, then only the cookies stored for

http

are returned.

For example:

SSID=Ap4P….GTEq; Domain=foo.com; Path=/; Expires=Wed, 13 Jan 2021

22:23:01 GMT; Secure; HttpOnly

Platform Availability

Android, iOS, Windows, and SPA

JavaScript Example var cookies = kony.net.getCookies("http://www.google.com"); for (index = 0; index < cookies.length; index++) { cookie = cookies[index]; kony.print("Cookie is: " + cookie);

}

Kony Studio API Developer's Guide

Version 3.1

Limitations l

In Windows, the cookies stored in the Browser Widget cookie store are returned. Cookies stored through native service calls are not returned.

In SPA, the cookies related to a currently loaded domain in a web page are accessible.

In SPA, cookies with the

httpOnly

flag cannot be accessed.

3.27.1.6 kony.net.HttpRequest

The HttpRequest object supports an HTTP or HTTPS request to any resource on the network and fetches the response.

Note: The HttpRequest API is only supported in JavaScript.

Creating HttpRequest object instance: var httpclient1 = new kony.net.HttpRequest()

Input Parameters

None

Return Values

None

Properties

The following are the properties of the HttpRequest object - for example, httpclient1.timeout.

Name Readable/Writable Description

timeout [number] Read / Write status [number] statusText [string]

Read only

Kony Studio API Developer's Guide

Version 3.1

The time in milliseconds a request can take before being terminated. By default, the value is zero, which means there is no timeout set. This timeout represents the connection timeout and the response timeout from the server.

Returns the HTTP status code. Returns 0 if the status of the request is not sent - that is send() API is still not invoked on this object

(or) in case of an exception.

Returns the HTTP reason phrase of the status line. Returns an empty string, if the status of the request is not sent that is send

() API is still not invoked on this object (or) in case of an exception. The reason-phrase for a given status code based on the http specification (RFC 2616). However, these phrases are only recommendations and may vary with other equivalent phrases by individual platform implementations.

responseType [string] Read only

Kony Studio API Developer's Guide

Version 3.1

Returns or sets the response type. By default, it is empty string. The possible values are: constants.HTTP_RESPONSE_

TYPE_TEXT constants.HTTP_RESPONSE_TYPE_

JSON constants.HTTP_RESPONSE_TYPE_

DOCUMENT constants.HTTP_RESPONSE_TYPE_

RAWDATA.

Note:

The RAWDATA type is not supported by SPA .

response[string] Read only

Kony Studio API Developer's Guide

Version 3.1

Returns the response body. The type of the value depends on the value of the responseType. In case of an exception, it returns empty string.

If responseType is constants.HTTP_

RESPONSE_TYPE_TEXT, then the response value is a response string.

If responseType is constants.HTTP_

RESPONSE_TYPE_JSON, then the response value is a result of Json.parse() on the response content.

If responseType is constants.HTTP_

RESPONSE_TYPE_DOCUMENT, then the response value is an XML string.

If responseType is constants.HTTP_

RESPONSE_TYPE_RAWDATA, then the response value is a platform-specific handle representing the raw data of binary content of type kony.types.RawBytes.

Note: For JSON type, if JSON parse fails, null is returned. For DOCUMENT type, native platforms do not perform any validations on the response.

readyState[integer] Read only

Kony Studio API Developer's Guide

Version 3.1

Return the current status of the http request object. The possible values are: l constants.HTTP_READY_STATE_

UNSENT = 0 (The state when the object has been constructed) l constants.HTTP_READY_STATE_

OPENED = 1 (The state when the open method has been successfully invoked) l constants.HTTP_READY_STATE_

HEADERS_RECEIVED = 2 (The state when all redirects have been followed and all HTTP headers of the final response have been received) l constants.HTTP_READY_STATE_

LOADING = 3 (The state when the response data is been received) l constants.HTTP_READY_STATE_

DONE = 4 (The state when the data transfer has been completed or something went wrong during transfer)

onReadyStateChange

[function]

Write only

Kony Studio API Developer's Guide

Version 3.1

The property to register an event callback that is invoked when there is a change in the state of the "readyState" property. Refer readyState description for different states.

Note: In BlackBerry10 platform, the application crashes when an event is invoked dynamically by assigning a

JSObject.

var request = new kony.new.HttpRequest(); request.onReadyStateChange = callbackfunction; //This will not work.

//Alternatively, you can use the below code to set the callback.

var request = new kony.new.HttpRequest(); request.setOnReadyStateChang

e (callbackfunction); //This will work.

//Where callbackfunction is the name of the callback.

Platform Availability

The HttpRequest API is supported in all platforms except Mobile Web and SPA.

Kony Studio API Developer's Guide

Version 3.1

3.27.1.7 kony.net.invokeServiceAsync

This API allows you to invoke a service asynchronously with the specified parameters.

Note: These APIs are generated by Kony Visualizer for the code generated using mapping editor.

Even though these APIs have been retained as is they have not been published as standard APIs provided by the Kony runtime libraries. These APIs will not be available to a developer not using

Kony Visualizer in future for development.

function asyncCallback(status, news)

{

// populate UI

}; var news_inputparam = {}; news_inputparam["serviceID"] = "news"; news_inputparam["httpheaders"] = {}; news_inputparam["httpconfig"] = {timeout:5}; news = appmiddlewareinvokerasync(news_inputparam, asyncCallback);

Signature

JavaScript: kony.net.invokeServiceAsync (

url

inputParamTable ,

callback,info )

Input Parameters url [String] - Mandatory

The URL containing the remote location from where the content is to be retrieved.

inputParamTable [Object] - Mandatory

The inputParamTable is the list of parameters that need to be passed to the remote service. The inputParamTable contains the following key-value pairs: l appID - Unique ID of the application.

Kony Studio API Developer's Guide

Version 3.1

l serviceID - Unique ID of the service.

l channel - Indicates the mobile application channel for which the request is been raised.

Valid values are "rc" for native clients and "wap" for Mobile Web and SPA clients.

Important: l

The above fields appID, serviceID, and channel are mandatory only when middleware is used.

If you use a third-party URL for invokeServiceAsync API, the URL should return only JSON value.

l httpheaders [Object] - The httpheaders is an optional key in the parameter table . Use this key when you want to pass custom headers to the remote service.

For example: httpheaders={authkey:"myauthkey", authtoken:"myauthtoken"}

Certain headers like useragent are overridden by the underlying SDK and cannot be set using the httpheaders key.

If the remote service requires basic authentication, you can set the header as follows:

Authorization:"Basic" <base64encoding of the username:password>". For example, httpheaders={Authorization:

"Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="}

Note: l

Make sure there is a space between Basic and the actual base64 encoded string.

Kony Studio API Developer's Guide

Version 3.1

In SPA and Desktop Web, if you use third-party URLs, then apply xmlHTTPRequest APIs and enable Cross-Origin Resource Sharing (CORS) headers on the target servers (that is, the server to which the service request is made).

If you make a third-party URL call without CORS headers, it results in security exception saying that browser has prevented cross origin request.

The following is an example on how to use this parameter: local myhttpheaders={authkey:

"myauthkey",authtoken:"myauthtoken"} local inputParamTable={appID:"SampleApp", serviceID:"accountLogin",channel:"rc", httpheaders:myhttpheaders}; l httpconfig

[Object] - The httpconfig is an optional key in the parameter table . Use this key when to pass custom configurations to set the timeout in seconds for network calls.

For example: httpconfig={timeout:5}

Important: On SPA and Desktop Web, if you are using third-party URLs, use the

HTTP request method.

To configure the HTTP request method, use "method." The possible values are: o

Get o

Post (default value)

Note: An invalid value to method leads to undefined behavior.

For example:

Kony Studio API Developer's Guide

Version 3.1

httpconfig = { timeout: 5, method: "get"} callback [Function] - Mandatory

The callback function that is called to handle the return values of the asynchronous network call (in case of success) and error messages (in case of failure). The following is the signature: callback(

status

resulttable

) l status - an integer value - indicating the status o

100 - network call initiated successfully. The resultset is not available, and it is nil.

200 - network is in progress (when you start receiving the first byte). The resultset is not available, and it is nil.

300 - network call canceled. The resultset is not available and it is nil.

400 - network call is finished (called in success and failure scenarios). Actual state can be queried using opstatus in the resultset.

Note: On Mobile Web, the callback function is always invoked with a status of 400. Other intermediate status codes are not applicable on

Mobile Web.

l resulttable - an object with key-value pairs. Follows the same structure (opstatus, errcode, and errmsg along with the actual network returned data).

The resulttable represents the object returned by the service. This object contains three values: opstatus errcode errmsg

Kony Studio API Developer's Guide

Version 3.1

If the opstatus is 0, the service call is a success while a non-zero value indicates a failure.

If the opstatus is a non-zero value, an errcode is generated. The following are the error codes: l

1000- Unknown error while connecting (if the platform cannot differentiate between network errors, the platform reports error code 1000 by default).

1011 - Device has no Wi-Fi or mobile connectivity. Try the operation after establishing connectivity.

1012 - Request failed.

1013 - Middleware returned invalid JSON string.

1014 - Request timed out.

1015 - Cannot find host.

1016 - Cannot connect to host.

1200 - SSL - Certificate related error codes.

The error message corresponding to each error code is captured in the errmsg parameter.

Important:

The following information is applicable only for iOS and Android platforms.

The resulttable also contains the httpresponse key. The httpresponse contains a value as a table containing responsecode, url, headers, and cookies keys.

httpresponse:{"headers":{"xxxx":"Basic realm=\"Authentication required\"","Content-Language":"en","Content-

Type":"text/html;charset=utf-8","Date":"Tue, 29 Jul 2014

10:17:04 GMT","Server":"Apache-Coyote/1.1","Content-

Length":"951"},"responsecode":401,"url":"http://x.x.x.x"}.

Kony Studio API Developer's Guide

Version 3.1

info [Object] - Optional

A JavaScript object consisting of key value pairs. If the info parameter is specified, it is passed to the callback function as a last parameter. If the info parameter is not specified, the callback function receives the info as null. The info object represents user data where in the application developers will pass it to the async API's, and the platform returns this info object to the corresponding async callback.This parameter helps developers remember the context when the methods are called in asynchronous fashion.Developers can define any custom keys and values within the info object based on the needs. Custom keys are not predefined keys with values.

Return Values connHandle

The connHandle represents the handle to the underlying URL connection. The connHandle helps cancel the network call using the cancel API.

null

If the input parameters are invalid.

Implementation Details

To ensure security, all JavaScript functions within an application are executed in a single thread. There is no separate thread for the asynchronous service callback functions. The callback function for the service call executes serially in the thread, only after the execution of other JavaScript functions

(queued up earlier).

Any subsequent user actions are queued if they occur during the execution of the callback function.

Therefore, parallel execution of multiple asynchronous calls (even the operation of waiting for the response) cannot be guaranteed.

API Usage

Based on the application requirement and logic, a developer should decide whether to invoke a service synchronously or asynchronously.

Kony Studio API Developer's Guide

Version 3.1

UI Behavior

There is no noticeable difference in the user interface because the user can perform other actions while the asynchronous network call is in progress.

Rules and Restrictions

Do not use other service calls or functions that use/update the same data structure that is applied by the asynchronous network call. If you invoke more than one asynchronous service call that accesses the same data structure, the behavior of the application is unpredictable. You should handle such validations or error handling mechanisms in the callback function that is executed when an asynchronous service call is made.

Note:

HTTP response splitting attack, cross-site scripting, browser hijacking, cookie manipulation, and crossuser defacement.

Exceptions

1200 - Network Error.

Platform Availability

Available on all platforms.

JavaScript Example function callbackfunction(status, resulttable)

{ if(status == 400)

{ if(resulttable["opstatus"] == 0)

{ alert("opstatus is zero");

Kony Studio API Developer's Guide

Version 3.1

}

} function startup()

{ try

{ var myhttpheaders={authkey:"myauthkey", authtoken:"myauthtoken"}; var inputParamTable=

{ appID:"SampleApp", serviceID:"accountLogin", channel:"rc", httpheaders:myhttpheaders

}; var connHandle = kony.net.invokeServiceAsync(

"http://www.test.kony.com", inputParamTable, callbackfunction);

} catch(err)

{ alert("Error"+err);

}

3.27.1.8 kony.net.isNetworkAvailable

This API enables you to check whether a network is available for data transport on a device.

Kony Studio API Developer's Guide

Version 3.1

Signature

JavaScript : kony.net.isNetworkAvailable (

networkType )

Input Parameters networkType [Integer Constant] - Mandatory

Specifies the network type on the device for data transport. You can specify any of the following as a value: l constants.NETWORK_TYPE_3G - Indicates if the device has sufficient network coverage to send data using the 3G channel. Available on Android, iOS, BlackBerry, and Windows (other platform will always return false when queried using kony.net.isNetworkAvailable

(constants.NETWORK_TYPE_3G).

Note: Some platforms such as Android do not differentiate between 3G and 2G connectivity. In this case, even if the device is on a 2G connection, the API would still indicate that the device is on 3G connectivity.

l constants.NETWORK_TYPE_WIFI - Indicates if the device has sufficient network coverage to send data using the Wi-Fi channel. Available on Android, iOS, BlackBerry, and Windows (other platforms will always return false when queried using kony.net.isNetworkAvailable

(constants.NETWORK_TYPE_WIFI).

l constants.NETWORK_TYPE_ANY - Indicates if the device has sufficient network coverage to send data over any supported data channels. Available on Android, iOS, BlackBerry, Windows,

HTML5 SPA, Mobile Web, and Desktop Web.

Return Values true

Indicates that the specified data network is available.

false

Indicates that the specified data network is unavailable.

Kony Studio API Developer's Guide

Version 3.1

Platform Availability

Available on all platforms except BlackBerry 10. Also, except BlackBerry 6.0.0.141, all other

BlackBerry 6.0 versions give null pointer exception when an incorrect parameter is provided.

JavaScript Example function checkIfNetworkIsAvailable()

{ return kony.net.isNetworkAvailable(constants.NETWORK_TYPE_ANY);

}

3.27.1.9 kony.net.setNetworkCallbacks

This API allows the developer to register for network status changes. You can then change the user experience according to the network availability.

Important: In BlackBerry,this API works as expected. But, when a user goes from offline to online and selects the mobile network and Wi-Fi network options, the API is executed two times. If the user selects mobile network or Wi-Fi, then the API executes only once.

Signature

JavaScript : kony.net.setNetworkCallbacks(

callbackconfig

)

Input Parameters callbackconfig [JSON Object] - Mandatory

A JSON object that comprises a property statusChange.

l statusChange [Function] - Mandatory: Invoked by Kony Platform when the device goes offline or is online. This callback receives an input parameter that indicates if the device was online or offline when this callback was invoked.

Kony Studio API Developer's Guide

Version 3.1

var config = {}; config.statusChange = function (isOnLine)

{ if(isOnLine)

{ alert("Device is online");

} else

{ alert("Device is offline");

}

Return Values

None

Platform Availability

Available on all platforms except Windows Phone 8, Windows Phone 8.1, Windows 8, BlackBerry 10, and Mobile Web.

JavaScript Example var config = {}; config.statusChange = function (isOnLine)

{ if(isOnLine)

{ alert("Device is online");

} else

{

Kony Studio API Developer's Guide

Version 3.1

alert("Device is offline");

}

} kony.net.setNetworkCallbacks(config);

3.28 kony.notificationsettings Namespace

The kony.notificationsettings namespace, part of the

Notifications API , provides the following

API elements.

Functions

3.28.1 Functions

The kony.notificationsettings namespace provides the following functions.

3.28.1.1 kony.notificationsettings.createAction

This API helps you create an action that can be used with category.

Signature

JavaScript: kony.notificationsettings.createAction (actionId, label, pspConfig)

Input Parameters actionId [String] - Mandatory

Specifies a unique ID to identify the action chosen by a user.

label [String] - Mandatory

Specifies a label that needs to be associated with a action.

pspConfig [JSObject] - Mandatory

Specifies the configuration function. The parameters follow:

Kony Studio API Developer's Guide

Version 3.1

l image [Number] - Mandatory: This parameter is applicable only on the Android platform. Set the image to be displayed for notification settings.

l activationMode [Number] - Mandatory: Specifies the activation mode. The options are: l kony.notificationsettings.ACTIVATION_MODE_FORWARDS: If you set this option, the action will occur in the foreground and launches the application interface.

l kony.notificationsettings.ACTIVATION_MODE_BACKWARDS: If you set this option, the action will occur in the background without launching the application interface.

Note:

The activationMode property is applicable only for the iOS platform.

l authenticationRequired [Boolean] - Mandatory: This parameter is applicable only on iOS platform. This parameter is applicable only when you set activationMode as kony.notificationsettings.ACTIVATION_MODE_BACKWARDS. The user needs to unlock the device, and action occurs in the background.

l destructive [Boolean] - Mandatory: This parameter is applicable only on iOS platform. Set this value to true, if the notification is self destructive. Otherwise, set it to false.

l visibleOn [String] - Mandatory: Set this parameter to display the notification on a watch, or both watch and phone. The options are: l kony.notificationsettings.WATCH_ONLY

l kony.notificationsettings.BOTH

Return Values

This API returns action as a JavaScript object.

Kony Studio API Developer's Guide

Version 3.1

Platform Availability

Available on iOS and Android platforms.

JavaScript Example

//Using kony.notificationsettings.createAction

var accept = kony.notificationsettings.createAction({

"id": "Accept",

"label": "Accept",

"pspConfig": {

"activationMode": kony.notificationsettings.ACTIVATION_

MODE_FORWARDS,

"authenticationRequired": true,

"destructive": true

}

}); var reject = kony.notificationsettings.createAction({

"id": "Reject",

"label": "Reject",

"pspConfig": {

"activationMode": kony.notificationsettings.ACTIVATION_

MODE_BACKWARDS,

"authenticationRequired": false,

"destructive": false

}

}); var decline = kony.notificationsettings.createAction({

"id": "Decline",

"label": "Decline",

"pspConfig": {

Kony Studio API Developer's Guide

Version 3.1

"activationMode": kony.notificationsettings.ACTIVATION_

MODE_BACKWARDS,

"authenticationRequired": true,

"destructive": false

}

});

3.28.1.2 kony.notificationsettings.createCategory

This API helps you create a category with a group of created actions.

Signature

JavaScript: kony.localnotifications.createCategory (categoryId, actions, pspConfig:

{minimalActions:[actions] });

Input Parameters categoryId [String] - Mandatory

Specifies a unique ID for the group of actions that are defined.

actions [array] - Mandatory

Specifies the actions that are associated with the category. Pass null, if no actions are associated with the category.

Note: In Default Context, you cannot add more than four actions on the iOS platform and three actions in the Android platform.

pspConfig [JSObject] - Mandatory

Specifies the configuration function. The parameter is: l minimalActions [array] - Mandatory: This parameter is applicable only on the iOS

Kony Studio API Developer's Guide

Version 3.1

platform. Specify the actions that are to be associated for minimal actions for the category.

Note: In default mode, you cannot add more than two actions.

Return Values

This API returns category as a JavaScript object.

Platform Availability

Available on iOS and Android platforms.

JavaScript Example

//Using kony.notificationsettings.createCategory

var defaultActionContextArr = [accept, reject, decline]; var minimalActionContextArr = [accept, reject]; var categoryObj = kony.notificationsettings.createCategory({

"categoryId": invitation,

"actions": defaultActionContextArr,

"pspConfig": {

"minimalActions": minimalActionContextArr

}

});

3.28.1.3 kony.notificationsettings.registerCategory

This API helps you register the created category with the application.

Signature

JavaScript: kony.notificationsettings.registerCategory (categories, pspConfig)

Kony Studio API Developer's Guide

Version 3.1

Input Parameters category [array] - Mandatory

Specifies the category objects that are to be registered.

pspConfig [JSObject] - Optional

This parameter is applicable on iOS platform only. It specifies the platform specific configuration function. The arguments are: l types [String] - Mandatory: Configure this parameter to register the type of notification. The Array for iPhone must contain any or all of the following: l

0 - Specifies the notification type as Badge.

1 - Specifies the notification type as Sound.

2 - Specifies the notification type as Alert.

Note: If the types are not passed or pspConfig is not defined, then all the notification types are registered by the API.

Note:

If the same API is invoked multiple times, the details of the last invoked call are updated.

Return Values

None

Platform Availability

Available on iOS and Android platforms.

Kony Studio API Developer's Guide

Version 3.1

JavaScript Example

//Using kony.notificationsettings.registerCategory

var categoryArr = [categoryObj]; kony.notificationsettings.registerCategory({

"categories": categoryArr,

"pspConfig": {

"types": [0, 1, 2]

}

});

Handling Local and Remote Notifications Callbacks: l

If the app is in the foreground state (app instance alive), an onlinecallback should be invoked.

If the app is in background state (app instance alive or not alive), an offlinecallback should be invoked.

Kony Studio API Developer's Guide

Version 3.1

3.29 kony.os Namespace

The kony.os namespace provides functions for the Operating System API. It contains the following

API elements.

Functions

3.29.1 Functions

The kony.os namespace contains the following functions.

3.29.1.1 kony.os.addHiddenField

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

Signature

JavaScript : kony.os.addHiddenField(

key , value , private

)

Input Parameters key [String] - Mandatory

Specifies the key of the hidden field that you would like to add.

value [String] - Mandatory

Specifies the value that corresponds to the specified key in the hidden field.

private [String] - Optional

Specifies if the hidden field can be read using the

kony.os.readHiddenField

API. The expected values for this field are either "private" or "public". The default value of this field id

"public".

Kony Studio API Developer's Guide

Version 3.1

Note:

Only when this value is specified, you can read the hidden value through

kony.os.readHiddenField

API.

Return Values

None.

Platform Availability

Available only on Mobile Web.

JavaScript 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

}

3.29.1.2 kony.os.addMetaTag

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

Signature

JavaScript : kony.os.addMetaTag (key, value)

Input Parameters key [String] - Mandatory

Adds a meta tag in html header

Kony Studio API Developer's Guide

Version 3.1

value [Object] - Mandatory

Adds meta tag attributes in the html header as key value pairs.

Return Values

This API has no return values.

Platform Availability

Applicable only on Mobile Web.

JavaScript Example kony.os.addMetaTag("test2", { "http-equiv":"refresh","content":"30"

});

3.29.1.3 kony.os.deviceInfo

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 at: http://docs.kony.com/video_ tutorials/default.htm#Device_Info.htm%3FTocPath%3D_____9 .

Signature

JavaScript : kony.os.deviceInfo()

Input Parameters

None

Return Values values[Object]

Returns a

DeviceInfo

object.

Kony Studio API Developer's Guide

Version 3.1

Platform Availability

Available on all platforms.

JavaScript Example var deviceInfo=kony.os.deviceInfo(); alert(deviceInfo); for (var key in deviceInfo)

{ if (deviceInfo.hasOwnProperty(key))

{ alert(key+":"+deviceInfo[key]);

}

3.29.1.4 kony.os.endSecureTransaction

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.

Signature

JavaScript:

.kony.os.endSecureTransaction()

Input Parameters

None

Return Values

None

Platform Availability

Available only on Mobile Web.

Kony Studio API Developer's Guide

Version 3.1

JavaScript Example kony.os.endSecureTransaction();

3.29.1.5 kony.os.freeMemory

This API provides the ability to query and fetch the system-wide memory available on the mobile device for allocation.

Use Case

You can use this API to: l

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.

Signature

JavaScript: kony.os.freeMemory()

Input Parameters

None

Return Values

Free memory[Number]

The available memory for allocation is returned. The returned memory always indicates the number of bytes available.

Kony Studio API Developer's Guide

Version 3.1

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.

JavaScript 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)

3.29.1.6 kony.os.getAppContext

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

Signature

JavaScript: kony.os.getAppContext()

Input Parameters

None

Return Values contextDetails[Object]

Returns an object with key-value pairs:

Kony Studio API Developer's Guide

Version 3.1

launchmode:0

indicates that the application is launched in normal mode.

launchmode:1

indicates that the application is launched in full screen mode.

Platform Availability

Applicable only on Mobile Web.

JavaScript 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

}

3.29.1.7 kony.os.getDeviceCurrentOrientation

This API returns the current orientation of the device. The possible values are portrait or landscape.

Signature

JavaScript : kony.os.getDeviceCurrentOrientation()

Input Parameters

None

Return Values

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

l constants.DEVICE_ORIENTATION_PORTRAIT

l constants.DEVICE_ORIENTATION_LANDSCAPE

Kony Studio API Developer's Guide

Version 3.1

Platform Availability

Available on iPhone, iPad, Windows 8, Android, BlackBerry, BlackBerry 10, Windows 7 / Kiosk, and

Desktop Web ( Always returns DEVICE_ORIENTATION_PORTRAIT in Desktop Web Channel)

JavaScript Example kony.os.getDeviceCurrentOrientation();

Returns the device orientation

3.29.1.8 kony.os.hasAccelerometerSupport

This API returns whether accelerometer is supported on a device.

Signature

JavaScript

: kony.os.hasAccelerometerSupport()

Input Parameters

None.

Return Values value[Boolean]

Returns whether accelerometer is supported on a device.

Platform Availability

Applicable only on iPhone, Android, BlackBerry, BlackBerry 10, and Windows platforms.

JavaScript Example kony.print(kony.os.hasAccelerometerSupport());

//prints true if device has accelerometer support

Kony Studio API Developer's Guide

Version 3.1

3.29.1.9 kony.os.hasCameraSupport

This API returns whether Camera is supported on a device.

Signature

JavaScript : kony.os.hasCameraSupport()

Input Parameters

None.

Return Values value[Boolean] true: the platform supports Camera false: the platform does not support Camera

Platform Availability

Available on all platforms* except Mobile Web and Windows 7 / Kiosk. *Dummy implementation for

SPA and Desktop Web that always returns False.

JavaScript Example kony.print(kony.os.hasCameraSupport());

//prints true if device has camera support

3.29.1.10 kony.os.hasGPSSupport

This API returns whether GPS is supported on a device.

Signature

JavaScript : kony.os.hasGPSSupport()

Kony Studio API Developer's Guide

Version 3.1

Input Parameters

None.

Return Values value[Boolean] true: the platform supports GPS.

false: the platform does not support GPS.

Platform Availability

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

JavaScript Example kony.print(kony.os.hasGPSSupport());

//prints true if device has GPS support

3.29.1.11 kony.os.hasOrientationSupport

This API returns whether Orientation is supported on a device.

You can view a video on using Display Orientation at: http://docs.kony.com/video_ tutorials/default.htm#DisplayOrientation.htm%3FTocPath%3D_____12 .

Signature

JavaScript: kony.os.hasOrientationSupport()

Input Parameters

None.

Kony Studio API Developer's Guide

Version 3.1

Return Values value[Boolean] true: the platform supports orientation.

false: the platform does not support orientation.

Platform Availability

Available on all platforms except Mobile Web.

JavaScript 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");

}

3.29.1.12 kony.os.hasTouchSupport

This API returns whether Touch is supported on a device.

Signature

JavaScript

: kony.os.hasTouchSupport()

Kony Studio API Developer's Guide

Version 3.1

Input Parameters

None.

Return Values value[Boolean] true: the platform supports touch.

false: the platform does not support touch.

Platform Availability

Available on all platforms except Mobile Web and Desktop Web.

JavaScript Example kony.print(kony.os.hasTouchSupport());

//prints true if device is a touch device

3.29.1.13 kony.os.print

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

Signature

JavaScript : kony.os.print(containerID)

Input Parameters containerID [Number] - Optional

The containerID can be a ID of any container widget that can be directly referenced from a form.

Note:

Kony Studio API Developer's Guide

Version 3.1

If the user is typing in a text box, the typed content will not be printed.

Print API can be used only after the target Form, Popup or Datagrid is rendered on the browser.

Print API cannot be used in pre-show, post-show, pre and post app init or any other functionality that is run before the target Form, Popup, or Datagrid is fully rendered.

When printing the form with widgets like ScrollBox, Image Strip, the print functionality prints only those widgets that are in the view or potentially occupy the available print space in portrait or landscape views.

Return Values

None.

Platform Availability

Applicable only on Desktop Web.

JavaScript Example kony.os.print()

3.29.1.14 kony.os.readHiddenField

This API allows the developers to read the hidden fields added by the

os.addHiddenField

API.

Signature

JavaScript : kony.os.readHiddenField(

key )

Input Parameters key [String] - Mandatory

Specifies the key of the hidden field that you would like to read.

Kony Studio API Developer's Guide

Version 3.1

Return Values value[String]

Returns the value that corresponds to the specified key.

nil nil is returned if there is no value assigned to the corresponding key.

Platform Availability

Available only on Mobile Web.

JavaScript Example function readHiddenField()

{ kony.os.readHiddenField("myhiddenfield")

// Reads the value that corresponds to the myhiddenfield key, i.e., myvalue

}

3.29.1.15 kony.os.removeAllMetaTags

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

Signature

JavaScript : kony.os.removeAllMetaTags ()

Input Parameters

None.

Kony Studio API Developer's Guide

Version 3.1

Return Values

This API has no return values.

Platform Availability

Applicable only on Mobile Web.

JavaScript Example kony.os.removeAllMetaTags()

3.29.1.16 kony.os.removeMetaTag

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

Signature

JavaScript

: kony.os.removeMetaTag (key)

Input Parameters key [String] - Mandatory

Removes a meta tag with the specific key in html header.

Return Values

This API has no return values.

Platform Availability

Applicable only on Mobile Web.

Kony Studio API Developer's Guide

Version 3.1

JavaScript Example kony.os.removeMetaTag("test1")

3.29.1.17 kony.os.startSecureTransaction

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.

Signature

JavaScript : kony.os.startSecureTransaction(callback, scope)

Input Parameters callback [Function] - Mandatory

If there are instances where cross site request forgery is attempted, this parameter should comprise a session/request expiry function.

scope [Integer] - Mandatory

Specifies whether this API will be valid per request or per session of the application. The possible values are as follows: l

0 - Request Scope: The data in the application is secure only on a per request basis.

Note: If you press the browser back button on BJS, the token is rendered invalid on the browser back request.

1 - Session Scope. The data is secure for an entire user session. This is the default value.

Kony Studio API Developer's Guide

Version 3.1

Return Values

This API has no return values.

Implementation Details

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.

JavaScript Example function callback()

{

} kony.os.startSecureTransaction(callback, 1)

3.29.1.18 kony.os.toCurrency

This API allows you to convert the given number to represent currency. At present, only USA currency is supported.

Kony Studio API Developer's Guide

Version 3.1

Signature

JavaScript : kony.os.toCurrency(

number

)

Input Parameters 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.

Return Values

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.

JavaScript Example

Perform a kony.os.toCurrency operation on the number "10000".

var tocurrency = kony.os.toCurrency(10000); kony.print(tocurrency);

//prints $ 10,000

Kony Studio API Developer's Guide

Version 3.1

3.29.1.19 kony.os.toNumber

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.

Signature

JavaScript: kony.os.toNumber(

argument )

Input Parameters argument [String or Number] - Mandatory

The argument that must be converted to a number.

Return Values

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.

Rules and Restrictions

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.

Kony Studio API Developer's Guide

Version 3.1

JavaScript 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

3.29.1.20 kony.os.userAgent

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: l device model l manufacturer l

OS version l browser version l

Java capabilities, and so on.

The following are a few sample useragents:

Useragent

Nokia6230i/2.0 (03.25) Profile/MIDP-2.0

Configuration/CLDC-1.1

Description

Nokia 6230i model mobile device

Kony Studio API Developer's Guide

Version 3.1

Useragent

SonyEricssonT610/R501 Profile/MIDP-1.0

Configuration/CLDC-1.0

BlackBerry9500/4.7 Profile/MIDP-2.0

Configuration/

BlackBerry9700/5.0 Profile/MIDP-2.1

Configuration/

Mozilla/4.0 (compatible; MSIE 7.0; Windows

Phone OS 7.0)

OPWV-SDK/62 UP.Browser/6.2.2.1.208 (GUI)

MMP/2.0

Mozilla/4.0 (compatible; MSIE 6.0; Windows NT

5.0)

Mozilla/5.0 (Windows; U; Windows NT 5.0; en-

US; rv:1.7.12) Gecko/20050915 Firefox/1.0.7

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

Description

SonyEricsson

T610 model mobile device

BlackBerry

9500 mobile device

BlackBerry

9700 mobile device

Windows

Phone mobile device

Openwave

Mobile

Browser 6.2.2

Microsoft

Internet

Explorer 6

Mozilla

Firefox 1.0.7

running on

Windows

2000 iPad

Kony Studio API Developer's Guide

Version 3.1

Useragent

Device Model. For example, Galaxy Nexus.

Description

Android and

Android

Tablet.

Use Case

You can use this API in the following scenarios when you need to identify: l

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.

Signature

Javascript: kony.os.userAgent()

Input Parameters

None

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: l

For Android and Android Tablet, device model is returned as an user agent.

For iOS Devices, user agent is returned as a string.

Kony Studio API Developer's Guide

Version 3.1

Platform Availability

Available on all platforms except Windows 7.

JavaScript 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);

3.30 kony.phone Namespace

The kony.phone namespace provides the following API elements.

Functions

3.30.1 Functions

The kony.phone namespace contains the following functions.

3.30.1.1 kony.phone.addCalendarEvent

This API adds a new event to the device calendar.

You can view a video on using Device Calendar at: http://docs.kony.com/video_ tutorials/default.htm#DeviceCalendar.htm%3FTocPath%3D_____11 .

Note: In Windows Phone 7.5, the calendar event is only added at the application level and not on the phone's default calendar application.

Signature

JavaScript: kony.phone.addCalendarEvent(

eventDetails

)

Kony Studio API Developer's Guide

Version 3.1

Input Parameters eventDetails [Object] - Mandatory

A table that contains the following key-value pairs: l summary [String] - Short description for the event.

l start [String] - The start date and time for the event. The format for date is "dd/mm/yyyy", and time is "hh:mm:ss".

l finish [String] - The finish date and time for the event. The format for date is "dd/mm/yyyy", and time is "hh:mm:ss".

l alarm [Number] - Time in seconds before the start time at which the phone must trigger an alarm.

l note [String] - Long description for the event.

l access [String] - Indicates the privacy setting for the event. The values can be one of the following:

1. public (default)

2. private

3. confidential

Return Values

None

Exceptions

PhoneError

The following error codes are defined for Phone APIs

Kony Studio API Developer's Guide

Version 3.1

2100 - Unable to send the Message l

2101 - Insufficient Permissions l

2102 - Cannot open mail, mail not configured l

2103 - Cannot open media gallery

Error l

100 – invalid type of parameters l

101 – invalid number of arguments l

102 – invalid input – thrown when the input is invalid based on the context.

103 – invalid operation – thrown when the operation is invalid based on the context.

104 – not supported error – thrown when the method is not supported at all.

105 – index out of range.

106 – unknown error.

Platform Availability

Available on all platforms except BlackBerry 10, Mobile Web, Windows 8, Kiosk, Desktop Web, and

SPA.

Few conditions:

1. In Android: l

READ_CALENDAR and WRITE_CALENDAR permissions are needed for this API.

This API is supported for Android 4.0 version and above (that is, Android API level later to

13 ). Invocation on Android version less than 4.0 ( that is, Android API level earlier to 14) will be ignored.

Kony Studio API Developer's Guide

Version 3.1

For alarm parameter, seconds will be rounded off to nearest minute. That is, it rounds off to Floor or Ceil based on < 30sec or >= 30sec.

Events will be added to Local Calendar (not syncable to email accounts) with Calendar name same as application name.

2. Events cannot be added in past time.

3. Time zone of event added is same as the device Time Zone.

Rules and Restrictions

The finish input parameter must be greater than the start input parameter.

JavaScript Example function addCalendarEvent()

{ try

{ alert("calendar event is about to start"); var evtobj={summary:"Event started", start:"15/04/2012

11:23:45", finish:"21/12/2012 12:59:45", alarm:40,note:"Event will ends at 12.59 PM", access:"public"};

} catch(PhoneError)

{ kony.phone.addCalendarEvent(evtobj);

//Adds a event to the device calendar alert("error in addCalendarEvent:: "+PhoneError);

}

Kony Studio API Developer's Guide

Version 3.1

3.30.1.2 kony.phone.dial

This API provides you with the ability to make a call to the specified telephone number.

Note: When you make calls using this API, the call charges as imposed by the Service Provider are applicable. This API is a dummy call on the iPhone simulator. You need to test this API on an iPhone device.

Use Case

You can use this API to make calls to other numbers without leaving the application.

Signature

JavaScript: kony.phone.dial(

number

)

Input Parameters number [String] - Mandatory

Number to which the call must be made.

Note:

Only numbers, +, - and space are treated as valid characters.

Return Values

None

Exceptions

PhoneError

The following error codes are defined for Phone APIs l

2101 - Insufficient Permissions

Kony Studio API Developer's Guide

Version 3.1

Implementation Details

When you make a call to the specified number using this API, the underlying OS is used to make the call.

Platform Availability

Not supported on Windows Kiosk,Windows 8, iPad, Android Tablets, Desktop Web, and Mobile Web platforms. You can use the phone widget to achieve the same functionality on Mobile Web.

JavaScript Example function CallTheNumber()

{ try

{

} catch(err)

{ var number="123456789"; kony.phone.dial(number); alert("error in dial:: "+err);

}

3.30.1.3 kony.phone.findCalendarEvents

This API finds an event in the device calendar.

Signature:

JavaScript: kony.phone.findCalendarEvents(

evtobj

)

Kony Studio API Developer's Guide

Version 3.1

Parameters: evtobj [Object] - Mandatory

A Hash table that has the following key-value pairs (details of the event): l type [String] - Specifies the criteria for searching the event. The criteria can be starting, ending, or occurring.

l starting - Searches for events starting between "start" and "finish".

l ending - Searches for events ending between "start" and "finish".

l occurring (default) : Searches for events that have any part of the event occurring during the period specified between

"start" and "finish".

l start [String] - Specifies the start date and time for the event. The format for date is

"dd/mm/yyyy", and time is "hh:mm:ss" l finish [String] - Specifies the finish date and time for the event. The format for date is

"dd/mm/yyyy", and time is "hh:mm:ss"

Note:

The finish date must be greater than the start date.

Return Values: eventHandle

Handle to the event (s) that match the specified input string in the device calendar. An array of objects contains: l summary [String] - Short description for the event.

l start [String] - The start date and time for the event. The format for date is

"dd/mm/yyyy", and time is "hh:mm:ss".

l finish [String] - The finish date and time for the event. The format for date is

"dd/mm/yyyy", and time is "hh:mm:ss".

Kony Studio API Developer's Guide

Version 3.1

l alarm [Number] - Time in seconds before the start time at which the phone must trigger an alarm.

l event ID [Number] - Identification number for that event.

l note [String] - Long description for the event.

l access [String] - Indicates the privacy setting for the event. The values can be one of the following:

1. public (default)

2. private

3. confidential null

If there is no event found that matches the specified criteria.

Exceptions:

PhoneError

The following error codes are defined for Phone APIs l

2100 - Unable to send the Message l

2101 - Insufficient Permissions l

2102 - Cannot open mail, mail not configured l

2103 - Cannot open media gallery

Error l

100 – invalid type of parameters l

101 – invalid number of arguments l

102 – invalid input – thrown when the input is invalid based on the context.

Kony Studio API Developer's Guide

Version 3.1

103 – invalid operation – thrown when the operation is invalid based on the context.

104 – not supported error – thrown when the method is not supported at all.

105 – index out of range.

106 – unknown error.

Platform Availability

Available on all platforms except BlackBerry 10, Mobile Web, Windows 8, Kiosk, Desktop Web, and

SPA.

Rules and Restrictions l

READ_CALENDAR permission is needed for this API.

This API is supported for Android 4.0 version and above (that is, Android API level later to 13).

Invocation on Android version less than 4.0 ( that is, Android API level earlier to 14) will be ignored.

This API searches only those events that are added by the application .

JavaScript Example function findCalendarEvent()

{ try

{ alert("Finding the calendar events"); var evtobj={type:"starting",start:"15/03/2012 12:46:45", finish:"24/12/2012 12:59:45"}; var events = kony.phone.findCalendarEvents(evtobj); alert("Found calendar event(s)");

} catch(err)

Kony Studio API Developer's Guide

Version 3.1

{

} alert("error in findCalendarEvents:: "+err);

}

3.30.1.4 kony.phone.openEmail

This API allows the application to launch the native email client with predefined email addresses, subject, body, and attachments.

Use Case

You can use this API to send emails without leaving the application.

Signature

JavaScript: kony.phone.openEmail(

torecipients

ccrecipients

bccrecipients ,

subject , messagebody

ismessagebodyhtml , attachments )

Input Parameters torecipients [Array of Strings] - Mandatory

List of email addresses to be included in the "to" list. For example,

"[email protected]","[email protected]" "[email protected]".

ccrecipients [Array of Strings] - Optional

List of email addresses to be included in the "cc" list. For example,

"[email protected]","[email protected]" "[email protected]".

bccrecipients [Array of Strings] - Optional

List of email addresses to be included in the "bcc" list. For example,

"[email protected]","[email protected]" "[email protected]".

Kony Studio API Developer's Guide

Version 3.1

subject [String]- Optional

Subject to be part of the email.

messagebody [String] -Optional

Body to be part of the email.

ismessagebodyhtml [Boolean] - Optional l true: message body must be treated as HTML content l false: message body must not be treated as HTML content

Note: BlackBerry does not support HTML body. This is an underlying SDK limitation.

attachments [Array of Objects] - Optional

Each attachment is a Hash-table with the following key-value pairs: l mimetype [String] Standard mime types like image/png or image/jpg or image/* etc.

l attachment [Object] Rawbytes received from the camera, image widget, or openmediagallery api.

l filename (Optional) [String] name of the file to appear as attachment.

Note: l

In Android, filename property is not supported.The Android SDK does not provide any provision for giving file name in attachments while launching native email Application.

For Windows 8 applications, attachments cannot be added programmatically. This is a limitation from Microsoft.

Return Values

None

Kony Studio API Developer's Guide

Version 3.1

Exceptions

PhoneError

The following error codes are defined for Phone APIs l

2100 - Unable to send the Message l

2101 - Insufficient Permissions l

2102 - Cannot open mail, mail not configured l

2103 - Cannot open media gallery

Platform Availability

Available on all platforms except Server Side Mobile Web, SPA, Kiosk, and Desktop Web. For these platform you can launch the native email client by using Richtext widget with an href tag similar to the one shown below:

<a href="mailto:[email protected]?subject=Foo&body=Bar">Email Me</a>

Rules and Restrictions l

BlackBerry does not support HTML tags in the body.

Android does not support base64 string as attachments. You can attach only those files on disk that are accessible by the native Email app and that can be accessed by the app.For example,

Images from Gallery, Kony Camera captured image that is available on the disk with public access.

JavaScript Example function openEmail()

{ try

{

Kony Studio API Developer's Guide

Version 3.1

var to=["[email protected]"]; var cc=["[email protected]"]; var bcc = ["[email protected]"]; var sub = "Hello";

} catch(err)

{ var msgbody = "Testing openEmail"; kony.phone.openEmail(to,cc,bcc,sub,msgbody,false,[]); alert("error in opening Email:: "+err);

}

3.30.1.5 kony.phone.openMediaGallery

This API allows you to open the picture gallery of the mobile device and pick an existing picture.

Use Case

You can use this API to use any of the multimedia resources (image files, audio files, or video files) available in the device media gallery within your application.

For iPad, openMediaGallery will show the Photos/Videos in the native popover. The popover can be anchored to a widget. The widget to which the popup should be anchored will be provided as a third parameter to openMediaGallery API.

You can view a video on using iPad Popover at: http://docs.kony.com/video_ tutorials/default.htm#iPadPopOver.htm%3FTocPath%3D_____16 .

Signature

JavaScript: kony.phone.openMediaGallery(

onselectioncallback , querycontext,widgetref

)

Kony Studio API Developer's Guide

Version 3.1

Input Parameters onselectioncallback [Function] - Mandatory

This callback function is invoked when a media is selected.

querycontext [Table] - Optional

Query context is an Object that can be populated with key-value pairs for fine tuning the media items for display (currently only one key "mimetype" supported to query the gallery items ). The possible values of the mimetype key can be image/*, video/*, audio/*.

widgetref [Widget Reference] - Optional

Applicable only on iPad. The widget to which the popup will be anchored to. For e.g.

formname.widgetname

Return Values

None

Exceptions

PhoneError

The following error codes are defined for Phone APIs l

2100 - Unable to send the Message l

2101 - Insufficient Permissions l

2102 - Cannot open mail, mail not configured l

2103 - Cannot open media gallery

Platform Availability

Supported on all platforms except BlackBerry 10, Mobile Web, Windows 8, SPA, Kiosk, and Desktop

Web.

Kony Studio API Developer's Guide

Version 3.1

JavaScript Example function openMediaGallery()

{ try

{ function onselectioncallback(rawbytes)

{ querycontext); alert("in selection callback"); if (rawbytes == null)

{ alert("nothing selected"); return;

} alert("return status is "+returnStatus);

//(convert the rawbytes to base64 and can be assigned to a image widget or use base64 to upload) var base64 = convertToBase64(rawbytes); frmTest.imgone.base64 = base64;

//Assigning rawbytes directly to a image widget

/*formid.imageid.rawdata = rawbytes;*/

} var querycontext = {mimetype:"video/*"}; returnStatus = kony.phone.openMediaGallery(onselectioncallback,

} catch(err)

{ alert("error in openMediaGallery:: "+err);

}

Kony Studio API Developer's Guide

Version 3.1

}

3.30.1.6 kony.phone.removeCalendarEvent

This API deletes an event that matches the specified event handled from the device calendar.

Note: To delete an event, you must first search the event using the find API and delete the event

Signature:

JavaScript:

kony.phone.removeCalendarEvent( eventHandle )

Parameters: eventHandle [Object] - Mandatory

Event handle is returned by the find operation.

Note: To delete an event, you must first search the event using the find API and delete the event.

Return Values:

None.

Exceptions:

PhoneError

The following error codes are defined for Phone APIs l

2100 - Unable to send the Message l

2101 - Insufficient Permissions

Kony Studio API Developer's Guide

Version 3.1

2102 - Cannot open mail, mail not configured l

2103 - Cannot open media gallery

Error l

100 – invalid type of parameters l

101 – invalid number of arguments l

102 – invalid input – thrown when the input is invalid based on the context.

103 – invalid operation – thrown when the operation is invalid based on the context.

104 – not supported error – thrown when the method is not supported at all.

105 – index out of range.

106 – unknown error.

Platform Availability

Available on all platforms except BlackBerry 10, Mobile Web, Windows 8, Kiosk, Desktop Web, and

SPA.

Rules and Restrictions l

READ_CALENDAR and WRITE_CALENDAR permissions are needed for this API.

This API is supported for Android 4.0 version and above (that is, Android API level later to 13).

Invocation on Android version less than 4.0 ( that is, Android API level earlier to 14) will be ignored.

If this API removes last calendar event added to local calendar, then the local calendar account will be deleted.

Kony Studio API Developer's Guide

Version 3.1

JavaScript Example: function removeCalendarEvent() { try { var evtobj = { type: "starting", start: "20/03/2014", finish: "21/03/2014"

}; var events = kony.phone.findCalendarEvents(evtobj); kony.phone.removeCalendarEvent(events[1]); alert("Event deleted successfully");

// It deletes an event that matches the specified

// event handle from the device calendar

} catch (err) { alert("error in removeCalendarEvent:: " + err);

}

3.30.1.7 kony.phone.sendSMS

This API provides access to the Messaging service of the underlying platform. You can send a text message to a specified number. This API accesses the messaging application of the underlying platform and uses that application to send text message to the specified number.

Important:

You can send only text messages and multimedia messages are not supported.

Note: When you send messages using this API, the charges as imposed by the Service Provider are applicable. On iPhone this API opens the Messages application with a prepopulated text and number.

Kony Studio API Developer's Guide

Version 3.1

Use Case

You can use this API to send messages to other numbers without leaving the application.

Signature

JavaScript: kony.phone.sendSMS(

phonenumber , text )

Input Parameters phonenumber [String] - Mandatory

Number to which the SMS must be sent.

text [String] - Mandatory

Content of the SMS.

Return Values

None

Exceptions

PhoneError

The following error codes are defined for Phone APIs l

2100 - Unable to send the Message.

2101 - Insufficient Permissions.

Implementation Details

When you send messages using this API, the messaging application of the underlying platform is used to send the message with the number and text you specified i.e., the phone number and the message are pre-populated in the messaging application.

Kony Studio API Developer's Guide

Version 3.1

Platform Availability

Available on all platforms except BlackBerry 10, Desktop Web,SPA, Mobile Web, Android Tablets, iPad, Kiosk.

JavaScript Example function sendSMS()

{ try

{

} catch(err)

{ var phNo="123456789"; var msg= "hello world"; kony.phone.sendSMS(phNo,msg); alert("error in sending sms:: "+err);

}

Note: This API allows you to send only text messages. It does not support multimedia messages.

3.31 kony.push Namespace

The kony.push namespace, which is part of the Notifications API, provides the following API elements.

Functions

Kony Studio API Developer's Guide

Version 3.1

3.31.1 Functions

The kony.push namespace contains the following functions.

3.31.1.1 kony.push.deRegister

This API allows an application on a device to deregister from Push Notifications. This API takes an empty Object as the parameter.

If the deregistration is successful, the platform invokes the onsuccessfulderegistration function. If the deregistration is a failure, the platform invokes the onfailurederegistration function.

Signature

JavaScript

: kony.push.deRegister(

emptyObject

)

Input Parameters emptyObject [Object]- Mandatory

Is an empty Object.

Return Values

None

Exceptions

The following error codes are applicable to onfailureregistration and onfailurederegistration functions: l

1402 - Unable to connect to push service - PNS service is not available l

1403 - Registration failed by PNS - Account related or device restrictions (thrown by push.register() API during an onfailureregistration callback).

1404 - Deregistration failed - Unable to close channel or PNS internal error while deregistration

(thrown by push.deregister() API during an onfailurederegistration callback).

Kony Studio API Developer's Guide

Version 3.1

1405 - Duplicate Registration - Actual registration details should be provided? (thrown by kony.

push.register() API during an onfailureregistration callback) l

1406 - Platform-specific issue. Full details are available in the errormessage. For example, received payload but payload is in incorrect format.

An error is thrown if input type is invalid or does not follow the expected structure.

102-Invalid input error

API Usage

You must use this API to deregister the application and the device from the Push Notifications service.

JavaScript Example

To deregister from Push Notifications, use the following code snippet: var myhash = new Hash(); kony.push.deRegister(myhash);

Platform Availability

Available on Android, iPhone, iPad, Windows, BlackBerry, and BlackBerry 10.

3.31.1.2 kony.push.getMessageCount

This API fetches the number of unread push notification messages that are stored on the device database.

Signature

JavaScript: kony.push.getMessageCount()

Input Parameters

None.

Kony Studio API Developer's Guide

Version 3.1

Return Values numberOfMessages [Number]

Returns the number of messages.

Exceptions

The following error codes are applicable to onfailureregistration and onfailurederegistration functions: l

1402 - Unable to connect to push service - PNS service is not available l

1406 - Platform-specific issue. Full details are available in the errormessage. For example, received payload but payload is in incorrect format.

Platform Availability

Available only on BlackBerry and BlackBerry 10.

JavaScript Example

The following code snippet is an example of this API: function callbackGetMessageCount()

{ var count = kony.push.getMessageCount(); kony.print("Message Count : "+count);

}

3.31.1.3 kony.push.getMessages

Gets the unread notification messages from the device database. Once this function is called, the device database is cleared and the message count is reset to zero.

Signature

JavaScript

:kony.push.getMessages()

Kony Studio API Developer's Guide

Version 3.1

Input Parameters

None.

Return Values messages [Object]

Returns an Object that has all the messages

Exceptions

The following error codes are applicable to onfailureregistration and onfailurederegistration functions: l

1402 - Unable to connect to push service - Push Notification Service (PNS) is not available .

1404 - Platform-specific issue. Full details are available in the error message. For example, received payload but payload is in incorrect format.

Platform Availability

Available only on BlackBerry and BlackBerry 10.

JavaScript Example

The following code snippet is an example of this API: function callbackGetMessages()

{ var messages = kony.push.getMessages(); alert(messages);

}

Kony Studio API Developer's Guide

Version 3.1

3.31.1.4 kony.push.register

This API allows you to register the application and the mobile device for Push Notifications. This API takes an Object as a parameter (the values in the table differ across platforms).

If the registration is successful, the platform invokes the onsuccessfulregistration function. If the registration is a failure, the platform invokes the onfailureregistration function.

Signature

JavaScript : kony.push.register(configObject)(

iPhone / Android

Windows )

Input Parameters configObject [Array] - Mandatory (iPhone)

The Array for iPhone must contain any or all of the following: l

0 - Specifies the Notification type as Badge.

1 - Specifies the Notification type as Sound.

2 - Specifies the Notification type as Alert.

configObject [Object] - Mandatory (Android)

A Hash table for Android must contain the following key value pairs: l senderid - Specifies the project ID of the account registered to use GCM.

The projectID is the ID for a created API project.For registering projectID for Push Notifications, see http://developer.android.com/guide/google/gcm/gs.html

#create-proj configObject [Object] - Mandatory (BlackBerry)

The Hash table for BlackBerry must contain the following key value pairs: l appid - Specifies the unique application ID.

Kony Studio API Developer's Guide

Version 3.1

Note:

You receive the application ID only after you register the application for Push

Notification with RIM.

l port - Specifies the port number on the device where the Push Notifications are received.

Note: You receive the port information only after you register the application for Push Notification with Research in Motion(RIM).

l bpasurl - Specifies an HTTP version of the PPG base URL (Push Proxy Gateway).

You receive the BPAS URL only after you register the application for Push Notification with

RIM.

l appicon - Specifies the icon to be displayed when there are no messages in the queue (typically the application logo).

l starappicon - Specifies the icon to be displayed when there are unread messages in the queue (typically the application logo with a star on the top-right corner of the image (Image dimensions 54x54)).

l statusbaricon - Specifies the icon to be displayed in the status bar (top area on the home screen of the device (Image dimensions 17x17)).

configObject [Object]- Optional (Windows)

Windows Phone does not require any input parameters. However, you can specify the following

Optional key value pairs in the Object: l remoteimageurls (Optional) - Specifies an array of remote images to be displayed for a Tile message.

The sender can specify the image to be displayed on the Tile notification by specifying the image URL.

l enableraw (Optional): This is a Boolean parameter and it specifies if the device must receive raw messages or not. The default value is true

(you can receive raw messages). If you do not want the device to receive raw messages, set the value to false .

l enabletile (Optional): This is a Boolean parameter and it specifies if the device must receive tile messages or not. The default value is true

(you can receive tile messages). If you do not want the device to receive tile messages, set the value to false .

Kony Studio API Developer's Guide

Version 3.1

l enabletoast (Optional): This is a Boolean parameter and it specifies if the device must receive toast messages or not. The default value is true (you can receive toast messages). If you do not want the device to receive toast messages, set the value to false .

Return Values

None

Exceptions

The following error codes are applicable to onfailureregistration and onfailurederegistration functions: l

1402 - Unable to connect to push service - PNS service is not available l

1403 - Registration failed by PNS - Account related or device restrictions (thrown by push.register() API during an onfailureregistration callback).

1405 - Duplicate Registration - Actual registration details should be provided? (thrown by kony.

push.register() API during an onfailureregistration callback) l

1406 - Platform-specific issue. Full details are available in the errormessage. For example, received payload but payload is in incorrect format.

An error is thrown if input type is invalid or does not follow the expected structure.

102-Invalid input error

API Usage

You must use this API to register the application and the device for Push Notifications with the Push

Notifications service provider.

JavaScript Example

The following are the examples for this API on various platforms:

Android

The following code snippet uses the senderid to register for Push Notifications:

Kony Studio API Developer's Guide

Version 3.1

//The following code snippet uses the senderid to register for Push

Notifications: var config = {senderid="4815162342"}; kony.push.register(config);

BlackBerry

The following code snippet uses the appid, port, bpasurl, appicon, starappicon, and statusbaricon to register for Push Notifications: var config = {appid:"1016-1no1ha3e5111ryMa71",port:20921,bpasurl:

"http://pushapi.eval.blackberry.com",appicon:"icon.png", starappicon:"starappicon.png",statusbaricon:"statusicon.png"} kony.push.register(config); iPhone

The following code snippet uses the notification types to register for Push Notifications:

//The following code snippet uses the notification types to register for

Push Notifications: var config=[0,1,2]; kony.push.register(config);

Windows Phone

The following code snippet uses the remoteimageurls as the key and the link specifies the images to be displayed in the tile notification as the value: var config={remoteimageurls:

["http://www.thisisfanzoo.com/blog/samples/ logo2.png",

Kony Studio API Developer's Guide

Version 3.1

"http://www.yahoo.com/samples/logo3.png"],enableraw:true,enabletile

:false, enabletoast:false}; kony.push.register(config);

Note:

Only network URL's are allowed. MPNS allows only images from trusted domains

(registered to MPNS) to be displayed to avoid image policies. There is no such restriction on local images.

Platform Availability

Available on Android, iPhone, iPad, Windows, BlackBerry, and BlackBerry 10.

3.31.1.5 kony.push.setCallbacks

When an application on a device (iPhone, Android, BlackBerry, or Windows Phone 7) registers or deregisters for Push Notifications, or if the device receives a Notification, the device executes the function of your choice.

You can specify the functions to be executed for Push Notification in an Object for this API.

Signature

JavaScript: kony.push.setCallbacks(

Object

)

Input Parameters

Object [Object] - Mandatory

A Hash table has the following key-value pairs: l onsuccessfulregistration [Function] - Mandatory: Specifies the function to be executed when the Push Notifications registration is successful.

l onfailureregistration [Function] - Mandatory: Specifies the function to be executed when the

Push Notifications registration fails.

Kony Studio API Developer's Guide

Version 3.1

l onlinenotification[Function] - Mandatory for iPhone, Android, and Windows. Optional for

BlackBerry. Specifies the function to be executed when the device receives a message when the application is running.

The message types for which this function is executed varies.

The message type on various platforms are as follows: iPhone: Sounds, Alerts, or Badges

Windows Phone 7: raw or toast

, Blackberry: Text Alert.

l offlinenotification [Function] - Mandatory for iPhone, Android, and Windows. Optional for

BlackBerry. Specifies the function to be executed when the device receives a message when the application is not running.

The message types for which this function is executed varies.

The message type on iPhone is as follows: iPhone: Sounds, Alerts, or Badges l onsuccessfulderegistration [Function] - Mandatory. Specifies the function to be executed when the Push Notification deregistration is successful.

l onfailurederegistration [Function] - Mandatory for BlackBerry, Android, and Windows. Optional for iPhone. Specifies the function to be executed when the Push Notification deregistration is a failure.

l offlinecallback [Function] - Mandatory. Specifies the function to be executed when an action is invoked.

l payload [] - <need to update> l actionId [String] - A unique id to identify the action.

Return Values

None

Exceptions

The following error codes are applicable to onfailureregistration and onfailurederegistration functions:

Kony Studio API Developer's Guide

Version 3.1

1403 - Registration failed by PNS - Account related or device restrictions (thrown by push.register() API during an onfailureregistration callback).

1404 - Deregistration failed - Unable to close channel or PNS internal error while deregistration

(thrown by push.deregister() API during an onfailurederegistration callback).

API Usage

You must call this API after the application is launched as this API will not be explicitly called by the user.

Implementation Details

The following are the implementation details of this API:

Based on the status of the registration or deregistration attempt (success or failure) and the state of the application on the device (active or inactive) when the Push Notifications arrive, use the following snippet to call the associated functions: object = {onsuccessfulregistration:onsuccess , onfailureregistration:onfailure , onlinenotification:onlineCallback , offlinenotification:offineCallback, onsuccessfulderegistration:onderegsuccess , onfailurederegistration:onderegfailure }; kony.push.setCallbacks

(object); onsuccessfulregistration

If the registration for Push Notifications is successful, this callback is executed by the underlying platform.

The callback takes string as the parameter.

The following code snippet is an example of the onsuccessfulregistration callback: function onsuccess(identifier)

{

Kony Studio API Developer's Guide

Version 3.1

kony.print("Registered SUCCESSFULLY :"+identifier);

//Send the identifier to the Push Notifications Sender.

} onfailureregistration

If the registration for Push Notifications is a failure, this callback is executed by the underlying platform.

The callback takes an Object as the parameter.

The following code snippet is an example of the onfailureregistration callback: function onfailure(errortable)

{ kony.print("Registration Failed"); kony.print(errortable["errorcode"]+errortable["errormessage]);

} onlinenotification

If the device receives a message when the application is running, this callback is executed by the underlying platform.

The callback takes an Object as the parameter.

Note: This function is not applicable on BlackBerry platform.

The following code snippet is an example of the onlinenotification callback: function onlineNotification(payload)

{

//payload is an Object that contains a set of key-value pairs provided by the respective Push Notification Server

Kony Studio API Developer's Guide

Version 3.1

} offlinenotification

If the device receives a message when the application is not running, this callback is executed by the underlying platform.

The callback takes an Object as the parameter.

Note: This function is not applicable on BlackBerry platform.

The following code snippet is an example of the offlinenotification callback: function offlineNotification(payload)

{

//payload is an Object that contains a set of key-value pairs provided by the respective Push Notification Server

} onsuccessfulderegistration

If the deregistration for Push Notifications is successful, this callback is executed by the underlying platform.

The callback takes string as the parameter.

The following code snippet is an example of the onsuccessfulderegistration callback: function onderegsuccess()

{ kony.print("Deregistered Successfully :");

}

Kony Studio API Developer's Guide

Version 3.1

onfailurederegistration

If the deregistration for Push Notifications is a failure, this callback is executed by the underlying platform.

The callback takes an Object as the parameter.

Note: This function is not applicable on iPhone platform.

The following code snippet is an example of the onfailurederegistration callback: function onderegfailure(errortable)

{ kony.print("Deregistration Failed"); kony.ui.Alert("Message : " +errortable ["errorcode"]+errortable

["errormessage"],null,"info",null,,"Info");

}

JavaScript Example function regSuccessAndroidCallback(regId)

{ kony.print("** JavaScript regSuccessCallback() called **"); kony.print(regId);

} function regFailureAndroidCallback(errormsg)

{ kony.print("* JavaScript regFailureCallback() called *"); kony.print(errormsg["failurereason"]); kony.print(errormsg["description"]);

} function onlinePushNotificationAndroidCallback(msg)

Kony Studio API Developer's Guide

Version 3.1

{

*"); kony.print("* JavaScript onlinePushNotificationCallback() called kony.print(msg); kony.print(msg["message"]);

} function offlinePushNotificationAndroidCallback(msg)

{ kony.print("* JavaScript offlinePushNotificationCallback() called

*"); kony.print(msg);

} function unregSuccessAndroidCallback()

{ kony.print("* JavaScript unregSuccessCallback() called *");

} function unregFailureAndroidCallback(errormsg)

{ kony.print("* JavaScript unregFailureCallback() called *"); kony.print(errormsg["errorcode"]); kony.print(errormsg["errormessage"]);

} function callbackAndroidSetCallbacks()

{ kony.push.setCallbacks({onsuccessfulregistration: regSuccessAndroidCallback, onfailureregistration: regFailureAndroidCallback,

Kony Studio API Developer's Guide

Version 3.1

onlinenotification: onlinePushNotificationAndroidCallback, offlinenotification: offlinePushNotificationAndroidCallback, onsuccessfulderegistration: unregSuccessAndroidCallback, onfailurederegistration: unregFailureAndroidCallback});

}

Platform Availability

Available on Android, iPhone, iPad, Windows, BlackBerry, and BlackBerry 10.

3.32 kony.store Namespace

The kony.store provides the following API elements.

Functions

3.32.1 Functions

The kony.store namespace provides the following functions.

3.32.1.1 kony.store.clear

This API allows you to empty the database by clearing all the key-value pairs. If there are no key-value pairs, then the API does not do anything.

Signature

JavaScript : kony.store.clear()

Parameters

None

Return Values

None.

Kony Studio API Developer's Guide

Version 3.1

Exceptions

LocalStorageError

Error

Implementation Details

For implementation details, see http://www.w3.org/TR/webstorage/#the-localstorage-attribute .

Platform Availability

Available on all platforms*. *Dummy Implementation on Mobile Web.

JavaScript Example try

{

} catch(err)

{ kony.store.clear(); alert("store is cleared"); alert("error occurred in clear() and the error is :"+err);

}

3.32.1.2 kony.store.getItem

This API returns a structured clone of the current value associated with the given key. If the given key does not exist in the list associated with the object then this method returns null for JavaScript.

Signature

JavaScript : kony.store.getItem(

keyname )

Parameters keyname [String] - Mandatory

Specifies the keyname from which the item needs to be fetched.

Kony Studio API Developer's Guide

Version 3.1

Return Values myitem [Object]

Returns the item located at the specified index.

Exceptions

LocalStorageError

Error

Implementation Details

For implementation details, see http://www.w3.org/TR/webstorage/#the-localstorage-attribute .

Platform Availability

Available on all platforms*. *Dummy Implementation on Mobile Web.

JavaScript Example var myValue = kony.store.getItem("name"); alert("name is "+myValue); kony.store.removeItem

This API removes the item identified by the key, if it exists. If no item with that key exists, the method does not perform any action.

Signature

JavaScript

:kony.store.removeItem( keyname

)

Parameters keyname [String] - Mandatory

Specifies the keyname for which the item needs to be removed.

Return Values

This API does not return a value.

Kony Studio API Developer's Guide

Version 3.1

Exceptions

LocalStorageError

Error

Implementation Details

For implementation details, see http://www.w3.org/TR/webstorage/#the-localstorage-attribute .

Platform Availability

Available on all platforms*. *Dummy Implementation on Mobile Web.

JavaScript Example kony.store.removeItem("name"); alert("name removed");

3.32.1.3 kony.store.key

This API returns the name of the n th key in the list. If n is greater than the number of key/value pairs in the object, then this method returns null for JavaScript.

Signature kony.store.key(

index )

Parameters index [Number] - Mandatory

Specifies the index for which the key name is to be returned.

Return Values keyname [String]

Returns the keyname of the specified index.

Kony Studio API Developer's Guide

Version 3.1

null/nil

Returns null/nil when the specified index is greater than the number of key/value pairs in the object.

Exceptions

LocalStorageError

Error

Implementation Details

For implementation details, see http://www.w3.org/TR/webstorage/#the-localstorage-attribute .

Platform Availability

Available on all platforms*. *Dummy Implementation on Mobile Web.

JavaScript Example var keyName = kony.store.key(0); alert("first key name is "+keyName);

3.32.1.4 kony.store.setItem

This API creates a structured clone of the given value. If this raises an exception then the list associated with the object is left unchanged.

Signature

JavaScript : kony.store.setItem(

key

value )

Parameters key [string] - Mandatory

Specifies the keyname for which the item needs to be set

Kony Studio API Developer's Guide

Version 3.1

value [object] - Mandatory

Specifies the value that must be set at the given index. This value can be a number, string,

Boolean.

Return Values

None.

Exceptions

LocalStorageError

Error

Implementation Details

For implementation details, see http://www.w3.org/TR/webstorage/#the-localstorage-attribute .

Platform Availability

Available on all platforms*. *Dummy Implementation on Mobile Web.

JavaScript Example kony.store.setItem("keyValue5", "this is a key value"); kony.store.setItem("keyValue4", true); kony.store.length

This API returns the length of the local storage.

Signature

JavaScript

: kony.store.length()

Parameters

None

Kony Studio API Developer's Guide

Version 3.1

Return Values mylength [String]

Returns the length of the local storage.

Exceptions

LocalStorageError

Error

Implementation Details

For implementation details, see http://www.w3.org/TR/webstorage/#the-localstorage-attribute .

Platform Availability

Available on all platforms*. *Dummy Implementation on Mobile Web.

JavaScript Example mylength = kony.store.length(); alert("length is "+mylength);

3.33 kony.stream Namespace

The kony.stream namespace, which forms the

Streaming API , provides the following API elements

Functions

3.33.1 Functions

The kony.stream namespace provides the following functions.

3.33.1.1 kony.stream.deregisterDataStream

This API allows you to deregister the application that was registered earlier with the Streaming Server.

Kony Studio API Developer's Guide

Version 3.1

Use Case

Use this API when you want to discontinue an application from streaming the data from a streaming server.

Signature

JavaScript: kony.stream.deregisterDataStream(

streamingidentifier

)

Input Parameters streamingidentifer [String] - Mandatory

Streaming identifier returned during registration.

Return Values

None.

Exceptions: l

StreamingError l

Error

Platform Availability

Available on all platforms except BlackBerry 10, Desktop Web and Windows Kiosk*. *Dummy

Implementation on Mobile Web.

JavaScript Example function deregisterDataStream()

{

//Defining config parameters to register stream.

var configParams = {url:"http//www.mobilestreaming.kony.com", method:"post"};

Kony Studio API Developer's Guide

Version 3.1

//Registers stream var streamObj = kony.stream.registerDataStream("http1.1", configParams, "json", myCallbackFunction);

//Reading the stream ID alert("Stream id is ::"+streamObj["streamID"]);

Windows

//Deregisters the data stream with the specified identifier on

Phone var status = kony.stream.deregisterDataStream(streamObj

["streamID"]);

//Reading the status alert("Status is ::"+status);

}

3.33.1.2 kony.stream.registerDataStream

This API registers the application for streaming with the OS provider of the underlying platform.

Signature

JavaScript: kony.stream.registerDataStream(

Input Parameters protocol [String] - Mandatory

Specifies the underlying streaming protocol to be used. Kony currently supports only HTTP1.1

protocol.

configparams [Table] - Mandatory

Specifies an Object with key-value pairs of configuration parameters required for the underlying

Kony Studio API Developer's Guide

Version 3.1

protocol.

The following are the configuration parameters for HTTP1.1 protocol: l url [String] - Mandatory: Specifies the URL of the streaming server of a web site that has data that can be streamed. For example: url="http://www.mobilestreaming.kony.com.

l cookie [Object] - Optional:Specifies an Object with the following key-value pairs: o streamingid (String) o jessessionid (String) cookie={streamingid:"12218181agdgdhjhjd", jessessionid:"198181819919agagah1t1g1"} l headers [Object] - Optional: Specifies the header parameters.

//For example: {authmode:basic} l params [Object] - Optional: Specifies any additional parameters.

For example: {quote:"goog"} l method [String] - Mandatory: Specifies the method. Possible values are:

get

post(Default value is post)

For example: "post" outputformat [String] - Mandatory.

Specifies the output format of the stream. Currently supported values are: l

String (default) l

JSON

Kony Studio API Developer's Guide

Version 3.1

Note:

If JSON is the output format specified, output from the streaming server is converted to an

Object and is passed as an input parameter to the callback function.

callback [Function] - Mandatory.

Specifies the function that needs to be executed when the streaming data is available.

Note: This function is also executed incase of any network error or system error in listening to the data stream.

The callback function has the following signature:

callbackFunction( status

data , context )

l status[Number] - indicates the status of the streaming operation. Possible values are: o

0 - indicates success o

1011 - Device has no wifi or mobile connectivity. Please try the operation after establishing connectivity.

1012 - Request Failed .This is a generic error and is thrown if the platform is not able to differentiate between various errors.

1014 - Request timed out o

1015 - Cannot find host.

1016 - Cannot connect to host.

1002 - Error reading from stream.

1019 - Error writing into stream.

1020 - End of stream with errors.

1021 - End of stream.

Kony Studio API Developer's Guide

Version 3.1

l data[Object or String] - If the output format is JSON it is an Object and if the output format is string, it is a String. Incase of any error, data will be null/nil.

l context[Object] - Contains additional information that needs to be passed to the underlying streaming API. For HTTP1.1 protocol, this table contains a value httpresponsecode.

Return Values

StreamID [String]

Stream identifier for this registration. This identifier is to be used during deregistration. Null incase there is any input error for a JavaScript application.

Exceptions l

StreamingError: Error thrown by Streaming API. Various error conditions related to Stream

Error will be covered through following error codes.

Error

Platform Availability

Available on all platforms except BlackBerry 10, Desktop Web and Windows Kiosk*. *Dummy

Implementation on Mobile Web.

JavaScript Example function myCallbackFunction(status, data, context)

{

//Execute the logic here

} function registerDataStream()

{

//Defining config parameters to register stream.

var configParams =

{url:"http//www.mobilestreaming.kony.com",method:

"post"};

Kony Studio API Developer's Guide

Version 3.1

//Registers stream var streamObj = kony.stream.registerDataStream("http1.1", configParams, "json", myCallbackFunction);

//Reading the stream ID alert("Stream id is ::"+streamObj["streamID"]);

}

3.33.1.3 kony.stream.setCallback

This API specifies the callback function that needs to be executed for a registered data stream.

Signature

JavaScript:

kony.stream.setCallback( streamingid

callbackfunction )

Input Parameters streamingid [String] - Mandatory

Specifies the unique ID that identifies the stream.

callbackfunction [Function] - Mandatory

Specifies the callback function that needs to be executed.

Return Values

None

Exceptions l

StreamingError: Error thrown by Streaming API. Various error conditions related to Stream

Error will be covered through following error codes.

Error

Kony Studio API Developer's Guide

Version 3.1

Platform Availability

Available on all platforms except BlackBerry 10, Desktop Web and Windows Kiosk*. *Dummy

Implementation on Mobile Web.

JavaScript Example

//Callback function for setCallback function myCallbackFunction1(status, data, context)

{

//Execute the logic here

} function setCallback()

{

//Invoking setCallback with the streamID :"1" kony.stream.setCallback("1", myCallbackFunction1);

}

3.34 kony.string Namespace

The kony.string namespace forms the String API and provides the following API elements.

Functions

3.34.1 Functions

The kony.string namespace provides the following functions.

3.34.1.1 kony.string.containsChars

This API verifies if any one of the specified set of characters is available in the given string and returns a boolean value.

Kony Studio API Developer's Guide

Version 3.1

Signature

JavaScript: kony.string.containsChars (

inputstring , characterArray )

Input Parameters inputstring [String] - Mandatory

Specifies the input string that needs to be verified.

characterArray [Array] - Mandatory

Specifies the set of characters that need to be searched within the input string.

Return Values status [Boolean] true - if the given input string contains any one of the characters in the specified list.

false - if there is an error in the input or if the given input string does not contain any of the specified input characters.

Exceptions

An error is thrown if input type is invalid or follows an unexpected structure.

102-Invalid input error.

Platform Availability

Available on all platforms.

JavaScript Example

In this example, kony.string.containsChars returns true if the input string consists the characters specified in the characterArray. For example, since the input string

"abcd|ADV" consists the characters specified in the character array, kony.string.containsChars returns true.

Kony Studio API Developer's Guide

Version 3.1

var inputstring = "abdcdADV"; var charsArr = ["|","-"]; kony.print(kony.string.containsChars(inputstring, charsArr));

// prints false as | and - are NOT contained in the input var inputstring = "abdcd|ADV" kony.print(kony.string.containsChars(inputstring, charsArr));

// prints true as | is contained in the input

3.34.1.2 kony.string.containsOnlyGivenChars

This API verifies if only (and only) the specified set of characters is available in the given string and returns a boolean value.

Signature

JavaScript: kony.string.containsOnlyGivenChars (

inputstring , characterArray )

Input Parameters inputstring [String] - Mandatory

Specifies the input string that needs to be verified.

characterArray [Array] - Mandatory

Specifies the set of characters that need to be searched within the input string.

Return Values status [Boolean] true - if the given input string contains only the characters in the specified list.

false - if there is an error in the input or if the given input string contains any other characters apart from the specified input characters.

Kony Studio API Developer's Guide

Version 3.1

Exceptions

An error is thrown if input type is invalid or follows an unexpected structure.

102-Invalid input error.

Platform Availability

Available on all platforms.

JavaScript Example

In this example, kony.string.containsOnlyGivenChars returns true only if the input string consists the characters specified in the characterArray. For example, since the input string "abdcdADV" consists only the characters specified in the character array, kony.string.containsOnlyGivenChars returns true.

//Test case where API returns true var inputStr = "abdcdADV"; var charsArr = ["a","b", "d", "c", "A", "D", "V"]; var resultantString = kony.string.containsOnlyGivenChars

(inputStr,charsArr); frmContainsOnlyGivenChars.containsOnlyGivenCharsLabel.text = resultantString;

//Test case where API returns false var inputStr = "abdcdADH"; var charsArr = ["a","b", "d", "c", "A", "D", "V"]; var resultantString = kony.string.containsOnlyGivenChars

(inputStr,charsArr); frmContainsOnlyGivenChars.containsOnlyGivenCharsLabel.text = resultantString;

Kony Studio API Developer's Guide

Version 3.1

3.34.1.3 kony.string.containsNoGivenChars

This API verifies that the input string does not contain any of the specified characters and returns a boolean value.

Signature

JavaScript:

kony.string.containsNoGivenChars ( inputstring , charsArray

)

Input Parameters inputstring [String] - Mandatory

Specifies the input string that needs to be verified.

charsArray [Array] - Mandatory

Specifies the set of characters that need to be searched within the input string.

Return Values status [Boolean] true - if the given input string contains none of the characters in the specified list.

false - if there is an error in the input or if the given input string contains any of the specified input characters.

Exceptions

An error is thrown if input type is invalid or follows an unexpected structure.

102-Invalid input error.

Platform Availability

Available on all platforms.

Kony Studio API Developer's Guide

Version 3.1

JavaScript Example

In this example, kony.string.containsNoGivenChars returns true only if the input string does not consist the characters specified in the characterArray. For example, since the input string "abdcdADV" consists none of the characters specified in the character array, kony.string.containsNoGivenChars

returns true.

var inputstring = "abdcdADV"; var charsArr = ["|","-"]; kony.print(kony.string.containsNoGivenChars(inputstring, charsArr));

//prints true as string does not contain the given characters

(| and - are NOT contained in the input) var inputstring = "abdcd|ADV"; var charsArr = ["|","-", "a" ]; kony.print(kony.string.containsNoGivenChars(inputstring, charsArr));

//prints false as string contains the given character "a".

3.34.1.4 kony.string.endsWith

This API returns a boolean value indicating if the source string ends with the specified string.

Signature

JavaScript: kony.string.endsWith(

sourcestring

comparestring ,

ignorecase

)

Input Parameters sourcestring [String] - Mandatory

Specifies the source string.

comparestring [String] - Mandatory

Specifies the string to be compared with the source string.

Kony Studio API Developer's Guide

Version 3.1

ignorecase [Boolean] - Optional

Default value is true, i.e, the comparison is not case sensitive.

If you want the comparison to be case sensitive, you must specify the value as false.

Return Values boolean true - source string ends with compared string.

false - source string does not end with compared string.

Platform Availability

Available on all platforms.

JavaScript Example

//Returns true since comparison is not case sensitive.The resultant is assigned to a label text.

var resultantString = kony.string.endsWith("Kony

Solutions","solutions",true); frmEndsWith.endsWithLabel.text = resultantString;

3.34.1.5 kony.string.equalsIgnoreCase

Determines whether two strings contain the same data, ignoring the case of the letters in the String.

Signature

JavaScript:

kony.string.equalsIgnoreCase( string1

string2 )

Input Parameters string1 [String] - Mandatory

Specifies the content of the first string.

Kony Studio API Developer's Guide

Version 3.1

string2 [String] - Mandatory

Specifies the content of the second string.

Return Values boolean true - both strings contain exactly the same data.

false - both strings do not contain exactly the same data

Platform Availability

Available on all platforms.

JavaScript Example

Perform a kony.string.equalsIgnoreCase on the string "Hello" with another string "HEllo": var ignorecase = kony.string.equalsIgnoreCase("Hello","HEllo") kony.print (ignorecase);

The kony.string.equalsIgnoreCase compares the strings "Hello" and "HEllo" without case sensitivity and returns a Boolean indicating if the strings are a match.

In this example, true is the value returned.

3.34.1.6 kony.string.isAsciiAlpha

This API verifies if the input string contains only ASCII alphabet characters and returns a boolean value.

Signature

JavaScript:

kony.string.isAsciiAlpha ( inputstring

)

Kony Studio API Developer's Guide

Version 3.1

Input Parameters inputstring [String] - Mandatory

Specifies the input string that needs to be verified.

Return Values status [Boolean] true - if the input string contains only alphabetic characters.

false - if there is an error in the input or the input string contains characters other than alphabet.

Exceptions

An error is thrown if input type is invalid or follows an unexpected structure.

102-Invalid input error.

Platform Availability

Available on all platforms.

JavaScript Example

In this example, the kony.string.isAsciiAlpha API returns true or false based on the input string entered.

var inputstring = "abdcdADV"; kony.print(kony.string.isAsciiAlpha(inputstring));

//prints true var inputstring = "123ab3dcdADV"; kony.print(kony.string.isAsciiAlpha(inputstring));

//prints false

Kony Studio API Developer's Guide

Version 3.1

3.34.1.7 kony.string.isAsciiAlphaNumeric

This API verifies if the input string contains only ASCII alphabet characters and numbers, and returns a boolean value.

Signature

JavaScript: kony.string.isAsciiAlphaNumeric (

inputstring

)

Input Parameters inputstring [String] - Mandatory

Specifies the input string that needs to be verified.

Return Values status [Boolean] true - if the input string contains only alphanumeric characters. i.e it can contain a string of numbers, characters or a string containing both numbers and characters.

false - if there is an error in the input or the input string contains characters other than alphanumeric.

Exceptions

An error is thrown if input type is invalid or follows an unexpected structure.

102-Invalid input error.

Platform Availability

Available on all platforms.

JavaScript Example

In this example, kony.string.isAsciiAlphaNumeric returns true or false based on the input string.

Kony Studio API Developer's Guide

Version 3.1

var inputstring = "abdcdADV"; kony.print(kony.string.isAsciiAlphaNumeric(inputstring));

//prints false because the string is not a combination of alphanumeric characters var inputstring ="abcd1234" kony.print(kony.string.isAsciiAlphaNumeric (inputstring));

//prints true because the string is a combination of alphanumeric characters

3.34.1.8 kony.string.isNumeric

This API verifies if the input string contains only numeric characters, and returns a boolean value.

Signature

JavaScript: kony.string.isNumeric (

inputstring

)

Input Parameters inputstring [String] - Mandatory

Specifies the input string that needs to be verified.

Return Values status [Boolean] true - if the input string contains only numeric characters.

false - if there is an error in the input or the input string contains characters other than numbers.

Exceptions

An error is thrown if input type is invalid or follows an unexpected structure.

102-Invalid input error.

Kony Studio API Developer's Guide

Version 3.1

Platform Availability

Available on all platforms.

JavaScript Example

In this example, kony.string.isNumeric returns true if the input string has only numbers.

kony.print(kony.string.isNumeric("123ab3dcdADV"));

// prints false kony.print(kony.string.isNumeric("12344")) ;

// prints true

3.34.1.9 kony.string.isValidEmail

This API verifies if the input string is a valid email address and returns a boolean value.

Signature

JavaScript: kony.string.isValidEmail (

inputstring

)

Input Parameters inputstring [String] - Mandatory

Specifies the input string that needs to be verified if it is a valid email address.

Return Values status [Boolean] true - if the given input string satisfies the email rules and is a valid email address.

false - if there is an error in the input or if the given input string does not satisfy email rules.

Rules and Restrictions

The API performs the following validations on the input string:

Kony Studio API Developer's Guide

Version 3.1

l has at least 6 characters.

l has @.

l has at least 4 characters after @.

l has . (dot) followed by at least 2 characters.

l has at least 1 character before @.

Exceptions

An error is thrown if input type is invalid or follows an unexpected structure.

Platform Availability

Available on all platforms.

JavaScript Example

In this example, kony.string.isValidEmail returns true only if the input string comprises a valid email address.

var inputstring = "abcd@"; kony.print(kony.string.IsValidEmail(inputstring));

//prints false as there are no chars after @ var inputstring = "abcd@tccc" kony.print(kony.string.IsValidEmail(inputstring));

//prints false as the chars after @ does not have . followed by at least 2 chars

3.34.1.10 kony.string.rep

This API generates a string which is equivalent to " n copies of the source string concatenated together".

Kony Studio API Developer's Guide

Version 3.1

Signature

JavaScript: kony.string.rep(

sourcestring , no

)

Input Parameters sourcestring [String] - Mandatory

Specifies the source string.

no [Number] - Mandatory

Specifies the number of times the source string must be repeated.

Return Values concatenatedstring [String]

A string containing n copies of the source string concatenated together is returned

Exceptions

An error is thrown if input type is invalid or does not follow the expected structure.

102-Invalid input error.

Platform Availability

Available on all platforms.

JavaScript Example

Perform a kony.string.rep operation on the source string "kony": var resultantString = kony.string.rep("kony",5); frmRep.concatenatedStringLabel.text = resultantString;

The resultant string contains konykonykonykonykony.

Kony Studio API Developer's Guide

Version 3.1

3.34.1.11 kony.string.reverse

This API reverses the characters in the source string.

Signature

JavaScript: kony.string.reverse(

string

)

Input Parameters string [String] - Mandatory

Specifies the source string.

Return Values reversedstring [String]

A string containing the characters of the source string in reverse is returned.

Exceptions

An error is thrown if input type is invalid or does not follow the expected structure.

102-Invalid input error

Platform Availability

Available on all platforms.

JavaScript Example

Perform a reverse operation on the source string "kony": var resultantString = kony.string.reverse("kony"); frmReverse.reversedStringLabel.text = resultantString;

The resultant string will contain ynok.

Kony Studio API Developer's Guide

Version 3.1

3.34.1.12 kony.string.startsWith

This API returns a boolean value indicating if the source string begins with the specified string.

Signature

JavaScript: kony.string.startsWith(

sourcestring

comparestring , ignorecase

)

Input Parameters sourcestring [String] - Mandatory

Specifies the source string.

comparestring [String] - Mandatory

Specifies the string to be compared with the source string.

ignorecase [Boolean] - Optional

Default value is true. If you do not specify the ignorecase parameter, the comparison of the string will be case insensitive. If you want the comparison to be case sensitive, you must specify the value as false.

Return Values boolean true - source string begins with the compared string.

false - source string does not begin with the compared string.

Exceptions

An error is thrown if input type is invalid or does not follow the expected structure.

102-Invalid input error.

Platform Availability

Available on all platforms.

Kony Studio API Developer's Guide

Version 3.1

JavaScript Example

Perform a kony.string.startsWith on the source string "Kony Solutions" for the string "kony" specifying the ignorecase parameter: var resultantString = kony.string.startsWith("Kony

Solutions","kony",true); frmStartsWith.startsWithLabel.text = resultantString;

The kony.string.startsWith compares the source string "Kony Solutions" with the string "kony" without case sensitivity and returns a boolean indicating if the source string begins with the specified string.

In this example, true is the value returned.

3.34.1.13 kony.string.trim

This API removes the leading and ending spaces from the source string.

Signature

JavaScript: kony.string.trim(

string

)

Input Parameters string [String] - Mandatory

Specifies the source string.

Return Values trimmedstring [String]

A string without the leading and ending spaces is returned.

Exceptions

An error is thrown if input type is invalid or does not follow the expected structure.

102-Invalid input error

Kony Studio API Developer's Guide

Version 3.1

Platform Availability

Available on all platforms.

JavaScript Example

Remove the leading and ending spaces in " kony solutions ": var resultantString = kony.string.trim("

"); kony solutions frmTrim.trimmedStringLabel.text = "\""+resultantString+"\"";

In this example, kony solutions is the value returned.

3.35 kony.theme Namespace

The kony.theme namespace implements the

Theme API . It contains the following API elements.

Functions

3.35.1 Functions

The kony.theme namespace provides the following functions.

3.35.1.1 kony.theme.createTheme

This API enables you to create a theme.

Signature

JavaScript

: kony.theme.createTheme(

)

Kony Studio API Developer's Guide

Version 3.1

Input Parameters url [String] - Mandatory

Specifies a string (URL) from which the theme is to be downloaded. The theme is represented as a JSON object.

Note: If the JSON object contains invalid skin attributes, the platforms use the default attributes (platform specific and may vary from platform to platform).

themeIdentifier [String] - Mandatory

Specifies a flag that indicates if the current theme must be replaced with the same identifier or use the theme only in the current session.

onsuccesscallback [Function]-Mandatory

Specifies the callback function that needs to be executed in case of success. This callback function is executed after the theme is created.

onerrorcallback [Function] - Mandatory

Specifies the callback function that needs to be executed in case of error. This callback function has the following signature: onerrorcallback (errorcode,errormessage) l errorcode - the error code thrown if there was a problem while creating the theme l errormessage - the error message that corresponds to the error code.

Exceptions o

1900- SkinError. This error occurs when there is an error related to skin.

Error - This error is thrown when there is a generic error.

Platform Availability

Available on all platforms except BlackBerry 10.

Kony Studio API Developer's Guide

Version 3.1

For SPA, Desktop Web, and Mobile Web ensure that the URL mentioned in the createTheme API should point only to a CSS file. The platforms do not support a URL with a .Theme file and convert it into a CSS file at run time.

JavaScript Example function onsuccesscallback()

{ alert("successfully set the theme to app")

} function onerrorcallback()

{ alert("Theme is not set to the app")

} kony.theme.createTheme("", "Mytheme", onsuccesscreatecallback,onerrorcreatecallback);

3.35.1.2 kony.theme.createThemeFromJSONString

This API enables you to create or replace a JSON string theme in the current session.

Signature

JavaScript

: kony.theme.createThemeFromJSONString( jsonString ,

themeIdentifier , onsuccesscallback

onerrorcallback

)

Input Parameters jsonString [String] - Mandatory

A well defined theme JSON string with which theme is created. The theme is represented as a

JSON object.

Kony Studio API Developer's Guide

Version 3.1

Note:

If the JSON object contains invalid skin attributes, the platforms use the default attributes (platform specific and may vary from platform to platform).

themeIdentifier [String] - Mandatory

Specifies an identifier with which current theme must be created or replace if the theme is already exists and this theme will be available only in the current session.

Note: The theme will not be created and an error callback is called, if null or undefined or non-string themeIdentifier is provided.

onsuccesscallback [Function]- Optional

Specifies the callback function that needs to be executed in case of success. This callback function is executed after the theme is created.

Note: The theme will be created but the successcallback is not called, if null or undefined successcallback is provided.

onerrorcallback [Function] - Optional

Exceptions o

1900- SkinError. This error occurs when there is an error related to skin.

Error - This error is thrown when there is a generic error.

Kony Studio API Developer's Guide

Version 3.1

Platform Availability

Available on iOS, Android, and Windows platforms.

JavaScript Example function testCreateThemeFormJSONString() { function onsuccesscallback() { alert("successfully created theme.")

} function onerrorcallback(errorcode, errormessage) { alert("Unable to create theme.")

} var jsonString = '{"btnNormal": { "wtype":"Button","bg_type" :

"one","background_color" : "ff000000","font_weight" : "bold","font_ size" : 120,"font_color" : "314e8900","font_name" : "Arial-

BoldMT","border_color" : "9f9f9f00","border_width" : 1,"border_ style" : "rc","shadow" :

{"x":0,"y":0,"br":0,"color":"00000000","inner":false},"text_shadow"

:{"x":0,"y":0,"br":0,"color":"00000000"}}}'; kony.theme.createThemeFromJSONString(jsonString, "MyTheme1", onsuccesscallback, onerrorcallback);

}

3.35.1.3 kony.theme.deleteTheme

This API allows you to delete a specified theme in the application programmatically.

Important:

Kony Studio API Developer's Guide

Version 3.1

On all Platforms, pre-bundled themes in the application cannot be deleted, but only the themes created through createTheme API, which are in memory, can be deleted.

On Windows Platforms, only the themes created using the createTheme API can be deleted.

Pre-bundled themes and currently used theme cannot be deleted.

Signature

JavaScript : kony.theme.deleteTheme(

themeidentifier

onsuccesscallback

onerrorcallback )

Input Parameters themeidentifier [String] - Mandatory

Specifies a string that denotes the theme ID. The specified theme will be deleted from the application.

onsuccesscallback [Function] - Mandatory

Specifies the callback function that needs to be executed in case of success. This callback function is executed after the theme is deleted.

onerrorcallback [Function] - Mandatory

Exceptions o

1900- SkinError. This error occurs when there is an error related to skin.

Error - This error is thrown when there is a generic error.

Kony Studio API Developer's Guide

Version 3.1

Platform Availability

Available on all platforms except Server side Mobile Web.

JavaScript Example kony.theme.deleteTheme ("green");

3.35.1.4 kony.theme.getAllThemes

This API returns all the themes available in the application.

Signature

JavaScript

: kony.theme.getAllThemes()

Input Parameters

None

Return Values

JavaScript: Array

Returns an array with a list of all theme Identifiers available in the application.

Exceptions o

1900- SkinError. This error occurs when there is an error related to skin.

Error - This error is thrown when there is a generic error.

Platform Availability

Available on all platforms.

Kony Studio API Developer's Guide

Version 3.1

JavaScript Example var themes=kony.theme.getAllThemes(); alert("No Of themes are "+themes.length);

3.35.1.5 kony.theme.getCurrentTheme

This API returns the current theme that is applied to the application.

Signature

JavaScript: kony.theme.getCurrentTheme()

Input Parameters

None

Return Values themeID[String]

Returns the identifier of the current theme that is applied to the application

Exceptions o

1900- SkinError. This error occurs when there is an error related to skin.

Error - This error is thrown when there is a generic error.

Platform Availability

Available on all platforms.

JavaScript Example var crntTheme=kony.theme.getCurrentTheme(); alert("current theme is:"+crntTheme+" And the type is "+typeof

Kony Studio API Developer's Guide

Version 3.1

(crntTheme));

3.35.1.6 kony.theme.getCurrentThemeData

This API returns the meta data of the current theme in the application.

Signature

JavaScript: kony.theme.getCurrentThemeData()

Input Parameters

None

Return Values metadata [Object]

Returns an object that contains the metadata of the current theme in the application

Exceptions o

1900- SkinError. This error occurs when there is an error related to skin.

Error - This error is thrown when there is a generic error.

Platform Availability

Available on all platforms except SPA, and Mobile Web.

For SPA, Desktop Web, Windows 7 Kiosk, and Mobile Web, this API will always return null. As theme files are converted into CSS, the platforms cannot have custom structures/variables in CSS files as browsers will fail to parse them.

Kony Studio API Developer's Guide

Version 3.1

JavaScript Example var crntThemeData=kony.theme.getCurrentThemeData(); alert("Current Theme Data is :"+crntThemeData);

3.35.1.7 kony.theme.isThemePresent

This API allows you to check the existence of specific theme in the application.

Signature

JavaScript: kony.theme.isThemePresent(

themeidentifier )

Input Parameters themeidentifier [String] - Mandatory

Specifies a string that represents a theme.

Return Values status [Boolean]

Returns the status of the execution of this API.

l true - if the specified theme is present in the application.

l false - if the specified theme does not exist in the application.

Exceptions o

1900- SkinError. This error occurs when there is an error related to skin.

Error - This error is thrown when there is a generic error.

Platform Availability

Available on all platforms

Kony Studio API Developer's Guide

Version 3.1

JavaScript Example var isThemePresent=kony.theme.isThemePresent("green"); alert("IS theme present ? True/False: "+isThemePresent);

3.35.1.8 kony.theme.setCurrentTheme

This API allows you to apply a specified theme to the application at runtime.

Signature

JavaScript : kony.theme.setCurrentTheme (

themeidentifier

onsuccesscallback

onerrorcallback

)

Input Parameters themeidentifier [String] - Mandatory

Specifies a string that denotes the theme ID. The specified theme is applied to the application.

onsuccesscallback [Function] - Mandatory

Specifies the callback function that needs to be executed in case of success. This callback function is executed after applying the specified theme.

onerrorcallback [Function] - Mandatory

Specifies the callback function that needs to be executed in case of error. This callback function has the following parameters: l errorcode - the error code thrown if there was a problem while applying the specified theme l errormessage - the error message that corresponds to the error code.

This callback function is executed if there is an error while applying the specified theme.

Kony Studio API Developer's Guide

Version 3.1

Exceptions o

1900- SkinError. This error occurs when there is an error related to skin.

Error - This error is thrown when there is a generic error.

Platform Availability

Available on all platforms.

JavaScript Example function onsuccesscallback()

{ alert("successfully set the theme to app")

} function onerrorcallback(1900, "Skin Error")

{ alert("Skin does not exist")

} kony.theme.setCurrentTheme("red",onsuccesscallback,onerrorcallback);

3.36 kony.timer Namespace

The kony.timer namespace implements the

Timer API . It contains the following API elements.

Functions

3.36.1 Functions

The kony.timer namepace provides the following functions.

3.36.1.1 kony.timer.cancel

This API cancels the timer that has already been scheduled for execution.

Kony Studio API Developer's Guide

Version 3.1

Signature

JavaScript: kony.timer.cancel(

timerid

)

Input Parameters timerid [String] - Mandatory

Specifies the unique ID that identifies the timer that needs to be canceled.

Return Values

None

Exceptions

Error

Error Codes l

100 - invalid arguments l

101 - internal error

Implementation Details

If the timer is waiting to be run, it will not be run the next time. If the timer is in the middle of execution, it will be allowed to complete and then canceled.

Platform Availability

Available on all platforms*. *Dummy Implementation on Mobile Web.

JavaScript Example function buttoncallback2()

{

Kony Studio API Developer's Guide

Version 3.1

try

{ kony.timer.cancel("mytimer");

} catch(err)

{ alert("error in second button onclick and err is:: "+err);

}

3.36.1.2 kony.timer.setCallBack

This API specifies the callback function that needs to be executed for a scheduled timer. The callback function handles the logic that needs to be executed after a scheduled timer was run successfully or the scheduled timer failed to execute. The setCallBack timer API is provided to override the existing time call back function which is defined in the "schedule" timer API.

Signature

JavaScript: kony.timer.setCallBack(

timerid , callbackfunction

)

Input Parameters timerid [String] - Mandatory

Specifies the unique ID that identifies the timer.

callbackfunction [Function] - Mandatory

Specifies the callback function that needs to be executed.

Return Values

None

Kony Studio API Developer's Guide

Version 3.1

Exceptions

Error

Platform Availability

Available on all platforms*. *Dummy Implementation on Mobile Web.

JavaScript Example

//nested function function timerFunc1()

{ alert("Timer invoked");

} kony.timer.setCallBack("mytimer",timerFunc1);

3.36.1.3 kony.timer.schedule

This API executes the given function after a specified interval of time.

Use Cases

You can use this API when you want to execute a function after a specified interval of time. i.e, for example to run a specific function for every 15 seconds.

Signature

JavaScript: kony.timer.schedule(

timerid

functionObj , interval

repeat

)

Input Parameters timerid [String] - Mandatory

Specifies the unique ID that identifies the timer.

Kony Studio API Developer's Guide

Version 3.1

functionObj [Function] - Mandatory

Specifies the function that needs to be executed.

interval [Number] - Mandatory

Specifies the time in seconds after which the function needs to be executed.

repeat [Boolean] - Mandatory

Specifies a flag that indicates if the function needs to executed once or repeated.

l true - indicates that the execution of the function needs to repeated at regular intervals l false - indicates that the function needs to be executed just once

Return Values

None

Exceptions

Error

Platform Availability

Available on all platforms*. *Dummy Implementation on Mobile Web.

JavaScript Example function timerFunc() //nested function

{ i=i+5; lbl1.text = i+" secs ";

} kony.timer.schedule("mytimer12",timerFunc, 5, true);

//The function timerFunc will be executed after every 5 seconds.

Kony Studio API Developer's Guide

Version 3.1

3.37 kony.types.RawBytes Namespace

Delete this text and replace it with your own content.

3.37.1 Objects

The kony.types namespace provides the following objects.

RawBytes

3.37.1.1 RawBytes Object

The RawBytes namespace represents the file content.

RawBytes

Properties:Name text: [type: String,

ReadOnly]

Description

UTF-8 representation of data in this RawBytes or null if this RawBytes represents a binary.

The following function is often used in conjunction with the RawBytes object to read data of type

RawBytes.

readAsText

3.38 kony.UI Namespace

The kony.UI namespace contains the following API elements.

Functions

Kony Studio API Developer's Guide

Version 3.1

Kony Studio API Developer's Guide

Version 3.1

3.38.1 kony.ui Namespace Functions

The kony.UI namespace contains the following functions.

kony.ui.Alert

This API provides you the ability to add alerts in the application. The alerts are of the following types: l information - an informative message is displayed on the screen. This message can be in turn a warning or a success message.

l confirmation - a confirmation message with Yes and No options is displayed on the screen.

l error - an error message is displayed on the screen.

All the alerts are modal in nature, i.e., the user cannot proceed with other UI operations unless the alert is dismissed.

Syntax kony.ui.Alert(

basicConfig,

pspConfig)

Parameters basicConfig basicConfig is an object with the following configuration properties: l message [String] - Mandatory: The message to be shown when an alert is thrown.

l alertType [Number] - Mandatory: Denotes the type of the alert. The possible values are as follows: o

ALERT_TYPE_CONFIRMATION o

ALERT_TYPE_ERROR o

ALERT_TYPE_INFO l alertTitle [String] - Optional: Title of the alert.

Kony Studio API Developer's Guide

Version 3.1

l yesLabel [String] - Optional: Text to be displayed for the Yes label. If the text for the Yes label is not provided, individual platforms display default values.

l noLabel [String] - Optional: Text to be displayed for the No label. If the text for the No label is not provided, individual platforms display default values.

l alertIcon [String] - Optional: Icon to be displayed to visually indicate the type of alert like -

Info, Error, Confirmation. This parameter is not supported on iPhone.

l alertHandler [Read / Write Event] - Mandatory: JavaScript function that should get called when alert is dismissed either through "yes" label button or through "no" label button.

pspConfig pspConfig is an object with platform specific configuration properties.

l ondeviceback [Write Event] - Optional: JavaScript function that should get called when alert is open and the device back button is pressed.

Note:

Supported on Windows Phone 8, Windows Phone 7.5 (Mango) channels and not supported on Windows Kiosk and Windows 8 channels.

{

} var pspConf = {ondeviceback:func1}; var confirmationAlert = kony.ui.Alert(basicConf, pspConf); function func1() kony.print("Example function on device back");

Note: The configuration properties should be passed only in the respective configuration objects otherwise they are ignored.

l contentAlignment: Used to align content of an alert. Following are the values of this property:

Kony Studio API Developer's Guide

Version 3.1

o contants.ALERT_CONTENT_ALIGN_LEFT // default o constants.ALERT_CONTENT_ALIGN_CENTER

o constants.ALERT_CONTENT_ALIGN_RIGHT

l iconPosition: It is used to align and alert title icon. Following are the values of this property: o constants.ALERT_ICON_POSITION_LEFT // default o constants.ALERT_ICON_POSITION_RIGHT

Note:

Click

here

to view a JavaScript example to create an alert using

contentAlignment

and

iconPostion

parameters.

Return Values

None.

Remarks

Invoking this API multiple times in the same action sequence leads to an erroneous behavior.

This API should be invoked at the end of a function as a best practice.

The following are the behavioral aspects of alerts on various platforms:

RichClient

In all native implementations alert is non blocking, i.e. the execution of any logic defined after the alert definition continues without the alert confirmation.

Important: Alert images are not supported on Windows 8 tablet.

Android

Android platform supports display of multiple alerts each time the kony.ui.Alert API is invoked. On device back, the alert gets dismissed and also the alert handler is raised.

Kony Studio API Developer's Guide

Version 3.1

For CONFIRMATION type alert, the alert callback is invoked with cancel flag. For example, false

Boolean argument.

For INFO & ERROR type alert, the alert callback is invoked with true argument.

iPhone iPhone does not support displaying image icons based on the alert types: info,confirmation, error.

"\n " as a newline character in the alert messages supported for iPhone Platform

Mobile Web/SPA/Desktop Web l

For advanced Mobile Web devices like iPhone, Android, and Palm Pre, alerts are displayed as popups. For basic devices, the alerts are displayed in a new page.

For all platforms you cannot customize alert icons/yes or no labels/ look and feel.

Titles of the alerts are provided by the browser and you cannot modify them. The alert title attribute does not apply for Mobile Web. Usually, the title on the alert will be the IP address or the domain name of the application.

Confirmation alerts in the basic devices will be displayed in another form.

If the alert message is nil

, alert is not displayed.

In case of all platforms, the execution of the logic defined after alert is blocked until the user clicks "yes" or "no".

For JavaScript conversion, an alert has to be created using another variant constructor,i.e an

Indexed argument constructor.

kony.ui.Alert(message, alertHandler, alertType, yesLabel, noLabel, alertTitle, pspConf).

Platform Availability

Available on all platforms.

Limitation on BlackBerry 10

The native alert dialog box does not support the use of icons.

Kony Studio API Developer's Guide

Version 3.1

Example

//Defining basicConf parameter for alert var basicConf = {message: "This is an info alert",alertType: constants.

ALERT_TYPE_INFO,alertTitle: "infoWithoutImage",yesLabel:"yes", noLabel: "no", alertHandler: handle2};

//Defining pspConf parameter for alert var pspConf = {};

//Alert definition var infoAlert = kony.ui.Alert(basicConf,pspConf); function handle2(response)

{ frm6.show();

} var pspConfig = {"iconPosition" : constants.ALERT_CONTENT_ALIGN_CENTER,

"contentAlignment":constants.ALERT_ICON_POSITION_LEFT } ; var alert = kony.ui.Alert({

"message": "Hello Alert",

"alertType": constants.ALERT_TYPE_ERROR,

"alertTitle": "I'm Alert",

"yesLabel": "Yes",

"noLabel": "",

"alertIcon": "",

"alertHandler": null

}, pspConfig);

Alerts are displayed on some platforms as follows:

Windows Phone Mango

Kony Studio API Developer's Guide

Version 3.1

BlackBerry STORM kony.ui.createAnimation Function

Creates an object that defines an animation.

Syntax kony.ui.createAnimation(

animationDefinition);

Parameters animationDefinition

An object that defines the transformations to perform during the animation.

Return Values

None.

Example var transformObject = kony.ui.makeAffineTransform(); transformObject.translate(10, 0); transformObject.scale(0.1, 1); animationDef = {

100: { transform": transformObject

Kony Studio API Developer's Guide

Version 3.1

}

} animationConfig = { duration: 0.3, fillMode: kony.anim.FILL_MODE_FORWARDS

} animationDefObject = kony.ui.createAnimation(animationDef); kony.ui.makeAffineTransform Function

Creates a transformation object that can be used in an animation definition.

Syntax kony.ui.makeAffineTransform();

Parameters

None.

Return Vales

An object that can be used to specify a transformation.

Example var transformObject = kony.ui.makeAffineTransform(); transformObject.translate(10, 0); transformObject.scale(0.1, 1); animationDef = {

100: {

"transform": transformObject

}

Kony Studio API Developer's Guide

Version 3.1

3.39 kony.worker Namespace

The kony.worker namespace implements the

Worker Thread API

. It contains the following API elements.

Functions

3.39.1 Functions

The kony.worker namespace provides the following functions.

hasWorkerThreadSupport

This API is used during runtime only in parent scope to determine whether the current platform environment has worker thread support.

This API is most useful in case of SPA and Desktop Web platforms where runtime query can be made to determine whether a browser environment supports Worker Threads or not.

Signature kony.worker.hasWorkerThreadSupport()

Parameters

None

Return Values

Boolean true

: When worker thread support is present.

false : When worker thread support is not present.

Platform Availability

Available for iOS, Android, Windows, SPA, and Desktop Web. For more information, see

Scope .

Kony Studio API Developer's Guide

Version 3.1

JavaScript Example var hasWorkerSupport = kony.worker.hasWorkerThreadSupport(); if (hasWorkerSupport) { var worker = new kony.worker.WorkerThread("worker1.js");

//do something

} else {

//workers not supported

} kony.worker.WorkerThread

The kony.worker.WorkerThread function creates a WorkerThread object and returns a handle to it. The worker object represents a worker thread.

Syntax kony.worker.WorkerThread(

workerjs);

Parameters workerjs

A string that contains either the name of javascript file name or functional module name which contains worker thread code.

Return Values

Returns a WorkerThread object.

Exceptions

When an error is encountered, the KonyError JS object is thrown with the following information:

Kony Studio API Developer's Guide

Version 3.1

Error

Code

3001

Name

WorkerThreadError

Message

WorkerThread:

MissingMandatoryParameter.

Failed to construct

WorkerThread

3002 WorkerThreadError WorkerThread:

InvalidParameter. Invalid script name

Reason

If no argument is given to the constructor API, this exception is thrown and workerThread object is not created.

If workerjs argument is not a string, then this exception is thrown and workerThread object is not created.

If the script or module mentioned by workerjs argument is not found, and if an "error" event handler is registered for this worker object in Parent scope then it is invoked with an error "event" object and its

"message" attribute set to following.

message:"WorkerThread: InvalidParameter. WorkerThread script not found" o

In this error scenario no ‘KonyError’ exception will be raised.

Also the filename, lineno properties in the error event object for this error scenario have undefined values.

If multiple arguments are provided separated by a comma, the first argument is considered as the

"workerjs" filename or module name and rest all are ignored.

Platform Availability

Available for iOS, Android, Windows, SPA, and Desktop Web. For more information, see

Scope .

JavaScript Example try { var worker = new kony.worker.WorkerThread("worker1.js");

Kony Studio API Developer's Guide

Version 3.1

} catch (e) { var err = kony.getError(e); if (err instanceof KonyError) { kony.print("KonyError Catch : " + JSON.stringify(err));

}

3.40 math Namespace

The math namespace provides the following API elements to help you include common mathematical tasks in your apps.

Functions

3.40.1 Functions

The math namespace provides the following functions.

3.40.1.1 math.max

This API returns the maximum value among the arguments.

Signature

JavaScript: Deprecated. Use max (x,y,..n) instead.

Return Values

Maximum Value [Number]

The return value is the maximum value among all the arguments

Kony Studio API Developer's Guide

Version 3.1

Platform Availability

Available on all platforms.

3.40.1.2 math.min

This API returns the minimum value among the arguments.

Signature

JavaScript: Deprecated. Use min(x,y,x,...n) Object instead.

Return Values

Minimum Value [Number]

The return value is the minimum value among all the arguments

Platform Availability

Available on all platforms.

3.40.1.3 math.pi

This API returns the value of pi.

Note: math.pi is not a function, but a property in math namespace.

Signature

JavaScript: Deprecated. Use PI Math object property instead.i.e Math.PI

Input Parameters

None.

Kony Studio API Developer's Guide

Version 3.1

Return Values value of pi [Number]

Value of pi is returned

Platform Availability

Available on all platforms.

3.40.1.4 math.pow

This API raises the first parameter to the power of the second parameter and returns the result.

Signature

JavaScript: Deprecated. User the pow(x,y) Object method instead.

Return Values xy

Raises the first parameter to the power of the second parameter

Implementation Details

It is advisable to use the expression x^y as it is much faster when compared to this API.

Rules and Restrictions l

On BlackBerry platform, this API is supported only from versions 4.6 and above.

On BlackBerry versions below 4.6, you need to define a custom Java method to achieve this functionality.

Platform Availability

Available on all platforms.

Kony Studio API Developer's Guide

Version 3.1

3.40.1.5 math.random

This API generates pseudo-random numbers which are uniformly distributed. This API generates a real number between 0 and 1.

Signature

JavaScript: Deprecated. Use random() math object method instead.

Return Values pseudo-random number [Number]

A pseudo-random number between the value 0 and 1 is generated

Platform Availability

Available on all platforms.

3.40.1.6 math.sqrt

This API returns the square root of the given number.

Signature

JavaScript: Deprecated. Use sqrt() object method instead.

Return Values square root [Number]

The square root of the number is returned nan (not a number)

This value is returned when the input parameter is a negative number

Platform Availability

Available on all platforms.

Kony Studio API Developer's Guide

Version 3.1

3.40.1.7 math.tointeger

This API converts the float value to an integer. The converted integer value is always the integer part of the specified float number (number before the decimal).

Signature

JavaScript: Deprecated. Use the floor() Object method instead.

Return Values integer [Number]

The return value is an integer

Platform Availability

Available on all platforms.

3.41 Sync Object

The Sync object implements the Sync API at the object level.

3.41.1 Methods

The Sync object contains the following methods.

3.41.1.1 <syncObject>.create

This API enables you to create a record in a Sync object.

Signature

Lua & JS : <syncObject>.create (

object , successCallback

errorCallback

)

Kony Studio API Developer's Guide

Version 3.1

Input Parameters

Object [object] - Mandatory

Specifies the object that needs to be created in the database.

successCallback [function] - Optional

Specifies the function which will get invoked on success.

errorCallback [function] - Optional

Specifies the function which will get invoked on error.

Platform Availability

Available on all platforms.

Examples function CreateProduct()

<syncObject>.create(objectProduct, successCallback , errorFailCallback) end function successCallback(res) window.Alert("Get All Success", nil, "info", "Ok", "", "", nil) end function errorFailCallback (err) window.Alert("Get All Failed", nil, "error", "Ok", "", "Error", nil) end

3.41.1.2 <syncObject>.deleteByPK

This API enables you to delete a record using the object's primary key.

Kony Studio API Developer's Guide

Version 3.1

Signature

Lua & JS : <syncObject>.deleteByPK (

pk , successCallback , errorCallback

)

Parameters pk [Integer] - Mandatory

Specifies the object's primary key using which the respective row data has to be deleted in the database successCallback [function] - Optional

Specifies the function which will get invoked on success.

errorCallback [function] - Optional

Specifies the function which will get invoked on error.

Platform Availability

Available on all platforms.

Examples function DeleteProductByPK()

<syncObject>.deleteByPK(123, successCallback , errorFailCallback) end function successCallback(res) window.Alert("Delete By Primary Key Success", nil, "info", "Ok", "",

"", nil) end function errorFailCallback (err) window.Alert("Delete By Primary Key Failed", nil, "error", "Ok", "",

Kony Studio API Developer's Guide

Version 3.1

"Error", nil) end

3.41.1.3 <syncObject>.getAll

This API fetches all the records for a Sync object.

Signature

Lua & JS : <syncObject>.getAll (

successCallback

errorCallback )

Input Parameters successCallback [function] - Optional

Specifies the function which will get invoked on success.

errorCallback [function] - Optional

Specifies the function which will get invoked on error.

Platform Availability

Available on all platforms.

Examples function SyncGetAll() sync.getAll(successCallback , errorFailCallback) end function successCallback(res) window.Alert("Get All Success", nil, "info", "Ok", "", "", nil) end function errorFailCallback (err)

Kony Studio API Developer's Guide

Version 3.1

window.Alert("Get All Failed", nil, "error", "Ok", "", "Error", nil) end

3.41.1.4 <syncObject>.getAllDetailsByPK

This API fetches a record using primary key value for a Sync object.

Signature

Lua & JS : <syncObject>.getAllDetailsByPK (

successCallback , errorCallback )

Parameters pk [object] - Mandatory

Specify the object's primary key using which the respective row data needs to be fetched from the database on the particular object.

successCallback [function] - Optional

Specifies the function which will get invoked on success.

errorCallback [function] - Optional

Specifies the function which will get invoked on error.

Platform Availability

Available on all platforms.

Examples function SyncGetAllDetailsByPK()

<syncObject>.getAllDetailsByPK(ProductId="123", successCallback , errorFailCallback) end

Kony Studio API Developer's Guide

Version 3.1

function successCallback(res) window.Alert("Get All Details By Primary Key Success", nil, "info",

"Ok", "", "", nil) end function errorFailCallback (err) window.Alert("Get All Details By Primary Key Failed", nil, "error",

"Ok", "", "Error", nil) end

3.41.1.5 <syncObject>.getPendingAcknowledgement

This API enables you to fetch pending acknowledgment for a Sync object.

Signature

Lua & JS : <syncObject>.getPendingAcknowledgement (

successCallback

errorCallback

)

Parameters successCallback [function] - Optional

Specifies the function which will get invoked on success.

errorCallback [function] - Optional

Specifies the function which will get invoked on error.

Platform Availability

Available on all platforms.

Examples function GetPendingAcknowledgement()

<syncObject>.getPendingAcknowledgement(successCallback ,

Kony Studio API Developer's Guide

Version 3.1

errorFailCallback) end function successCallback(res) window.Alert("Get Pending Acknowledgement Success", nil, "info",

"Ok", "", "", nil) end function errorFailCallback (err) window.Alert("Get Pending Acknowledgement Failed", nil, "error",

"Ok", "", "Error", nil) end

3.41.1.6 <syncObject>.getPendingUpload

This API enables you to fetch all the rows for a Sync object which are pending for upload.

Signature

Lua & JS :

<syncObject>.getPendingUpload ( successCallback , errorCallback

)

Parameters successCallback [function] - Optional

Specifies the function which will get invoked on success.

errorCallback [function] - Optional

Specifies the function which will get invoked on error.

Platform Availability

Available on all platforms.

Kony Studio API Developer's Guide

Version 3.1

Examples function GetPendingUpload()

<syncObject>.getPendingUpload(successCallback , errorFailCallback) end function successCallback(res) window.Alert("Get Pending Upload Success", nil, "info", "Ok", "",

"", nil) end function errorFailCallback (err) window.Alert("Get Pending Upload Failed", nil, "error", "Ok", "",

"Error", nil) end

3.41.1.7 <syncObject>.getXXX

This API retrieves all the records from the related object(XXX) corresponding to the current primary key.

Signature

Lua & JS :

<syncObject>.getXXX (

pk , successCallback ,

errorCallback

)

Parameters pk [Integer] - Mandatory

Specifies the object's primary key using which the respective row data needs to be fetched from the database.

successCallback [function] - Optional

Specifies the function which will get invoked on success.

Kony Studio API Developer's Guide

Version 3.1

errorCallback [function] - Optional

Specifies the function which will get invoked on error.

Platform Availability

Available on all platforms.

Examples

E.g.: If there is a relationship from Order to OrderDetails the below function will retrieve all the OrderDetails corresponding to that order.

function GetOrderDetails()

<syncObject>.getOrderDetails(123, successCallback , errorFailCallback) end function successCallback(res) window.Alert("Get Order Details Success", nil, "info", "Ok", "", "", nil) end function errorFailCallback (err) window.Alert("Get Order Details Failed", nil, "error", "Ok", "",

"Error", nil) end

3.41.1.8 <syncObject>.remove

This API enables you to delete a record for a Sync object using the where clause.

Signature

Lua & JS : <syncObject>.remove (

whereclause , successCallback , errorCallback

)

Kony Studio API Developer's Guide

Version 3.1

Parameters whereclause [String] - Mandatory

Specifies the string using which the data from database has to be fetched.

successCallback [function] - Optional

Specifies the function which will get invoked on success.

errorCallback [function] - Optional

Specifies the function which will get invoked on error.

Platform Availability

Available on all platforms.

Examples function DeleteProduct()

<syncObject>.remove(ProductId="123", successCallback , errorFailCallback) end function successCallback(res) window.Alert("Delete Success", nil, "info", "Ok", "", "", nil) end function errorFailCallback (err) window.Alert("Delete Failed", nil, "error", "Ok", "", "Error", nil) end

3.41.1.9 <syncObject>.rollbackPendingLocalChanges

This API enables you to rollback the object level pending changes which are not synchronized.

Kony Studio API Developer's Guide

Version 3.1

Signature

Lua & JS : <syncObject>.rollbackPendingLocalChanges (

successCallback

errorCallback )

Parameters successCallback [function] - Optional

Specifies the function which will get invoked on success.

errorCallback [function] - Optional

Specifies the function which will get invoked on error.

Platform Availability

Available on all platforms.

Examples function RollbackPendingLocalChanges()

<syncObject>.rollbackPendingLocalChanges(successCallback , errorFailCallback) end function successCallback(res) window.Alert("Rollback Pending Local Changes Success", nil, "info",

"Ok", "", "", nil) end function errorFailCallback (err) window.Alert("Rollback Pending Local Changes Failed", nil, "error",

"Ok", "", "Error", nil) end

Kony Studio API Developer's Guide

Version 3.1

3.41.1.10 <syncObject>.rollbackPendingLocalChangesByPK

This API enables you to fetch all the records for a Sync object.

Signature

Lua & JS :

<syncObject>.rollbackPendingLocalChangesByPK ( pk

successCallback , errorCallback )

Parameters pk [Integer] - Mandatory

Specify the object's primary key using which the respective row data needs to be rollback in the database successCallback [function] - Optional

Specifies the function which will get invoked on success.

errorCallback [function] - Optional

Specifies the function which will get invoked on error.

Platform Availability

Available on all platforms.

Examples function <syncObject>.RollbackPendingLocalChangesByPK()

<syncObject>.rollbackPendingLocalChangesByPK(123, successCallback , errorFailCallback) end function successCallback(res) window.Alert("Rollback Pending Local Changes Success", nil, "info",

"Ok", "", "", nil)

Kony Studio API Developer's Guide

Version 3.1

end function errorFailCallback (err) window.Alert("Rollback Pending Local Changes Failed", nil, "error",

"Ok", "", "Error", nil) end

3.41.1.11 <syncObject>.update

This API enables you to update a record for a Sync object using a where clause

Signature

Lua & JS :

<syncObject>.update ( whereClause

successCallback , errorCallback )

Parameters whereclause [String] - Mandatory

Specifies the string using which the data from database to be fetched.

successCallback [function] - Optional

Specifies the function which will get invoked on success.

errorCallback [function] - Optional

Specifies the function which will get invoked on error.

Platform Availability

Available on all platforms.

Examples function UpdateProduct()

<syncObject>.update(ProductId="123", successCallback ,

Kony Studio API Developer's Guide

Version 3.1

errorFailCallback) end function successCallback(res) window.Alert("Update Product Success", nil, "info", "Ok", "", "", nil) end function errorFailCallback (err) window.Alert("Update Product Failed", nil, "error", "Ok", "",

"Error", nil) end

3.41.1.12 <syncObject>.updateByPK

This API enables you to update a record using the object's primary key.

Signature

Lua & JS : <syncObject>.updateByPK (

pk , successCallback , errorCallback

)

Parameters pk [Integer] - Mandatory

Specifies the object's primary key using which the respective row data needs to be updated in the database successCallback [function] - Optional

Specifies the function which will get invoked on success.

errorCallback [function] - Optional

Specifies the function which will get invoked on error.

Kony Studio API Developer's Guide

Version 3.1

Platform Availability

Available on all platforms.

Examples function UpdateProductByPK()

<syncObject>.updateByPK("123", successCallback , errorFailCallback) end function successCallback(res) window.Alert("Get Product by Primary Key Success", nil, "info",

"Ok", "", "", nil) end function errorFailCallback (err) window.Alert("Get Product by Primary Key Failed", nil, "error",

"Ok", "", "Error", nil) end

3.42 sync Namespace

The sync namespace implements the Sync API. It contains the following API elements.

Functions

3.42.1 Functions

The

sync namespace

contains the following functions.

3.42.1.1 sync.getPendingAcknowledgement

This API is used to fetch pending acknowledgment for all objects.

Kony Studio API Developer's Guide

Version 3.1

Signature

Lua & JS : sync.getPendingAcknowledgement (

successCallback , errorCallback

)

Input Parameters successCallback [function] - Optional

Specifies the function which will get invoked on success.

errorCallback [function] - Optional

Specifies the function which will get invoked on error.

Platform Availability

Available on all platforms.

Examples function SyncGetPendingAcknowledgement() sync.getPendingAcknowledgement(successCallback , errorFailCallback) end function successCallback(res) window.Alert("Sync Pending Acknowledgement Success", nil, "info",

"Ok", "", "", nil) end function errorFailCallback (err) window.Alert("Sync Pending Acknowledgement Failed", nil, "error",

"Ok", "", "Error", nil) end

3.42.1.2 sync.getPendingUpload

This API fetches all the rows for all objects those are pending for upload.

Kony Studio API Developer's Guide

Version 3.1

Signature

Lua & JS : sync.getPendingUpload

(successCallback

errorCallback )

Input Parameters successCallback [function] - Optional

Specifies the function which will get invoked on success.

errorCallback [function] - Optional

Specifies the function which will get invoked on error.

Platform Availability

Available on all platforms.

Examples function SyncGetPendingUpload() sync.getPendingUpload(successCallback , errorFailCallback) end function successCallback(res) window.Alert("Sync Pending Upload Success", nil, "info", "Ok", "",

"", nil) end function errorFailCallback (err) window.Alert("Sync Pending Upload Failed", nil, "error", "Ok", "",

"Error", nil) end

3.42.1.3 sync.init

This API is used to initialize the creation of device database for sync.

Kony Studio API Developer's Guide

Version 3.1

Signature

Lua & JS :

sync.init ( initSuccessCallback

initFailCallback )

Input Parameters initSuccessCallback [function] - Optional

Specifies the function which will get invoked on success.

initFailCallback [function] - Optional

Specifies the function which will get invoked on failure.

Platform Availability

Available on all platforms

Examples function SyncInit() sync.init(initSuccessCallback , initFailCallback) end function initSuccessCallback(res) window.Alert("Sync Initialized", nil, "info", "Ok", "", "", nil) end function initFailCallback (err) window.Alert("Sync Failed", nil, "error", "Ok", "", "Error", nil) end

3.42.1.4 sync.reset

This API is used to reset the device database to initial state. This API will remove all data from the database.

Kony Studio API Developer's Guide

Version 3.1

Signature

Lua & JS : sync.reset (

successCallback , errorCallback )

Input Parameters successCallback [function] - Optional

Specifies the function which will get invoked on success.

errorCallback [function] - Optional

Specifies the function which will get invoked on error.

Platform Availability

Available on all platforms.

Examples function SyncReset() sync.reset(successCallback , errorFailCallback) end function successCallback(res) window.Alert("Sync Reset Success", nil, "info", "Ok", "", "", nil) end function errorFailCallback (err) window.Alert("Sync Reset Failed", nil, "error", "Ok", "", "Error", nil) end

3.42.1.5 sync.rollbackPendingLocalChanges

This API is used to roll back the application level pending changes which are not synchronized.

Kony Studio API Developer's Guide

Version 3.1

Signature

Lua & JS :

sync.rollbackPendingLocalChanges ( successCallback , errorCallback )

Input Parameters successCallback [function] - Optional

Specifies the function which will get invoked on success.

errorCallback [function] - Optional

Specifies the function which will get invoked on error.

Platform Availability

Available on all platforms.

Examples function SyncRollbackPendingChanges() sync.rollbackPendingLocalChanges(successCallback , errorFailCallback) end function successCallback(res) window.Alert("Sync Rollback Pending Changes Success", nil, "info",

"Ok", "", "", nil) end function errorFailCallback (err) window.Alert("Sync Rollback Pending Changes Failed", nil, "error",

"Ok", "", "Error", nil) end

Kony Studio API Developer's Guide

Version 3.1

3.42.1.6 sync.startSession

This API is used to start the sync process and download the data from the Enterprise Data Source to the device database.

Signature

Lua & JS : sync.startSession(

config )

Input Parameters config [table] - Mandatory

Specifies the table to set the configuration parameters.

Platform Availability

Available on all platforms.

Examples function startSyncSession(config) local config = {} config.onsyncstart = onsyncstartDemo config.onuploadstart = onuploadstartDemo config.onuploadsuccess = onuploadsuccessDemo config.ondownloadstart = ondowloadstartDemo config.ondownloadsuccess = ondownloadsuccessDemo config.onbatchstored = onbatchstoredDemo config.onbatchprocessingstart = onbatchprocessingstartDemo config.onbatchprocessingsuccess = onbatchprocessingsuccessDemo config.onsyncsuccess = onsyncsuccessDemo config.onsyncerror = onsyncerrorDemo config.onscopestart = onscopestartDemo config.onscopeerror = onscopeerrorDemo config.onscopesuccess = onscopesuccessDemo

Kony Studio API Developer's Guide

Version 3.1

// where onXXXXDemo is function which will be called on these callbacks

// the below values can be passed by the developer config.userid= "syncadmin"; config.password="SyncAdmin123"; config.appid = "APPIDNorthwind"; config.serverhost ="10.10.5.63"; config.serverport =8080; config.sessiontasks = {Scope1 = {doupload = true, dodownload = false}, Scope2 = {doupload = true,dodownload = false}} sync.startSession(config) //starting sync session end

3.43 table Namespace

The table namespace provides the following API elements.

Functions

3.43.1 Functions

The table namespace provides the following functions.

3.43.1.1 table.append

This API appends the content of the source table to the target table and returns the modified target table.

Signature

JavaScript:

kony.table.append ( targettable , sourcetable )

Kony Studio API Developer's Guide

Version 3.1

Input Parameters targettable [Table] - Mandatory

Specifies the target table to which the source table will be appended sourcetable [Table] - Mandatory

Specifies the source table that needs to be appended to the target table

Return Values

Modified table [Table]

A modified table is returned, if the input data was appended to the given table.

nil nil is returned if there is an error in the input parameters or executing this API

Error Codes l

100 - invalid arguments l

101 - internal error

Platform Availability

Available on all platforms.

3.43.1.2 table.concat

This API extracts all the elements of a table and concatenates the elements to form a string. A separator can be specified which can be placed between concatenated elements.

Signature

JavaScript: kony.table.concat (

inputtable , separator , startposition , endposition

)

Kony Studio API Developer's Guide

Version 3.1

Input Parameters inputtable [Table] - Mandatory

Specifies the input table from which the elements will be concatenated.

Note: Elements other than string, number, and Boolean are ignored.

separator [String] - Optional

Specifies the separator character that needs to be inserted between the concatenated elements startposition [Number] - Optional

Specifies the start index within the table from which the elements need to be taken for concatenation. If you do not specify the end position the default value is the last index.

Note: 0 <startposition < endposition endposition [Number] - Optional

Specifies the end index within the table till which the elements need to be taken for concatenation.

If you do not specify the startposition the default value is the first index.

Note:

0 < endposition < length of input table

Return Values

ConcatenatedString [Object]

All the elements of a table concatenated to form a string nil nil is returned if there is an error in the input parameters or executing this API

Kony Studio API Developer's Guide

Version 3.1

Error Codes l

100 - invalid arguments l

101 - internal error

Platform Availability

Available on all platforms.

3.43.1.3 table.contains

Tests if the specified key is part of the table.

Signature

JavaScript:

kony.table.contains ( inputtable

key

)

Input Parameters inputtable [Table] - Mandatory

Specifies the table within which the search is to be made key - Mandatory

Specifies the key that needs to be searched in the given table

Note: key can be a string or a number.

Return Values status [Boolean] true - if the specified key is found in the input table false - if there is an error in the input parameters or the input table does not contain the specified key

Kony Studio API Developer's Guide

Version 3.1

Error Codes l

100 - invalid arguments l

101 - internal error

Platform Availability

Available on all platforms.

3.43.1.4 table.filter

This API filters the given table based on the provided criteria and returns a set of values that match the given criteria.

Signature

JavaScript: kony.table.filter (

inputtable , criteriafunction )

Input Parameters inputtable [Table] - Mandatory

Specifies the table that needs to be filtered criteriafunction [Function] - Mandatory

Specifies the function that defines the criteria for filtering

Return Values

Modified table [Table]

A modified table is returned if the API is successfully executed for every element in the table nil nil is returned if there is an error in the input parameters or executing this API

Kony Studio API Developer's Guide

Version 3.1

Error Codes l

100 - invalid arguments l

101 - internal error

Platform Availability

Available on all platforms.

3.43.1.5 table.get

This API searches the given input table and returns the value at the specified key; if the key is a number, this API returns the value at the index.

Signature

JavaScript: kony.table.get (

inputtable , index )

Input Parameters inputtable [Table] - Mandatory

Specifies the table on which the search should be performed index [Number]- Mandatory

Specifies the key based on which the search will be done

Note: index can be a string or a number.

Return Values

Value [String]

If the key is a string, value corresponding to the specified key is returned

If the key is a number, value at the specified index is returned

Kony Studio API Developer's Guide

Version 3.1

nil nil is returned if there is an error in the input parameters or executing this API

Error Codes l

100 - invalid arguments l

101 - internal error l

0 - invalid key

Platform Availability

Available on all platforms

3.43.1.6 table.insert

This API inserts a specified value into the given table in the list part. If a position is specified, the value is inserted before the element currently at that position. If no position is specified, the value is appended to the end of the table. If the specified position is not within the range of the list part of the table, the new element is added to the hash part of the table.

Signature

JavaScript: kony.table.insert (

inputtable , position

value )

Input Parameters inputtable [Table] - Mandatory

Specifies the input table into which the given value needs to be inserted. The input table is modified.

position [Number] - Optional

Specifies the index of the table before which the given value needs to be inserted.

value [Userdata] - Mandatory

Specifies the value that needs to be inserted into the given input table

Kony Studio API Developer's Guide

Version 3.1

Return Values

None

Error Codes l

100 - invalid arguments l

101 - internal error

Platform Availability

Available on all platforms.

3.43.1.7 table.map

This API performs the given action on the input table and returns the modified table.

Signature

JavaScript: : kony.table.map (

inputtable , criteriafunction )

Input Parameters inputtable [Table] - Mandatory

Specifies the table on which the action needs to be performed.

criteriafunction [Function] - Mandatory

Specifies the function that defines the criteria for performing action on the table.

Return Values

Modified table [Table]

A modified table is returned if the API is successfully executed for every element in the table nil nil is returned if there is an error in the input parameters or executing this API

Kony Studio API Developer's Guide

Version 3.1

Error Codes l

100 - invalid arguments l

101 - internal error

Platform Availability

Available on all platforms.

3.43.1.8 table.mapnew

This API performs the given action on the input table and returns a new table.

Signature

JavaScript:

kony.table.mapnew ( inputtable

criteriafunction

)

Input Parameters inputtable [Table] - Mandatory

Specifies the table on which the action needs to be performed criteriafunction [Function] - Mandatory

Specifies the function that defines the criteria for performing action on the table.

Return Values

New table [Table]

A new table is returned if the API is successfully executed for every element in the table nil nil is returned if there is an error in the input parameters or executing this API

Error Codes

The following error codes are returned:

Kony Studio API Developer's Guide

Version 3.1

100 - invalid arguments l

101 - internal error

Platform Availability

Available on all platforms.

3.43.1.9 table.remove

This API removes an element from the list part of the table. If a position is specified, the element at the position is removed. If no position is specified, the last element in the table is removed. The removed element is returned. This API operates only on the list part of the table.

Signature

JavaScript: kony.table.remove (

inputtable , position

)

Input Parameters inputtable [Table]- Mandatory

Specifies the input table from which the element needs to be removed.

position [Number]- Optional

Specifies the index of the input table from where the element needs to be removed. Position must be greater than zero and less than the length of the input table.

Note: If position is greater than the size of the table, the input table is not modified and returns an error with error code 100.

Return Values

Removed element

The element that has been removed from the input table is returned

Error Codes l

100 - invalid arguments l

101 - internal error

Platform Availability

Available on all platforms.

3.43.1.10 table.removeall

This API removes data from the table represented by the table id.

Signature

JavaScript: kony.table.removeAll (

tableid

)

Input Parameters tableid [String] - Mandatory

Specifies the table id whose data needs to be deleted

Return Values

None.

Error Codes

There are no error codes associated with this API.

Platform Availability

Available on all platforms.

Kony Studio API Developer's Guide

Version 3.1

Kony Studio API Developer's Guide

Version 3.1

3.43.1.11 table.sort

This API sorts the elements of the input table and returns the modified table. This API sorts only the list part of the table and the hash part of the table is ignored.

Signature

JavaScript: kony.table.sort (

inputtable

sortkey

comparisonfunction

)

Input Parameters inputtable [Table] - Mandatory

Specifies the input table that needs to be sorted.

sortkey [String] - Optional

Specifies the key based on which the table needs to be sorted comparisonfunction [Function] - Optional

Specifies the comparison function that is called every time the sort algorithm tries to compare two elements in the table

Return Values

Modified table [Table]

A modified table that has been sorted is returned

Important: The input table is modified and is returned.

Error Codes l

100 - invalid arguments l

101 - internal error

Kony Studio API Developer's Guide

Version 3.1

Platform Availability

Available on all platforms.

3.43.1.12 unpack

This API returns the elements from the given table. This function is equivalent to

return list[i], list[i+1], .... list[j]

Signature

JavaScript:

kony.table.unpack ( inputtable

)

Input Parameters inputtable [Table] - Mandatory

Specifies the input table that needs to be iterated

Return Values

Returns a list of elements from a given table. If a table has 5 elements, a list of 5 elements will be returned.

Error Codes l

100 - invalid arguments l

101 - internal error

Implementation Details

You can achieve the same functionality by writing a custom function that displays all the elements of a table.

Platform Availability

Available on all platforms.

Kony Studio API Developer's Guide

Version 3.1

3.44 WorkerThread Object

The WorkerThread object is used to manage a worker thread. For details, see

Worker Thread API .

3.44.1 Methods

The WorkerThread object contains the following methods.

3.44.1.1 addEventListener

Event Handlers can be registered using addEventListener() method on the worker Objects and once registered messages and errors from a worker thread can be received in parent thread.

Due to the asynchronous parallel execution nature of the newly created worker thread, which starts executing the worker JS script upon creation. It is always advisable to immediately register the

‘message’ event handler as well as ‘error’ event handler on the worker handle in parent thread context after creation of the worker. This ensures that posted messages or errors in worker scope are handed over to the respective ‘message’ or ‘error’ event listeners in parent scope.

message event handler:

Registered "message" event handler will be invoked in Parent or Worker thread whenever postMessage() is called from inner scope of Worker or Parent thread.

1. In parent scope, call to worker.

postmessage() invokes message event handler registered using addEventListener() in Workers inner Scope.

2. In worker scope, call to postmessage() invokes message event handler registered using addEventListener() in Parents scope.

Multiple message event handlers can also be registered in parent scope and workers inner scope and all the registered event handlers will be invoked in the registered order whenever a postMessage() is called.

Kony Studio API Developer's Guide

Version 3.1

error event listener:

The error handler can also be registered using addEventListener () in parent thread scope on worker object and as well as in worker thread’s inner scope, which will be invoked whenever an unhandled exception occurs in workers inner scope.

The error event object has the following three fields: message, filename, lineno.

If an error event handler is registered in worker inner scope and in parent scope on the worker object, then both the event handlers are invoked in case of an unhandled exception in worker’s inner scope.

Multiple error event handlers can be registered on the worker handle in parent scope and also in worker threads inner scope. Registered error event handlers will be invoked in the order of registration in case of unhandled exception in worker thread.

If an error event handler is not registered for a worker in parent scope or in worker inner scope and if an unhandled exception arises in worker’s inner scope then worker halts execution and no error info is propagated.

The error event handlers work for unhandled exceptions occurring only in worker scope but not in main parent scope.

Signature

JavaScript:

Parent scope: worker.addEventListener(key, listener);

Worker scope: addEventListener(key, listener); self.addEventListener(key, listener); this.addEventListener(key, listener);

Kony Studio API Developer's Guide

Version 3.1

Input Parameters key message: When message event handler is being registered.

error: When error event handler is being registered.

listener

The listener parameter indicates the event listener function to be added.

Return Values

None

Exceptions

1. If no argument is given or if the number of arguments are less than two, it raises an exception and throws a "KonyError" JS Object with the following attributes: errorCode: 3001.

message: "addEventListener: MissingMandatoryParameter. Mandatory arguments missing"

2. If the first argument is not equal to "message" or "error" and if second argument is not a function object, it raises an exception and throws a "KonyError" JS Object with the following attributes: errorCode: 3002.

message: "addEventListener: InvalidParameter. Invalid arguments"

3. In Worker scope if these exceptions are not handled and if an "error" event handler is registered in worker’s inner scope or/and in Parent scope for this worker object then it is invoked with an error event object and its message attribute set to following.

In case of exception 1)

Kony Studio API Developer's Guide

Version 3.1

message: "addEventListener: MissingMandatoryParameter . Mandatory arguments missing"

In case of exception 2) message: "addEventListener: InvalidParameter. Invalid arguments"

4. In Parent(not a worker to some other parent) scope if these exceptions are not handled registered "error" event handler will not be invoked.

Platform Availability

Available for iOS, Android, Windows, SPA, and Desktop Web. For more information, see

Scope

JavaScript Example

//Parent Scope var worker = new kony.worker.WorkerThread("worker1.js"); var evtMessageHandler_1 = function (event) { kony.print ("Parent Scope : In message handler 1");

}; var evtErrorHandler_1 = function (event) { kony.print("Parent Scope: In error handler 1"); kony.print('ERROR: Line ' + event.lineno + ' in ' + event.filename +

': ' + event.message);

};

"message" event handler :

//Parent Scope var worker = new kony.worker.WorkerThread("worker1.js");

Kony Studio API Developer's Guide

Version 3.1

var evtMessageHandler_1 = function (event) { kony.print ("Parent Scope : In message handler 1");

}; var evtMessageHandler_2 = function (event) { kony.print ("Parent Scope : In message handler 2");

}; worker.addEventListener("message", evtMessageHandler_1); worker.addEventListener("message", evtMessageHandler_2);

//Worker Scope var evtMessageHandler_1 = function (event) { kony.print ("Worker Scope : In message handler 1");

}; self.addEventListener("message", evtMessageHandler_1);

//or this.addEventListener("message", evtMessageHandler_1);

//or addEventListener("message", evtMessageHandler_1);

"error" event listener :

//Parent Scope var worker = new kony.worker.WorkerThread("worker1.js"); var evtErrorHandler_1 = function (event) {

Kony Studio API Developer's Guide

Version 3.1

kony.print("Parent Scope: In error handler 1"); kony.print('ERROR: Line ' + event.lineno + ' in ' + event.filename +

': ' + event.message);

}; var evtErrorHandler_2 = function (event) { kony.print("Parent Scope: In error handler 2");

};

// worker.addEventListener("error", evtErrorHandler_1); worker.addEventListener("error", evtErrorHandler_2);

//Worker Scope var evtErrorHandler_1 = function (event) { kony.print("Worker Scope: In error handler 1");

}; self.addEventListener("error", evtErrorHandler_1);

//or this.addEventListener("error", evtErrorHandler_1);

//or addEventListener("error", evtErrorHandler_1);

Kony Studio API Developer's Guide

Version 3.1

3.44.1.2 close

Worker thread can be terminated from inner scope of the worker by invoking close(). The worker thread is killed immediately without an opportunity to complete its operations or clean up.

The tasks pending in the message queue and callbacks registered for network, timer APIs etc are discarded without wait until completion.

Signature

JavaScript :

Worker scope: close(); self.close(); this.close();

Input Parameters

None

Return Values

None

Platform Availability

Available for iOS, Android, Windows, SPA, and Desktop Web. For more information, see

Scope

JavaScript Example

//worker init

//post a message to parent

Kony Studio API Developer's Guide

Version 3.1

self.postMessage("Hello from Worker");

//do some work

//terminate this worker from inner scope self.close();

Limitations

When close() is invoked in worker scope, and if worker is currently executing a large task, it might not immediately terminate, it will continue to execute the task to completion and then terminate.

When close () is invoked in worker scope, and if there are pending tasks waiting in the message queues for this worker to perform, some platforms might discard all the pending tasks without accepting them for execution and terminate, and on some platform all the pending tasks are executed to completion and then the worker terminates.

Hence it is to be noted that to achieve cross platform consistency, it is always advised that close

() be invoked in worker scope once all the tasks in message queues are completed.

3.44.1.3 postMessage postMessage() sends a JSON object or String message to the Parent/worker's scope by invoking respective registered "message" event handlers.

In Parent thread scope, call to worker.postMessage() invokes "message" event handler which is registered using addEventListener() in Workers inner Scope.

In Worker thread scope, call to postMessage() invokes "message" event handler which is registered using addEventListener() in Parents scope.

Kony Studio API Developer's Guide

Version 3.1

The JSON or string object passed to postMessage() is delivered to the registered "message" event handler. The "event" object "data" attribute will have the message passed: "event.data".

Adhering to the JSON standard, the JSON object passed to postMessage() API should be serializeble

JSON without opaque object handles or function object handles etc.

Signature

JavaScript : postMessage(<String> or <JSON>);

//Parent scope:

//JSON Object

worker.postMessage({‘msg’ : ‘hello’});

//String

worker.postMessage("messsage hello");

//Worker scope:

//JSON Object

postMessage({‘msg’ : ‘hello’});

//String

postMessage("messsage hello");

Input Parameters l

String

For parent scope, here is an example: worker.

postMessage("messsage hello");

For worker scope, here is an example:

postMessage("messsage hello");

JSON Object

Kony Studio API Developer's Guide

Version 3.1

For parent scope, here is an example: worker.

postMessage({'msg' : 'hello'});

For worker scope, here is an example:

postMessage({'msg' : 'hello'});

Return Values

None

Exceptions

1. If no argument is given it raises an exception and throws a "KonyError" JS Object with the following attributes: errorCode: 3001.

message: "postMessage: MissingMandatoryParameter. Message undefined"

2. If the message argument passed is not String or JSON object, it raises an exception and throws a "KonyError" JS Object with the following attributes: errorCode: 3002.

message: "postMessage: InvalidParameter. Invalid Message"

In case of exception 1: message: "postMessage: MissingMandatoryParameter. Message undefined"

In case of exception 2: message: "postMessage: InvalidParameter. Invalid Message"

Kony Studio API Developer's Guide

Version 3.1

4. In Parent (not a worker to some other parent) scope if these exceptions are not handled registered "error" event handler will not be invoked.

Platform Availability

Available for iOS, Android, Windows, SPA, and Desktop Web. For more information, see

Scope

JavaScript Example var worker = new kony.worker.WorkerThread("worker1.js");

// Parent scope:

//JSON Object worker.postMessage({'msg' : 'hello'});

//String worker.postMessage('message hello');

// Worker scope:

//JSON Object postMessage({'msg' : 'hello'});

//or this.postMessage({'msg' : 'hello'});

//or self.postMessage({'msg' : 'hello'});

//String

//or postMessage('message hello'); this.postMessage('message hello');

//or self.postMessage('message hello');

Kony Studio API Developer's Guide

Version 3.1

3.44.1.4 removeEventListener

This API is used to remove the previously registered message or error event listener that was registered using addEventListener().

This API can be used in both parent and worker scope

Signature

JavaScript :

Parent scope: worker.removeEventListener(key, listener);

Worker scope: removeEventListener(key, listener); self.removeEventListener(key, listener); this.removeEventListener(key, listener);

Input Parameters key message: In case of message event handler.

error: In case of error event handler.

listener: The listener parameter indicates the event listener function to be removed.

Kony Studio API Developer's Guide

Version 3.1

Exceptions

1. If no argument is given or if the number of arguments are less than two, it raises an exception and throws a "KonyError" JS Object with the following attributes: errorCode: 3001.

message: "removeEventListener: MissingMandatoryParameter.

Mandatory arguments missing"

message: "removeEventListener: InvalidParameter. Invalid arguments"

In case of exception 1: message: "removeEventListener: MissingMandatoryParameter.

Mandatory arguments missing"

In case of exception 2: message: "removeEventListener: InvalidParameter. Invalid arguments"

4. In Parent(not a worker to some other parent) scope if these exceptions are not handled registered "error" event handler will not be invoked.

Platform Availability

Available for iOS, Android, Windows, SPA, and Desktop Web. For more information, see

Scope

Kony Studio API Developer's Guide

Version 3.1

JavaScript Example

"message" event handler :

//Parent Scope var worker = new kony.worker.WorkerThread("worker1.js"); var evtMessageHandler_1 = function (event) { kony.print ("Parent Scope : In message handler 1");

}; var evtMessageHandler_2 = function (event) { kony.print ("Parent Scope : In message handler 2");

};

//adding event listeners worker.addEventListener("message", evtMessageHandler_1); worker.addEventListener("message", evtMessageHandler_2);

//removing event listener worker.removeEventListener("message", evtMessageHandler_2);

//Worker Scope var evtMessageHandler_1 = function (event) { kony.print ("Worker Scope : In message handler 1");

}; var evtMessageHandler_2 = function (event) { kony.print ("Worker Scope : In message handler 2");

};

//adding event listeners

Kony Studio API Developer's Guide

Version 3.1

self.addEventListener("message", evtMessageHandler_1); self.addEventListener("message", evtMessageHandler_2);

//removing event listener self.removeEventListener("message", evtMessageHandler_2);

"error" event listener :

//Parent Scope var worker = new kony.worker.WorkerThread("worker1.js"); var evtErrorHandler_1 = function (event) { kony.print("Parent Scope: In error handler 1");

}; var evtErrorHandler_2 = function (event) { kony.print("Parent Scope: In error handler 2");

};

//adding event listeners worker.addEventListener("error", evtErrorHandler_1); worker.addEventListener("error", evtErrorHandler_2);

//removing event listener worker.removeEventListener("error", evtErrorHandler_2);

//Worker Scope var evtErrorHandler_1 = function (event) { kony.print("Worker Scope: In error handler 1");

};

Kony Studio API Developer's Guide

Version 3.1

var evtErrorHandler_2 = function (event) { kony.print("Worker Scope: In error handler 2");

};

//adding event listeners self.addEventListener("error", evtErrorHandler_1); self.addEventListener("error", evtErrorHandler_2);

//removing event listener self.removeEventListener("error", evtErrorHandler_2);

3.44.1.5 terminate

When called from parent scope immediately terminates the worker. This does not offer the worker an opportunity to finish its operations. It is simply stopped at once.

The tasks pending in the message queue and callbacks registered for network, timer APIs are discarded without wait until completion.

Signature

JavaScript : worker.terminate();

Input Parameters

None

Return Values

None

Platform Availability

Available for iOS, Android, Windows, SPA, and Desktop Web. For more information, see

Scope

Kony Studio API Developer's Guide

Version 3.1

JavaScript Example var worker = new kony.worker.WorkerThread("worker1.js");

//post a message to the worker worker.postMessage("Hello from Parent");

//terminate the worker worker.terminate();

Limitations

When terminate() is invoked in Parent thread on worker, and if worker is currently executing a large task, it might not immediately terminate, it will continue to execute the task to completion and terminate.

When terminate() is invoked in Parent thread on worker, and if there are pending tasks waiting in the message queues for this worker to perform, some platforms might discard all the pending tasks without accepting them for execution and terminate, and on some platform all the pending tasks are executed to completion and then the worker terminates.

Hence it is to be noted that to achieve cross platform consistency, it is always advised that terminate() be invoked on the worker once all the tasks in message queues are completed.

Živjo! Sem AI chatbot, posebej usposobljen za pomoč pri Kony 7.0 Beta Mobile Application Development Platform API Developer's Guide. Temeljito sem pregledal dokument in vam lahko pomagam najti točne informacije, ki jih potrebujete, ali razložim vsebino na jasen in preprost način. Ne glede na to, ali iščete navodila o določenih funkcijah, korake za odpravljanje težav ali splošno uporabo, lahko zastavite svoja vprašanja. Več podrobnosti kot navedete o svojih pomislekih ali potrebah, natančneje in učinkoviteje vam lahko pomagam!

Pomočnik tipka

Pomočnik je prekinil povezavo. Poskusite znova pozneje.

Izgleda, da ste prišli do dokumenta, ki je napisan v več jezikih, vključno z jezikom, ki ni vaš materni jezik. Uporabite lahko naslednje povezave, da začasno skrijete strani brez jezika, ki ga želite.

Oglas

Kony

Mobile Application Development

Platform (MADP)

API Developer's Guide

Release 7.0 Beta

Document Relevance and Accuracy

This document is considered relevant to the Release stated on this title page and the document version stated on the Revision History page. Remember to always view and download the latest document version relevant to the software release you are using.

Revision History

Table of Contents

1. Preface

1.1 Purpose

1.2 Intended Audience

1.3 Formatting Conventions

1.4 Related Documents

1.5 Contact Us

2. Overview

2.1 Platform Availability

2.2 Accelerometer APIs

os.platform

().hasaccelerometer

2.3 Alert API

2.4 App Group API

2.5 Application APIs

2.6 Application Settings API

2.7 Background Jobs

kony.backgroundjob.registerBackgroundFetch

kony.net.HttpRequest

Background Fetch

kony.backgroundjob.setBackgroundFetchCompletionStatus

backgroundCallBack

constants.BACKGROUND_

TASK_STATUS_FAILED

kony.net.HttpRequest

<HttpRequestObject>.backgroundTransfer = true

<HttpRequestObject>.backgroundTransfer = true

<HttpRequestObject>.backgroundTransfer = true

kony.net.HttpRequest

<HttpRequestObject>.getSession()

<HttpRequestObject>.backgroundTransfer = true

kony.net.HttpRequest

2.8 Badge APIs

2.9 Beacon FFI APIs

BeaconManagerAuthorizationStatusAuthorized

authorizationStatusChanged

monitoringCallback

beaconRegionState

BeaconRegionStateInside

beaconRegionState

BeaconRegionStateOutside

startRangingBeaconsRegion

startRangingBeaconsInRegion

rangingCallback

2.10 Bookmark and Refresh API

2.11 Camera API

2.12 Charm Setting APIs

2.13 Cryptography APIs

encryptedtext = E

(D

(E

(text to be encrypted)))

decryptedtext = D

(E

(D

(text to be decrypted)))

2.14 Data Store API

2.15 Functional Modules API

functionalModule.xml

2.16 GeoLocation APIs

appinit

form.preshow

2.17 Gesture API

2.18 Hybrid API

2.19 Input and Output APIs

2.20 Internationalization APIs

<language_Country>.properties

en_US.properties.

fr_CA.properties

2.21 kony.localAuthentication Namespace

2.22 Language APIs

2.23 Live Tiles API