Add tracking_token documentation for explicit device linking

Update API request/response docs and expand the device tracking
page with explicit device linking guidance and examples.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: oschwald

content/minfraud/api-documentation/requests.md

@@ -198,6 +198,7 @@ transaction.
   "ip_address": "2001:db8::ff00:42:8329",
   "session_age": 3600.5,
   "session_id": "c2ffa1b7-f5c5-4702-beb2-4254794fe391",
+  "tracking_token": "abc123...",
   "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.89 Safari/537.36"
 }
 ```
@@ -234,6 +235,12 @@ transaction.
 
   [Learn more about the /device/session\_id input on our Knowledge Base.](https://support.maxmind.com/knowledge-base/articles/device-inputs-minfraud#session-information)
   {{</minfraud-schema-row>}}
+
+  {{< minfraud-schema-row key="tracking_token" type="request" valueType="string" valueTypeNote="max length: 255" >}}
+  The token returned by the [Device Tracking Add-On](/minfraud/track-devices) `trackDevice()` function, used for explicit device linking. When provided, this token enables high-confidence device matching that does not rely on IP address alone.
+
+  [Learn more about explicit device linking on our device tracking page.](/minfraud/track-devices#explicit-device-linking)
+  {{</minfraud-schema-row>}}
 {{</ schema-table >}}
 
 <!-- prettier-ignore-end -->

content/minfraud/api-documentation/responses.md

@@ -1395,6 +1395,8 @@ this array for issues when integrating the web service.
   | `SHIPPING_COUNTRY_NOT_FOUND` | The shipping country could not be found in our database. This may impact our ability to provide accurate distance calculations.                                                                                                                           |
   | `SHIPPING_POSTAL_NOT_FOUND`  | The shipping postal code could not be found in our database. This may impact our ability to provide accurate distance calculations.                                                                                                                            |
   | `SHIPPING_REGION_NOT_FOUND`  | The shipping region could not be found in our database. This may impact our ability to provide accurate distance calculations.                                                                                                                            |
+  | `TRACKING_TOKEN_INVALID`     | The tracking token provided was invalid or malformed.                                                                                                                                                                                                     |
+  | `TRACKING_TOKEN_NOT_FOUND`   | The tracking token provided was not found on our system.                                                                                                                                                                                                  |
   {{</minfraud-schema-row>}}
 
   {{< minfraud-schema-row key="warning" type="response" valueType="string" valueTypeNote="max length: 255" score="true" insights="true" factors="true" >}}

content/minfraud/track-devices.md

@@ -77,6 +77,10 @@ and provides direct access to the tracking result.
         accountId: MAXMIND_ACCOUNT_ID,
       })
     )
+    .then(({ trackingToken }) => {
+      // Store the tracking token to include in your minFraud API request
+      console.log('Tracking token:', trackingToken);
+    })
     .catch((e) => console.error(e));
 </script>
 ```
@@ -93,14 +97,119 @@ npm install @maxmind/device-tracking
 ```javascript
 import { trackDevice } from '@maxmind/device-tracking';
 
-const result = await trackDevice({
+const { trackingToken } = await trackDevice({
   accountId: MAXMIND_ACCOUNT_ID,
 });
+
+// Store the tracking token to include in your minFraud API request
+console.log('Tracking token:', trackingToken);
 ```
 
 See the [package README](https://github.com/maxmind/device-tracking#readme) for
 full API documentation.
 
+## Explicit device linking
+
+By default, the minFraud service matches devices using IP address. This works
+well in most cases, but IP-based matching can be less reliable when multiple
+users share the same IP address. Common scenarios include:
+
+- **Shared or corporate IPs** where many employees or users share a single
+  public IP address.
+- **Carrier-Grade NAT (CGNAT)** where an ISP assigns the same public IP to
+  many subscribers.
+- **VPNs** where multiple users route traffic through the same VPN endpoint.
+
+Explicit device linking solves this by using a `tracking_token` to match devices
+with high confidence, independent of IP address.
+
+### How it works
+
+The `trackDevice()` function returns a Promise that resolves to an object
+containing a `trackingToken` string. When you pass this token to the minFraud
+API in the
+[`/device/tracking_token`](/minfraud/api-documentation/requests#schema--request--device)
+field, the service uses it to match the device directly. When a valid token is
+found, the device is matched with high confidence regardless of IP address
+changes.
+
+### Implementation steps
+
+1. Call `trackDevice()` on the client side and capture the returned
+   `trackingToken`.
+2. Pass the token to your backend (e.g., via a hidden form field, session
+   storage, or API call).
+3. Include the token in your minFraud API request's `device` object as
+   `tracking_token`.
+
+#### Web (module snippet)
+
+```html
+<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
+      document.getElementById('tracking-token').value = trackingToken;
+    })
+    .catch((e) => console.error(e));
+</script>
+```
+
+On your backend, include the token in the minFraud API request:
+
+```json
+{
+  "device": {
+    "ip_address": "2001:db8::ff00:42:8329",
+    "tracking_token": "token-value-from-client"
+  }
+}
+```
+
+#### Web (npm package)
+
+```javascript
+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 }),
+});
+```
+
+### Token handling
+
+- The tracking token is an **opaque string**. Do not parse it or make
+  assumptions about its format, as the format may change without notice.
+- Tokens should be treated as **transient**. Generate a fresh token for each
+  session or transaction rather than storing tokens long-term.
+
+### 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`
+
+### Custom hostname
+
+You can configure a custom `hostname` option when calling `trackDevice()` to
+serve the device tracking script from your own domain. This can help bypass
+ad-blockers that may block requests to third-party domains.
+
 ## Cookie and web storage usage
 
 The device tracking add-on uses cookies and local storage as methods of

stopwords.txt

@@ -32,6 +32,7 @@ cfif
 cfloop
 cfoutput
 cfset
+CGNAT
 Chūō
 Clojars
 Comcel