Android PingID SDK Mobile API for Android

PingID SDK provides the ability to integrate PingID MFA functionality into your mobile applications.

The PingID SDK Mobile API for Android is included in the SDK package. The functions, parameters and error codes are listed below.

For further details on how to integrate PingID SDK into your Android applications, refer to Android implementation in the Getting started section.

PingID SDK Mobile API - Android

PingID

Nested Class Summary

Modifier and Type	Class and Description
`static class`	`PingID.PIDActionStatus`: The enum of Action Statuses.
`static class`	`PingID.PIDActionType`: The enum of Action Types.
`static class`	`PingID.PIDDataCenterType`: The enum of Data Center type. `PIDDataCenterTypeDefault`: Default Data Center. `PIDDataCenterTypeNA`: North America Data Center. `PIDDataCenterTypeAU`: Australia Data Center. `PIDDataCenterTypeEU`: Europe Data Center.
`static class`	`PingID.PIDErrorDomain`: The enum of errors returned from the init function.
`static class`	`PingID.PIDIgnoreIntervalUnit`: The enum of Interval Types.
`static class`	`PingID.PIDSupportedMfaType`: Supported MFA types.
`static class`	`PingID.PIDTrustLevel`: The enum of available trust levels (action to be taken when prompted to pair a device).
`static interface`	`PingID.PingIdSdkEvents`: Interface for events triggered from the PingID SDK library.

Method Detail

init

public static void init(android.app.Application application,
                        java.lang.String applicationId,
                        PingID.PingIdSdkEvents pingIdSdkEvents,
                        java.lang.String pushSenderId)
                 throws java.lang.Exception

Initialization function for the PingID SDK library.

Parameter	Description
`application`	Android application instance of the customer app.
`applicationId`	Application identifier.
`pingIdSdkEvents`	Object which implements the PingIDSDKEvents interface.
`pushSenderId`	Gcm/Fcm Sender Id

Throws:

java.lang.Exception: Exception in case of an error during initialization.

Initializes the PingID singleton instance with supported MFA of type PIDSupportedMfaTypeAutomatic. This method will be deprecated in future releases. Please use init(Application application, String applicationId, PingIdSdkEvents pingIdSdkEvents, String pushSenderId, PIDSupportedMfaType pidSupportedMfaType) instead.

init

public static void init(android.app.Application application,
                        java.lang.String applicationId,
                        PingID.PingIdSdkEvents pingIdSdkEvents,
                        java.lang.String pushSenderId,
                        PingID.PIDSupportedMfaType pidSupportedMfaType)
                 throws java.lang.Exception

Initialization function for the PingID SDK library.

Parameter	Description
`application`	Android application instance of the customer app.
`applicationId`	Application identifier.
`pingIdSdkEvents`	Object which implements the PingIDSDKEvents interface.
`pushSenderId`	Gcm/Fcm Sender Id.
`pidSupportedMfaType`	Supported MFA Type.

Throws:

java.lang.Exception: Exception in case of an error during initialization.

Initializes the PingID singleton instance.

getInstance

public static PingID getInstance()

Returns the running instance of this object.

Returns:

PingIDSdkClient instance

setUserSelection

public void setUserSelection(pingidsdkclient.PIDUserSelectionObject pidUserSelectionObject)
                      throws java.lang.Exception

Used for starting the pairing action after the user has chosen how to pair (primary/trusted/ignore).

Parameter	Description
`pidUserSelectionObject`	PIDUserSelectionObject instance with data about whether and how to pair the new device.

Throws:

java.lang.Exception: Exception thrown in case of an error.

getPingIdSdkServerUrlForDebugging

public java.lang.String getPingIdSdkServerUrlForDebugging()

Get PingID SDK server URL for debugging. release build always return null.

Returns:

The string: For debugging only.

isGooglePlayServicesAvailable

public boolean isGooglePlayServicesAvailable()

Is google play services available on this device.

Returns:

The boolean: Returns whether push messages (using Google Play services) is enabled or disabled on this device.

