The PingOne Native SDK provides the ability to integrate PingOne MFA functionality into your native applications. Topics include:

• PingOne MFA Native SDK flows

• PingOne Native SDK for Android

• PingOne Native SDK for iOS

• PingOne MFA SDK error codes

Pairing - automatic enrollment

The automatic enrollment flow requires as little as one extra step from the user. The first time the user logs into an application which has an embedded PingOne Native SDK component, they are asked if they wish to trust that device. Once they approve, PingOne works behind the scenes, without requiring anything else from the user.

During user authentication, a native app communicates with the PingOne platform to generate a token. The token allows pairing the device to the user in the context of a customer application. The user is not required to type or scan anything.

1. The user is identified on the customer native application, usually with a unique user identifier, for example, a username.
2. The PingOne Native SDK returns a native payload to the customer native application. The payload is a small data package created by the PingOne Native SDK component, which is used as part of the device's authorization.
3. The customer native application sends an authentication request to the PingOne Platform, including the native payload.
4. The customer native application receives an ID token.
5. The customer native application passes the ID token to the PingOne Native SDK.
6. The PingOne Native SDK returns a pairing object to the customer native application, to pair or ignore the device.
7. The customer native application prompts the user for the approve or deny action via a dialog. Based on the user's choice, the customer native application notifies PingOne Native SDK.
8. The PingOne Native SDK completes the transaction accordingly, by communicating directly with PingOne Platform.

Implement automatic pairing of native app as MFA authenticator app

In order to enable automatic pairing of a native app as an MFA authenticator app, there are several tasks that must be coordinated between admin and developers.
In brief, you will do the following:

• Create a native application with Authenticator configuration.
• Configure a sign-on policy containing an MFA step that references an MFA policy where the native application is configured as an authenticator.
• Assign the sign-on policy to the native app.
• Write code in the application to support automatic app enrollment.

Follow the detailed steps below:

Supply the relevant details for the admin to do the following in the PingOne admin console:

Admin tasks

1. Create a native app. See Add an application - Native.
2. In Edit an application, on the Mobile tab:
   • Add the Package name (Android) and Bundle ID (iOS) of your native application.
   • Configure the push credentials per platform.
3. Create a new MFA policy.
4. In the MFA policy, use the Add Application option to select the name of your mobile app. In the settings for the app you added, select the Auto Enrollment option.
5. Create a sign-on policy, and add an MFA step. See Add an authentication policy.
6. In the MFA step, select the MFA policy that you configured. Also, if you want to allow automatic enrollment even if the user does not have any existing paired devices, set the "NONE OR INCOMPATIBLE METHODS" setting to Bypass.
7. Return to the Applications page and edit your mobile application. On the Policies tab, choose the sign-on policy that you created. This is necessary so that the authenticator element of your application will be launched when users try to access the application.

Developer tasks

In your native application code (also described in the iOS and Android README.md files, see PingOne Native SDK for iOS or PingOne Native SDK for Android):

7. Get the native payload from the SDK (PingOne.generateMobilePayload())
8. Pass the received payload of the OIDC request to the authorization service, as the mobilePayload query parameter.
9. Call processIdToken() with the token you received from PingOne platform.
10. If automatic pairing is triggered (i.e. the user was not already paired with the device), processIdToken() will return a pairing object with approve() and deny() functions. Calling approve() will pair the user with the device.

Automatic device authorization

During automatic device authorization, a native app communicates with the PingOne platform to generate a token. The token allows authenticating the user device in the context of a customer application. The user is not aware of this, and is not required to type or scan anything.

1. The customer native app requests a native payload from the PingOne Native SDK.
2. The PingOne Native SDK returns a native payload to the customer native application.
3. The customer native application sends an authentication request to the PingOne Platform, including the native payload.
4. If the platform's authentication flow (sign-on policy) contains an MFA step, and extra verification is disabled, the platform verifies that the native device is paired and active, authenticates the native device, and the MFA step succeeds. The flow skips to step 9.
5. The platform verifies that the native device is paired and active and sends a "silent" push notification to the native application via the APNS/GCM notification service.
6. The native application passes the "silent" notification to the PingOne Native SDK.
7. The PingOne Native SDK acknowledges receiving the "silent" push by sending a confirmation directly to the PingOne platform.
8. The platform authenticates the native device, and the MFA step succeeds.
9. The customer native application receives an ID token from the PingOne Platform.
10. The customer native application passes the ID token to the PingOne Native SDK.
11. The PingOne Native SDK returns null to the customer native application, indicating that authorization has completed and no further action needs to be taken.

Implement automatic device authorization

Admin tasks

The admin configuration that was implemented for automatic enrollment, is applied to automatic device authorization.

1. Create a native app, or edit an existing app. See Add an application - Native.
2. In Edit an application, on the Mobile tab:
   • Add the Package name (Android) and Bundle ID (iOS) of your native application.
   • Configure the push credentials per platform.
3. Create a new MFA policy.
4. In the MFA policy, use the Add Application option to select the name of your mobile app. In the settings for the app you added, enable Device Authorization. In the Extra Verification drop-down list, you can optionally select Permissive or Restrictive. For details on these two options, see Adding an MFA policy.
5. Create a sign-on policy, and add an MFA step. See Add an authentication policy.
6. In the MFA step, select the MFA policy that you configured.
7. Return to the Applications page and edit your mobile application. On the Policies tab, choose the sign-on policy that you created. This is necessary so that the MFA policy you configured and included in the sign-on policy will be applied when users try to access the application.

Developer tasks

In your native application code (also described in the iOS and Android README.md files, see PingOne Native SDK for iOS or PingOne Native SDK for Android):

