Browser Events

The Browser widget has the following events associated with it:

handleRequest Event

An event callback which gets invoked by the platform before browser widget navigates to a new URL.

Syntax

handleRequest()

Optional Parameters

eventobject

Optional. A unique Id that identifies the browser widget.

params

Optional. An object that identifies the url parameters as key-values pair.

Following are the parameters of the object.

originalURL [String] - Optional

Specifies the original url.

queryParams[Object] - Optional

Specifies the dictionary containing the query parameters passed to the URL as key, values in the dictionary.

requestMethod[String] - Optional - Supported only on iOS

Specifies the request method type. Following are the available options:

Constants.BROWSER_REQUEST_METHOD_GET
Constants.BROWSER_REQUEST_METHOD_POST

header[JSObject] - Optional - Supported only on iOS

Specifies a dictionary containing all the HTTP header fields.

Read/Write

Write only

Remarks

This is useful in scenarios where the developer wants to keep track of the URLs that the browser field navigates to. For example, in a payment flow (that is, being executed inside a browser widget) on successful redirection to a payment confirmation page the developer would like to take the user to a new native form.

On iOS platform, whenever handleRequest is set to browser and request comes to browser widget to load the url or html, then before loading the content, handle request is called. Also, whenever a user selects any hyperlink then also handleRequest is called.

The return value from this function determines how the browser widget handles the original request. If a false value is returned, then the browser widget continues navigation to the original URL and if the true value is returned then the developer has to handle the request.

The handleRequest event is not triggered for the web pages that change the HTML content dynamically within the same page.

The handleRequest event is not triggered for the bookmark navigation on the same page in the Android platform.

Example



//The below function is the call back for handleRequest event
function handleRequestCallback(browserWidget, params) {
    kony.print("handleRequest event triggered");
    kony.print("Original URL" + params["originalURL"]);
    kony.print("Request Method" + params["requestMethod"]);
    kony.print("Header" + JSON.stringify(params["header"]));
    //Ignore this request and continue loading other URLs.
    return false;
    //If false is returned, platform will load the originalurl in the browser widget.
}

frmobj.brw1.handleRequest = handleRequestCallback

Platform Availability

iPhone
iPad
Android

onFailure Event

An event callback which gets invoked by the platform when the given URL fails to load. The behavior of this callback has changed in Visualizer 7.3 and may require changes to your code, particularly the addition of the errorObject parameter.

Syntax

onFailure()

Optional Parameters

eventObject

Required. A unique Id that identifies the browser widget.

errorObject

Required. An object that provides details for the error. See Remarks for possible values. This value is new in Visualizer 7.3.

Read/Write

Read + Write

Remarks

The errorObject is a dictionary object that has these predefined keys:

errorCode - the Quantum error code
errorMessage – error message
errorDetails – platform specific error details
httpStatusCode - Actual HTTP status code. For iOS this will be set to -1.

All errors reported by this callback:

Error Code	Error Message	Android	iOS
1000	Unknown error while connecting. The platform cannot differentiate between network errors, The platform reports error code 1000 by default.	ERROR_UNKNOWN	ErrorUnknown
1001	Cannot connect to host.	ERROR_CONNECT ERROR_HOST_LOOKUP	ErrorCannotConnectToHost ErrorDNSLookupFailed ErrorCannotFindHost, ErrorRedirectToNonExistentLocation
1002	Input Stream Related Errors	ERROR_IO	ErrorRequestBodyStreamExhausted
1003	Permission Related	ERROR_AUTHENTICATION ERROR_PROXY_AUTHENTICATION ERROR_UNSUPPORTED_AUTH_SCHEME	ErrorUserAuthenticationRequired
1004	Invalid input url	ERROR_BAD_URL ERROR_UNSUPPORTED_SCHEME	ErrorBadURL, ErrorUnsupportedURL
1005	Invalid method provided
1006	File Errors	ERROR_FILE ERROR_FILE_NOT_FOUND	ErrorFileDoesNotExist, ErrorFileIsDirectory, ErrorNoPermissionsToReadFile, ErrorDataLengthExceedsMaximum
1007	Device Connectivity related issues		ErrorNetworkConnectionLost, ErrorNotConnectedToInternet ErrorDataNotAllowed ErrorCallIsActive ErrorInternationalRoamingOff
1008	Request failed.
1009	Invalid Server Response
1010	Request timed out.	ERROR_TIMEOUT
1011	User Canceled		ErrorBadServerResponse ErrorCannotParseResponse ErrorCannotDecodeRawData, ErrorCannotDecodeContentData ErrorBadServerResponse
1012	Redirection related Errors	ERROR_REDIRECT_LOOP	ErrorHTTPTooManyRedirects
1013	Too many requests during this load	ERROR_TOO_MANY_REQUESTS
1014	User canceled authentication		ErrorUserCancelledAuthentication
1015	App transport security requires secure connection		ErrorAppTransportSecurityRequiresSecureConnection
1016	Resource related Errors		ErrorResourceUnavailable, ErrorZeroByteResource
1018	SSL related error	ERROR_FAILED_SSL_HANDSHAKE	ErrorSecureConnectionFailed, ErrorServerCertificateHasBadDate, ErrorServerCertificateUntrusted, ErrorServerCertificateHasUnknownRoot, ErrorServerCertificateNotYetValid, ErrorClientCertificateRejected, ErrorClientCertificateRequired, ErrorCannotLoadFromNetwork

This event is called only for the given request URL, but not for the subsequent web navigation request failures.

This event is also not called when htmlString is set to the web widget.

Example


