PingOne Protect SDK for Web

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

npm package for Signals SDK

There is also an npm package for the Signals SDK that you can use. The readme file for the package contains the relevant instructions.

Main steps

Using the web SDK involves the following steps:

Importing the necessary script
Initializing the SDK
Getting the data for risk assessment
Update your Content Security Policy (CSP)

Importing the script

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

To use the latest version of the PingOne Signals SDK, use latest in the path:

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

To use a specific version of the PingOne Signals SDK, include the version number in the path. For example:

<script
        src="https://apps.pingone.com/signals/web-sdk/5.6.10/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.3.7 or later of the Signals SDK, use this following code.

The example shown here includes a number of options that you can turn on in the initialization code. Some of these, such as those for the PingID Device Trust agent, have equivalent UI elements in PingFederate and PingOne DaVinci that can be used to enable the options. If you use these UI elements, there is no need to include the options in the SDK initialization 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,
        // Set htmlGeoLocation to true if you want the SDK payload to include browser-based user location data if the user has provided their consent
        // htmlGeoLocation: true,
        // Set agentIdentification to true if you are using risk policies that contain the PingID Device Trust predictor
        // agentIdentification: true,
        // If you have set agentIdentification to true, use agentTimeout to specify the timeout the trust agent should use if you don't want to use the default timeout setting. Can be between 200 and 10,000 milliseconds.
        // agentTimeout: 5000,
        // If you have set agentIdentification to true, use agentPort to specify the port to use when connecting to the trust agent if you don't want to use the default port (9400)
        // agentPort: 8800,
        // Set isIAFDetectionEnabled to true to have the SDK detect AI agents
        // isIAFDetectionEnabled: true
        //
    }).then(function () {
        console.log("PingOne Signals initialized successfully");
    }).catch(function (e) {
        console.error("SDK Init failed", e);
    });
});

If you are using a version of the SDK between 5.2.1 and 5.3.6, use the following 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.0.3 or earlier of the Signals SDK, use the following code:

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

The code above contains the String placeholder <`envId`>. Replace this with the ID of your PingOne environment.

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);
});

Update your Content Security Policy (CSP)

Even if you are running the Signals SDK from your server or using the npm package, the SDK must communicate with the PingOne server, so add the following to your CSP:

script-src 'self' https://apps.pingone.com;
connect-src 'self' https://apps.pingone.com;
style-src 'self' https://apps.pingone.com 'unsafe-inline';

PingOne Platform APIs