User Guides
Home
Start typing to search…

Web SDK

The Digital Intelligence Web SDK works by including an HTML script tag or via NPM, detailed below, within the pages that should capture device risk data. Upon inclusion, the SDK will start automatically, capturing data in the way it has been configured through the Socure and client configurations.


Before you start

Before you begin, you need a configured and provisioned Socure account. Then you can retrieve your SDK key from the Developer Workbench > SDK Keys page in RiskOS™.


Adding the Web SDK code

There are two ways to incorporate the SDK into your application. It can be included via a <script> tag directly within the website where capture needs to happen. Alternatively, it can be incorporated within the website via inclusion as an NPM dependency.


Option 1: Setup via a Script Tag

In the following Web SDK code, replace <SOCURE-SDK-KEY> with your SDK key. The code should be added to all pages that will be used to make RiskOS API calls. We recommend that you deploy the Web SDK code across your application or the user funnel. When included via script tag, the SDK is automatically initialized. By including the Web SDK across the user funnel, observations about the device can be made across the session allowing for more granular monitoring.

<script defer src="https://sdk.dv.socure.io/latest/device-risk-sdk.js"
            data-public-key="<SOCURE-SDK-KEY>">
</script>

Instead of including the data-public-key via the script tag, you can start the Device Risk SDK using the initialize(...) method, as described in the next section. Note that if the script is included asynchronously, you must ensure that the script is fully loaded and the SigmaDeviceManager object is available before calling the initialize(...) method.


Option 2: Setup via NPM

Include the SDK in your application by first installing the dependency:

npm install --save @socure-inc/device-risk-sdk

Next the SDK needs to be initialized to start collection. The initialization should only happen once within the application. Ideally this should be in a high level component within a web framework like React to ensure it isn't continually re-initialized on state changes. Initialization can be done as follows:

SigmaDeviceManager.initialize({
  sdkKey: <SOCURE-SDK-KEY>,
});

Configuration

Configuration of the SDK can be done by passing the options to the initialize method using the object or via attributes on the script tag. The configuration object is as follows:

interface SigmaDeviceOptions {
  sdkKey: string;
  configBaseUrl?: string;
  useSocureGov?: boolean;
  customerSessionId?: string;
  disableDeviceCookie?: boolean;
  deviceCookieName?: string;
  disableEventFilter?: boolean;
  enableDetailedMediaCapture?: boolean;
}

The configuration options are as follows with the [script tag] equivalent in brackets.

  • sdkKey [data-public-key]: The SDK Key that can be found in the For Developers > SDK Keys page in RiskOS™

  • configBaseUrl [data-base-url]: Optional The base URL for the SDK to use when making requests. This needs to be configured when the SDK is being accessed through a proxy.

  • useSocureGov [data-use-socure-gov]: Optional A flag to enable the use of the Socure GovCloud environment. This should only be set to true if the SDK key is a SocureGov key. This option is ignored if configBaseUrl is set.

  • customerSessionId [data-customer-session-id]: Optional A customer defined identifier to use for the ongoing device session. See Using customer provided identifiers for more details

  • disableDeviceCookie [data-disable-device-cookie]: Optional Disables the creation of a Socure device cookie by the SDK. Disabling this may impact device tracking across subdomains by the SDK.

  • deviceCookieName [data-device-cookie-name]: Optional A method to override the default Socure device cookie name which is _s_did. This can be useful if the default value conflicts with an existing cookie name.

  • disableEventFilter [data-disable-event-filter]: Optional A flag to disable the filter applied to behavioral events that restricts reported events to only those that are relevant to forms. This is false by default. Setting this to true will remove the filter and allow all events to be reported. We do not recommend using this now unless the built-in event filter is restricting the reporting of events due to the use of Shadow DOM or other non-standard form elements.

  • enableDetailedMediaCapture: Optional A flag to enable the detailed media capture. This is false by default. Setting this to true will enable the detailed media capture.

📘

Note:

