JavaScript Agent v6

You can integrate our device fingerprinting module directly into a web app using our JavaScript agent. Use the CDN-hosted script to ensure you always load the latest available version. Visit the SEON Web SDK GitHub page to see the latest version and its changelog.

The agent produces an encrypted payload that you send as the session attribute of a Fraud API request; the decrypted data comes back as device_details in the Fraud API response.

Integration
Configuration parameters
Behavioural features
Content Security Policy
NPM integration
Payload
Suspicious flags
Example payload
Common issues

Integration

1Load the agent

Include the script — for example inside the <head> tags of your site. You can also lazy-load it or execute it on a specific action (clicking Login, Payment or Registration), as long as you make sure the module has finished loading before you invoke its methods.

<html>
  <head>
    ...
    <script src="[source_url]"></script>
  </head>
  <body>
    ...
  </body>
</html>

Any of these script source URLs works as [source_url]:

https://cdn.dfsdk.com/js/v6/agent.umd.js
https://cdn.deviceinf.com/js/v6/agent.umd.js
https://cdn.seonintelligence.com/js/v6/agent.umd.js

2Call seon.init() on page load

This starts behavioural analysis and yields more data points for bot detection and more accurate intelligence signals.

// On page load:
seon.init();

const config = {
  geolocation: {
    canPrompt: false,
  },
  networkTimeoutMs: 2000,
  fieldTimeoutMs: 2000,
  region: 'eu',
  silentMode: true,
};

Without seon.init() you still receive valid device intelligence signals from most functions, but the payload will carry no behavioural signals, and bot detection and the browser hash will be less precise.

3Generate the session

seon.getSession(config) collects the available information and returns an encrypted, base64-encoded payload. Pass your config object if you are not using the defaults.

const session = await seon.getSession(config);
// 'session' holds the encrypted device fingerprint to send to SEON

4Send it with the Fraud API request

Post the payload string to your backend and set it as the session property of your Fraud API request. Still make the Fraud API call if session is missing — the snippet may not have executed.

await fetch('/api/score-transaction', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ userId, session }),
});

Including the lightweight JavaScript agent or the mobile SDKs is optional, but it provides in-depth analysis of each user's device. Working examples live in the StackBlitz collection.

Configuration parameters

To configure the module, create a config object and pass it to seon.getSession(config) — or to seon.init(config) for the behavioural options.

regionstring

Set this to the region closest to your user base to reduce Device Intelligence runtime. Only eu is currently supported.

Default eu

fieldTimeoutMsinteger

Global timeout for Device Intelligence, in milliseconds. Prefer this over wrapping getSession() in your own timeout — a partial result is still generated when this one expires.

networkTimeoutMsinteger

Timeout for the agent's network call, in milliseconds.

silentModeboolean

Suppresses the agent's warnings and errors in the DevTools console. Turning it off lets the agent enable additional features such as devtools_open and potential_screen_sharing detection.

dnsResolverDomainstring

The DNS resolver domain to use, matched to your script host: seon.io → seondnsresolve.com, deviceinf.com → deviceinfresolver.com, getdeviceinf.com → getdeviceinfresolver.com, seonintelligence.com → seonintelligenceresolver.com.

throwOnarray of string

Causes for which the agent should throw. By default it throws only for an invalid options object and otherwise always runs to completion.

geolocationobject

Browser Geolocation API settings.

5 child attributes

enabledboolean

Whether geolocation collection is enabled.

Default false

highAccuracyboolean

Request high accuracy from the Geolocation API. May slightly increase fingerprinting time.

canPromptboolean

Whether the agent may trigger the browser's geolocation permission prompt.

maxAgeSecondsinteger

Maximum acceptable age of a cached position, in seconds. 0 forces a fresh position.

timeoutMsinteger

Timeout for the Geolocation API to return a position.

behavioralDataCollectionobject

Behavioural biometrics collection settings. Pass these to seon.init().

2 child attributes

targetsstring

