Skip to content

Add tracking_token to Device request object #249

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
horgh merged 3 commits into from
Feb 25, 2026
Merged

Add tracking_token to Device request object #249

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
54f405d
Add tracking_token to Device request object
oschwald Feb 23, 2026
7a7a3df
Fix PHPStan errors in ReportTransactionTest
oschwald Feb 24, 2026
50dd6bc
Capitalize description for consistency
oschwald Feb 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
------------------

Expand Down
1 change: 1 addition & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand Down
9 changes: 9 additions & 0 deletions src/MinFraud.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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) {
Expand All @@ -228,6 +232,7 @@ public function withDevice(
$sessionId = (string) $v;
}

$trackingToken = $this->remove($values, 'tracking_token');
Copy link

@gemini-code-assist gemini-code-assist bot Feb 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

For consistency with other token-like fields such as session_id, it is recommended to validate the type when extracting tracking_token from the $values array and cast the result to a string. This ensures that the internal state remains consistent regardless of whether the method was called with named arguments or an associative array.

            $v = $this->remove($values, 'tracking_token', ['integer', 'string']);
            if ($v !== null) {
                $trackingToken = (string) $v;
            }

$userAgent = $this->remove($values, 'user_agent');

$this->verifyEmpty($values);
Expand Down Expand Up @@ -261,6 +266,10 @@ public function withDevice(
$values['session_id'] = $sessionId;
}

if ($trackingToken !== null) {
$values['tracking_token'] = $trackingToken;
}
Comment on lines +269 to +271
Copy link

@gemini-code-assist gemini-code-assist bot Feb 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The tracking_token field has a length constraint of 1 to 255 characters according to the MaxMind minFraud API documentation. Adding client-side validation here ensures consistency with other fields like session_id and prevents invalid requests from being sent to the web service.

        if ($trackingToken !== null) {
            if ($trackingToken === '' || \strlen($trackingToken) > 255) {
                $this->maybeThrowInvalidInputException(
                    "Tracking token ($trackingToken) must be a string with length between 1 and 255",
                );
            }
            $values['tracking_token'] = $trackingToken;
        }


if ($userAgent !== null) {
$values['user_agent'] = $userAgent;
}
Expand Down
34 changes: 11 additions & 23 deletions tests/MaxMind/Test/MinFraud/ReportTransaction/ReportTransactionTest.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
1 change: 1 addition & 0 deletions tests/MaxMind/Test/MinFraudTest.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand Down
1 change: 1 addition & 0 deletions tests/data/minfraud/full-request.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
}
Expand Down