1. Get the native payload from the SDK (PingOne.generateMobilePayload())
2. Pass the received payload of the OIDC request to the authorization service, as the mobilePayload query parameter.
3. Call processIdToken() with the token you received from PingOne platform.
4. If device authorization is triggered (i.e. verification that the user's device is already paired and active), processIdToken() will return null, indicating that authorization has completed and no further action needs to be taken.

During an authentication code flow, a native app communicates with the PingOne platform to initiate authentication with an authentication code, which can be a QR code. The flow starts with a call to the Create Authentication Code endpoint. The Mobile SDK validates the code value and returns an AuthenticationObject to the mobile app.

1. The customer mobile app requests an authentication code flow from the PingOne Mobile SDK.
2. The Mobile SDK requests validation of the authentication code value from the PingOne platform.
3. If the authentication code value is validated by the PingOne platform, the Mobile SDK creates an AuthenticationObject.
4. The Mobile SDK returns the AuthenticationObject to the customer mobile app.
5. If the status property value of the AuthenticationObject is CLAIMED, the flow continues. For all other status values, the flow ends.
6. If the number of users is two or more, the flow presents the user with an option to choose a specific user from the list. If the AuthenticationObject specifies only one user, the flow continues without requiring this step.
7. If the user approval setting has a value of REQUIRED, the mobile app prompts the user to approve or deny the current authentication session. If user approval is set to NOT_REQUIRED, the authentication flow skips this step.
8. The customer mobile app makes a validation request to the Mobile SDK.
9. The Mobile SDK claims authentication with the selected user and queries the PingOne server.
10. The PingOne server returns an authentication status.

Implement an authentication code flow

Admin tasks

To configure direct triggering of the mobile application in an authentication code flow:

1. Create a native app, or edit an existing app. See Add an application - Native.
2. Use the Authenticator tab to allow mobile authentication for the app. If your organization uses the PingOne MFA SDK to allow authentication with a QR code in certain flows, the admin can optionally configure a universal link or schema app link to enable direct triggering of the mobile application when scanning a QR code with a QR scanner. See Editing an application - Native.

Developer tasks

In your native application code (also described in the iOS and Android README.md files, see PingOne Native SDK for iOS or PingOne Native SDK for Android):

1. Pass the retrieved authentication code to the mobile SDK by calling PingOne.authenticate().
2. Parse the retrieved AuthenticationObject. If the status field equals CLAIMED, proceed to the next step.
3. If the number of users is more than one and/or the value of the field needsApproval equals REQUIRED, the AuthenticationObject will contain approve() and deny() options.
4. Call the approve() method of the AuthenticationObject with the corresponding userId to complete the authentication.

Overview

The PingOne MFA Native SDK provides the ability to integrate PingOne MFA functionality into your native applications.

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

The PingOne MFA Native SDK package is available for download at https://github.com/pingidentity/pingone-mobile-sdk-android. Further details for setup and integrating PingOne MFA Native SDK into your native apps are available in the README file in the Android folder of the downloadable package.

The PingOne SDK for Android supports the following software versions:

• Android 8 (API 26) and greater

See Edit an application in the admin guide for the server-side configuration steps.

PingOne MFA Native SDK sample app

The PingOne MFA Native SDK bundle provides a sample app that includes all the basic flows in order to help you get started.

The sample app package for Android is available for download at https://github.com/pingidentity/pingone-mobile-sdk-android. Further details are available in the README file in the Android folder of the downloadable package.

Authenticator sample app

The Authenticator sample app is a native app that has the sole function of performing strong authentication. It provides a simple example for developers and solution architects, to enable easy and rapid deployment of an authenticator app with minimal effort.

For scenarios which solely require creation of a native authenticator rather than a full native native app, the Authenticator sample app offers a passwordless and secured solution, that only requires compilation of the sample with customer's branding and credentials, and uploading it to the app store.

The Authenticator sample app package for Android is available for download at https://github.com/pingidentity/pingone-authenticator-sample-app-android/. Further details are available in the README file.

Mobile device integrity check

PingOne has an integrated mobile device integrity check in its MFA flows, which allows mobile applications to deny access when a mobile device is suspected to be compromised.

Mobile device integrity check - admin UI configuration

Each application must be set up and configured in the organization's PingOne environment, either in the admin UI, or using the MFA devices API. The development team provides the admin with the application name and details.

The admin's configuration of device integrity detection is detailed in the PingOne admin guide. See Editing an application - Native.

Mobile device integrity check - Android implementation

PingOne uses Google's Play Integrity API to check the integrity of the mobile device. For details on the capabilities of the Play Integrity API, see the Play Integrity API documentation.

Mobile app developers are responsible for enabling and monitoring usage of the Play Integrity API.

The following steps are required:

1. Create a Google Cloud project or use an existing one
   For details on working with Google Cloud projects, see Creating and managing projects. The PingOne mobile SDK component requires the number of your Google Cloud project.

2. Enable the Google Play Integration API
   Go to APIs and Services and select Enable APIs and Services. Search for the Play Integrity API, select it, and then select Enable.

3. Link your application to the Google Cloud project
   Applications distributed on Google Play must be linked to the Google Cloud project so that they can call the Play Integrity API. In the developer console of the Google Play Store, choose your application. Go to Setup > App integrity > Google Cloud Project, and link your application to the Google Cloud project where you've enabled the Play Integrity API.

4. Configure how your responses are encrypted and decrypted (optional)
   For applications distributed on Google Play, you can choose between Google-managed response encryption (the default and recommended option) and self-managed response encryption. For both of these options, you'll need to provide the relevant keys in the PingOne console when you define the application. See Configure how your responses are encrypted and decrypted for more information on managing and downloading response encryption keys.

5. Monitor Play Integrity API usage
   If your quota for Play Integrity API usage is reached, users could end up getting blocked. So it's important to monitor Play Integrity usage. For more information on usage tiers and requesting a higher quota, see API usage tiers.

6. Request a higher quota if needed
   The form for requesting a move to a higher usage tier includes questions that are application-dependent. For the question How are you calling the Play Integrity API?, select the A third party I'm using in the app is calling the API option, and specify PingOne Mobile SDK Android.

7. Estimate the number of queries per day to request a specific tier
   The quota request should take into account both your application's expected traffic and the mobile SDK component's caching and retry policy. If there was a successful response from the Play Integrity API that passed the integrity test, no additional Play Integration requests will be made until after the integrity check cache duration that you defined for the application.

PingOne MFA Native SDK API - Android

See the API documentation.

Overview

The PingOne MFA Native SDK provides the ability to integrate PingOne MFA functionality into your native applications.

The PingOne MFA Native SDK API for iOS is declared in the PingOne.h header file included in the SDK package. This header file (replicated below) includes descriptions for all functions, parameters and error codes.

The PingOne MFA Native SDK package is available for download at https://github.com/pingidentity/pingone-mobile-sdk-ios. Further details for setup and integrating PingOne MFA Native SDK into your native apps are available in the README file.

The PingOne SDK for iOS supports the following software versions:

• Xcode 14 and above
• iOS 12.0 and above

See Edit an application in the admin guide for the server-side configuration steps.

PingOne MFA Native SDK sample app

The PingOne MFA Native SDK bundle provides a sample app that includes all the basic flows in order to help you get started.

The sample app package for iOS is available for download at https://github.com/pingidentity/pingone-mobile-sdk-ios. Further details are available in the README file.

Authenticator sample app

The Authenticator sample app is a native app that has the sole function of performing strong authentication. It provides a simple example for developers and solution architects, to enable easy and rapid deployment of an authenticator app with minimal effort.

For scenarios which solely require creation of a native authenticator rather than a full native native app, the Authenticator sample app offers a passwordless and secured solution, that only requires compilation of the sample with customer's branding and credentials, and uploading it to the app store.

The Authenticator sample app package for iOS is available for download at https://github.com/pingidentity/pingone-authenticator-sample-app-ios. Further details are available in the README file.

Mobile device integrity check

PingOne has an integrated mobile device integrity check in its MFA flows, that allows mobile applications to deny access when a mobile device is suspected to be compromised.

Mobile device integrity check - admin UI configuration

Each application must be set up and configured in the organization's PingOne environment, either in the admin UI, or using the MFA devices API. The development team provides the admin with the application name and details.

The admin's configuration of device integrity detection is detailed in the PingOne admin guide. See Editing an application - Native.

PingOne MFA Native SDK API - iOS

See the API documentation.

Pairing object error codes

The pairing object always returns both a push authenticator status and an OTP status. If the status is FAILED, a Push authenticator error code and message or an OTP error code and message is returned with the status.

Push authenticator error codes

OTP error codes

PingOne Neo is a decentralized identity solution that gives control of identity data back to users. PingOne Neo empowers businesses to give their users full control over how they securely store and share verified credentials without unnecessary friction.

PingOne Neo provides enterprises with identity verification capabilities and the capability to issue identity claims for users to store in their wallet app and verify user data. Embed personal identity using these SDKs into a service to issue digital cards to users and let them store verifiable, shareable data in their wallet app.

PingOne Neo has two components:

• PingOne Verify Native SDKs
• PingOne Wallet Native SDKs

PingOne Verify Native SDKs collect information required for verifying a user’s identity and share the collected information with the PingOne Verify service. PingOne Verify Native SDKs are available in for two operating systems:

• PingOne Verify SDK for iOS

• PingOne Verify SDK for Android

PingOneVerify iOS SDK provides a secure interface for an iOS app to use the PingOne Verify service for validating a user’s identity. The SDK also parses the responses received from the service for different operations and forwards the same to the app via callbacks.

Download the Sample App.

• Xcode 12 or greater
• iOS 13 or greater

The sample app cannot run on a simulator and works only on a device, because the app requires the camera to capture a selfie and the related user ID documents.

1. Ensure your Xcode is set up with a provisioning profile and a signing certificate to be able to install the app on a device. See the Apple Xcode document Run an app on a device for more information.

2. Clone or download the PingOne Verify SDK for iOS sample code to your computer and open PingOneVerify.xcodeproj located in the PingOneVerify_iOS directory.

   You will find all other XCFramework dependencies required for PingOne Verify in the PingOneVerify_iOS/dependencies directory.

3. To run the sample app, select the scheme PingOneVerify_iOS --> , and click Run.

PingOneVerify iOS SDK provides a secure interface for an iOS app to use the PingOne Verify service for validating a user’s identity. The SDK also parses the responses received from the service for different operations and forwards the same to the app via callbacks.

Add the dependencies needed for your application.

The PingOne Verify iOS SDK relies on XCFramework components. You’ll need to add these to Xcode for use by your application.

1. Drag and drop the following components from the SDK folder to the section Frameworks, Libraries, and Embedded Content in Xcode:

   • PingOneVerify.xcframework

   • BlinkID.xcframework

   • VoiceSdk.xcframework

2. Right click from your project folder and select Add Files to (your project name).

3. Add import PingOneVerify to the top of the Swift file where the SDK is initialized

1. Import PingOneVerify_iOS in your desired ViewController (It must extend UIViewController)

   import PingOneVerify_iOS
   

2. Extend DocumentSubmissionListener protocol and its functions

   class YourViewController: UIViewController, DocumentSubmissionListener {
   
       func onDocumentSubmitted(response: DocumentSubmissionResponse) {
           // Callback when document is successfully submitted
       }
   
       func onSubmissionComplete(status: DocumentSubmissionStatus) {
           // Callback when verification transaction is completed
       }
   
       func onSubmissionError(error: DocumentSubmissionError) {
       // Callback when there is an error during submission
       }
   
   }
   

3. Instantiate a PingOneVerifyClient.Builder and set its listener and rootViewController (Required)

   PingOneVerifyClient.Builder()
       .setListener(self)
       .setRootViewController(self)
   

4. Optionally, you can set an explicit qrString using the PingOneVerifyClient.Builder

   PingOneVerifyClient.Builder()
       .setListener(self)
       .setRootViewController(self)
       .setQrString(qrString: "https://api.pingone.com...")
   

5. Optionally, you can set a Selfie Capture Settings with your preference using the PingOneVerifyClient.Builder.

   // Default is 45 seconds for captureTime and true for shouldCaptureAfterTimeout
   let selfieCaptureSettings = SelfieCaptureSettings(captureTime: 15, shouldCaptureAfterTimeout: false)
   PingOneVerifyClient.Builder()
       .setListener(self)
       .setRootViewController(self)
       .setDocumentCaptureSettings(documentCaptureSettings: [selfieCaptureSettings])
   

6. Start Verification Process

   PingOneVerifyClient.Builder()
       .setListener(self)
       .setRootViewController(self)
       .startVerification { pingOneVerifyClient, clientBuilderError in
           if let pingOneVerifyClient = pingOneVerifyClient {
               // Handle pingOneVerifyClient
           } else if let clientBuilderError = clientBuilderError {
               // Handle builderError
           }
       }
   

1. onDocumentSubmitted(response: DocumentSubmissionResponse)

   • Called whenever a document is successfully submitted.
   • Appropriate DocumentSubmissionResponse is returned

   func onDocumentSubmitted(response: DocumentSubmissionResponse) {
       print("The document status is \(response.documentStatus)")
       print("The document submission status is \(response.documentSubmissionStatus)")
           
       guard let documents = response.document else { return }
       for (key, value) in documents {
           print("\(key): \(value)")
       }
   }
   

2. onSubmissionComplete(status: DocumentSubmissionStatus)

   • Called when all required documents have been submitted for a transaction.
   • DocumentSubmissionStatus will always be .completed

   func onSubmissionComplete(status: DocumentSubmissionStatus) {
       // present a basic alert to indicate completion
       let alertController = UIAlertController(title: "Document Submission Complete", message: "All documents have been successfully submitted", preferredStyle: .alert)
       alertController.addAction(UIAlertAction(title: "Okay", style: .default))
       DispatchQueue.main.async {
           self.present(alertController, animated: true)
       }
   }
   

3. onSubmissionError(error: DocumentSubmissionError)

   • Called when error occurs during SDK flow.
   • Appropriate DocumentSubmissionError is returned

   func onSubmissionError(error: DocumentSubmissionError) {
       print(error.localizedDescription)
   }
   

DocumentSubmissionResponse object holds information pertaining to the document that was successfully submitted to the ID Verification service.

@objc public class DocumentSubmissionResponse: NSObject, Codable {
    public var documentStatus: [String: DocumentStatus]
    public var documentSubmissionStatus: DocumentSubmissionStatus
    public var document: [String: String]
    public var createdAt: String // Timestamp of when transaction was created
    public var updatedAt: String // Timestamp of when transaction was last updated
    public var expiresAt: String // Timestamp of when transaction expires

    public func getDocumentStatus() -> [String: DocumentStatus]
    public func getDocumentSubmissionStatus() -> DocumentSubmissionStatus
    public func getDocument() -> [String: String]
    public func getCreatedAt() -> String
    public func getUpdatedAt() -> String
    public func getExpiresAt() -> String
}

documentStatus dictionary shows the status of each document requested. For example, if the requested documents for a certain transaction are the following:

• Email

• Phone

• Selfie

and the callback onDocumentSubmitted(response: DocumentSubmissionResponse was fired after submitting Email, the documentStatus property will look like this:

["Email": .PROCESSED, "Phone": .REQUIRED, "Selfie", .REQUIRED]

The list of DocumentStatus states can be found in DocumentStatus

documentSubmissionStatus property shows the status of the entire verification transaction. Detailed information regarding DocumentSubmissionStatus can be found in DocumentSubmissionStatus

document dictionary holds information about the document that was just submitted to the ID Verification service. Only applicable keys are populated in the document dictionary

Data model of document

An enum describing the status of a particular document

@objc public enum DocumentStatus {
    case REQUIRED // document is required
    case OPTIONAL // document is optional; user may choose to skip
    case COLLECTED // document has been collected
    case PROCESSED // document has been processed
    case SKIPPED // document is skipped by user's choice
}

An enum describing the status of the verification transaction

@objc public enum DocumentSubmissionStatus {
    case not_started // transaction has not been initiated
    case started // transaction has been initiated, but not completed
    case process // transcation is being processed
    case completed // transaction has been processed and is completed
}

A configurable object to customize selfie capture experience

@objc public class SelfieCaptureSettings {
    public let captureTime: TimeInterval // selfie capture time (default is 45 seconds)
    public let shouldCaptureAfterTimeout: Bool // whether user should be able to capture selfie after timeout (default is true)
    public var optional: Bool // whether user can decide to skip selfie capture (default is false)
}

ClientBuilderError

ClientBuilderError is returned when PingOneVerify SDK is initialized incorrectly. It subclasses BuilderError and QRError and is returned during Builder.startVerification()

BuilderError

QRError

DocumentSubmissionError

UI Customization for PingOne Verify

UIAppearanceSettings

UIAppearanceSettings instance allows you to customize the SDK's user interface during run time.

@objc public class UIAppearanceSettings: NSObject {
	private var logoImage: UIImage?
	private var backgroundColor: UIColor?
	private var bodyTextColor: UIColor?
	private var headingTextColor: UIColor?
	private var navigationBarColor: UIColor?
	private var navigationBarTextColor: UIColor?
	private var iconTintColor: UIColor?
	private var solidButtonAppearance: ButtonAppearance?
	private var borderedButtonAppearance: ButtonAppearance?
}

Example usage:

    private func getUiAppearanceSettings() -> UIAppearanceSettings {
        let solidButtonAppearance = ButtonAppearance(backgroundColor: .red, textColor: .white, borderColor: .red)
        let borderedButtonAppearance = ButtonAppearance(backgroundColor: .clear, textColor: .red, borderColor: .red)
        
        return UIAppearanceSettings()
            .setSolidButtonAppearance(solidButtonAppearance)
            .setBorderedButtonAppearance(borderedButtonAppearance)
    }
    
    override func viewDidLoad() {
        super.viewDidLoad()
        let uiAppearanceSetting = self.getUiAppearanceSettings()
        
        PingOneVerifyClient.Builder(isOverridingAssets: false)
        .setListener(self)
        .setRootViewController(self)
        .setUIAppearanceSetting(uiAppearanceSetting)
        .startVerification { pingOneVerifyClient, clientBuilderError in
            if let pingOneVerifyClient = pingOneVerifyClient {
                // Handle pingOneVerifyClient
            } else if let clientBuilderError = clientBuilderError {
                // Handle builderError
            }
        }
    }

UI Customization

If using custom image resources, set PingOneVerifyClient.Builder(isOverridingAssets: Bool) to true. When the isOverridingAssets flag is true, the icon tint color is not applied to the custom images.

If PingOneVerifyClient.Builder(isOverridingAssets: Bool) is set to false, the icon tint color is automatically applied to all the icon images.

You can customize these images:

To customize an image resource:

1. Include your custom image with the same name in the app asset folder

You can customize the following color resources:

• navigation color

• button color

• button background color

• button text color

• button border color

• application background color

• heading text color

• body text color

To customize:

1. Pass a custom UIAppearanceSettings instance in the PingOneVerifyClient.Builder.

2. Use Branding from the PingOne platform API.

3. Use Branding & Themes tab found in PingOne Admin Console -> Experiences -> Branding & Themes as described in Branding and themes.

UIAppearanceSettings always has higher priority than Branding and themes.

Thus, if both UIAppearanceSettings and Branding and themes are used, the configuaration specified in UIAppearanceSettings is shown.

For localization and messages, you can replace the values found in PingOneVerifyLocalizable.strings.

You can customize items such as:

• logo

• navigation color

• button color

• button background

• button text

• application background

• heading text

• body text

To customize:

• Use Branding from the PingOne platform API.

• Use Branding & Themes tab found in PingOne Admin Console -> Experiences -> Branding & Themes as described in Branding and themes.

For Localization, use the Localizable.strings file to modify.

PingOne Verify Native SDK utilizes Verify Policies. You can apply policies two ways:

• Use Verify Policies from the PingOne platform API.

• Use Policies tab found in PingOne Admin Console -> PingOne Verify -> Policies to customize verify policy for a particular environment.

PingOneVerify Android SDK provides a secure interface for an android app to use the PingOne Verify service for validating a user’s identity. The SDK also parses the responses received from the service for different operations and forwards the same to the app via callbacks.

Download the Sample App.

• Android Studio with Gradle
• Android SDK 24 and up

The sample app cannot run on a simulator and works only on a device, because the app requires the camera to capture a selfie and and the related user ID documents.

1. Clone or download the PingOne Verify SDK for Android sample code to your computer.

   The Sample Code directory contains the Android project that is ready to be built when the prerequisites are satisfied.

2. To open the sample app as a project in Android Studio, go to File --> New --> Import Project. Choose the SampleCode/PingOneVerify folder as the project's root folder.

PingOneVerify Android SDK provides a secure interface for an Android app to use the PingOne Verify service for validating a user’s identity. The SDK also parses the responses received from the service for different operations and forwards the same to the app via callbacks.

Add the dependencies needed for your application.

If you haven't done so already, clone or download the PingOne Verify SDK for Android sample app. You'll find the *.aar and *.jar dependencies required for the PingOne Verify Android SDK in the SDK directory.

1. Create a libs folder, if it doesn’t exist under your module, and copy the downloaded *.aar dependencies:

   • PingOneVerify-2.1.0.aar

   • id_scanner_sdk.aar

   • voice_sdk.aar

2. Add the following to your module level build.gradle file to include the dependencies in your module:

   dependencies {
       implementation fileTree(include: ["*.aar"], dir: "libs")
       ...
   }
   

3. Because these components are loaded locally, you must also include the SDK’s dependencies in the configuration to compile and run it.

   dependencies {
   
       implementation fileTree(include: ["*.aar"], dir: "libs")
   
       implementation 'androidx.constraintlayout:constraintlayout:2.1.4'
       implementation 'androidx.fragment:fragment:1.6.1'
       implementation 'androidx.appcompat:appcompat:1.6.1'
       implementation 'androidx.camera:camera-camera2:1.2.3'
       implementation 'androidx.camera:camera-core:1.2.3'
       implementation 'androidx.camera:camera-view:1.2.3'
       implementation 'androidx.camera:camera-lifecycle:1.2.3'
       implementation 'androidx.annotation:annotation:1.6.0'
   
       implementation 'com.github.bumptech.glide:glide:4.13.0'
       annotationProcessor 'com.github.bumptech.glide:compiler:4.13.0'
   
       implementation 'com.google.android.material:material:1.9.0'
       implementation 'com.google.android.gms:play-services-mlkit-barcode-scanning:18.3.0'
       implementation 'com.google.android.gms:play-services-mlkit-face-detection:17.1.0'
       implementation 'com.google.code.gson:gson:2.9.0'
       implementation group: 'com.googlecode.libphonenumber', name: 'libphonenumber', version: '8.13.7'
   
       implementation 'com.squareup.retrofit2:converter-moshi:2.7.2'
       implementation 'com.squareup.retrofit2:retrofit:2.9.0'
       implementation 'com.squareup.okhttp3:okhttp:4.9.3'
       implementation 'com.squareup.moshi:moshi:1.14.0'
       implementation group: 'com.squareup.okhttp3', name: 'okhttp-urlconnection', version: '4.9.3'
   
       implementation 'com.squareup.moshi:moshi:1.14.0'
       implementation 'com.squareup.moshi:moshi-kotlin:1.14.0'
       implementation 'com.google.code.gson:gson:2.9.0'
       implementation("androidx.fragment:fragment-ktx:1.6.1")
   
       implementation("com.appmattus.certificatetransparency:certificatetransparency-android:1.1.1")
   
       }
   

1. Import com.pingidentity.sdk.pingoneverify.PingOneVerifyClient in your desired Activity or Fragment

   import com.pingidentity.sdk.pingoneverify.PingOneVerifyClient;
   

2. Implement the DocumentSubmissionListener interface and its functions

   public class MainFragment extends Fragment implements DocumentSubmissionListener {
       @Override
       public void onDocumentSubmitted(DocumentSubmissionResponse response) {
           // Callback when document is successfully submitted
       }
       @Override
       public void onSubmissionComplete(DocumentSubmissionStatus status) {
           // Callback when verification transaction is completed
       }
       @Override
       public void onSubmissionError(DocumentSubmissionError error) {
           // Callback when there is an error during submission
       }
   }
   

3. Instantiate a PingOneVerifyClient.Builder and set its listener and rootActivity (Required)

   new PingOneVerifyClient.Builder()
       .setListener(this)
       .setRootActivity(getActivity())
   

4. Optionally, you can set an explicit qrString using the PingOneVerifyClient.Builder

   new PingOneVerifyClient.Builder()
       .setListener(this)
       .setRootActivity(getActivity())
       .setQrString(qrString: "https://api.pingone.com...")
   

5. Optionally, you can set a Selfie Capture Settings with your preference using the PingOneVerifyClient.Builder.

   // Default is 45 seconds for captureTime and true for shouldCaptureAfterTimeout
   SelfieCaptureSettings selfieCaptureSettings = new SelfieCaptureSettings(15, false)
   List<CaptureSettings> settings = new ArrayList<>();
   settings.add(selfieCaptureSettings);
   
   new PingOneVerifyClient.Builder()
       .setRootActivity(getActivity())
       .setListener(this)
       .setDocumentCaptureSettings(Collections.singletonList(new SelfieCaptureSettings(15, false)));
   

6. Start Verification Process

   new PingOneVerifyClient.Builder()
       .setListener(this)
       .setRootActivity(getActivity())
       .startVerification(new PingOneVerifyClient.Builder.BuilderCallback() {
           @Override
           public void onSuccess(PingOneVerifyClient client) {
               Log.d("initPingOneClient", "success");
           }
   
           @Override
           public void onError(String errorMessage) {
               Log.e(TAG, "Init Client failed with " + errorMessage);
           }
       });
   }
   

1. onDocumentSubmitted(DocumentSubmissionResponse response)

   • Called whenever a document is successfully submitted.
   • Appropriate DocumentSubmissionResponse is returned

   public void onDocumentSubmitted(DocumentSubmissionResponse response)  {
       Log.d("The  document  status  is :", response.getDocumentStatus())
       Log.d("The  document  submission  status  is",          response.getDocumentSubmissionStatus())
       Map<String,String> documents = response.getDocument();  
       documents.forEach((k,v)->Log.d("(Key, Value):", "("+ k + ","+ v +")"));
   }
   

2. onSubmissionComplete(DocumentSubmissionStatus status)

   • Called when all required documents have been submitted for a transaction.
   • DocumentSubmissionStatus will always be .COMPLETED

   public void onSubmissionComplete(DocumentSubmissionStatus status) {
       //  present  a  basic  alert  to  indicate  completion
       new AlertDialog.Builder(getActivity())  
           .setTitle("Document SubmissionCOMPLETE")  
           .setMessage("All  documents  have  been  successfully  submitted")  
           .create()  
           .show();
   }
   

3. onSubmissionError(DocumentSubmissionError error)

   • Called when error occurs during SDK flow.
   • Appropriate DocumentSubmissionError is returned

   public void onSubmissionError(DocumentSubmissionError error) {  
       Log.e("onSubmissionError", error.getMessage());
   }
   

DocumentSubmissionResponse object holds information pertaining to the document that was successfully submitted to the ID Verification service.

public class DocumentSubmissionResponse implements Serializable{
    private Map<String, String> documentStatus;
    private DocumentSubmissionStatus documentSubmissionStatus
    private Map<String, String> document
    private String createdAt; // Timestamp of when transaction was created
    private String updatedAt; // Timestamp of when transaction was last updated
    private String expiresAt; // Timestamp of when transaction expires
    public func getDocumentStatus() -> [String: DocumentStatus]
    public func getDocumentSubmissionStatus() -> DocumentSubmissionStatus
    public Map<String, String> getDocument()
    public Date getCreatedAt()
    public Date getUpdatedAt()
    public Date getExpiresAt()
}

documentStatus dictionary shows the status of each document requested. For example, if the requested documents for a certain transaction are the following:

• Email

• Phone

• Selfie

and the callback onDocumentSubmitted(DocumentSubmissionResponse response) was fired after submitting Email, the documentStatus property will look like this:

["Email": .PROCESSED, "Phone": .REQUIRED, "Selfie", .REQUIRED]

The list of DocumentStatus states is in DocumentStatus.

DocumentSubmissionStatus property shows the status of the entire verification transaction. Detailed information regarding DocumentSubmissionStatus is in DocumentSubmissionStatus.

document dictionary holds information about the document that was just submitted to the ID Verification service. Only applicable keys are populated in the document dictionary.

Data model of document

An enum describing the status of a particular document

public enum DocumentStatus {
    case REQUIRED, // document is required
    case OPTIONAL, // document is optional; user may choose to skip
    case COLLECTED, // document has been collected
    case PROCESSED, // document has been processed
    case SKIPPED; // document is skipped by user's choice
}

An enum describing the status of the verification transaction

public enum DocumentSubmissionStatus implements Serializable {
    @Json(name = "NOT_STARTED") NOT_STARTED, // transaction has not been initiated
    @Json(name = "STARTED") STARTED,// transaction has been initiated, but not completed
    @Json(name = "COMPLETED") COMPLETED, // transcation is being processed
    @Json(name = "PROCESS") PROCESS // transaction has been processed and is completed
}

A configurable object to customize selfie capture experience

public class SelfieCaptureSettings {
    public int captureTime; // selfie capture time (default is 45 seconds)
    public boolean shouldCaptureAfterTimeout; // whether user should be able to capture selfie after timeout (default is true)
}

ClientBuilderError

ClientBuilderError is returned when PingOneVerify SDK is initialized incorrectly. It subclasses BuilderError and QRError and is returned during Builder.startVerification()

BuilderError

QRError

DocumentSubmissionError

UI Customization for PingOne Verify

UIAppearanceSettings

UIAppearanceSettings instance allows you to customize the SDK's user interface during run time.

public class UIAppearanceSettings {

    private ImageLink logoImage;
    private String backgroundColor;
    private String bodyTextColor;
    private String headingTextColor;
    private String navigationBarColor;
    private String navigationBarTextColor;
    private String iconTintColor;
    private ButtonAppearance solidButtonAppearance;
    private ButtonAppearance borderedButtonAppearance;
}

Example usage:

	final UIAppearanceSettings settings = new UIAppearanceSettings()
                .setLogoImage(logoImage)
                .setSolidButtonAppearance(new ButtonAppearance("#FF0000","#FF0000","#FFFFFF")) // red backgroundColor, red borderColor, white textColor
                .setBorderedButtonAppearance(new ButtonAppearance("#00FFFFFF","#FF0000","#FF0000")); // clear backgroundColor, red borderColor, red textColor
	
	new PingOneVerifyClient.Builder(false)
                .setRootActivity(getActivity())
                .setListener(this)
                .setUIAppearance(settings)
                .startVerification(new PingOneVerifyClient.Builder.BuilderCallback() {
                    @Override
                    public void onSuccess(PingOneVerifyClient client) {
                        // Use pingOneVerifyClient
                    }

                    @Override
                    public void onError(String errorMessage) {
                        // Handle builderError
                    }
                });

UI Customization

If using custom image resources, set PingOneVerifyClient.Builder(bool) to true. When the boolean flag is true, the icon tint color is not applied to the custom images.

If PingOneVerifyClient.Builder(bool) is set to false, the icon tint color is automatically applied to all the icon images.

You can customize these images:

To customize an image resource:

1. Include your custom image with the same name in the corresponding drawable folder.

You can customize the following color resources:

• navigation color

• button color

• button background color

• button text color

• application background color

• heading text color

• body text color

To customize:

1. Pass a custom UIAppearanceSettings instance in the PingOneVerifyClient.Builder.

2. Use [Branding]/pingone/platform/v1/api/#branding) from the PingOne platform API.

3. Use Branding & Themes tab found in PingOne Admin Console -> Experiences -> Branding & Themes as described in Branding and themes.

UIAppearanceSettings always has higher priority than Branding and themes.

Thus, if both UIAppearanceSettings and Branding and themes are used, the configuaration specified in UIAppearanceSettings is shown.

For localization and messages, you can replace the values found in PingOneVerifyLocalizable.xml.

You can customize items such as:

• logo

• navigation color

• button color

• button background

• button text

• application background

• heading text

• body text

To customize:

• Use Branding from the PingOne platform API.

• Use Branding & Themes tab found in PingOne Admin Console -> Experiences -> Branding & Themes as described in Branding and themes.

For Localization, use the strings.xml file in res/values to modify.

PingOne Verify Native SDK utilizes Verify Policies. You can apply policies two ways:

• Use Verify Policies from the PingOne platform API.

• Use Policies tab found in PingOne Admin Console -> PingOne Verify -> Policies to customize verify policy for a particular environment.

This defines the usage and interfaces of the PingOne Wallet Native SDKs to interact with PingOne credentialing services. The SDK provides for a user to receive, save, and share credentials for identification and verification purposes. PingOne Wallet Native SDKs are available in for two operating systems:

• PingOne Wallet Native SDK for iOS

• PingOne Wallet Native SDK for Android

PingOne Wallet Native SDK flows

Wallet initialization

When the wallet SDK initializes for the first time, it creates a new application instance for the default region supplied in the PingOneWalletClient.Builder, registers with the credentials service, and saves the application identifier with cryptographic keys locally. When the SDK receives a request for another region, it registers the same set of keys with the credential service running in the region where the request originated before processing the request.

Credential presentation

Upon scanning a QR, receiving a notification, or clicking a deep link the application passes the information to the SDK. The SDK then uses this information to fetch and parse the Presentation Request, and find the credentials in storage that match. These pass back to the Wallet Application that decides and approves which credentials to share. The SDK identifies the protocol in the presentation request (Native vs OPENID4VP) and prepares a Presentation Response accordingly. If the request is for presenting credentials for a session on the same device, the SDK asks the app to redirect the user to the corresponding URL in the browser after submitting the presentation response.

Overview

The PingOne Wallet SDK enables you to integrate PingOne Wallet functionality into your native applications.

The PingOne Wallet Native SDK package is available for download at https://github.com/pingidentity/pingone-wallet-mobile-sdk-ios. Further details for setup and integrating PingOne Wallet Native SDK into your native apps are available in the README file in the top level folder of the downloadable package.

PingOne Wallet Native SDK sample app

The PingOne Wallet Native SDK bundle provides a sample app that includes all the basic flows to help you get started.

The sample app package for iOS is available for download at https://github.com/pingidentity/pingone-wallet-mobile-sdk-ios. Further details are available in the README file in the top level folder of the downloadable package.

Overview

The PingOne Wallet SDK enables you to integrate PingOne Wallet functionality into your native applications.

The PingOne Wallet Native SDK package is available for download at https://github.com/pingidentity/pingone-wallet-mobile-sdk-android. Further details for setup and integrating PingOne Wallet Native SDK into your native apps are available in the README file in the top level folder of the downloadable package.

PingOne Wallet Native SDK sample app

The PingOne Wallet Native SDK bundle provides a sample app that includes all the basic flows to help you get started.

The sample app package for Android is available for download at https://github.com/pingidentity/pingone-wallet-mobile-sdk-android. Further details are available in the README file in the top level folder of the downloadable package.

You can use the PingOne Signals (Protect) SDK to obtain information for additional risk-related variables and then pass this information on to the risk evaluation.

The data provided by the Signals SDK can be used with the PingOne Protect Integration Kit for PingFederate or PingOne Risk Integration Kit for PingFederate, with the PingOne Protect API, or as part of a flow designed with DaVinci.

• If you are using the Signals SDK with the PingOne Protect Integration Kit for PingFederate, see Integrating device profiling.
• If you are using the Signals SDK with the PingOne Risk Integration Kit for PingFederate (versions 1.3.1 or 1.3), see Adding device profiling to a web application.
• If you are using the Signals SDK with the PingOne Protect API, see Creating risk evaluations.
• If you are using the Signals SDK as part of a flow designed with DaVinci, see PingOne Protect Connector.

Signals (Protect) SDK for iOS

Signals (Protect) SDK for Android

Signals (Protect) SDK for Web

PingOne Signals (Protect) SDK for iOS (version 5.2.8)

Using the iOS version of the SDK involves the following steps:

• Adding the SDK to your app using CocoaPods or Swift Package Manager
• Importing the SDK module
• Initializing the SDK
• Getting the data for risk assessment

Adding the SDK to your app

Adding the SDK to your app using CocoaPods

If you’re new to CocoaPods, see the official documentation for information on how to create and use Podfiles.

Open your project’s Podfile and add the following to your app’s target:

pod 'PingOneSignals', '~> 5.2.8'

Run pod install from the command line:

pod install

Adding the SDK to your app using Swift Package Manager

1. Select File > Add Packages… in Xcode’s menu bar.
2. Search for the PingOne Signals SDK using the repo's URL: https://github.com/pingidentity/pingone-signals-sdk-ios
3. Set the Dependency Rule to Branch with the value 'main' or select an exact version, and make sure that Add to Project is set to your project.
4. Select Add Package.
5. Verify that the package was downloaded in your project.

SDK initialization

Initialize the SDK. You'll typically do this in your app's application:didFinishLaunchingWithOptions: method, or any other entry point during your application launch. For example:

import PingOneSignals

let initParams = POInitParams()
initParams.envId = <envId> // optional
// If you are using the PingFed authentication API and version 1.3 of the Integration Kit, uncomment the following line to turn off the collection of behavioral data
// initParams.behavioralDataCollection = false
let pingOneSignals = PingOneSignals.initSDK(initParams: initParams)

pingOneSignals.setInitCallback { error in
    if let error = error {
        print("Init failed - \(error.localizedDescription)")
    } else {
        print("SDK Initialized")
    }
}

Optionally, set an event listener to get calls on successful or failed SDK initialization.

Getting the data for risk assessment

Get the data for risk assessment by adding a call to the SDK's getData method, for example:

import PingOneSignals

let pingOneSignals = PingOneSignals.sharedInstance()
pingOneSignals?.getData { data, error in
    if let data = data {
        print("data: \(data)")
    } else if let error = error {
        print("error getting data: \(error)")
    }
}

PingOne Signals (Protect) SDK for Android (version 5.1.5)

Using the Android version of the SDK involves the following steps:

• Adding Maven Central repository
• Adding the SDK to your app dependencies
• Initializing the SDK
• Getting the data for risk assessment

Adding the Maven Central repository

Add the mavenCentral repository to your root build.gradle file:

allprojects {
    repositories {
        mavenCentral()
        …
    }
}

Adding the SDK to your app dependencies

Add the following to your application-level build.gradle file:

implementation "com.pingidentity.signals:android-sdk:5.1.5"

SDK initialization

Extend the Application class and add the following in the onCreate method:

public class MyApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();

        // optional
        PingOneSignals.setInitCallback(new InitCallback() {
            @Override
            public void onError(@NonNull String message, @NonNull String code, @NonNull String id) {
                Log.i("PingOneSignals", "onError " + message + " code: " + code + " id: " + id);
            }

            @Override
            public void onInitialized() {
                Log.i("PingOneSignals ", "SDK Initialized");
            }
        });

      POInitParams initParams = new POInitParams();
      initParams.setEnvId(<envId>); // optional
      // If you are using the PingFed authentication API and version 1.3 of the Integration Kit, uncomment the following line to turn off the collection of behavioral data
      // initParams.setBehavioralDataCollection(false);
      PingOneSignals.init(this, initParams);
    }
}

