Orchestration SDKs

Step 2. Integrating PingOne Protect DaVinci flows in iOS

PingOne iOS

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

Initializing PingOne Protect data collection on the client

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

Rather than wait to receive a ProtectCollector from the server, you can initialize PingOne Protect data collection in your client app, providing your own configuration settings.

There are two main methods for early initialization of PingOne Protect data collection on the client:

  1. Direct initialization using the Protect interface

  2. Use the ProtectLifecycle module for iOS

Direct initialization using the Protect interface

The DaVinci Client allows you to initialize data collection directly using the Protect interface. This provides maximum flexibility in 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:

    await Protect.config { protectConfig in
    protectConfig.isBehavioralDataCollection = true
    protectConfig.isLazyMetadata = true
    protectConfig.envId = "3072206d-c6ce-ch15-m0nd-f87e972c7cc3"
    protectConfig.deviceAttributesToIgnore = ["deviceId", "serialNumber"]
    protectConfig.isConsoleLogEnabled = true
}

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

    try await Protect.initialize()

print("Protect data collection initialized.")

Use the ProtectLifecycle module for iOS

The DaVinci Client for iOS provides the ProtectLifecycle module for simplifying the management of data collection.

As a DaVinci 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 DaVinci 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:

let davinci = DaVinci.createDaVinci { config in
    config.module(OidcModule.config) { oidcValue in
        oidcValue.clientId = "dummy"
        // ... Other OIDC configuration
    }
    config.module(ProtectLifecycleModule.config) { protectValue in
        protectValue.isBehavioralDataCollection = true
        protectValue.isLazyMetadata = true
        protectValue.envId = "3072206d-c6ce-ch15-m0nd-f87e972c7cc3"
        protectValue.deviceAttributesToIgnore = ["deviceId"]
        protectValue.isConsoleLogEnabled = true

        protectValue.pauseBehavioralDataOnSuccess = true
        protectValue.resumeBehavioralDataOnStart = true
    }
}

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 manually pausing and resuming the capture of behavioral data:

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

Returning data to a DaVinci flow for risk evaluation

To perform risk evaluations, the PingOne server requires you to return metadata and optionally behavioural data from the client.

On receipt of ProtectCollector, use the collect() method to collect the required data,and populate the response ready to return to the server.

If you haven’t already initialized PingOne Protect data collection on the client, the collect() method uses the parameters within the ProtectCollector to initialize PingOne Protect data collection.

This method of initializing PingOne Protect data collection means that you can alter collection settings on the server without having to recompile your client apps.

However, initializing and returning PingOne Protect data in the same step reduces the amount of behavioural data your client can collect.

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

node.collectors.forEach { collector in
    switch collector {
    case let protectCollector as ProtectCollector:
        let result = await protectCollector.collect()
        switch result {
        case .success:
            // Data collection successful: Proceed to the next node in the DaVinci flow.
            node.next()
        case .failure:
            // Data collection failed: Implement robust error handling.
            // Example: Log the error, display an informative message, or implement a retry mechanism.
            break
        }
    // ... Handle other collector types
    default:
        break
    }
}