Enabling enableDetailedMediaCapture will cause the SDK to cycle through available media devices which can cause the recording light to flash on and off. It is recommended to only enable this if you will actively be using the camera or microphone. In the event you would prefer to trigger this manually when requesting camera access, you can use the captureDetailedMediaInfo() method instead.


Using the SDK

Upon inclusion of the above script, the SigmaDeviceManager becomes available. This object provides methods of interacting with the Socure SDK. Most notably it provides a way of fetching the current sessionToken.

The getSessionToken method returns a Promise that will resolve to the sessionToken for use in a RiskOS API call. A sample of getting this sessionToken would look as follows:

SigmaDeviceManager.getSessionToken().then((sessionToken) => {
  console.log("sessionToken", sessionToken);
  // Logic to store this sessionToken
})

Once retrieved, this sessionToken should be recorded by your application for use in the RiskOS API requests associated with this transaction. The sessionToken will be passed to RiskOS™ API call in the di_session_token field.

For compatibility with v1, getDeviceSessionId is aliased to getSessionToken and will continue to work for the time being. However, the getDeviceSessionId is deprecated and will be removed in a future release.


Socure Javascript Device Cookie

Socure uses multiple methods of maintaining the identity of a device. One method is the creation of a first party cookie by the SDK. This cookie aids in tracking the device across all the subdomains the SDK is implemented against. For example, this helps in maintaining device identification across domain.com and payments.domain.com automatically.


Controlling Data Collection

By default the SDK will begin collecting data automatically. This includes data about the device and the way the user is interacting with the application. This data will be tracked as long as the web page (or tab) is in the foreground. Data collection is paused automatically when the page is in the background and automatically resumes when in the foreground.

In the event that further control over data collection is needed, two methods are supplied by the SDK:

  • SigmaDeviceManager.pauseDataCollection() - Will pause ongoing user behavior and interaction data collection. Data collection will not resume until SigmaDeviceManager.resumeDataCollection() is called.
  • SigmaDeviceManager.resumeDataCollection() - Will resume data collection if collection was paused.

Capturing detailed media device information

v2.8.0+ of the SDK has support for the SigmaDeviceManager.captureDetailedMediaInfo() method. This method triggers the capture of detailed information about the attached media devices. This method can be used to trigger the capture at a specific point in the application flow as opposed to the automatic capture that happens when the SigmaDeviceOptions.enableDetailedMediaCapture config flag is set to true.

📘

Note:

Calling this method can cause the recording light to flash on and off for each of the attached media devices.


Server-side configuration

By default, nothing needs to be done server-side to enable the collection of device data. However, if certain server configurations are in place, there are some updates that will need to be made to use the SDK.


Content-Security-Policy

A Content-Security-Policy is a header that is used to control which resources can be used by a given web page. For more details, see the Mozilla Developer Network documentation.

If a Content-Security-Policy is in place, the following elements will be needed to make sure the SDK can correctly report to Socure services.


connect-src

The connect-src directive restricts the URLs which can be interacted with by script interfaces. For more details, see the Mozilla Developer Network documentation.

To allow the most flexibility, the following connect-src can be set in the Content Security Policy to make sure all Socure services are reachable, including any additional subdomains that may be required in the future.

connect-src https://*.socure.io;

Should you wish to restrict it more explicitly, the connect-src policy will need to be configured as follows:

connect-src https://ingestion.dv.socure.io https://analytics.dv.socure.io https://network.dv.socure.io;,

script-src

The script-src directive restricts which domains can be used for loading JavaScript. For more details, see the Mozilla Developer Network documentation.

All versions of the SDK are fetched through the sdk.dv.socure.io domain. To include a script-src Content-Security-Policy, include the following:

script-src https://sdk.dv.socure.io/

Full example

The following is a full example of a Content-Security-Policy that is compatible for a site using the Socure Digital Intelligence Web SDK:

Content-Security-Policy: "connect-src 'self' https://*ingestion.dv*.socure.io; script-src 'self' https://sdk.dv.socure.io/"

Updated about 2 months ago