Device Profiling

This guide covers browser-based experiences. For Android, iOS, Flutter, and React Native applications, use a Signifyd Mobile SDK.

Install the JavaScript

Add the following script once to the shared template used by the pages you want to profile. Place it before the closing </head> tag.

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

The defer attribute allows the browser to continue parsing the page while the script downloads. Do not include the script more than once on the same page.

Choose where profiling runs

When possible, deploy the script throughout each customer journey evaluated by Signifyd. Relevant pages can include landing, product, login, registration, account management, cart, checkout, and returns pages.

Broader deployment:

• Gives profiling more time to complete before your backend submits an API event.
• Captures navigation signals from more of the customer journey.
• Reduces dependence on a customer remaining on the final checkout page long enough for profiling to finish.
  If you control a hosted payment page, install the script there as well and use the same session ID as the related customer journey.

Provide a unique session ID

Replace YOUR-SESSION-ID-HERE with an opaque identifier for the checkout or other activity being evaluated. The session ID connects the browser profile to the corresponding event sent to Signifyd.
For reliable matching across Signifyd services, use a session ID that:

• Is unique to the activity and is not reused across unrelated customer journeys.
• Remains unchanged across the pages and Signifyd API events that belong to that activity.
• Contains 11 to 127 uppercase or lowercase English letters, digits, underscores, or hyphens.
• Does not contain customer information such as an email address, phone number, or account number.

A UUID works well:

82ce5fca-c2b2-429b-b487-6c3053469f85

Send the session ID

Include the exact session ID used by the script in the related Signifyd API request. For APIs with a device object, send it in device.sessionId with the customer's IP address in device.clientIpAddress:

{
  "device": {
    "sessionId": "82ce5fca-c2b2-429b-b487-6c3053469f85",
    "clientIpAddress": "203.0.113.7"
  }
}

The device.sessionId value sent by your backend must exactly match the script's data-order-session-id value. If they differ, Signifyd cannot associate the profile with the corresponding order, account event, or session lookup.
Send the customer's public IP address. Do not substitute your server, proxy, or CDN address.

Test the integration

Test a complete customer journey in a non-production environment before rollout.

Confirm that the script initialized

After the page loads, open the browser console and run:

window.sigScriptLoader?.isInitialized

The result should be true. This confirms that the entry script initialized. It does not confirm that profiling completed or that Signifyd matched the profile to an API event.

Confirm that profiling completed

Open the Network panel in your browser developer tools before loading the page:

1. Confirm that script-tag.js loads successfully.
2. Confirm that the subsequent /o/lite.js profiling resource loads successfully.
3. Filter requests for fp-web.
4. Confirm that the browser sends a request to dp.signifyd.com/fp-web.
5. Confirm that the request receives an HTTP 200 response and uses the expected session ID.

An HTTP 200 response confirms that the profiling endpoint accepted the request. It does not by itself confirm that a later API event used the same session ID.
Repeat this check across the relevant pages in the customer journey. For a single-page application, confirm that another profiling request is sent after each configured virtual route change.

Confirm that Signifyd matched the profile

Submit a test Checkout or Sale event using the same session ID, then use Data Quality to confirm that device data is present on the event.

Listen for errors

The script logs integration errors to the browser console and dispatches a sigScriptError event on document. Listen for this event during development and testing:

document.addEventListener('sigScriptError', (event) => {
  console.warn('Signifyd device profiling:', event.detail)
})

Register the listener on document, not window.

Troubleshoot the integration

The script did not initialize

If window.sigScriptLoader?.isInitialized does not return true:

1. Confirm that script-tag.js loaded successfully.
2. Confirm that the script is installed before the closing </head> tag.
3. Check the browser console for Content Security Policy violations.
4. During testing, disable privacy or content-blocking extensions that may block profiling resources.

The script reports that it is already initialized

The script was included more than once on the page. Remove the duplicate script tag. One installation exposes both the standard page-load behavior and the browser API used by single-page applications.

No fp-web request appears

1. Confirm that data-order-session-id contains a real session ID rather than the placeholder value.
2. Check the browser console for sigScriptError details.
3. Check the Network and Console panels for blocked requests or Content Security Policy violations.
4. Confirm that the page did not remove or replace the script before profiling started.

fp-web returns HTTP 200, but Data Quality shows no device data

1. Confirm that the API request's device.sessionId exactly matches data-order-session-id.
2. Confirm that the API event was submitted after profiling had time to complete.
3. Confirm that Data Quality shows the intended test order and team.
4. Confirm that the session ID was not reused for an unrelated checkout.

Enable debug logging

Run the following command in the browser console, then reload the page:

window.SIG_SCRIPT_DEBUG?.enableLogging()

Debug output can help identify the session ID selected by the script and where profiling stopped.

Other integration patterns

For a single-page application, use the browser API to profile configured virtual route changes and start new sessions. First-party proxying routes script and profiling requests through a domain owned by your organization.