updateExistingPayloadWithUserSelection

public java.lang.String updateExistingPayloadWithUserSelection(java.lang.String userAnswer,
                                                               java.lang.String ignoreInterval)
                                                        throws java.lang.Exception

Returns the current payload as a string.

Parameter	Description
`userAnswer`	The user answer in case we need it in the payload.
`ignoreInterval`	Period of time to ignore this device.

Returns:

The current payload.

Throws:

java.lang.Exception: The exception.

generatePayload

public java.lang.String generatePayload()
                                 throws java.lang.Exception

* @Deprecated - use the generatePayload(final PayloadCallback callback) method instead

Deprecated.

Returns the current mobile payload as a string.

Returns:

The current payload.

Throws: java.lang.Exception: When an error occurs.

generatePayload

public java.lang.String generatePayload(PayloadCallback callback)
                                 throws java.lang.Exception

Returns the current mobile payload as a string in a callback parameter in a different thread (asynchronously).

Returns:

The current payload.

Throws: java.lang.Exception: When an error occurs.

setServerPayload

public void setServerPayload(java.lang.String payload,
                             java.lang.String userAnswer,
                             java.lang.String deviceName)
                      throws java.security.SignatureException,
                             java.lang.Exception

Sets the payload received from the customer server.

Parameter	Description
`payload`	The string containing the payload.
`userAnswer`	The string containing the device type (primary/trusted) that the user has chose.

Throws:

java.lang.Exception: Exception in case of error. java.security.SignatureException

setServerPayload

public void setServerPayload(java.lang.String payload)
                      throws java.lang.Exception

Sets the payload received from the customer server.

Parameter	Description
`payload`	The string containing the payload.

Throws:

java.lang.Exception: Exception in case of error.

setAuthenticationUserSelection

public void setAuthenticationUserSelection(PingID.PIDUserSelectionObject userSelection)
                                    throws java.lang.Exception

Sets the authentication result of the user’s selection (approve/deny/block) in the customer app

Parameter	Description
`userSelection`	The result (success/failure).

Throws:

java.lang.Exception: Exception in case of error.

postIDPAuthenticationStepWithDataCenter

public void postIDPAuthenticationStepWithDataCenter(PingID.PIDDataCenterType dataCenter)

This is a mandatory post action method which should be executed once, after receiving an access token from Ping Federate.

Parameter	Description
`dataCenter`	The data center that should be used.

setPushDisabled

public void setPushDisabled(boolean pushDisabled)

Sets a boolean value indicating whether the PingID SDK library should behave as if there are no Push capabilities on this device.

Parameter	Description
`pushDisabled`	The push is disabled.

setSimulatePushDisabled

@Deprecated

public void setSimulatePushDisabled(boolean pushDisabled)

Deprecated.

Sets a boolean value indicating whether the PingID SDK library should behave as if there are no Push capabilities on this device. Deprecated. Please replace with “setPushDisabled”.

Parameter	Description
`pushDisabled`	The push is disabled.

isPushDisabled

public boolean isPushDisabled()

Returns whether push capabilities are disabled.

Returns:

The boolean

sendLogs

public void sendLogs()

Sends PingID SDK library logs to the PingID SDK servers. This will be done asynchronously, and when finished, the “onLogsSentToServer” method will be triggered with a support Id value to enable the developer to track the problem.

isDeviceTrusted

public boolean isDeviceTrusted()

Returns the trusted status of current device.

Returns:

The boolean

validateAuthenticationToken

public void validateAuthenticationToken(String token)

Validates the authentication token from a QR code.

Parameter	Description
`token`	The token that was extracted from the QR Code.

getOneTimePasscode

public java.lang.String getOneTimePasscode()
                                 throws java.lang.Exception
* @Deprecated - use the getRestrictiveOneTimePasscode method instead

Deprecated.

Returns the OTP or empty string if the root detection feature is active.

Throws: java.lang.Exception: When an error occurs.

getRestrictiveOneTimePasscode

