More PingIdentity APIs

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

| Enum Constant | Description | |—| | PIDDataCenterTypeAU | Australia America Data Center. | | PIDDataCenterTypeDefault | Default Data Center. | | PIDDataCenterTypeEU | North America Data Center. | | PIDDataCenterTypeNA | Europe America Data Center. |

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