A querySelector string selecting the elements to track. Left undefined, behaviour is tracked on the whole page; pass an empty string to disable collection entirely. Targets must already exist in the DOM when init() runs.

formFilloutDurationTargetIdstring

Element ID of the form whose fill-out time should be measured. Only the first matching element is considered; if undefined this data point is not collected.

referrerobject

How the referrer URL is reported.

2 child attributes

maxLengthinteger

Maximum length of the reported URL.

searchParamsboolean

Whether to include the URL's search parameters.

windowLocationobject

How the current page URL is reported.

2 child attributes

maxLengthinteger

Maximum length of the reported URL.

searchParamsboolean

Whether to include the URL's search parameters.

Behavioural features

Calling seon.init() enables behavioural analysis. Collection starts at seon.init() and ends when seon.getSession() is called; the behavioural data is included in the generated session string automatically. The recommended pattern is therefore init on form load, getSession on form submit, so the analysis covers the whole fill-out.

By default user interaction is analysed on the whole page. To target specific inputs or forms, use the behavioralDataCollection option:

// On load
seon.init({
  behavioralDataCollection: {
    targets: 'input[type="text"], .behavior', // querySelector string
    formFilloutDurationTargetId: 'myForm',    // form with id 'myForm'
  }
});

// On form submit
await seon.getSession();

To disable behavioural collection altogether, pass an empty string:

seon.init({
  behavioralDataCollection: {
    targets: '', // pass an empty string for targets
  }
});

Suspicious behaviour surfaces in the suspicious_flags response field, which for behavioural signals can contain suspicious_keypress_characteristics, suspicious_mouse_movement, suspicious_form_fillout, paste_used, autofill_used, potential_remote_interaction and potential_remote_control.

Content Security Policy

If your site sends CSP headers, allow the following sources for full functionality, depending on your host configuration:

Directive	Value
`connect-src`	`*.seondnsresolve.com` (or the resolver domain matching your host)
`worker-src`	`blob:` — required for running fields in web workers
`img-src`	`data:` and `http://127.0.0.1:*` (the latter only when `silentMode` is disabled)

Resolver domains by script host:

Script host	`connect-src` value
Default	`*.seondnsresolve.com`
`deviceinf.com`	`*.deviceinfresolver.com`
`getdeviceinf.com`	`*.getdeviceinfresolver.com`
`seonintelligence.com`	`*.seonintelligenceresolver.com`

NPM integration

Alternatively, integrate the SDK through npm. With this method you have to keep the package updated yourself to pick up our latest features and bugfixes.

npm install @seontechnologies/seon-javascript-sdk
# or
yarn add @seontechnologies/seon-javascript-sdk

Payload

The library collects device information and prepares an encrypted payload for the Fraud API. The client-side data is not readable — it is revealed in the Fraud API response and on the Admin Panel. Some fields can be null when the browser does not support or return that data point; in every other case data types are preserved.

typestring

Source of the fingerprint — web for the JavaScript Agent.

sourcestring

The SDK version that produced the payload. Example: js-6.5.1.

session_idstring

Unique identifier generated for the session when the fingerprint was created.

true_device_idstring

Unique and persistent device identifier.

device_hashstring

Unique identifier of the device at hardware level, based on SEON's algorithm.

browser_hashstring

Unique identifier of the browser, based on SEON's algorithm.

cookie_hashstring

Unique identifier of the user's current session.

spoofing_hashstring

Hash of the detected fingerprint spoofing attempts. Only populated when some form of spoofing is detected.

suspicious_flagsarray of string

Fraud indicators raised for this session. See Suspicious flags for the full list and the default rule scores.

osstring

Operating system of the user's device.

platformstring

Platform reported by the user's browser.

browserstring

Name of the user's browser.

browser_versionstring

Version of the user's browser.

browser_version_ageinteger

Age of the browser version, in years.

user_agentstring

The user agent string of the user's browser.

unpopular_user_agentboolean

true when the user agent is not among the widely used ones.

user_agent_dataobject

User Agent Data API values. Chromium-based browsers only.

7 child attributes

