voltmx.gms Namespace

The voltmx.gms Namespace contains the following API elements:

Constants

Functions

Constants

The voltmx.gms namespace provides the following constants:

Dialog Status Callback

Constant	Description
GMS_UPDATE_REQUEST_ACCEPTED	The user has accepted the Google Play Services update request.
GMS_UPDATE_REQUEST_CANCELLED	The user has canceled the Google Play Services update request.
GMS_UPDATE_REQUEST_NOT_SHOWN	The Update dialog box does not appear as the API is invoked in the background without displaying the UI.

Request Status Callback

Constant	Description
GMS_UPDATE_REQUIRED	Security Crypto Provider patching is not done as Google Play Services requires and update or is disabled on the device.
SECURITY_PROVIDER_UPDATE_NOT_POSSIBLE	Security Crypto Provider patching can not be done as Google Play Services is not available on the device or an unresolvable error was encountered during patching.
GMS_UPDATE_INPROGRESS	Security Crypto Provider patching is not done as an update to Google Play Services is being installed on the device. When the Google Play Services update is in progress, the dialog box is not displayed, and Security Crypto Provider patching is skipped in silent mode.
SECURITY_PROVIDER_UPDATE_SUCCESS	Security Crypto Provider patching is successful.
GMS_LIBRARY_MISSING	Security Crypto Provider patching is not done as the GMS (Google Mobile Services/Google Play Services) Library is not bundled with the application (during the build process). To bundle the GMS Library with the app, follow the steps mentioned here.

Hints StatusCodes

Constant	Description
HINT_RETRIEVAL_SUCCESSFUL	Represents the successful retrieval of credentials from the hint.
HINT_RETRIEVAL_CANCELLED	Represents that the user has dismissed the hint picker dialog and the hint retrieval is in the canceled state.
NO_HINTS_AVAILABLE	Represents the state where no hints are available. For example, when no email account or phone number is associated with the device.
PLAYSERVICES_AUTH_LIBRARY_MISSING	Returned when the required Google Play Services Library is not implemented.
GMS_LIBRARY_MISSING	Returned when the GMS (Google Mobile Services) library is not implemented.
GOOGLE_PLAY_SERVICES_UNAVAILABLE	Returned when the Google Play Services are missing. Use the GMSErrorCode key to retrieve the Native Error Code associated with the Google Play Services Error.

Functions

The voltmx.gms namespace provides the following functions:

voltmx.gms.requestHint

---

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

voltmx.gms.requestHint({  
"callback" : callback,  
"hintTypes" : \[voltmx.gms.HINT\_TYPE\_EMAIL,voltmx.gms.HINT\_TYPE\_PHONE\_NUMBER\],  
"showCancelButton" : false  
});

Input Parameters

Parameter	Description
callback [Function] - Mandatory	A callback function that is executed after the API call is complete. This function contains a result info object with the following keys: statusCode - A StatusCode constant. GMSErrorCode - The error raised by the underlying Google Mobile Services. The value for this key is set only when the statusCode returned is voltmx.gms.GOOGLE_PLAY_SERVICES_UNAVAILABLE. selectedHint- Contains the following information about the hint that is selected by the user. id - [String]: Typically, the id is an email address, user name, or phone number. The id may also be an encoded unique identifier for a federated identity account. > Note: Phone number identifiers are normalized to the E.164 standard. userFullName - [String]: The display name of the id, if available. Typically, the display name will be the name of the user or some other string that the user can easily recognize and distinguish from other accounts that they may have. userFirstName - [String]: First name of the user userLastName - [String]: Family name or surname of the user profilePictureURI - [String]: The URL to an image of the user, if available.
> Note: The value for this key is set only when the statusCode returned is voltmx.gms.HINT_RETRIEVAL_SUCCESSFUL. These values are available only when the native code returns it.

| | hintTypes - Mandatory | Specifies the types of the hint to be retrieved in an Array. The hint type must be specified using the following constants: voltmx.gms.HINT_TYPE_EMAIL: When hints must be requested for the email address field. voltmx.gms.HINT_TYPE_PHONE_NUMBER: When hints must be requested for the phone number field. In a situation where the user might be indecisive about the type of field, both the constants can be passed in the form of an array to populate both email address and phone number hints. | | showCancelButton - Optional | Specifies if a cancel button must be displayed for the hint dialog. By default, the value of this parameter is set to true. |

Example

