kony.gms Namespace

The requestHintAPI displays a list of email addresses and phone numbers that are registered with a device as hints to the user (based on the values of the hintTypes parameter). Users can then select and retrieve a hint from the available hints displayed in the list.

In situations where users need to fill input text fields with email address or phone number (such as in a Sign-in or Sign-up forms, or sms verification), this API helps users retrieve appropriate hint texts relevant to the input field. These user hints help speed up the on-boarding or verification process for an app.

Syntax

kony.gms.requestHint({
"callback" : callback,
"hintTypes" : [kony.gms.HINT_TYPE_EMAIL,kony.gms.HINT_TYPE_PHONE_NUMBER],
"showCancelButton" : false
});

Input Parameters

Example

signupForm1(){
    kony.gms.requestCredentialHints({
      "callback" : this.callback.bind(this),
       "hintTypes" : [kony.gms.HINT_TYPE_EMAIL,kony.gms.HINT_TYPE_PHONE_NUMBER],
      "showCancelButton" : false
      })
  }, 
  callback(info) {
        if (result.statusCode == kony.gms.HINT_RETRIEVAL_SUCCESSFUL) {
          this.view.tbEmail.text = info.selectedHint.id;
          this.view.tbUserName.text = info.selectedHint.userFullName;
          this.view.tbFirstName.text = info.selectedHint.userFirstName;
          this.view.tbLastName.text = info.selectedHint.userLastName;
          }
  }

Return Value

List of hints

Remarks

Ensure that you add the supportGooglePlayAuthLib=true entry in the androidbuild.properties file.

Platform Availability

Android

This API provides attestation results for the device.

An attestation result states whether the device on which the API is invoked matches the profile of a device that has passed the Android compatibility test.

When you request a compatibility check, you must provide a nonce, which is a random token generated in a cryptographically secure manner. You can obtain a nonce by generating it within your app, each time you make a compatibility check request. As a more secure option, you can obtain a nonce from your own server, using a secure connection.

A nonce used with an attestation request must be at least 16 bytes in length. After you make a request, the response includes your nonce, so that you can verify it against the one that you sent. Ensure that you use a nonce value once, for a single request. Use a different nonce for any subsequent attestation requests.

The result is returned through the success or failure callbacks.

Syntax

kony.gms.safetynet.attest(apikey, nonce, successCallback, failureCallback);

Input Parameters

Example

var uuid = kony.os.createUUID();
var timestamp = new Date().getTime();
var nonce = uuid + timestamp; // generating nonce at client. However generating at server is best practice.
var apiKey = “google_api_key”; // check reference links to know how to get the API key.
kony.gms.safetynet.attest(apiKey, nonce, successCallback, failureCallback);
function successCallback(result){
}
function failureCallback(errorCode,errormessage){
}

Return Values

None

Remarks

None

Platform Availability

• Android

This API allows your app to determine whether the user has enrolled for the Verify Apps feature.

The result is returned through the result callback.

Syntax

kony.gms.safetynet.isVerifyAppsEnabled(successCallback, failureCallback);

Input Parameters

Example

function isVerifyAppsEnabled() {
    kony.gms.safetynet.isVerifyAppsEnabled(successCallback, failureCallback);
}
function successCallback(result) {
    alert("isVerifyAppsEnabled API result is " + result); // Perform the appropriate action based on the result.
}
function failureCallback(errorCode, errorMessage) {
alert("isVerifyAppsEnabled API failed with errorCode" + errorCode + " and errorMessage " + errorMessage);
}

Return Values

None

Remarks

None

Platform Availability

• Android

The API allows your app to invoke a dialog box requesting that the user enable the Verify Apps feature.

The result is returned through the result callback.

Syntax

kony.gms.safetynet.enableVerifyApps(successCallback, failureCallback);

Input Parameters

Example

kony.gms.safetynet.enableVerifyApps(successCallback, failureCallback);
function successCallback (result) {
    alert("enableVerifyApps API result is " + result); // Perform the appropriate action based on the result.
}
function failureCallback(errorCode, errorMessage) {
alert(" enableVerifyApps API failed with errorCode " + errorCode + " and errorMessage " + errorMessage);
}

Return Values

None

Remarks

None

Platform Availability

• Android

This API identifies a list of installed apps that are known to be potentially harmful to the device. The list includes categories for the identified apps so that your app can take appropriate action.

The result is returned through the success or failure callbacks.

Syntax

kony.gms.safetynet.listHarmfulApps(successCallback, failureCallback);

Input Parameters

Example