public java.lang.String getRestrictiveOneTimePasscode(GetRestrictiveOneTimePasscodeCallback callback)
                                 throws java.lang.Exception

Returns the OTP and status of the response in a callback parameter in a different thread (asynchronously)

Throws: java.lang.Exception: When an error occurs.

setRootDetection

public void setRootDetection(boolean toActivate, PIDDataCenterType dataCenter, String androidDeviceVerificationApiKey)

Activate mobile root detection.
If root detection is enabled on the server, this function must be called.
If root detection is not enabled on the server, this function is optional.

Parameter	Description
`toActivate`	Turn root defection on or off. Activate SafetyNet.
`androidDeviceVerificationApiKey`	Google SafetyNet API key.

PingID.PIDActionStatus

Enum Constant Summary

Enum Constant	Description
`FAILURE`	Failure action status.
`SUCCESS`	Success action status.

PingID.PIDActionType

Enum Constant Summary

Enum Constant	Description
`PIDActionTypeApprove`	Approve action type.
`PIDActionTypeBlock`	Block action type.
`PIDActionTypeDeny`	Deny action type.
`PIDActionTypeNone`	None action type.

PingID.PIDDataCenterType

Enum Constant Summary

PingID.PIDErrorDomain

Enum Constant Summary

Enum Constant	Description
`PIDErrorAppDisabled`	Application disabled error.
`PIDErrorDeviceTokenIsMissing`	Missing Push Sender Id.
`PIDErrorNoInternetConnection`	Internet connectivity error.
`PIDErrorProblemWithPublicKey`	Error in public key error.
`PIDErrorTimeout`	Timeout error.
`PIDErrorUnknown`	Error unknown.
`PIDErrorWithPairing`	Error in the pairing flow.
`PIDErrorWrongAppID`	Wrong application Id error.
`PIDErrorWrongSignature`	Wrong signature error.
`PIDInternalError`	Internal error.
`PIDMissingPermissions`	Missing permissions error.
`PIDNetworkError`	Network error.

PingID.PIDIgnoreIntervalUnit

Enum Constant	Description
`days`	Days interval type.
`hours`	Hours interval type.
`minutes`	Minutes interval type.
`months`	Months interval type.
`weeks`	Weeks interval type.
`years`	Years interval type.

PingID.PIDSupportedMfaType

Enum Constant	Description
`PIDSupportedMfaTypeAutomatic`
`PIDSupportedMfaTypeDisableRemoteNotifications`	PIDSupportedMfaTypeEnforceRemoteNotifications: MFA Supports remote notifications only.
`PIDSupportedMfaTypeEnforceRemoteNotifications`	PIDSupportedMfaTypeAutomatic: MFA Supports Remote Notifications with automatic fallback to one time passcode.

PingID.PIDTrustLevel

Enum Constant	Description
`PIDTrustLevelIgnored`	Indicator that the device should be ignored for a specific time interval.
`PIDTrustLevelPrimary`	Indicator that the device should be paired as a primary device.
`PIDTrustLevelTrusted`	Indicator that the device should be paired as a trusted device.

PingID.PingIdSdkEvents

Method Detail

onPairingOptionsRequired

void onPairingOptionsRequired(java.util.List<java.lang.String> availableTrustLevels,
                              pingidsdkclient.DeviceDetails deviceDetails)

Triggered when the PingID SDK library requires the application to prompt the user for the pairing action type to be performed: pair as primary/trusted or ignore the device.

Parameter	Description
`availableTrustLevels`	The available trust level.
`deviceDetails`	The device details.

onPairingOptionsRequiredWithPasscode

void onPairingOptionsRequiredWithPasscode(java.util.List<java.lang.String> availableTrustLevels,
                                          java.lang.String deviceName)

Triggered when the PingID SDK library requires the application to prompt the user for the pairing action type to be performed: pair as primary/trusted or ignore the device. Triggered when the user’s authorizing primary/trusted device is offline or unreachable.

Parameter	Description
`availableTrustLevels`	The available trust level.
`deviceDetails`	The device details.

