Merge pull request #249 from maxmind/greg/eng-4050

Add tracking_token to Device request object

Author: horgh

CHANGELOG.md

@@ -1,6 +1,14 @@
 CHANGELOG
 =========
 
+3.7.0
+------------------
+
+* Added `tracking_token` to the `/device` request object. This is the
+  token generated by the
+  [Device Tracking Add-on](https://dev.maxmind.com/minfraud/track-devices)
+  for explicit device linking.
+
 3.6.0 (2026-01-20)
 ------------------
 

README.md

@@ -156,6 +156,7 @@ $request = $mf->withDevice(
     ipAddress: '152.216.7.110',
     sessionAge: 3600.5,
     sessionId: 'foobar',
+    trackingToken: 'tst_abc123',
     userAgent: 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.89 Safari/537.36',
     acceptLanguage: 'en-US,en;q=0.8'
 )->withEvent(

src/MinFraud.php

@@ -190,6 +190,9 @@ public function with(array $values): self
      *                                             time since the start of the first visit.
      * @param string|null          $sessionId      An ID that uniquely identifies a visitor's
      *                                             session on the site
+     * @param string|null          $trackingToken  The tracking token generated by the
+     *                                             Device Tracking Add-on for explicit
+     *                                             device linking
      *
      * @return MinFraud A new immutable MinFraud object. This object is a clone
      *                  of the original with additional data.
@@ -203,6 +206,7 @@ public function withDevice(
         ?string $ipAddress = null,
         ?float $sessionAge = null,
         ?string $sessionId = null,
+        ?string $trackingToken = null,
         ?string $userAgent = null,
     ): self {
         if (\count($values) !== 0) {
@@ -228,6 +232,7 @@ public function withDevice(
                 $sessionId = (string) $v;
             }
 
+            $trackingToken = $this->remove($values, 'tracking_token');
             $userAgent = $this->remove($values, 'user_agent');
 
             $this->verifyEmpty($values);
@@ -261,6 +266,10 @@ public function withDevice(
             $values['session_id'] = $sessionId;
         }
 
+        if ($trackingToken !== null) {
+            $values['tracking_token'] = $trackingToken;
+        }
+
         if ($userAgent !== null) {
             $values['user_agent'] = $userAgent;
         }

tests/MaxMind/Test/MinFraud/ReportTransaction/ReportTransactionTest.php

@@ -18,26 +18,18 @@ class ReportTransactionTest extends ServiceClientTester
 {
     public function testMinimalRequest(): void
     {
-        $this->assertEmpty(
-            // @phpstan-ignore-next-line
-            $this->createReportTransactionRequest(
-                Data::minimalRequest(),
-                1
-            )->report(Data::minimalRequest()),
-            'response for minimal request'
-        );
+        $this->createReportTransactionRequest(
+            Data::minimalRequest(),
+            1
+        )->report(Data::minimalRequest());
     }
 
     public function testFullRequest(): void
     {
         $req = Data::fullRequest();
-        $this->assertEmpty(
-            // @phpstan-ignore-next-line
-            $this->createReportTransactionRequest(
-                $req
-            )->report($req),
-            'response for full request'
-        );
+        $this->createReportTransactionRequest(
+            $req
+        )->report($req);
     }
 
     public function testRequestsWithNulls(): void
@@ -52,14 +44,10 @@ public function testRequestsWithNulls(): void
                 'transaction_id' => null,
             ]
         );
-        $this->assertEmpty(
-            // @phpstan-ignore-next-line
-            $this->createReportTransactionRequest(
-                Data::minimalRequest(),
-                1
-            )->report($req),
-            'response from request including nulls'
-        );
+        $this->createReportTransactionRequest(
+            Data::minimalRequest(),
+            1
+        )->report($req);
     }
 
     public function testRequiredFields(): void

tests/MaxMind/Test/MinFraudTest.php

@@ -129,6 +129,7 @@ public function testFullInsightsRequestUsingNamedArgs(string $class, string $ser
                 ipAddress: '152.216.7.110',
                 sessionAge: 3600.5,
                 sessionId: 'foobar',
+                trackingToken: 'tst_abc123',
                 userAgent: 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.89 Safari/537.36',
             )
             ->withEmail(

tests/data/minfraud/full-request.json

@@ -93,6 +93,7 @@
     "ip_address": "152.216.7.110",
     "session_age": 3600.5,
     "session_id": "foobar",
+    "tracking_token": "tst_abc123",
     "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.89 Safari/537.36",
     "accept_language": "en-US,en;q=0.8"
   }