Optionally, set an event listener to get calls on successful or failed SDK initialization.

Getting the data for risk assessment

Get the data for risk assessment by adding a call to the SDK's getData method, and pass as a parameter a class that implements the GetDataCallback interface, for example:

import com.pingidentity.signalssdk.sdk.GetDataCallback;
import com.pingidentity.signalssdk.sdk.SignalsCollection;

public class MyClass {

    public void callGetData() {
          PingOneSignals.getData(new GetDataCallback() {
                   @Override
                     public void onSuccess(@NonNull String data) {
                              Log.i("PingOneSignals ", "data:  " + data);
                      }

                    @Override
                    public void onFailure(@NonNull String reason) {
                             Log.i("PingOneSignals ", "onFailure reason: " + reason);
                    }
           });
    } 
}

PingOne Signals (Protect) SDK for Web

Version of the Signals SDK to use

When using the PingFederate Authentication API, use the version of the Signals SDK that supports the Risk/Protect Integration Kit that you installed in PingFederate:

• For all versions of the PingOne Protect Integration Kit, use version 5.2.10 or later of the PingOne Signals SDK.
• For PingOne Risk Integration Kit 1.3.1, use version 5.2.10 or later of the PingOne Signals SDK.
• For PingOne Risk Integration Kit 1.3, use version 5.0.3 of the PingOne Signals SDK.