architecturestring

CPU architecture, for example arm.

bitnessstring

CPU bitness, for example 64.

mobileboolean

Whether the browser reports itself as mobile.

modelstring

Device model, where reported.

platformstring

Platform name, for example macOS.

platform_versionstring

Platform version.

ua_full_versionstring

Full browser version.

device_typestring

Type of device: desktop, phone, tablet, TV, and so on.

device_memoryinteger

Size of the device memory, in gigabytes.

hardware_concurrencyinteger

Number of logical processor cores.

price_rangestring

Estimated price range of the user's device.

One of low, medium, high

mobile_detailsobject

Factory device information for the mobile device used — model, resolution, battery size, average price.

privateboolean

Whether the user is browsing in private mode.

vpnboolean

Whether the user is using a VPN.

proxyboolean

Whether the user is using a proxy.

adblockboolean

Whether an ad blocker is installed in the user's browser.

extensionsarray of string

Installed extensions detected against SEON's extension list.

device_ipstring

IP address the session data came from.

device_ip_ispstring

ISP of the device IP.

device_ip_countrystring

Country of the device IP.

device_ip_regionstring

Region of the device IP. Currently US states only.

dns_ipstring

User's DNS IP address.

dns_ip_ispstring

ISP of the DNS IP.

dns_ip_countrystring

Country of the DNS IP.

dns_ip_regionstring

Region of the DNS IP. Currently US states only.

webrtc_activatedboolean

Whether WebRTC is turned on.

webrtc_ipsarray of string

WebRTC IPs found in the user's browser.

webrtc_countinteger

Number of WebRTC IPs found.

device_locationobject

Location data for the device. Returned only when config.device.include requests device_location or extended_device_location. The base form carries latitude, longitude, accuracy, is_simulated and status; the extended form adds the reverse-geocoded country_code, region, city and zip.

9 child attributes

latitudenumber

Latitude reported by the device.

longitudenumber

Longitude reported by the device.

accuracynumber

Accuracy of the reported position, in metres.

is_simulatedboolean

Whether the position appears to be simulated.

statusstring

Outcome of the geolocation collection, for example SUCCESS.

country_codestring

Reverse-geocoded country code. Extended device location only.

regionstring

Reverse-geocoded region. Extended device location only.

citystring

Reverse-geocoded city. Extended device location only.

zipstring

Reverse-geocoded postal code. Extended device location only.

timezonestring

Timezone of the user, for example Europe/Budapest.

timezone_offsetstring

The device's timezone setting as a UTC offset.

timezone_countrystring

ISO country code of the detected timezone.

localestring

The user's language, region and any special variant preferences.

languagesarray of string

The user's preferred languages.

keyboard_layout_namestring

Keyboard layout language of the user.

keyboard_layout_hashstring

Hash of the keyboard's key mapping.

canvas_hashstring

Identifier generated from the browser's canvas rendering.

audio_hashstring

Identifier built on the browser's audio capabilities. Helps separate regular browsers from fraud tools and privacy browsers.

math_hashstring

Hash of high-precision math function outputs. Browser engines implement these differently, so the value narrows down the engine.

mime_types_hashstring

Hash of the media types and formats the browser supports.

system_colors_hashstring

Hash of the built-in base fonts' colours and sizes.

webglobject

WebGL rendering data points.

9 child attributes

webgl_hashstring

A single hash of all WebGL-related information.

webgl_image_hashstring

Hash of an object drawn with WebGL.

webgl_parameters_hashstring

Hash of the WebGL API parameters.

webgl_parameters_noiseboolean

true when noise was detected while hashing the WebGL parameters.

webgl_2_image_hashstring

Hash of an object drawn with WebGL 2.

webgl_2_parameters_hashstring

Hash of the WebGL 2 parameters.

webgl_2_parameters_noiseboolean

true when noise was detected while hashing the WebGL 2 parameters.

webgl_rendererstring

Renderer string of the graphics driver.

webgl_vendorstring

Vendor string of the graphics driver.

font_hashstring

