Orchestration SDKs

Step 2. Integrating PingOne Protect auth journeys in Android

PingOne Advanced Identity Cloud PingAM Android

Integrating your application with PingOne Protect enables you to perform risk evaluations during your customer’s journey.

Initializing data collection

The earlier you can initialize data collection, the more data it can collect to make a risk evaluation.

These are three main methods for initializing data collection when using auth journeys:

  1. Initializing using the Protect interface

  2. Use the ProtectLifecycle module for Android

  3. Initializing on receipt of a PingOne Protect initialize callback

Initializing using the Protect interface

The Journey module allows you to initialize data collection directly using the Protect interface. This provides the client app maximum control over how the collection operates.

To directly initialize data collection using the Protect interface, complete these steps:

  1. Add a configuration object to your code that defines the property values for data collection.

    The available properties are as follows:

    Parameter Description

    envID

    Required. Your PingOne environment identifier.

    For example, 3072206d-c6ce-ch15-m0nd-f87e972c7cc3

    deviceAttributesToIgnore

    Optional. A list of device attributes to ignore when collecting device signals.

    For example, AUDIO_OUTPUT_DEVICES or IS_ACCEPT_COOKIES.

    isBehavioralDataCollection

    When true, collect behavioral data.

    Default is true.

    isConsoleLogEnabled

    When true, output SDK log messages in the developer console.

    Default is false.

    isLazyMetadata

    When true, calculate metadata on demand rather than automatically after calling start.

    Default is false.

    customHost

    Optional. Specify a custom host for the Protect API, which can be useful in specific deployment scenarios.

    Example code:

    Protect.config {
    isBehavioralDataCollection = true
    isLazyMetadata = true
    envId = "3072206d-c6ce-ch15-m0nd-f87e972c7cc3"
    deviceAttributesToIgnore = listOf("deviceId", "androidId", "serialNumber")
    isConsoleLogEnabled = true
}

  2. Call the initialize() function to start the data collection using the configuration object:

    Protect.initialize()

Log.d("Protect", "Protect data collection initialized.")

Use the ProtectLifecycle module for Android

The Journey Client for Android provides the ProtectLifecycle module for simplifying the management of data collection.

As a Journey client module, it is aware of the current state of authentication, and can automatically pause and resume behavioral data collection when required.

Configure the ProtectLifecycle module in your Journey Client configuration, as with other modules.

The available properties are as follows:

Parameter Description

envID

Required. Your PingOne environment identifier.

For example, 3072206d-c6ce-ch15-m0nd-f87e972c7cc3

deviceAttributesToIgnore

Optional. A list of device attributes to ignore when collecting device signals.

For example, AUDIO_OUTPUT_DEVICES or IS_ACCEPT_COOKIES.

isBehavioralDataCollection

When true, collect behavioral data.

Default is true.

isConsoleLogEnabled

When true, output SDK log messages in the developer console.

Default is false.

isLazyMetadata

When true, calculate metadata on demand rather than automatically after calling start.

Default is false.

customHost

Optional. Specify a custom host for the Protect API, which can be useful in specific deployment scenarios.

pauseBehavioralDataOnSuccess

When true, the DaVinci Client automatically pauses behavioral data collection after successful authentication.

Default is false.

resumeBehavioralDataOnStart

When true, the DaVinci Client automatically starts behavioral data collection when it initializes.

Example code:

val journey = Journey {
    serverUrl = "https://openam-forgerock-sdks.forgeblocks.com/am"
    realm = "alpha"
    cookie = "ch15fefc5407912"
    module(ProtectLifecycle) {
        isBehavioralDataCollection = true
        isLazyMetadata = true
        envId = "3072206d-c6ce-ch15-m0nd-f87e972c7cc3"
        deviceAttributesToIgnore = listOf("deviceId")
        isConsoleLogEnabled = true

        pauseBehavioralDataOnSuccess = true
        resumeBehavioralDataOnStart = true
    }
}

Initializing on receipt of a PingOne Protect initialize callback

You can choose not to initialize data collection on app startup and instead initialize it on-demand, when your authentication journey reaches the relevant node.

Use the start() method to initialize data collection in response to receiving a PingOneProtectInitializeCallback from the server:

Android example of on-demand PingOne Protect initialization
node.callbacks.forEach {
    when (it) {
        is PingOneProtectInitializeCallback -> {
            // Initialize the Protect SDK
            when (val result = it.start()) {
                is Success -> {
                    // Initialization successful: Proceed to the next step in the Journey.
                    node.next()
                }
                is Failure -> {
                    // Initialization failed: Implement robust error handling.
                }
            }
        }
    }
}

Pausing and resuming behavioral data capture

Part of the data collection includes collecting behavioral data, such as how the user interacts with the app, to help when performing evaluations.

There are scenarios where you might want to pause the collection of behavioral data:

  • To reduce memory and processor utilization. Continuously collecting behavioral data beyond authentication could reduce the performance of your client app.

  • You only want to consider device attribute data when performing PingOne Protect evaluations.

You can pause, and also resume behavioral data collection if required.

The SDKs provide the pauseBehavioralData() and resumeBehavioralData() methods for pausing and resuming the capture of behavioral data.

Protect.pauseBehavioralData() // Pause data collection.
Protect.resumeBehavioralData() // Resume data collection.

Returning collected data for a risk evaluation

To perform risk evaluations, the PingOne server requires you to return the captured behavioural data.

On receipt of PingOneProtectEvaluationCallback, use the collect() method to populate the response with the captured data.

When the data is successfully collected, call node.next() to submit the data back to the server for evaluation.

node.callbacks.forEach {
    when (it) {
        is PingOneProtectEvaluationCallback -> {
            when (val result = it.collect()) {
                is Success -> {
                    // Data collection successful: Proceed to the next node.
                    node.next()
                }
                is Failure -> {
                    // Data collection failed: Implement robust error handling.
                    // Example: Log the error, display an informative message, or implement a retry mechanism.
                }
            }
        }
        // ... Handle other callback types
    }
}