Ping SDKs

Step 2. Configure the Ping (ForgeRock) Login Widget for PingOne Protect

Integrating the Ping (ForgeRock) Login Widget with PingOne Protect enables you to perform risk evaluations during your customer’s journey.

Complete the following tasks to fully integrate with PingOne Protect:

  1. Initialize data collection

  2. Pause and resume behavioral data capture

  3. Return collected data for a risk evaluation

Initialize data collection

You must initialize the PingOne Signals SDK so that it collects the data needed to evaluate risk.

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

There are two options for initializing the PingOne Signals SDK in the Ping (ForgeRock) Login Widget:

  1. The Ping (ForgeRock) Login Widget automatically initializes the PingOne Signals SDK on receipt of a PingOneProtectInitializeCallback callback from a journey you have started.

  2. Manually initialize the PingOne Signals SDK, import the module and pass in any configuration parameters you need, as follows:

    import Widget, { configuration, journey, protect } from '@forgerock/login-widget';

new Widget({ target: widgetEl });

// Start PingOne Protect Signals SDK
await protect.start({
  envId: 3072206d-c6ce-ch15-m0nd-f87e972c7cc3,
  behavioralDataCollection: true,
  consoleLogEnabled: true,
});

    The PingOne Signals SDK supports a number of parameters which you can supply yourself, or are contained in the PingOneProtectInitializeCallback callback.

    Show PingOne Signals SDK start parameters

    Parameter

    Description

    Android

    iOS

    JavaScript

    envID

    Required. Your PingOne environment identifier.

    deviceAttributesToIgnore

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

    For example, AUDIO_OUTPUT_DEVICES or IS_ACCEPT_COOKIES.

    isBehavioralDataCollection

    behavioralDataCollection

    When true, collect behavioral data.

    Default is true.

    isConsoleLogEnabled

    consoleLogEnabled

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

    Default is false.

    isLazyMetadata

    lazyMetadata

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

    Default is false.

    N/A

    deviceKeyRsyncIntervals

    Number of days that device attestation can rely upon the device fallback key.

    Default: 14

    N/A

    disableHub

    When true, the client stores device data in the browser’s localStorage only.

    When false the client uses an iframe.

    Default is false.

    N/A

    disableTags

    When true, the client does not collect tag data.

    Tags are used to record the pages the user visited, forming a browsing history.

    Default is false.

    N/A

    enableTrust

    When true, tie the device payload to a non-extractable crypto key stored in the browser for content authenticity verification.

    Default is false.

    N/A

    externalIdentifiers

    Optional. A list of custom identifiers that are associated with the device entity in PingOne Protect.

    N/A

    hubUrl

    Optional. The iframe URL to use for cross-storage device IDs.

    N/A

    waitForWindowLoad

    When true, initialize the SDK on the load event, instead of the DOMContentLoaded event.

    Default is true.

Return collected data for a risk evaluation

To perform risk evaluations, the PingOne server requires the captured data.

There are two options for returning data in the Ping (ForgeRock) Login Widget:

  1. On receipt of a PingOneProtectEvaluationCallback callback within a journey, the Ping (ForgeRock) Login Widget automatically returns the captured data.

  2. Use the getData() method to manually return the captured data:

    import Widget, { configuration, journey, protect } from '@forgerock/login-widget';

new Widget({ target: widgetEl });

// Start PingOne Protect Signals SDK
await protect.start({
  envId: 3072206d-c6ce-ch15-m0nd-f87e972c7cc3,
  behavioralDataCollection: true,
  consoleLogEnabled: true,
});

// Return gathered data to the server
await protect.getData();

Pause and resume behavioral data capture

The PingOne Protect Signals SDK can capture 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. For example, the user might not be interacting with the app, or you only want to use device attribute data to be considered when performing PingOne Protect evaluations. You can then resume behavioral data collection when required.

There are two options for pausing and resuming behavioral data capture in the Ping (ForgeRock) Login Widget:

  1. The PingOneProtectEvaluationCallback callback can include a flag to pause or resume behavioral capture, which the Ping (ForgeRock) Login Widget automatically responds to.

  2. Use the pauseBehavioralData() and resumeBehavioralData() methods to manually pause or resume the capture of behavioral data:

    import Widget, { configuration, journey, protect } from '@forgerock/login-widget';

new Widget({ target: widgetEl });

// Start PingOne Protect Signals SDK
await protect.start({
  envId: 3072206d-c6ce-ch15-m0nd-f87e972c7cc3,
  behavioralDataCollection: true,
  consoleLogEnabled: true,
});

// Return gathered data to the server
await protect.getData();

// Pause behavioral data collection
protect.pauseBehavioralData();

// Resume behavioral data collection
protect.resumeBehavioralData();