Unique identifier of the user's installed fonts.

font_listarray of string

Names of the fonts installed on the user's device.

font_countinteger

Number of accessible fonts in the user's browser.

font_noiseboolean

Whether font noising was detected — a technique for spoofing the installed font list to defeat fingerprinting.

pluginsobject

Installed browser plugins.

3 child attributes

plugin_countinteger

Number of accessible plugins in the user's browser.

plugin_hashstring

Unique identifier of the user's installed plugins.

plugin_listarray of string

Names of the plugins installed on the user's device.

screen_dataobject

Screen and window measurements — screen_width, screen_height, screen_available_width, screen_available_height, screen_color_depth, screen_pixel_depth, device_pixel_ratio, orientation_type, orientation_angle, is_extended, window_inner_*, window_outer_*, window_screen_*, window_scroll_*, document_width and document_height.

unpopular_device_resolutionboolean

true when the user's screen resolution is not among the widely used ones.

media_devicesobject

The device's media devices.

3 child attributes

audio_input_countinteger

Number of audio input devices, such as microphones.

audio_output_countinteger

Number of audio output devices, such as speakers and headphones.

video_input_countinteger

Number of video input devices, such as webcams.

batteryobject

Battery charge state and level.

2 child attributes

battery_chargingboolean

Whether the device is currently charging.

battery_levelinteger

Current battery level.

min 0, max 100

permissionsobject

The browser's permission states.

3 child attributes

grantedarray of string

Browser APIs for which the user granted permission.

promptarray of string

Browser APIs the user has neither granted nor denied — the user will be prompted on first use.

deniedarray of string

Browser APIs for which the user denied permission.

drm_key_systemsarray of string

Available Digital Rights Management providers.

touch_supportboolean

Whether the user's browser supports a touch screen.

max_touch_pointsinteger

Maximum number of simultaneous touch contact points the device supports.

mouse_movedboolean

Whether the mouse moved during fingerprinting — that is, between seon.init() and seon.getSession().

has_focusboolean

Whether the current page's content has focus.

cookie_enabledboolean

Whether cookies are enabled in the user's browser.

do_not_trackboolean

Whether the browser's Do Not Track feature is turned on.

java_enabledboolean

Whether Java applets are turned on. No modern major browser supports them.

flash_enabledboolean

Whether the browser supports Flash.

referrerstring

The URL of the page that linked to the current page.

window_locationstring

URL of the page where the fingerprint was generated, including path and query parameters.

Suspicious flags

device_details.suspicious_flags is an array of fraud indicators. The default rule score for each is listed below; flags with no default rule are available for you to build your own rules on.