kony.gms.safetynet.listHarmfulApps(successCallback, failureCallback);
function successCallback(result) {
    var apps = "";
    if (result != null) {
        for (var index in result) {
            apps = apps + "\n\nApp Details\n";
            apps = apps + "apkPackageName " + result[index].apkPackageName + "\n";
            apps = apps + "apkSha256 " + result[index].apkSha256 + "\n";
            apps = apps + "apkCategoryMessage " + result[index].apkCategory;
        }
    }
    if (apps === "") {
        alert("no harmful apps found in the device");
    } else {
       alert("harmful apps found in the device \n" + apps); // do Appropritate action based on the result.
    }
}
function failureCallback(errorCode, errorMessage) {
alert("listHarmfulApps API failed with errorCode " + errorCode + " and errorMessage " + errorMessage);
}

Return Values

None

Remarks

None

Platform Availability

• Android

The getSecurityProvidersList API returns a list of names all the providers that were installed during the life cycle of the app. In the list that is returned, the precedence order of the providers is preserved such that the first entry in the list is the default provider.

In case of successful provider patching, the first entry in the list must include a new provider from the GMS, GmsCore_OpenSSL.

Syntax

kony.gms.getSecurityProvidersList();

Input Parameters

None

Example

var providerList = kony.gms.getSecurityProvidersList();
kony.print("array values ::" + providerList);
if (providerList.includes("GmsCore_OpenSSL")) {
    kony.print("PROVIDER UPDATED");
} else {
    kony.print(" PROVIDER UPDATE required");
}

Return Value

List of provider names

Platform Availability

• Android

The installSecurityProvider API tries to install the security provider from Google Play Services into the application's process synchronously, and sets the provider as the default security provider.

If the value of the showUpdateDialog parameter is set to true, an appropriate Google Play Services Update or Error Resolution dialog box is displayed to the user, if required (when the value of the statusCode is set to GMS_UPDATE_REQUIRED). When the user performs an action in the dialog box, the updateDialogListener callback is triggered with the appropriate statusCode value (from the Dialog Status Callback Constants).

Even if the user selects Accept in the Google Play Services Update or Error Resolution dialog box (with the status code GMS_REQUEST_ACCEPTED), it does not imply that the installation of the security provider is successful. Users must download (or update to) the latest version of Google Play Services from the Google Play Store, and then invoke this API to install the security provider in the application process.

Syntax

kony.gms.installSecurityProvider(requestConfig);

Input Parameters

requestConfig - A mandatory parameter that is a JSON Object and contains the following fields.

Example

function providersync() {
    var updateRequestParms = {
        "showUpdateDialog": true,
        "updateDialogListener": requestDialogCallback,
        "statusCallback": statusCallback
    }
    kony.gms.installSecurityProvider(updateRequestParms);

}
function statusCallback(status) {
    var statusCode = status.statusCode;
    var gmsCode = status.gmsErrorCode;
    var updateDialogListener = status.showUpdateDialog;
    kony.print("statusCode :" + statusCode);
    kony.print("gmsCode :" + gmsCode);
    kony.print("updateDialogListener requested :" + updateDialogListener);
    if (statusCode == kony.gms.SECURITY_PROVIDER_UPDATE_SUCCESS) {
        isUpdated = true;
        kony.print("update successful");
    } else if (statusCode == kony.gms.GMS_UPDATE_REQUIRED) {
        kony.print("update required");
    } else if (statusCode == kony.gms.GMS_UPDATE_IN_PROGRESS) {
        kony.print("update in progress");
    }
}
function requestDialogCallback(status) {
    var statusCode = status.statusCode;
    kony.print("statusCode :" + statusCode);
    if (statusCode == kony.gms.GMS_REQUEST_ACCEPTED) {
        kony.print("update request accepted ");
    } else if (statusCode == kony.gms.GMS_REQUEST_CANCELLED) {
        kony.print("update request cancelled");
    }
}

Return Value

None

Platform Availability

• Android

The installSecurityProviderAsync API tries to install the security provider from Google Play Services into the application's process asynchronously, by replacing the current security provider.

Syntax

kony.gms.installSecurityProviderAsync(requestConfig);

Input Parameters

requestConfig - A mandatory parameter that is a JSON Object and contains the following fields.

Example

