API Reference
API Reference

Device Profiling

Signifyd’s device profiling solution uniquely tracks and identifies devices and behaviors used by customers and criminals that are attempting transactions on your site.

📘

Note

Merchants who already utilize a compatible device profiling solution may, instead of deploying Signifyd's device profiling script, send device information via the device field in the relevant API calls.

👍

Tip

Device profiling data is key to Signifyd's model efficacy and a required part of a successful implementation.

To learn more about how Device Profiling works, you can find our full documentation here.

Setup

If your integration includes a mobile application (iOS or Android), testing will need to be coordinated with Signifyd during implementation.

1. Install the JavaScript snippet

Place the following script just before the closing tag on your checkout page. The script loads asynchronously and does not affect page load time.

We recommend that you load the script on the checkout page. If you are using Return Abuse Prevention or Account Integrity, the tag must also be placed on those pages as relevant.

<script
  defer
  type="text/javascript"
  id="sig-api"
  data-order-session-id="YOUR-SESSION-ID-HERE"
  src="https://cdn-scripts.signifyd.com/api/script-tag.js"
></script>

2. Provide a unique session id

Replace data-order-session-id with a unique session id for the current user's checkout. We recommend appending with a Signifyd Team ID number if you have multiple teams.

The session id must formatted as followed:

  • Less than 128 characters long
  • Upper and lowercase English letters (a-z, A-Z)
  • Digits (0-9)
  • Underscore (_)
  • Hyphen (-)

3. Send the session id on event completion

After an event (e.g.: a login, an order, a return) is completed on your website you will need to add the value you used for data-order-session-id to the body of the API POST request to the corresponding API under the device object:

{
  "device": {
    "clientIPAddress": "192.168.1.1",
    "sessionID": "YOUR-SESSION-ID-HERE",
    …
  }
}

View the Checkout or Sale docs for additional information on creating orders.

Testing / Debugging

Testing the Signifyd device profiling script

During testing, you may want to confirm that the Signifyd device profiling script is working correctly. To do so, you can open the dev tools on your browser and check that sigScriptLoader.isInitialized is set to true.

Listening for error events

When an issue occurs within the Signifyd device profiling script, an error message is displayed in the browser's developer console tab. You may also want the ability to be aware of this within your application or perform an action when an error happens.

The Signifyd device profiling script dispatches an event whenever an error occurs that can be received by the invoking application. The event type is sigScriptError and this can be listened for via an event listener to handle the outcome of an error being raised.

Below is an example of listening for the error event:

<script>
  document.addEventListener('sigScriptError', function (error) {
    // Logic that happens whenever error occurs within Signifyd device profiling script
    // Details of error can be found in error.detail
    console.log('Error details: ', error.detail)
  })
</script>