Flag	Meaning	Default score
`bots_and_automation`	The browser is automated. Detected tools include Selenium, Puppeteer, Playwright and PhantomJS.	12
`experimental_user_agent_spoofing`	User agent spoofing inferred from browser feature inconsistencies.	8
`high_risk`	The device includes highly suspicious details, such as VM detection.	5
`medium_risk`	As `low_risk`, with higher confidence of abnormality.	3
`privacy_extension`	A privacy extension such as Privacy Badger or Disconnect was detected.	2
`low_risk`	The browser has some suspicious values, making it low risk.	1
`potential_fraud_browser`	A known fraud browser such as Multilogin, Sphere or VMLogin.	1
`privacy_browser`	A browser with anti-fingerprinting, such as Brave or Tor.	1
`potential_ai_agent`	The session is controlled by an AI agent rather than human interaction. Where applicable an additional flag indicates the agent type.	—
`potential_remote_control`	Network analysis combined with behavioural signals indicates an active remote control session.	—
`potential_remote_interaction`	Remote access inferred from behavioural signals. Highly accurate in a browser, but dependent on your integration.	—
`potential_screen_sharing`	Possible screen sharing, based on port scanning. Requires `silentMode: false`.	—
`possible_device_farm`	Device orientation and motion patterns suggest the device is part of a device farm.	—
`potential_simulator`	Simulator usage.	—
`potential_inapp_browser`	A webview browser environment.	—
`reused_session`	An identical encrypted fingerprint appears across multiple transactions, suggesting a reused or compromised fingerprint.	—
`session_manipulation`	Experimental. Alterations in the fingerprint suggest the session was intentionally tampered with.	—
`navigator_spoof`	The Navigator API has been spoofed, so system data points such as `hardware_concurrency` and `device_memory` are unreliable.	—
`htmlcanvaselement_spoof`	The Canvas API has been spoofed or tampered with.	—
`webglrenderingcontext_spoof`	The WebGL API has been spoofed or altered.	—
`geolocation_spoof`	The Geolocation API is spoofed or manipulated, so the reported geolocation is unreliable.	—
`fake_os`	OS spoofing in the user agent field. JS SDK 5.6.0+.	—
`touch_radius_spoof`	Possible emulation or remote control, based on touch event properties.	—
`touch_timestamp_spoof`	Possible remote-controlled or emulated touch activity, based on event timestamps.	—
`no_hardware_acceleration`	Hardware acceleration is disabled in the browser.	—
`devtools_open`	DevTools are open. Requires `silentMode: false`.	—
`vpn_`	Probable VPN usage. JS SDK 5.7.1+.	—
`proxy_`	Probable proxy usage, based on network fingerprinting. JS SDK 5.7.1+.	—
`suspicious_keypress_characteristics`	Unusual typing characteristics, such as a very high keystrokes-per-minute rate.	—
`suspicious_mouse_movement`	Suspicious mouse movement, for example perfectly linear or unusually fast.	—
`suspicious_touch_movement`	Suspicious touch interactions.	—
`suspicious_form_fillout`	Unusual form filling behaviour, such as untimely navigation.	—
`paste_used`	A paste event occurred.	—
`autofill_used`	Autofill was used.	—
`no_user_interaction`	Behavioural collection is set up but ineffective, due to integration issues or missing event data.	—

Example payload