function providerAsync() {
    var updateRequestParms = {
        "showUpdateDialog": true,
        "updateDialogListener": requestDialogCallbackAsync,
        "statusCallback": statusCallbackAsync
    }
    kony.gms.installSecurityProviderAsync(updateRequestParms);
}
function statusCallbackAsync(status) {
    var statusCode = status.statusCode;
    var gmsCode = status.gmsErrorCode;
    var updateDialogListener = status.showUpdateDialog;
    kony.print("statusCode :" + statusCode);
    kony.print("gmsCode :" + gmsCode);
    kony.print("updateDialogListener requested :" + updateDialogListener);
    if (statusCode == kony.gms.SECURITY_PROVIDER_UPDATE_SUCCESS) {
        isUpdated = true;
        kony.print("update successful");
    } else if (statusCode == kony.gms.GMS_UPDATE_REQUIRED) {
        kony.print("update required");
    } else if (statusCode == kony.gms.GMS_UPDATE_IN_PROGRESS) {
        kony.print("update in progress");
    }
}
function requestDialogCallbackAsync(status) {
    var statusCode = status.statusCode;
    kony.print("statusCode :" + statusCode);
    if (statusCode == kony.gms.GMS_REQUEST_ACCEPTED) {
        kony.print("update request accepted ");
    } else if (statusCode == kony.gms.GMS_REQUEST_CANCELLED) {
        kony.print("update request cancelled");
    }
}

Return Value

None

Platform Availability

• Android

The getStatusString API returns the statusCode (that is returned by the kony.gms.isGooglePlayServicesAvailable API) in a human-readable string format.

The string that is returned can be used to display customized notifications (by using the kony.gms.showCustomErrorNotification) and custom dialogs boxes (by using the kony.gms.raiseGooglePlayErrorResolutionIntent).

Syntax

kony.gms.getStatusString(statusCode);

Input Parameters

Example

function checkGMSAvailabiltity() {
    var googlePlayServicesAvailabilityStatus = kony.gms.isGooglePlayServicesAvailable();
    //This check is to ensure googleplayservices is available and uptodate in device.
    if (kony.gms.getStatusString(googlePlayServicesAvailabilityStatus) == "SUCCESS") {
        // call any google api which needs above prior checkings..
    } else {
        if (kony.gms.isUserResolvableError(googlePlayServicesAvailabilityStatus)) {
            var errorString = kony.gms.getStatusString(googlePlayServicesAvailabilityStatus);
            // this errorString can be used in showing custom notification or dialogs.
        } else {
            kony.print("google play services are not available in device");
        }
    }
}

Return Value

String

A message that describes the statusCode that is returned by the kony.gms.isGooglePlayServicesAvailable API in a readable format.

Platform Availability

• Android

The isBaseLibraryAvailable API checks if the base client library is integrated with the application.

Syntax

kony.gms.isBaseLibraryAvailable();

Input Parameters

None

Example

var isBaseLibAvailable = kony.gms.isBaseLibraryAvailable();
if (isBaseLibAvailable) // This check is to ensure google play base client library is available
{

    var googlePlayServicesAvailabilityStatus = kony.gms.isGooglePlayServicesAvailable();
    // Based on this googlePlayServicesAvailabilityStatus, user may proceed with gms feature 
    api calling or call resolution api to make google play services available.

} else {
    kony.print("Base Client Library is not integrated with the application");
}

Return Value

Boolean

The API returns true if the base library is integrated with the app. If the base library is not integrated, the API returns false.

Platform Availability

• Android

The isGooglePlayServicesAvailable API checks if Google Play Services is installed and enabled on the device. The API also checks if the version of Google Play Services that is installed is not older than the one that is required for the app (based on the value of the minApkVersion parameter). If the value of the minApkVersion parameter is not valid, the kony.gms.isGooglePlayServicesAvailable API gets invoked without an argument.

Syntax

kony.gms.isGooglePlayServicesAvailable();
or
kony.gms.isGooglePlayServicesAvailable(minApkVersion);

Input Parameters

Example

var googlePlayServicesAvailabilityStatus = kony.gms.isGooglePlayServicesAvailable();
//This check is to ensure googleplayservices is available and uptodate in device.
if (kony.gms.getStatusString(googlePlayServicesAvailabilityStatus) == "SUCCESS") {
    // call any google api which needs above prior checkings..
} else {
    // proceed with resolution api
}

Example 2

var versionCode = 203965037; // google play services apk version code
var googlePlayServicesAvailabilityStatus = kony.gms.isGooglePlayServicesAvailable(versionCode);

//This check is to ensure googleplayservices is available and uptodate in device.
if (kony.gms.getStatusString(googlePlayServicesAvailabilityStatus) == "SUCCESS") {
    // call any google api which needs above prior checkings..
} else {
    // proceed with resolution api
}

Return Value

Number

This API returns the status code that indicates whether there was an error. The API can return any of the following values of the ConnectionResult class:

• SUCCESS
• SERVICE_MISSING
• SERVICE_UPDATING
• SERVICE_VERSION_UPDATE_REQUIRED
• SERVICE_DISABLED
• SERVICE_INVALID