onPairingCompleted

void onPairingCompleted(PingID.PIDActionStatus status,
                        PingID.PIDErrorDomain pidErrorDomain)

Triggered when pairing flow is completed.

Parameter	Description
`status`	The status of the operation.

onIgnoreDeviceCompleted

void onIgnoreDeviceCompleted(PingID.PIDActionStatus status,
                             PingID.PIDErrorDomain pidErrorDomain)

Triggered when the ignore device operation is completed.

Parameter	Description
`status`	The status of the operation.

onAuthenticationCompleted

void onAuthenticationCompleted(PingID.PIDActionStatus status,
                               PingID.PIDActionType actionType,
                               PingID.PIDErrorDomain pidErrorDomain)

Triggered when the authentication is completed (approved/denied/blocked).

Parameter	Description
`status`	The status of the operation.

onGeneralMessage

void onGeneralMessage(java.lang.String msg)

Used to pass debug messages to the customer app.

Parameter	Description
`msg`	The message.

onPairingProgress

void onPairingProgress(java.lang.String msg)

Used to notify the customer app about progress in the pairing flow.

Parameter	Description
`msg`	The message.

onAuthenticationRequired

void onAuthenticationRequired(android.os.Bundle data)

Triggered when there is an incoming authentication request from the PingID SDK server.

onError

void onError(java.lang.Throwable throwable,
             java.lang.String description)

Used to notify the customer app about errors in pairing and authentications.

Parameter	Description
`throwable`	The throwable.
`description`	The description.

onLogsSentToServer

void onLogsSentToServer(PingID.PIDActionStatus status,
                        java.lang.String supportId)

Triggered after logs have been uploaded to the PingID SDK server (successfully or unsuccessfully).

Parameter	Description
`status`	The status.
`supportId`	The support id.

onGooglePlayServicesStatusReceived

void onGooglePlayServicesStatusReceived(int status)

Triggered after the PingID SDK library checks the Google Play Services status on the device running the customer app.

Parameter	Description
`status`	The status returned from the Google Play Services library.

onOneTimePasscodeChanged

void onOneTimePasscodeChanged(java.lang.String newOneTimePasscode)

Triggered when the OneTimePasscode changes.

Parameter	Description
`newOneTimePasscode`	The otp.

onAuthenticationCancelled

void onAuthenticationCancelled()

Triggered when the PingID SDK server cancels an authentication.

onServicePayloadReceivedWithStatusDone

void onServicePayloadReceivedWithStatusDone()

Called when the SDK receives the payload from the PingID server and parses it sucessfully.

authenticationTokenStatus

void authenticationTokenStatus(Bundle sessionInfo, PIDErrorDomain pidErrorDomain)

Get the token status once it changes.

Parameter Description

Parameter	Description
`sessionInfo`	`sessionInfo` includes the parameter “authentication_token_status” with the possible statuses: `CLAIMED`: The authentication token was successfully claimed. `CLAIMED_AND_PUSH_FAILED`: The authentication token was successfully claimed. The push verification failed. `CLAIMED_AND_PUSHLESS`: The authentication token was successfully claimed. The push verification was not executed since the device is pushless. `PENDING_USER_APPROVAL`: The mobile application should ask the user for approval. `MOBILE_USER_SELECTION`: The mobile application should select the user from the user list. (an additional “users” parameter will be returned in the response). `MOBILE_USER_SELECTION_AND_APPROVAL`: The mobile application should select the user from the user list AND ask the user for approval (an additional “users” parameter will be returned in the response). `WEB_USER_SELECTION`: The web is selecting the users. `PENDING_PUSH_VERIFICATION`: A silent push was sent to the mobile for extra verification. `CANCELED`: The authentication with the given authentication token was canceled. `DENIED`: The user denied the authentication with the given authentication token. `sessionInfo` may also include “client_context” and a “users” array. Each element in the “users” array is a JSON object with the following properties: `username`: The username. This value is never empty. `firstName`: The user’s first name. This value may be empty. `lastName`: The user’s last name. This value may be empty. `status`: The user’s status, which is expected to be one of the following: `ACTIVE` `SUSPENDED`
pidErrorDomain	Error notification. Null, when there is no error.

