voltmx.gms Namespace
The voltmx.gms Namespace contains the following API elements:
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
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
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
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
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
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
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
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
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
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
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 theGMS_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
Input Parameters
None
Example
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
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
Return Value
None
Platform Availability
Android
voltmx.gms.installSecurityProviderAsync
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
Input Parameters
requestConfig - A mandatory parameter that is a JSON Object and contains the following fields.
Parameter | Description |
---|---|
showUpdateDialog [Boolean] - Optional | Displays the status of the Google Play Services update. Set the value of this parameter to true to automatically display the Google Play Services update or Error Resolution dialog box. 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
Return Value
None
Platform Availability
Android
Error Codes
Code | Description |
---|---|
100 | The number of parameters is invalid. |
101 | The parameter type is invalid. |
Google Play Services Update and Error Handling APIs
Note: Before you use these APIs, ensure that you add the
com.google.android.gms:play-services-base
entry in the build.gradle file of the project. You can use the voltmx.gms.isBaseLibraryAvailable API to check if the entry is already available in the build.gradle file.
voltmx.gms.getStatusString
The getStatusString API returns the statusCode (that is returned by the voltmx.gms.isGooglePlayServicesAvailable API) in a human-readable string format.
The string that is returned can be used to display customized notifications (by using the voltmx.gms.showCustomErrorNotification) and custom dialogs boxes (by using the voltmx.gms.raiseGooglePlayErrorResolutionIntent).
Syntax
Input Parameters
Parameter | Description |
---|---|
statusCode [Number] | The statusCode value that is returned by the voltmx.gms.isGooglePlayServicesAvailable API. |
Example
Return Value
String
A message that describes the statusCode that is returned by the voltmx.gms.isGooglePlayServicesAvailable API in a readable format.
Platform Availability
Android
voltmx.gms.isBaseLibraryAvailable
The isBaseLibraryAvailable API checks if the base client library is integrated with the application.
Syntax
Input Parameters
None
Example
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
voltmx.gms.isGooglePlayServicesAvailable
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 voltmx.gms.isGooglePlayServicesAvailable API gets invoked without an argument.
Syntax
Input Parameters
Parameter | Description |
---|---|
minApkVersion [Number] | The version of the Google Play Services library that is declared in the android:versionCode attribute of the AndroidManifest.xml. |
Example
Example 2
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
voltmx.gms.isUserResolvableError
The isUserResolvableError API determines whether an error can be resolved through a user action such as, on a dialog box or a notification.
Syntax
Input Parameters
Parameter | Description |
---|---|
statusCode [Number] | The statusCode value that is returned by the voltmx.gms.isGooglePlayServicesAvailable API. |
Example
Return Value
Boolean
The API returns true if the error can be resolved by using the Resolution APIs (such as voltmx.gms.showResolutionDialog, voltmx.gms.showErrorNotification, and so on). If the error cannot be resolved, the API returns false.
If the API returns true, you can invoke the voltmx.gms.showResolutionDialog API to display a dialog box.
Platform Availability
Android
voltmx.gms.makeGooglePlayServicesAvailable
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 Volt MX Main Activity must be used to display the UI.
Note: You must not invoke this API when the app is running in the background.
Syntax
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:
Parameter | Description |
---|---|
statusCode [Number] | A statusCode constant. This parameter can have the following values:voltmx.gms.RESOLUTION_DIALOG_ACCEPTED: The statusCode returned when the API is successfully executed, and the user navigates away from the error screen.voltmx.gms.RESOLUTION_DIALOG_FAILED: The statusCode returned when the invocation of the API fails due to invalid statusCodes.voltmx.gms.GMS_LIBRARY_MISSING: The statusCode returned when the GMS library is not linked to the app.voltmx.gms.API_NOT_SUPPORTED_IN_BACKGROUND: The statusCode returned when the app is running in the background, and the API is invoked. |
requestCode [Number] | The mapping of the responses that occur when the same result callback is used for multiple requests. |
resultCode [Number] | A value that is provided by the system based on the user action that is performed. |
statusMessage [String] | This message to be displayed if the invocation of the API fails. |
Example
Return Value
None
Platform Availability
Android
voltmx.gms.raiseGooglePlayErrorResolutionIntent
The raiseGooglePlayErrorResolutionIntent API is used to address the statusCode that is returned from voltmx.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 Volt MX Main 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 voltmx.gms.showResolutionDialog API is triggered.
This api is not allowed in app background state.
Syntax
Input Parameters
Parameter | Description |
---|---|
statusCode [Number] | The statusCode value that is returned by the voltmx.gms.isGooglePlayServicesAvailable API. |
requestCode [Number] | The mapping of the responses that occur when the same result callback is used for multiple requests. |
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: statusCode [Number]: A statusCode constant. This parameter can have the following values:voltmx.gms.RAISE_INTENT_SUCCESS: The statusCode returned when the API is successfully executed, and the user navigates away from the error screen.voltmx.gms.RAISE_INTENT_FAILED: The statusCode returned when the invocation of the API fails due to invalid statusCodes.voltmx.gms.GMS_LIBRARY_MISSING: The statusCode returned when the GMS library is not linked to the app.voltmx.gms.API_NOT_SUPPORTED_IN_BACKGROUND: The statusCode returned when the app is running in the background, and the API is invoked. requestCode [Number]: The value of the requestCode parameter that is passed during the invocation of the API. resultCode [Number]: A value that is provided by the system based on the user action that is performed. statusMessage [String]: This message to be displayed if the invocation of the API fails. |
Example
Return Value
None
Platform Availability
Android
voltmx.gms.showCustomErrorNotification
The showCustomErrorNotification API displays a customized notification to address the statusCode that is returned by the voltmx.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
Input Parameters
Parameter | Description |
---|---|
statusCode [Number] | The statusCode value that is returned by the voltmx.gms.isGooglePlayServicesAvailable API. |
channelId [Number] | A unique ID that must be set for a channel. The channelId must be unique for each pakage. |
notificationId [Number] | A unique identifier for a notification in the app. |
priority [Number] | The priority for the notification. |
title [String] | The text to be displayed in the first line or heading of the notification. |
text [String] | The text to be displayed in the second line of the notification. |
Example
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
voltmx.gms.showErrorNotification
The showErrorNotification API displays a system notification to address the statusCode that is returned by the voltmx.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
Input Parameters
Parameter | Description |
---|---|
statusCode [Number] | The statusCode value that is returned by the voltmx.gms.isGooglePlayServicesAvailable API. |
Example
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
voltmx.gms.showResolutionDialog
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
voltmx.gms.showResolutionDialog(statusCode, requestCode, resultCallback);
Input Parameters
Parameter | Description |
---|---|
statusCode [Number] | The statusCode value that is returned by the voltmx.gms.isGooglePlayServicesAvailable API. |
requestCode [Number] | The mapping of the responses that occur when the same result callback is used for multiple requests. |
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: statusCode [Number]: A statusCode constant. This parameter can have the following values:voltmx.gms.RESOLUTION_DIALOG_ACCEPTED: The statusCode returned when the API is successfully executed, and the user navigates away from the error screen.voltmx.gms.RESOLUTION_DIALOG_CANCELLED: The statusCode returned when the dialog box is dismissed by the user.voltmx.gms.RESOLUTION_DIALOG_FAILED: The statusCode returned when the invocation of the API fails due to invalid statusCodes.voltmx.gms.GMS_LIBRARY_MISSING: The statusCode returned when the GMS library is not linked to the app.voltmx.gms.API_NOT_SUPPORTED_IN_BACKGROUND: The statusCode returned when the app is running in the background, and the API is invoked. requestCode [Number]: The value of the requestCode parameter that is passed during the invocation of the API. resultCode [Number]: A value that is provided by the system based on the user action that is performed. |
Example
Return Value
None
Platform Availability
Android