Platform Availability

• Android

The isUserResolvableError API determines whether an error can be resolved through a user action such as, on a dialog box or a notification.

Syntax

kony.gms.isUserResolvableError(statusCode);

Input Parameters

Example

var googlePlayServicesAvailabilityStatus = kony.gms.isGooglePlayServicesAvailable();
//This check is to ensure googleplayservices is available and uptodate in device.
if (kony.gms.getStatusString(googlePlayServicesAvailabilityStatus) == "SUCCESS") {
    // call any google api which needs above prior checkings..
} else {
    if (kony.gms.isUserResolvableError(googlePlayServicesAvailabilityStatus)) {
        // call resolution api
    } else {
        kony.print("google play services are not available in device");
    }
}

Return Value

Boolean

The API returns true if the error can be resolved by using the Resolution APIs (such as kony.gms.showResolutionDialog, kony.gms.showErrorNotification, and so on). If the error cannot be resolved, the API returns false.

If the API returns true, you can invoke the kony.gms.showResolutionDialog API to display a dialog box.

Platform Availability

• Android

The makeGooglePlayServicesAvailable API displays a dialog box to address any errors based on the value of the statusCode parameter.

The dialog box displays a localized message about the error, and upon confirmation from the user (by tapping on the dialog box) directs them to the Google Play Store if the Google Play Services is out of date or missing. Users are directed to the system settings if Google Play Services is disabled on the device.

This API attempts to make Google Play Services available on the device. If Google Play Services is already available on the device, the resultCallback may be triggered immediately.

If it is necessary to display a UI to complete this request, (for example, while directing the user to the Google Play Store) the KonyMain Activity must be used to display the UI.

NOTE: You must not invoke this API when the app is running in the background.

Syntax

kony.gms.makeGooglePlayServicesAvailable(resulCallback);

Input Parameters

resultCallback [Function]: A callback function that is executed when a user actions performed and the API call is complete. The resultCallback function is a JSON Object that has the following keys:

Example

function makeGMSAvailabile() {
    //This check is to ensure googleplayservices is available and uptodate in device.
    kony.gms.makeGooglePlayServicesAvailable(resulCallback)
}

function resulCallback(result) {
    if (result.statusCode == kony.gms.MAKE_RESOLUTION_CALL_SUCCESS) {
        var googlePlayServicesAvailabilityStatus = kony.gms.isGooglePlayServicesAvailable();
        // Cross checking if resolution is done
        if (kony.gms.getStatusString(googlePlayServicesAvailabilityStatus) == "SUCCESS") {
            // call any google api which needs above prior checkings..
        }
    }
}

Return Value

None

Platform Availability

• Android

The raiseGooglePlayErrorResolutionIntent API is used to address the statusCode that is returned from kony.gms.isGooglePlayServicesAvailable if it can be resolved by the user.

When a user taps the notification, they are directed to the Google Play Store if the Google Play Services is out of date or missing. Users are directed to the system settings if Google Play Services is disabled on the device

This API has been introduced to handle background tasks that cannot (or must not) display dialog boxes.

If it is necessary to display a UI to complete this request, (for example, while directing the user to the Google Play Store) the KonyMain Activity must be used to display the UI.

Developers can use this API to display a user-defined UI instead of the system dialogs that appears when the with kony.gms.showResolutionDialog API is triggered.

This api is not allowed in app background state.

Syntax

kony.gms.raiseGooglePlayErrorResolutionIntent(statusCode, requestCode, resultCallback);

Input Parameters

Example

function checkGMSAvailabiltity() {
    googlePlayServicesAvailabilityStatus = kony.gms.isGooglePlayServicesAvailable();
    //This check is to ensure googleplayservices is available and uptodate in device.
    if (kony.gms.getStatusString(googlePlayServicesAvailabilityStatus) == "SUCCESS") {
        // call any google api which needs above prior checkings..
    } else {
        if (kony.gms.isUserResolvableError(googlePlayServicesAvailabilityStatus)) {
            var errorString = kony.gms.getStatusString(googlePlayServicesAvailabilityStatus);
            // this errorString can be used in showing custom notification or dialogs.
            // Assume u have code for custom dialog(i.e customPopup) with button named "Take Action". 
            This button has onclick callback event named "onActionClick".
            customPopup.isVisible = true;
        } else {
            kony.print("google play services are not available in device");
        }
    }
}

function onActionClick() {
    customPopup.isVisible = false;
    kony.gms.raiseGooglePlayErrorResolutionIntent(googlePlayServicesAvailabilityStatus, requestCode, resultCallback)
}

