@seontechnologies/seon-javascript-sdk - npm Package Compare versions

Comparing version 5.11.1 to 6.0.0

agent.d.ts

@@ -1,93 +0,177 @@
-/** SEON JavaScript SDK - Copyright (c) SEON Technologies Ltd., 2023 (https://seon.io) */
-export type ResolvableHost = 'seon.io' | 'seondf.com' | 'deviceinf.com' | 'getdeviceinf.com';
-/**
- * Configuration parameters for the SDK
- *
- * @see https://docs.seon.io/api-reference#javascript-agent-v5
- */
-export interface SDKConfigOptions {
+export type CanThrowOn = 'geolocationPermissionDenied';
+
+export interface GeolocationOptions {
     /**
-     * Enable/disable audio_fingerprint module. Note: changing this flag will affect the browser_hash.
-     * Highly recommended to enable. Disabled by default.
+     * Whether to enable geolocation or not.
+     *
+     * Default: false
      */
-    audio_fingerprint?: boolean;
+    enabled?: boolean;
     /**
-     * Enable/disable canvas_fingerprint module. Note: changing this flag will affect the
-     * browser_hash. Highly recommended to enable. Enabled by default.
+     * Enables high accuracy for the Geolocation API. It might slightly increase the fingerprinting
+     * time.
+     *
+     * Default: true
      */
-    canvas_fingerprint?: boolean;
-    /** If CNAME cloaking is set up for the SDK, use this field to specify your domain. */
-    cname_server?: string;
-    /** Timeout for the DNS resolver in milliseconds. Default: 2000 */
-    dnsTimeout?: number;
-    /** Return the list of detected fonts in addition to the font_hash. Default: false */
-    font_list?: boolean;
+    highAccuracy?: boolean;
     /**
-     * Domain where the JavaScript Agent is hosted. If the field is not added or defined, it defaults
-     * to seon.io.
+     * Controls whether the SDK can generate a geolocation permission prompt in the browser. The
+     * access to the Geolocation API in the browser is restricted, and only allowed when a user
+     * explicitly grants permission. By default the SEON SDK does not interrupt the user flow in any
+     * way, so it will not prompt users, but this also means that if geolocation permission was not
+     * granted to the site by other means, the geolocation information will be missing from the
+     * result.
      *
-     * In case of an ad blocker blocks our script, please use one of our alternative hosts and make
-     * sure you use the same domain as host that you used for loading the script.
+     * Additionally, if a prompt is given to the user, the SDK will stall until the user either
+     * grants or denies the permission. This means that the 'getSession' Promise might hang for a
+     * longer time, effectively increasing the time it takes to fingerprint a user's browser.
+     *
+     * Default: false
      */
-    host?: ResolvableHost;
+    canPrompt?: boolean;
     /**
-     * Maximum delay for accurate proxy identification. Values greater than 5000 will be clamped to
-     * 5000. Default: 0 (no delay is allowed)
+     * The Geolocation API can return cached data. This option controls the maximum age in seconds
+     * of a cached position that is acceptable to return. If set to 0, it means that the device
+     * cannot use a cached position and must attempt to retrieve the real current position.
+     *
+     * Default: 0
      */
-    max_proxy_delay?: number;
-    /** Callback function for error during config setup. */
-    onError?: (msg?: string) => void;
-    /** Callback function for successful config setup. */
-    onSuccess?: (msg?: string) => void;
+    maxAgeSeconds?: number;
     /**
-     * Session ID is a custom string that you can use to link device data with transactions. It is a
-     * custom unique identifier that should be based on your customer current session, for example
-     * tracking cookies.
+     * **Note: This option is only considered if 'canPrompt' is true.**
+     *
+     * Timeout for the Geolocation API to return the position of the device. This timeout is
+     * measured from when the user grants the permission to the page (or from the `getSession` call
+     * if the permission was already given).
+     *
+     * This option can be set to `Infinity`. In this case the SDK won't return until the position is
+     * available.
+     *
+     * This timeout only works if 'canPrompt' is enabled. This option is only necessary because
+     * waiting for the user to grant or deny permission takes indefinite amount of time. If
+     * 'canPrompt' is not enabled then the global timeout applies to the geolocation field as well,
+     * so this option will have no effect.
+     *
+     * Default: 1000
      */
-    session_id: string;
-    /** @private */
-    similarity_hash?: boolean;
-    /** @private */
-    verbose?: boolean;
+    timeoutMs?: number;
+}
+
+export interface SDKOptions {
     /**
-     * Enable/disable webgl_fingerprint module. Note: changing this flag will affect the browser_hash.
-     * Highly recommended to enable. Enabled by default.
+     * It is recommended to set this option to the closest supported region of your user base to
+     * reduce the runtime of fingerprinting.
+     *
+     * Supported regions:
+     *
+     * - "eu"
+     *
+     * Default: "eu"
      */
-    webgl_fingerprint?: boolean;
+    region?: string;
     /**
-     * Geolocation feature config.
+     * The domain to use for DNS checks. You might need to change this domain to one of our
+     * alternative domains to avoid adblockers. Please note that if your site uses CSP headers, then
+     * you must set a 'connect-src' directive to allow requests to this domain and all subdomains.
      *
-     * - None: No geolocation.
-     * - Fast: We wait for geolocation up to the DC response. Lower chance to receive a location fix.
-     *   Lower accuracy.
-     * - Accurate: We wait for geolocation up to the dns timeout. Higher chance to receive a location
-     *   fix. Higher accuracy.
-     * - Strict: Same as 'accurate'. In the future this will throw an Error when no Geolocation data is
-     *   available.
+     * **Note: The default value is subject to change between minor versions in order for us to keep
+     * a default value that is not blacklisted. If this behavior is undesirable for you, please set
+     * this option explicitly.**
      *
-     * Default: 'fast'
+     * Supported domains:
+     *
+     * - "seondnsresolve.com"
+     * - "seondfresolver.com"
+     * - "deviceinfresolver.com"
+     * - "getdeviceinfresolver.com"
+     * - "seonintelligenceresolver.com"
+     *
+     * Default: "seondnsresolve.com"
      */
-    geolocation?: 'none' | 'fast' | 'accurate' | 'strict';
+    dnsResolverDomain?: string;
+    /** Options for the geolocation feature */
+    geolocation?: GeolocationOptions;
     /**
-     * The maximum age of geolocation data in seconds.
+     * Timeout for the network call in milliseconds.
      *
-     * Default: 600 (10 minutes)
+     * For the most accurate device fingerprinting results we utilize network requests to our
+     * services. This option sets the maximum time that the SDK will wait for the response of these
+     * requests.
+     *
+     * It is advisable to increase this timeout if some detections (especially the proxy and vpn) do
+     * not always return consistent result.
+     *
+     * Default: 2000
      */
-    geolocation_age?: number;
+    networkTimeoutMs?: number;
     /**
-     * Whether to enable a possible geolocation permission prompt or not. This is also because some
-     * browsers don't user the 'granted' state, only 'prompt' state. So it is only possible to get the
-     * geolocation if we use prompt. If geolocation is set to 'strict', then this flag will always be
-     * 'true'.
+     * Global timeout for the fingerprinting in milliseconds.
      *
-     * Default: false
+     * This option **can** limit the maximum runtime of the fingerprinting. It is recommended to
+     * primarily rely on this option, rather than wrapping the 'getSession' call in a timeout,
+     * because this way a partial result is still generated in case of a timeout.
+     *
+     * There are some caveats to setting this option:
+     *
+     * - When reaching the specified timeout, the SDK will stop all pending checks, and return all
+     *   device details that have already been collected. So in case of a timeout, the SDK will
+     *   still generate an output, but it might only be a partial one.
+     * - This is not a hard limit. Setting this value to a very low value (e.g. 100 ms) will probably
+     *   still result in response times greater than the defined value because some internal
+     *   operations must always complete for a valid result. The recommended minimum value is
+     *   2000ms.
+     * - Setting 'geolocation.canPrompt' to true and 'geolocation.timeout' will always force the SDK
+     *   to wait for the user to either grant or deny the permission prompt (if given). Thus in this
+     *   case the fingerprinting runtime will depend on the geolocation collection except when it
+     *   finishes faster than the defined 'fieldTimeoutMs'
+     * - If the 'networkTimeoutMs' is greater than this option, and the network request is still
+     *   pending when the defined timeout occurs, then the 'networkTimeoutMs' will be honored and
+     *   the network request will still be awaited (until 'networkTimeoutMs').
+     *
+     * Default: 5000
      */
-    geolocation_prompt?: boolean;
+    fieldTimeoutMs?: number;
     /**
-     * Whether to include url parameters in the document.referrer property (referrer url).
+     * A list of possible causes for the SDK to throw an error.
      *
-     * Default: false Max length: 1024
+     * By default the SDK only throws an error for an invalid 'options' object, but otherwise always
+     * runs to completion.
+     *
+     * In some cases it might be desirable to throw an error when specific conditions are met during
+     * execution. E.g. due to legal requirements you must collect geolocation data from users on
+     * your site. If a user denies geolocation permission then you would have to wait for the
+     * fingerprinting, send the result the SEON, await the result, and then block access to the user
+     * because they denied the geolocation prompt. This would be inconvenient, so instead you can
+     * define that in the event of a user denying the geolocation permission, the SDK should throw a
+     * JavaScript error indicating the issue.
+     *
+     * Possible values:
+     *
+     * - "geolocationPermissionDenied" -> throws SEONGeolocationPermissionDenied error if the
+     *   geolocation permission prompt is denied
+     *
+     * Default: []
      */
-    referrer_parameters?: boolean;
+    throwOn?: CanThrowOn[];
     /**
+     * Configuration of the window_location property that will be included in the results.
+     *
+     * The location field could be very large for long URLs, which would mean the generated session
+     * string would also be too large. To mitigate this, there's a maximum allowed length for this
+     * field. The inclusion of the URL's search params are disabled by default but can be enabled.
+     *
+     * Default: { maxLength: 128, searchParams: false }
+     */
+    windowLocation?: URLStringConfig;
+    /**
+     * Configuration of the referrer property that will be included in the results.
+     *
+     * The referrer field could be very large for long URLs, which would mean the generated session
+     * string would also be too large. To mitigate this, there's a maximum allowed length for this
+     * field. The inclusion of the URL's search params are disabled by default but can be enabled.
+     *
+     * Default: { maxLength: 128, searchParams: false }
+     */
+    referrer?: URLStringConfig;
+    /**
      * Whether to allow the JavaScript SDK to trigger warnings and errors on the DevTools console.
@@ -101,43 +185,82 @@ * Turning this off will allow the SDK to create a more accurate fingerprint.
      */
-    silent_mode?: boolean;
+    silentMode?: boolean;
+}
+
+export interface URLStringConfig {
     /**
-     * Max length of the window.location property (current url).
+     * Maximum length of the URL.
      *
-     * Default: 128 Max: 1024
+     * Default: 128, Allowed range: 0-1024
      */
-    window_location_length?: number;
+    maxLength: number;
+    /**
+     * Whether to include search parameters of the URL.
+     *
+     * Default: false
+     */
+    searchParams: boolean;
 }
-/**
- * The setup function for the SDK that takes a configuration object. Only the session_id field is
- * required.
- *
- * @see https://docs.seon.io/api-reference#javascript-agent-v5
- */
-declare const config: (options: SDKConfigOptions) => void;
-/**
- * This function must be called after the SDK was initialized using the seon.config() function. It
- * returns a Promise with the encrypted payload. Alternatively you can pass a callback function that
- * will be called with the result.
- *
- * @see https://docs.seon.io/api-reference#javascript-agent-v5
- */
-declare const getBase64Session: (callback?: (result: string) => void) => Promise<string>;
-export { config, getBase64Session };
+
+export interface SDKInitOptions {
+    /** Settings for the behavioral biometrics data collection */
+    behavioralDataCollection?: BehaviorCollectionOptions;
+}
+
+export interface BehaviorCollectionOptions {
+    /**
+     * QuerySelector string that selects the targets for which the behavior biometrics should be
+     * enabled.
+     *
+     * If left undefined, it will track behavior on the whole page. To disable this feature, specify
+     * an empty string.
+     *
+     * Default: undefined
+     */
+    targets?: string;
+    /**
+     * Selects the form by its element ID to measure the fillout time. Only the first matching
+     * element is considered.
+     *
+     * If left undefined, this datapoint will not be available.
+     *
+     * Default: undefined
+     */
+    formFilloutDurationTargetId?: string;
+}
+
+export type getSessionFunction = (options?: SDKOptions) => Promise<string>;
+export type initFunction = (initOptions?: SDKInitOptions) => void;
+
 declare const _default: {
     /**
-     * The setup function for the SDK that takes a configuration object. Only the session_id field is
-     * required.
+     * Initializes the SDK and some internal event listeners.
      *
-     * @see https://docs.seon.io/api-reference#javascript-agent-v5
+     * This function should be called on page load with an optional initOptions object. As such it
+     * is lightweight and shouldn't affect load times much. Calling this function is not required
+     * but recommended.
+     *
+     * @param [initOptions] - Init configuration options
      */
-    config: (options: SDKConfigOptions) => void;
+    init: initFunction;
     /**
-     * This function must be called after the SDK was initialized using the seon.config() function. It
-     * returns a Promise with the encrypted payload. Alternatively you can pass a callback function
-     * that will be called with the result.
+     * Collects the device fingerprint of the browser.
      *
-     * @see https://docs.seon.io/api-reference#javascript-agent-v5
+     * It is recommended to call this function on a user action, e.g. on a form submit. The 'init'
+     * function should also be called before this one for a more accurate fingerprint. This is an
+     * optional but recommended step.
+     *
+     * @example
+     *     // On page load:
+     *     seon.init();
+     *     // Later on when the fingerprint is needed:
+     *     const session = await seon.getSession();
+     *     // 'session' variable holds the encrypted device fingerprint that should be sent to SEON
+     *
+     * @param [options] - Configuration options for the SDK
+     * @returns A Promise that resolves to the encrypted device fingerprint as a base64 encoded
+     *   string
      */
-    getBase64Session: (callback?: (result: string) => void) => Promise<string>;
+    getSession: getSessionFunction;
 };
+
 export default _default;

package.json

@@ -18,3 +18,3 @@ {
   ],
-  "main": "agent.cjs.js",
+  "main": "agent.umd.js",
   "module": "agent.esm.js",
@@ -25,3 +25,3 @@ "author": "SEON Technologies Ltd.",
   "files": [
-    "agent.js",
+    "agent.umd.js",
     "agent.cjs.js",
@@ -33,3 +33,3 @@ "agent.esm.js",
   "types": "agent.d.ts",
-  "version": "5.11.1"
+  "version": "6.0.0"
 }

README.md

@@ -1,2 +0,2 @@
-# SEON JavaScript SDK v5
+# SEON JavaScript SDK v6
 
@@ -14,7 +14,7 @@ To successfully utilize this library, you must have a SEON account set up. (https://seon.io)
 ```html
-<script src="https://cdn.seondf.com/js/v5/agent.js"></script>
+<script src="https://cdn.seondf.com/js/v6/agent.umd.js"></script>
 <!-- or -->
-<script src="https://cdn.deviceinf.com/js/v5/agent.js"></script>
+<script src="https://cdn.deviceinf.com/js/v6/agent.umd.js"></script>
 <!-- or -->
-<script src="https://cdn.getdeviceinf.com/js/v5/agent.js"></script>
+<script src="https://cdn.seonintelligence.com/js/v6/agent.umd.js"></script>
 ```
@@ -25,29 +25,13 @@
 ```javascript
-window.seon.config({
-  host: "seondf.com",
-  session_id: "[session_id]",
-  audio_fingerprint: true,
-  canvas_fingerprint: true,
-  webgl_fingerprint: true,
-  onSuccess: function(message) {
-    console.log("success", message);
-  },
-  onError: function(message) {
-    console.log("error", message);
-  }
-});
-```
+// On page load
+window.seon.init();
 
-For more information about the config options, please visit https://docs.seon.io/api-reference#javascript-agent-v5 .
-
-After successful configuration, you can collect the device fingerprint with the `getBase64Session` function:
-
-```javascript
-window.seon.getBase64Session().then((encryptedPayload) => {
-    console.log(encryptedPayload);
-});
+// Later when the fingerprint is needed
+const session = await window.seon.getSession();
+// 'session' variable holds the encrypted device fingerprint as a base64 encoded string
 ```
 
+For more information about the config options, please visit https://docs.seon.io/api-reference/fraud-api#javascript-agent-v6 .
 This will give you the collected device info in an encrypted format. You can not decrypt it yourself,
-you have to send it as the `session` parameter to SEON's proprietary Fraud API (see https://docs.seon.io/api-reference#fraud-api).
+you have to send it as the `session` parameter to SEON's proprietary Fraud API (see https://docs.seon.io/api-reference/fraud-api).
 The Fraud API will return the device fingerprint in the `device_details` field.
@@ -68,25 +52,14 @@
 ```javascript
-import seon from 'seon-javascript-sdk';
+import seon from '@seontechnologies/seon-javascript-sdk';
 // or
-// const seon = require('seon-javascript-sdk');
+// const seon = require('@seontechnologies/seon-javascript-sdk');
 
-seon.config({
-  host: "seondf.com",
-  session_id: "[session_id]",
-  audio_fingerprint: true,
-  canvas_fingerprint: true,
-  webgl_fingerprint: true,
-  onSuccess: function(message) {
-    console.log("success", message);
-  },
-  onError: function(message) {
-    console.log("error", message);
-  }
-});
+// On page load
+seon.init();
 
-seon.getBase64Session().then((encryptedPayload) => {
-    console.log(encryptedPayload);
-});
+// Later when the fingerprint is needed
+const session = await seon.getSession();
+// 'session' variable holds the encrypted device fingerprint as a base64 encoded string
 ```
 
-For more information, visit https://docs.seon.io/api-reference#javascript-agent-v5 .
+For more information and configuration options, visit our public GitHub [repository](https://github.com/seontechnologies/seon-web-sdk-public) and consult the [API reference](https://docs.seon.io/api-reference/fraud-api#javascript-agent-v6).

New alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

1358522

increased by4.44%

Lines of code

5415

increased by3713.38%

Worsened metrics

Number of lines in readme file

63

decreased by-30%

Number of medium supply chain risk alerts

13

increased by8.33%

No dependency changes