// This function is the callback for the onFailure event that checks for iOS native error -999
function onFailureCallback(eventObj, error) {
	if (error.errorCode !== 1011) { 
		// native error -999 is mapped to error 1011.
		kony.print("Unable to display report.");
	}
}
frmBrowser.myBrowser.onFailure=onFailureCallback;

Platform Availability

iOS
Android

onKeyPress Event

This event takes a callback as an input that is invoked by the platform when the user presses a key (on the keyboard).

Syntax

onKeyPress(eventObject, eventPayload, context)

Input Parameters

eventObject:

An Object that contains the instance of the widget that triggered the onKeyPress event.

eventPayload:

An Object that contains information about the keyboard interactions. Based on the key that the user presses, the value of the eventPayload varies as follows:

Key	Description
altKey	Returns a boolean value. The value is true when the Alt key (Option key on macOS systems) is pressed.
ctrlKey	Returns a boolean value. The value is true when the Ctrl key is pressed.
shiftKey	Returns a boolean value. The value is true when the Shift key is pressed.
metaKey	Returns a boolean value. The value is true when the meta key ( windows key ⊞ on windows systems, command key ⌘ on macOS systems) is pressed.
capsLock	Returns a boolean value. The value is true when the capsLock key is turned on.
keyCode	Returns the ASCII code of the key pressed .
preventDefault	Returns a function. This function can be invoked to prevent the default action of the widget.

context:

An Object that represents information about the row that contains the target widget that triggered the onKeyPress event.

rowIndex: The index of the row that contains the target widget for a Segment widget.

itemIndex: The index of the row that contains the target widget for a CollectionView widget.

sectionIndex: The index of the section that contains the target widget.

widgetInfo: The widget reference of the Segment or CollectionView widget.

Read/Write

Read + Write

Remarks

The onKeyPress event is not linked with native keypress event, i.e both the events are different.
For widgets (such as TextBox and TextArea) that support both the onKeyDown and onKeyPress events, the onKeyDown event takes higher priority.
If a widget has both the onKeyDown and onKeyPress events configured, the onKeyDown event is invoked first, followed by the onKeyPress event.
The Web Framework provides support for both the onKeyDown and onKeyPress events on the TextBox and TextArea widgets. However, Temenos recommends that you use only one of the events for a widget.

Example



/*This event is triggered in both TextBox and TextArea widgets for Android platform.*/

/*This example demonstrates how to set an onKeyPress event callback to a Button widget that is placed inside form


frmButton.myButton.onKeyPress = onKeyPressCallBack;

function onKeyPressCallBack(eventObject, eventPayload) {
    console.log('onKeyPress event triggered');
}

Platform Availability

Available in the IDE
Available on the Responsive Web platform

onSafeBrowsingHit Event

This event registers a callback that notifies the application that a loading URL has been flagged by Safe Browsing. If this event callback is not registered, the application displays a default interstitial page.

Handler signature

onSafeBrowsingHit()

Parameters

browserwidgetref [widgetref]: This parameter provides the widget reference of the Browser widget that has triggered the onSafeBrowsingHit event.
requestUrl[String]: This parameter provides the URL which triggered the onSafeBrowsingHit event.
threatType [Number]: This parameter specifies the reason why the requestUrl parameter is a threat.

The following constant are applicable for this parameter:
- constants.BROWSER_SAFE_BROWSING_THREAT_UNKNOWN
- constants.BROWSER_SAFE_BROWSING_THREAT_MALWARE
- constants.BROWSER_SAFE_BROWSING_THREAT_PHISHING
- constants.BROWSER_SAFE_BROWSING_THREAT_UNWANTED_SOFTWARE

Remarks

You should use the onSafeBrowsingHit callback and the setSafeBrowsingResponse Method together to create a custom interstitial page when the Browser widget loads a flagged URL.

Example



/*Sample snippet for creating a custom interstitial flexContainer inside the form:frmBrowser with the browser widget:myBrowser*/
//setting safebrowsing hit callback
frmBrowser.myBrowser.onSafeBrowsingHit = onSafeBrowsingHitForCustomInterstition;
var reqUrl;

function onSafeBrowsingHitForCustomInterstition(widget, requestUrl, threatType) {
    reqUrl = requestUrl; //getting SafeBrowsingPrivacyPolicyUrl to display the link in custom interstitial page.
    var doc = kony.ui.BrowserSettings.getSafeBrowsingPrivacyPolicyUrl();
    frmBrowser.richtext.text = "&lt;p&gt;Its a custom message for Google Safe Browsing which has detected malware." + "&lt;a href=" + doc + "&gt;&lt;font color=\"blue\"&gt;Learn more/font&gt;&lt;/a&gt;&lt;/p&gt;";
    //making the interstitial flexContainer visible in onSafeBrowsingHit event callback.
    frmBrowser.flexCustomInterstition.isVisible = true;
}

function proceed_button_click(eventobject) { //making the interstitial flexContainer invisible after clicking proceed button
    frmBrowser.flexCustomInterstition.isVisible = false;
    frmBrowser.browserID.setSafeBrowsingResponse(reqUrl, constants.BROWSER_SET_SAFEBROWSING_RESPONSE_PROCEED);
}

function backtosafety_button_click(eventobject) { //making custom interstitial flexContainer invisible after clicking backtosafety button.
    frmBrowser.flexCustomInterstition.isVisible = false;
    frmBrowser.browserID.setSafeBrowsingResponse(reqUrl, constants.BROWSER_SET_SAFEBROWSING_RESPONSE_BACKTOSAFETY);
}

The screenshot of the custom interstitial FlexContainer created by using the Example code is as follows.

Platform Availability

Android (API Level 27 and later)