function resulCallback(result) {
    if (result.statusCode == kony.gms.kony.gms.RAISE_INTENT_SUCCESS) {
        checkGMSAvailabiltity();
        / / / Cross checking
        if resolution is done and proceed with api calls.
    }
}

Return Value

None

Platform Availability

• Android

The showCustomErrorNotification API displays a customized notification to address the statusCode that is returned by the kony.gms.isGooglePlayServicesAvailable API, if it can be resolved by the user.

When a user taps the notification, they are directed to the Google Play Store if the Google Play Services is out of date or missing. Users are directed to the system settings if Google Play Services is disabled on the device

This API has been introduced to handle background tasks that cannot (or must not) display dialog boxes.

Syntax

kony.gms.showCustomErrorNotification(statusCode, channelId, notificationId, priority, title, text);

Input Parameters

Example

function checkGMSAvailabiltity() {
    var googlePlayServicesAvailabilityStatus = kony.gms.isGooglePlayServicesAvailable();
    //This check is to ensure googleplayservices is available and uptodate in device.
    if (kony.gms.getStatusString(googlePlayServicesAvailabilityStatus) == "SUCCESS") {
        // call any google api which needs above prior checkings..
    } else {
        if (kony.gms.isUserResolvableError(googlePlayServicesAvailabilityStatus)) {
            var errorString = kony.gms.getStatusString(googlePlayServicesAvailabilityStatus);
            // this errorString can be used in showing custom notification or dialogs.
            var isCallSuccesful = kony.gms.showCustomErrorNotification(googlePlayServicesAvailabilityStatus, channedId, notificationId, priority, errorString, text)
            if (isCallSuccesful) {}
        } else {
            kony.print("google play services are not available in device");
        }
    }
}

Return Value

Boolean

The API returns true if the API is successfully invoked. The API returns false if the invocation of the API fails.

Platform Availability

• Android

The showErrorNotification API displays a system notification to address the statusCode that is returned by the kony.gms.isGooglePlayServicesAvailable API, if it can be resolved by the user.

When a user taps the notification, they are directed to the Google Play Store if the Google Play Services is out of date or missing. Users are directed to the system settings if Google Play Services is disabled on the device

This API has been introduced to handle background tasks that cannot (or must not) display dialog boxes.

Syntax

kony.gms.showErrorNotification(statusCode);

Input Parameters

Example

function checkGMSAvailabiltity() {
    var googlePlayServicesAvailabilityStatus = kony.gms.isGooglePlayServicesAvailable();
    //This check is to ensure googleplayservices is available and uptodate in device.
    if (kony.gms.getStatusString(googlePlayServicesAvailabilityStatus) == "SUCCESS") {
        // call any google api which needs above prior checkings..
    } else {
        if (kony.gms.isUserResolvableError(googlePlayServicesAvailabilityStatus)) {
            var isCallSuccesful = kony.gms.showErrorNotification(googlePlayServicesAvailabilityStatus);
            if (isCallSuccesful) {}
        } else {
            kony.print("google play services are not available in device");
        }
    }
}

Return Value

Boolean

The API returns true if the API is successfully invoked. The API returns false if the invocation of the API fails.

Platform Availability

• Android

The showResolutionDialog API displays a dialog box to address any errors based on the value of the statusCode parameter.

The dialog box displays a localized message about the error, and upon confirmation from the user (by tapping on the dialog box) directs them to the Google Play Store if the Google Play Services is out of date or missing. Users are directed to the system settings if Google Play Services is disabled on the device.

Syntax

kony.gms.showResolutionDialog(statusCode, requestCode, resultCallback);

Input Parameters

Example

function checkGMSAvailabiltity() {
    var googlePlayServicesAvailabilityStatus = kony.gms.isGooglePlayServicesAvailable();
    //This check is to ensure googleplayservices is available and uptodate in device.
    if (kony.gms.getStatusString(googlePlayServicesAvailabilityStatus) == "SUCCESS") {
        // call any google api which needs above prior checkings..
    } else {
        if (kony.gms.isUserResolvableError(googlePlayServicesAvailabilityStatus)) {
            var requestCode = 101;
            kony.gms.showResolutionDialog(googlePlayServicesAvailabilityStatus, requestCode, resulCallback)
        } else {
            kony.print("google play services are not available in device");
        }
    }
}

function resulCallback() {
    if (result.statusCode == kony.gms.kony.gms.RESOLUTION_DIALOG_ACCEPTED) {
        checkGMSAvailabiltity();
        / / / Cross checking
        if resolution is done and proceed with api calls.
    }
}

Return Value

None

Platform Availability

• Android