DOCSEARCHbyAlgolia
Submit Docs

TrustDevice-JS

repository·main·Indexed 43 days ago

https://github.com/trustdecision/trustdevice-js

A lightweight JavaScript library (v1.0.6) for device fingerprinting, uniqueness determination, and risk identification. It generates stable device identifiers that persist across browser data clearing and detects risk labels such as disabled cookies and debugger usage. Supports a wide range of browsers, including IE 9+, Chrome 33+, and Firefox 29+.

Tokens
1.6K
Snippets
5
Records
7
Agent score
53%

What's inside TrustDevice-JS

  1. Understand Open Source features and risk labels

    main

    The open-source version of TrustDevice-JS provides basic device identification and risk detection.

    Core Capabilities:

    • Basic Device ID: Generates a consistent identifier that remains the same even after uninstalling/reinstalling applications or clearing browser data.
    • Equipment Information: Provides basic device details for data analysis.
    • Basic Risk Identification: Detects specific risk scenarios.

    Available Risk Labels:

    RiskLabelRisk Description
    disabledCookieCookies are set to disable.
    debuggerThe attacker or developer opens the browser developer tool for debugging.

  2. Integrate TrustDevice-JS into your web application

    main

    To integrate the library, you must inject a script tag that loads the fingerprinting engine (e.g., fm.js). You should configure a global window._fmOpt object to handle the result of the device identification process. The success callback provides the deviceId.

    Note: The example below uses a relative path ./dist/fm.js. In a production environment, ensure the path points to the correct location of the library files. The script includes a cache-busting timestamp appended to the URL.

    <script>
    (function () {
      window._fmOpt = {
        success: function (result) {
          console.log('deviceId: ', result.deviceId)
        }
      }
      var fm = document.createElement('script');
      fm.type = 'text/javascript';
      fm.async = true;
      fm.src =
      './dist/fm.js?t='
      + (new Date().getTime()/3600000).toFixed(0);
      var s = document.getElementsByTagName('script')[0];
      s.parentNode.insertBefore(fm, s);
    })();
  </script>

  3. Understand the device identification result object

    main

    The success callback receives a result object containing three main components: device_id, device_risk_label, and device_detail.

    Result Schema

    • device_id: A 32-character MD5 hash representing the unique device identifier. It is either retrieved from a persistent cookie (key: B106E2F6056FE017) or generated from the device_detail object and then cached in that cookie.
    • device_risk_label: An object containing risk scores for specific detection tasks. Currently includes:
      • debugger: Risk score related to debugger detection.
      • disabledCookie: Risk score related to disabled cookies.
    • device_detail: An object containing the raw device telemetry. Key fields include:
      • screen, navigator: Merged properties from screen and navigator detection.
      • canvas, maxTouchPoints, timezone, touchSupport, gpu, support, font: Results from their respective detection modules.
      • audioRipple, userAgentData: Results from asynchronous detection modules.
      • timezoneStr: The string representation of the timezone.
      • documentReferrer: The document referrer (if available).
      • initTime: The time elapsed (in ms) since the library initialization started.
    {
  "device_id": "...32_char_md5_hash...",
  "device_risk_label": {
    "debugger": 0,
    "disabledCookie": 0
  },
  "device_detail": {
    "screen": { "width": 1920, "height": 1080 },
    "navigator": { "userAgent": "..." },
    "canvas": "...",
    "timezoneStr": "America/New_York",
    "initTime": 150
  }
}

  4. Integrate TrustDevice-JS via the window._fmOpt callback

    main

    TrustDevice-JS is designed to be integrated by ensuring a global configuration object window._fmOpt is present on the window object before the library loads. The library performs various device detection tasks (screen, navigator, canvas, etc.) and returns the results through a success callback defined in window._fmOpt.success.

    To use the library, you must define _fmOpt and provide a success function to receive the device identification data.

    <script>
  window._fmOpt = {
    success: function(result) {
      console.log('Device Identification Result:', result);
    }
  };
</script>
<!-- Load the trustdevice-js library after the configuration above -->
<script src="path/to/trustdevice-js.js"></script>

  6. Get the device's timezone string with getTimezoneStr()

    main

    The getTimezoneStr() function retrieves the IANA timezone string (e.g., 'America/New_York') from the browser using the Intl.DateTimeFormat API. If the browser does not support the Intl API or the timezone cannot be resolved, it returns an empty string ''.

    import { getTimezoneStr } from './src/detection/timezone.js';

const timezoneString = getTimezoneStr();
console.log(timezoneString); // e.g., 'Europe/London' or ''

  7. Get the device's UTC offset with getTimezone()

    main

    The getTimezone() function calculates the device's timezone offset in minutes relative to UTC. It performs a calculation across different months (June and December) to account for potential Daylight Saving Time (DST) transitions, returning the minimum offset found to ensure a stable value for device fingerprinting.

    import getTimezone from './src/detection/timezone.js';

const offsetMinutes = getTimezone();
console.log(offsetMinutes); // Returns the offset in minutes