sessionInfo

sessionInfo includes the parameter “authentication_token_status” with the possible statuses:

CLAIMED: The authentication token was successfully claimed.
CLAIMED_AND_PUSH_FAILED: The authentication token was successfully claimed. The push verification failed.
CLAIMED_AND_PUSHLESS: The authentication token was successfully claimed. The push verification was not executed since the device is pushless.
PENDING_USER_APPROVAL: The mobile application should ask the user for approval.
MOBILE_USER_SELECTION: The mobile application should select the user from the user list. (an additional “users” parameter will be returned in the response).
MOBILE_USER_SELECTION_AND_APPROVAL: The mobile application should select the user from the user list AND ask the user for approval (an additional “users” parameter will be returned in the response).
WEB_USER_SELECTION: The web is selecting the users.
PENDING_PUSH_VERIFICATION: A silent push was sent to the mobile for extra verification.
CANCELED: The authentication with the given authentication token was canceled.
DENIED: The user denied the authentication with the given authentication token.

sessionInfo may also include “client_context” and a “users” array.
Each element in the “users” array is a JSON object with the following properties:

username: The username. This value is never empty.
firstName: The user’s first name. This value may be empty.
lastName: The user’s last name. This value may be empty.
status: The user’s status, which is expected to be one of the following:
- ACTIVE
- SUSPENDED

pidErrorDomain Error notification.
Null, when there is no error.

didUntrustDevice

void didUntrustDevice()

Be notified if the device was untrusted from the server.

PingIdPushHelper

Method Detail

handlePushMessage

public static void handlePushMessage(android.content.Context context,
                                     java.lang.String from,
                                     android.os.Bundle data)

Enables the customer app to process PingID SDK push messages that arrive to the customer app’s GCM/FCM listener

Parameter	Description
`context`	Context for processing the msg
`from`	GCM/FCM Sender Id
`data`	Bundle containing the msg data

PingID SDK Mobile API error codes

Error	Description	Failure reason	Recovery suggestion
PIDErrorInternal	An internal error occurred.	An unknown error has occurred.	Please contact PingID Support.
PIDErrorWithPairing	There was a problem with the pairing process.	An unknown error has occurred.	Please contact PingID Support.
PIDErrorAppDisabled	The current App Id is disabled in the PingOne admin console.	The current App Id is disabled in the PingOne admin console.	You can enable the app in the PingOne admin console.
PIDErrorRemoteNotificationTimeout	Remote notification timeout.	The remote notification didn’t reach the device. This could be due to a certificate problem or a connectivity issue.	Make sure the certificates in PingOne admin console are valid for both enviroments. Also make sure that you have a working internet connection.
PIDErrorNoInternetConnection	There was a problem with your internet connection.	There was a problem with your internet connection.	Check that you have a working internet connection.
PIDErrorWrongSignature	There was a problem verifying the response from the server.	An unknown error has occurred.	Please contact PingID Support.
PIDErrorReachability	There was a problem connecting to the server.	There was a problem connecting to the server.	Check that you have a working internet connection.
PIDErrorServerResponse	There was a problem with the server response.	There was a problem with the server response.	Please contact PingID Support.
PIDErrorServerInternal	There was a problem with the server response.	There was a problem with the server response.	Please contact PingID Support.
PIDErrorWithServerPayload	There was a problem with the server payload.	The server payload can’t be decoded.	Make sure that you pass the exact payload value you receive from the customer server response to the setServerPayload method.
PIDErrorSelectionIsMissing	There was a problem with your PIDUserSelectionObject.	One or more mandatory items were not selected.	PIDUserSelectionObject must contain at least a trustLevel or an action.
PIDErrorDeviceTokenIsMissing	There was a problem finding the device token.	One or more mandatory items were not found.	PingID SDK must contain the device token in order to support remote notification MFA.