{
  "device_details": {
    "type": "web",
    "source": "js-6.5.1",
    "session_id": "14e671a5f503b0d0d8d978a67de0866b",
    "true_device_id": "0195943f-b231-7c7c-9586-b3b0cccb039a",
    "device_hash": "c92d19d5c29dbd2834e2281d28b35fd5",
    "browser_hash": "9fc8c3bdc369cdb1bd5c29542eedc092",
    "cookie_hash": "9831c012f5d3056e2399968b55296f91",
    "spoofing_hash": "fbdcfe51a27dadafac9ccf8a2e34b9bd",
    "suspicious_flags": [],
    "os": "macOS 10.15 Catalina",
    "platform": "MacIntel",
    "browser": "CHROME",
    "browser_version": "134.0.0.0",
    "browser_version_age": 0,
    "device_type": "desktop",
    "device_memory": 8,
    "hardware_concurrency": 8,
    "price_range": "medium",
    "private": false,
    "vpn": false,
    "proxy": false,
    "adblock": false,
    "extensions": [],
    "device_ip": "188.0.0.0",
    "device_ip_isp": "Magyar Telekom",
    "device_ip_country": "HU",
    "device_ip_region": null,
    "dns_ip": "141.101.104.187",
    "dns_ip_isp": "CloudFlare Inc",
    "dns_ip_country": "AT",
    "dns_ip_region": null,
    "webrtc_activated": true,
    "webrtc_ips": ["188.0.0.0"],
    "webrtc_count": 1,
    "device_location": {
      "latitude": 47.4379457,
      "longitude": 19.1125038,
      "accuracy": 20,
      "status": "SUCCESS",
      "country_code": "HU",
      "region": "HU-BU",
      "city": "Budapest",
      "zip": "1204"
    },
    "timezone": "Europe/Budapest",
    "timezone_offset": "+01:00",
    "timezone_country": "HU",
    "locale": "en-GB",
    "languages": ["en-GB", "en-US", "en"],
    "keyboard_layout_name": "Hungarian",
    "keyboard_layout_hash": "eac72b515383ac8b4bbbb232ff6841f1",
    "canvas_hash": "cf06210f828cb8744cb449a843b83305",
    "audio_hash": "124.04346607114712",
    "math_hash": "a931b6543effb809b4abb1ecb36431db",
    "mime_types_hash": "12ce62938a9f2e8b926a65dfc687824d",
    "system_colors_hash": "2a20eb8a0076d38e67fafce18f2c5377",
    "webgl": {
      "webgl_hash": "41f3cabaf3febc32cc1bb223db03867d",
      "webgl_image_hash": "9e0924fc01f9d18c4f8ea400b2de8bec",
      "webgl_parameters_hash": "97ec8905c1226b744a9edbffbc5f4a34",
      "webgl_parameters_noise": false,
      "webgl_renderer": "ANGLE (Apple, ANGLE Metal Renderer: Apple M1 Pro, Unspecified Version)",
      "webgl_vendor": "Google Inc. (Apple)"
    },
    "font_hash": "4160d90df34f64c3683c5b1e54bd7d57",
    "font_count": 17,
    "font_noise": false,
    "plugins": {
      "plugin_count": 5,
      "plugin_hash": "a61464d4341e30d7773ad797e19ea630",
      "plugin_list": ["PDF Viewer", "Chrome PDF Viewer", "WebKit built-in PDF"]
    },
    "screen_data": {
      "screen_width": 1512,
      "screen_height": 982,
      "screen_available_width": 1512,
      "screen_available_height": 869,
      "screen_color_depth": 30,
      "device_pixel_ratio": 2.0,
      "orientation_type": "landscape-primary",
      "orientation_angle": 0,
      "is_extended": false,
      "window_inner_width": 1512,
      "window_inner_height": 782
    },
    "unpopular_device_resolution": false,
    "unpopular_user_agent": false,
    "media_devices": {
      "audio_input_count": 1,
      "audio_output_count": 1,
      "video_input_count": 1
    },
    "battery": {
      "battery_charging": true,
      "battery_level": 100
    },
    "permissions": {
      "granted": ["accelerometer", "geolocation", "gyroscope"],
      "prompt": ["camera", "microphone", "notifications"],
      "denied": []
    },
    "drm_key_systems": ["org.w3.clearkey"],
    "touch_support": false,
    "max_touch_points": 0,
    "mouse_moved": false,
    "has_focus": true,
    "cookie_enabled": true,
    "do_not_track": null,
    "java_enabled": false,
    "flash_enabled": false,
    "referrer": "",
    "window_location": "https://randomsite.random",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Safari/537.36",
    "user_agent_data": {
      "architecture": "arm",
      "bitness": "64",
      "mobile": false,
      "model": "",
      "platform": "macOS",
      "platform_version": "15.3.1",
      "ua_full_version": "134.0.6998.89"
    }
  }
}

Common issues

Symptom	Cause	Fix
`session` is sent but `device_details` is `null`, and no device data appears on the Transaction Details page	The encrypted payload is corrupted	Review the integration and check that the payload reaches the API unmodified
Fields are missing from the payload	CSP is blocking the agent	Allow the resolver domains in `connect-src` — see Content Security Policy
No behavioural signals in the payload	`seon.init()` was never called, or was called after the target elements were added to the DOM	Call `seon.init()` on page/form load, before the targets render
Fingerprinting takes too long	No timeout configured	Set `fieldTimeoutMs` rather than wrapping `getSession()` — a partial result is still produced

Next steps

Fraud API Request — where the session payload is sent
Fraud API Response — where device_details comes back
Migration guides — upgrading from v5

Other device fingerprinting SDKs

For additional support, contact your SEON representative.

JavaScript Agent v6

Table of Contents

Integration

1Load the agent

2Call seon.init() on page load

3Generate the session

4Send it with the Fraud API request

Configuration parameters

Behavioural features

Content Security Policy

NPM integration

Payload

Suspicious flags

Example payload

Common issues

Next steps

Related references

Other device fingerprinting SDKs