PingOne Signals SDK

This package exposes the PingOne Signals/Protect JavaScript SDK in browser environments to help collect device and browser telemetry for risk evaluation and fraud detection.

Important: This package only runs in the browser. If you are using SSR frameworks (Next.js, Nuxt, Remix), import it dynamically on the client side.

Table of contents

• What is it?
• Installation
• Quick start
• Usage in frameworks (React/Next.js)
• Initialization parameters
• Typical flows and examples
• Troubleshooting
• Legacy initialization (older SDKs)
• Documentation and links

What is it?

This package re-exports the PingOne Protect SDK for Web and provides the SDK object via a default export. Internally, the SDK is attached to the global window as _pingOneSignals. Refer to the official PingOne Protect SDK for Web documentation for the full API and behavior.

Installation

npm install @protect/signals-sdk
# or
yarn add @protect/signals-sdk
# or
pnpm add @protect/signals-sdk

Quick start

Initialize the SDK

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

Retrieving SDK data (getData)

Version: All SDK versions

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

Notes:

• Call getData after the SDK is ready and initialized (see Quick start and initialization sections above).
• The structure of the returned data is defined by the SDK and may evolve; consult the official documentation for details.
• If using older versions of the SDK, see the Legacy initialization (older SDKs) section.

Usage in frameworks (React/Next.js)

This package throws if it is required on the server. In SSR frameworks, import it dynamically on the client.

React (CRA/Vite):

Version: Latest SDK

import { useEffect } from 'react';

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

function App() {
  useEffect(() => {
    import('@protect/signals-sdk').then(() => {
      onPingOneSignalsReady(function () {
        _pingOneSignals
          .init({
            // If you are using the PingFed authentication API and version 1.3 of the Integration Kit, uncomment to turn off behavioral data collection
            // behavioralDataCollection: false,
          })
          .then(function () {
            console.log('PingOne Signals initialized successfully');
            // Optionally get data
            return _pingOneSignals.getData();
          })
          .then(function (result) {
            if (result) console.log('get data completed: ' + result);
          })
          .catch(function (e) {
            console.error('SDK Init/getData failed', e);
          });
      });
    });
  }, []);

  return <div>My App</div>;
}

Next.js (client-only):

Version: Latest SDK

'use client';
import { useEffect } from 'react';

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

export default function Page() {
  useEffect(() => {
    (async () => {
      await import('@protect/signals-sdk');
      onPingOneSignalsReady(function () {
        _pingOneSignals
          .init({
            // behavioralDataCollection: false,
          })
          .then(function () {
            console.log('PingOne Signals initialized successfully');
            return _pingOneSignals.getData();
          })
          .then(function (result) {
            if (result) console.log('get data completed: ' + result);
          })
          .catch(function (e) {
            console.error('SDK Init/getData failed', e);
          });
      });
    })();
  }, []);

  return <main>Login</main>;
}

Initialization parameters

Use these options with either configure(...) in Modern SDKs or init(...) in Legacy SDKs, as supported by your SDK version. See “Version notes” above.

| Name | Mininal Version | Description | | ---- |-----------------| ----------- | | behavioralDataCollection | 5.2.1 | Set to false to turn off behavioral data collection when using the PingFederate authentication API with PingOne Risk Integration Kit v1.3. Default: true (collected unless disabled). | | disableTags | 5.3.0 | Disables the default tags array that records visited URLs and visit timestamps. Default: false (tags are collected). | | universalDeviceIdentification | 5.3.0 | When true, device data in the SDK payload is provided as a signed JWT. Default: false. | | agentIdentification | 5.4.0 | Enable if your risk policies use the PingID Device Trust predictor. Default: false. | | agentTimeout | 5.4.0 | Applicable when agentIdentification is true. Timeout for the trust agent in milliseconds. Allowed range: 200–10,000 ms. Uses SDK default if not set. | | agentPort | 5.4.0 | Applicable when agentIdentification is true. Port used to connect to the trust agent. Default: 9400. |

Typical flows and examples

Different deployments may use the SDK differently. Common patterns include:

• Early initialization: Load and initialize the SDK as soon as possible (e.g., in the or the earliest client hook) to maximize signal coverage.
• Associate user/session: When available, associate telemetry with the current user or a session/transaction identifier.
• Evaluate risk: Send the collected telemetry/fingerprint identifiers (as documented) to your backend. Your backend interacts with PingOne Protect risk evaluation APIs and policies and returns a decision (allow/challenge/deny) to your application.
• React to decisions: Apply step-up (MFA), block, or allow flows based on policy outcomes.

Note: This NPM package does not implement server-side risk evaluation. You must implement server calls according to your organization’s PingOne Protect configuration.

Troubleshooting

• Error: "Protect Signals SDK can only be used in the browser."
  • You imported the package in a server/SSR context. Use dynamic import on the client.
• SDK object is undefined
  • Ensure your bundler isn’t tree-shaking the import. Use the default export and access the object in a browser context.
• No signals collected
  • Initialize and start the SDK early in the page lifecycle. Confirm your environment/application IDs are correct.

Legacy initialization (older SDKs)

Initialization for SDK v5.2.1 or earlier

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: 'YOUR_ENV_ID'
  }).then(function () {
    console.log("PingOne Signals initialized successfully");
  }).catch(function (e) {
    console.error("SDK Init failed", e);
  });
});

Documentation and links

• Protect Signals SDK Documentation: https://docs.pingidentity.com/pingone/threat_protection_using_pingone_protect/p1_protect_signals_sdk.html
• PingOne Identity API docs: https://apidocs.pingidentity.com/pingone/platform/v1/api/