Web

The Device Tracking Add-On is JavaScript code for you to add to your website. It runs on a visiting device so that the minFraud service can assign a Device ID and begin collecting fingerprint information. We recommend including the JavaScript below on your product and landing pages as well as all the pages within your purchase flow. This will help detect fraudsters if they change or enable proxies while browsing your website.

To speed page load time, JavaScript should be placed in the footer of the HTML webpage.

Note that, in order to be effective, the Device Tracking Add-On must, at a minimum, be included on the page where the IP address is captured for a minFraud query.

Implementation

Replace MAXMIND_ACCOUNT_ID with your MaxMind account ID.

Classic snippet

<script>
  (function () {
    var mmapiws = (window.__mmapiws = window.__mmapiws || {});
    mmapiws.accountId = MAXMIND_ACCOUNT_ID;
    var loadDeviceJs = function () {
      var element = document.createElement('script');
      element.async = true;
      element.src = 'https://device.maxmind.com/js/device.js';
      document.body.appendChild(element);
    };
    if (window.addEventListener) {
      window.addEventListener('load', loadDeviceJs, false);
    } else if (window.attachEvent) {
      window.attachEvent('onload', loadDeviceJs);
    }
  })();
</script>

Module snippet

If your site targets modern browsers (those supporting JavaScript modules), you can use the module version of the device tracking script. This avoids the use of global variables and provides direct access to the tracking result.

<script type="module">
  import('https://device.maxmind.com/js/device-module.js')
    .then(({ trackDevice }) =>
      trackDevice({
        accountId: MAXMIND_ACCOUNT_ID,
      })
    )
    .catch((e) => console.error(e));
</script>

npm package

If your site uses a JavaScript bundler or build system (e.g., Webpack, Vite, Next.js), you can install the device tracking module as an npm package.

npm install @maxmind/device-tracking

import { trackDevice } from '@maxmind/device-tracking';

await trackDevice({
  accountId: MAXMIND_ACCOUNT_ID,
});

See the package README for full API documentation.

Explicit device linking examples

The following examples show how to capture the tracking token on the client and send it to your backend for inclusion in a minFraud API request. For more background on explicit device linking, see Track Devices.

Module snippet with token capture

<script type="module">
  import('https://device.maxmind.com/js/device-module.js')
    .then(({ trackDevice }) =>
      trackDevice({
        accountId: MAXMIND_ACCOUNT_ID,
      })
    )
    .then(({ trackingToken }) => {
      // Send the tracking token to your backend
      const field = document.getElementById('tracking-token');
      if (field) {
        field.value = trackingToken;
      }
    })
    .catch((e) => console.error(e));
</script>

npm package with token capture

import { trackDevice } from '@maxmind/device-tracking';

const { trackingToken } = await trackDevice({
  accountId: MAXMIND_ACCOUNT_ID,
});

// Send the tracking token to your backend for inclusion in the minFraud request
await fetch('/your-api/transaction', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ trackingToken }),
});

Backend API request

On your backend, include the token in the minFraud API request:

{
  "device": {
    "ip_address": "2001:db8::ff00:42:8329",
    "tracking_token": "token-value-from-client"
  }
}

Protecting device tracking from ad blockers

Ad blockers can stop the device tracking script from loading, which decreases the coverage and effectiveness of device tracking.

To reduce this, you can serve the device tracking script from a hostname on your own domain instead of from device.maxmind.com. We set this up with you as a one-time change, and it does not change how you query the minFraud service.

Because the setup is hands-on, this option is available for higher-volume and enterprise accounts. As a general guide, accounts sending more than 50,000 queries per month, or accounts with a dedicated customer success manager, are eligible.

To get started, contact us or reach out to your customer success manager.

We recommend implementing the explicit device linking described above before or at the same time as moving to your own hostname.

Choosing a hostname

We recommend a hostname that does not reference MaxMind or device tracking. For example, use mm.your-company.com rather than maxmind.your-company.com or device.your-company.com.

Use this hostname only for MaxMind device tracking, not for anything else on your site.

How setup works

1. You give us a hostname on your own domain.
2. We add the hostname to our system and send you DNS records to add to your domain.
3. You add the DNS records and let us know, and we validate them.
4. After validation succeeds, you update the device tracking code on your site to use the new hostname. If your site uses a Content Security Policy, update it as well (see CSP requirements).
5. Device tracking requests should start working on the new hostname shortly after. Send us the URL of a page that includes the script so that we can verify the integration.

Updating your integration

Replace TRACKING_HOSTNAME with the hostname you set up with us.

Your existing code may hardcode the old hostname in more than one place, so search your integration for it and replace every occurrence.

The module and npm examples below also capture the tracking token. The token capture is optional; in the npm example, point the fetch at your own endpoint or remove it.

For the module snippet, use the hostname in the import() URL and pass it as the host option:

<script type="module">
  const host = 'TRACKING_HOSTNAME';
  import(`https://${host}/js/device-module.js`)
    .then(({ trackDevice }) =>
      trackDevice({
        accountId: MAXMIND_ACCOUNT_ID,
        host,
      })
    )
    .then(({ trackingToken }) => {
      // Optional: send the tracking token to your backend
      const field = document.getElementById('tracking-token');
      if (field) {
        field.value = trackingToken;
      }
    })
    .catch((e) => console.error(e));
</script>

For the npm package, pass the host option. The package uses it for both the script URL and the tracking request, so there is nothing else to change:

import { trackDevice } from '@maxmind/device-tracking';

const { trackingToken } = await trackDevice({
  accountId: MAXMIND_ACCOUNT_ID,
  host: 'TRACKING_HOSTNAME',
});

// Optional: send the tracking token to your backend
await fetch('/your-api/transaction', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ trackingToken }),
});

For the classic snippet, set apiHost and use it in the script src:

<script>
  (function () {
    var mmapiws = (window.__mmapiws = window.__mmapiws || {});
    mmapiws.accountId = MAXMIND_ACCOUNT_ID;
    mmapiws.apiHost = 'TRACKING_HOSTNAME';
    var loadDeviceJs = function () {
      var element = document.createElement('script');
      element.async = true;
      element.src = 'https://' + mmapiws.apiHost + '/js/device.js';
      document.body.appendChild(element);
    };
    if (window.addEventListener) {
      window.addEventListener('load', loadDeviceJs, false);
    } else if (window.attachEvent) {
      window.attachEvent('onload', loadDeviceJs);
    }
  })();
</script>

In all three cases, the hostname you set must be bare, without a scheme or path.

Content Security Policy (CSP) requirements

If your site uses a Content Security Policy, you will need to add the following directives to allow the device tracking script to load and communicate with MaxMind’s servers:

• script-src: device.maxmind.com
• connect-src: d-ipv4.mmapiws.com, d-ipv6.mmapiws.com

If you serve device tracking from a hostname on your own domain, use that hostname in both directives instead: it replaces device.maxmind.com in script-src and both d-ipv4.mmapiws.com and d-ipv6.mmapiws.com in connect-src.

Cookie and web storage usage

The device tracking add-on uses cookies and local storage as methods of distinguishing unique devices across visits and domains.

The add-on sets two types of cookies, both named __mmapiwsid with two-year expiration:

1. First-party cookie: Set for the effective second-level domain of your site; for instance, on www.maxmind.com, the cookie would be set for maxmind.com.

2. Third-party cookie: Set by MaxMind’s servers to enable cross-domain device tracking. This allows the same device to be identified when it visits different customer websites using our device tracking.

The local storage key is also named __mmapiwsid and provides an additional method of device identification.

MaxMind may use other browser storage techniques in the future to enhance the performance of the device tracking add-on.