signupForm1(){
    voltmx.gms.requestCredentialHints({
      "callback" : this.callback.bind(this),
       "hintTypes" : [voltmx.gms.HINT_TYPE_EMAIL,voltmx.gms.HINT_TYPE_PHONE_NUMBER],
      "showCancelButton" : false
      })
  }, 
  callback(info) {
        if (result.statusCode == voltmx.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

Attestation API

voltmx.gms.safetynet.attest

---

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

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

Input Parameters

Parameter	Description
apiKey [String]	An Android API key obtained from the Google developer console.
nonce [String]	A cryptographic nonce used for anti-replay and tracking of requests.
successCallback [Function]	The callback function that must be executed when communication with the service is successful. This callback is invoked with an argument in string format that is a cryptographically-signed attestation. This parameter does not indicate if the device has passed SafetyNet attestation.
failureCallback [Function]	The callback function that must be executed when the API call fails. The signature of the callback function is failureCallback(errorCode,errormessage), where the errorCode parameter is a SafetyNetStatusCodes constant, and errorMessage parameter is a string containing the reason for the failure.

Example

var uuid = voltmx.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.  
voltmx.gms.safetynet.attest(apiKey, nonce, successCallback, failureCallback);  
function successCallback(result){  
}  
function failureCallback(errorCode,errormessage){  
}

Return Value

None.

Remarks

None.

Platform Availability

• Android

---

Verify Apps API

voltmx.gms.safetynet.isVerifyAppsEnabled

---

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

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

Input Parameters

Parameter	Description
successCallback [Function]	The callback function that must be executed after the execution of the API call is complete. The function contains information whether the Verify Apps feature is enabled or not. This callback is invoked with an argument in boolean format, where the value true means that this feature is enabled. If the value is false, the feature is not enabled.
failureCallback [Function]	The callback function that must be executed when the API call fails. The signature of the callback function is failureCallback(errorCode,errormessage), where the errorCode parameter is a SafetyNetStatusCodes constant, and errorMessage parameter is a string containing the reason for the failure.

Example

function isVerifyAppsEnabled() {  
    voltmx.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

---

voltmx.gms.safetynet.enableVerifyApps

---

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

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

Input Parameters

Parameter	Description
successCallback [Function]	The callback function that must be executed after the execution of the API call is complete. The function contains information about all the actions that the user has performed related to the Verify Apps feature, including whether they have given consent to enable it. This callback is invoked with an argument in boolean format, where the value true means that this feature is enabled. If the value is false, the feature is not enabled.
failureCallback [Function]	The callback function that must be executed when the API call fails. The signature of the callback function is failureCallback(errorCode,errormessage), where the errorCode parameter is a SafetyNetStatusCodes constant, and errorMessage parameter is a string containing the reason for the failure.

Example

voltmx.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

---

voltmx.gms.safetynet.listHarmfulApps

---

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

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

Input Parameters

Parameter	Description
successCallback [Function]	The callback function that must be executed when the API call is successful. The signature of the callback function is successCallback(resultInfo), where, resultInfo contains an array of jsobjects, where each jsobject contains the following information: apkCategory [String]: Message about the potentially harmful app category defined in VerifyAppsConstants. apkPackageName [String]: The package name of the potentially harmful app. apkSha256 [String]: The SHA-256 of the potentially harmful APK file.
failureCallback [Function]	The callback function that must be executed when the API call fails. The signature of the callback function is failureCallback(errorCode,errormessage), where the errorCode parameter is a SafetyNetStatusCodes constant, and errorMessage parameter is a string containing the reason for the failure.

Example

voltmx.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

---

Security Provider APIs

Note: Ensure that you include the GMS base library dependency in the app by adding the supportGooglePlayBaseLib = true entry in the androidbuild.properties file of the project. If you do not add this dependency, the security provider APIs return the GMS_LIBARAY_MISSING constant in the request callback.

voltmx.gms.getSecurityProvidersList

---

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

voltmx.gms.getSecurityProvidersList();

Input Parameters

None

Example

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

Return Value

List of provider names

Platform Availability

Android

voltmx.gms.installSecurityProvider

---

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

voltmx.gms.installSecurityProvider(requestConfig);

Input Parameters

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

Parameter	Description
showUpdateDialog [Boolean] - Optional	Set the value of this parameter to true to automatically display the Google Play Services update or Error Resolution dialog box. If you invoke this API when the app is running in the background (or there is no UI), the dialog box does not appear. The default value of this parameter is false.
statusCallback [Function] - Mandatory	A callback function that provides the status of the provider update. The statusCallback function is a JSON Object that has the following keys: statusCode: A constant that specifies the status of installation, either success or failure. For the list of possible constants, refer Request Status Callback Constants. gmsErrorCode: The error code returned by native GMS library. This parameter is set when the statusCode is set to GMS_UPDATE_REQUIRED. showUpdateDialog: The value of the showUpdateDialog parameter that is passed when the API is invoked. This information helps in deciding if a GMS Update or Error resolution dialog box is already displayed when the statusCode is set to GMS_UPDATE_REQUIRED.
updateDialogListener [Function] - Optional	A callback function that provides the status of the user action on the Google Play Services update or Error Resolution dialog box. The updateDialogListener function is a JSON Object that has the following keys: statusCode: A constant that specifies the status of the user action. For the list of possible constants, refer Request Status Callback Constants. gmsErrorCode: The error code returned by native GMS library that is used to display the GMS Update or Error Resolution dialog box. This parameter is set when the statusCode is set to GMS_UPDATE_REQUEST_CANCELLED or GMS_UPDATE_REQUEST_NOT_SHOWN.

Example

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

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

Return Value

None

Platform Availabilit