When integrating through the PingOne API, always use the latest version of the PingOne Signals SDK

Main steps

Using the web SDK involves the following steps:

• Importing the necessary script
• Initializing the SDK
• Getting the data for risk assessment

Importing the script

Import the required script by including the following code segment in each relevant page.

<script
        src="https://apps.pingone.com/signals/web-sdk/5.4.0/signals-sdk.js"
        defer>
</script>

Initializing the SDK

Initialize the SDK by adding a listener for the PingOneSignalsReadyEvent event:

function onPingOneSignalsReady(callback) {
    if (window['_pingOneSignalsReady']) {
        callback();
    } else {
        document.addEventListener('PingOneSignalsReadyEvent', callback);
    }
}

Then, if you are using version 5.0.3 or earlier of the Signals SDK, use this code:

onPingOneSignalsReady(function () {
    _pingOneSignals.initSilent({
        envId : <envId>
    }).then(function () {
        console.log("PingOne Signals initialized successfully");
    }).catch(function (e) {
        console.error("SDK Init failed", e);
    });
});

If you are using version 5.2.1 or later of the Signals SDK, use this code:

onPingOneSignalsReady(function () {
    _pingOneSignals.init({
        // If you are using the PingFed authentication API and version 1.3 of the Integration Kit, uncomment the following line to turn off the collection of behavioral data
        // behavioralDataCollection: false
    }).then(function () {
        console.log("PingOne Signals initialized successfully");
    }).catch(function (e) {
        console.error("SDK Init failed", e);
    });
});

If you are using version 5.3.7 or later of the Signals SDK, use this code:

onPingOneSignalsReady(function () {
    _pingOneSignals.init({
        // If you are using the PingFed authentication API and version 1.3 of the PingOne Risk Integration Kit, uncomment the following line to turn off the collection of behavioral data
        // behavioralDataCollection: false,
        // By default, the SDK creates a "tags" array containing the URLs visited and the time of the visit. Uncomment the following line to disable the collection of this data
        // disableTags: true,
        // Set universalDeviceIdentification to true if you want the device data in the SDK payload to be provided as a signed JWT
        // universalDeviceIdentification: true
    }).then(function () {
        console.log("PingOne Signals initialized successfully");
    }).catch(function (e) {
        console.error("SDK Init failed", e);
    });
});

Getting the data for risk assessment

Get the data for risk assessment by adding a call to the SDK's getData method, for example:

_pingOneSignals.getData()
   .then(function (result) {
       console.log("get data completed: " + result)
   }).catch(function (e) {
       console.error('getData Error!', e);
});