Force new visit if AI agent information changes

Author: mneudert

plugins/AIAgents/Columns/AIAgentName.php

@@ -11,8 +11,11 @@
 
 namespace Piwik\Plugins\AIAgents\Columns;
 
+use Piwik\Container\StaticContainer;
+use Piwik\Log\LoggerInterface;
 use Piwik\Plugin\Dimension\VisitDimension;
 use Piwik\Plugins\AIAgents\AIAgents;
+use Piwik\Tracker\Action;
 use Piwik\Tracker\Request;
 use Piwik\Tracker\Visitor;
 
@@ -38,7 +41,40 @@ public function __construct()
         };
     }
 
+    public function shouldForceNewVisit(Request $request, Visitor $visitor, ?Action $action = null)
+    {
+        $previousProvider = $visitor->getVisitorColumn($this->columnName);
+        $provider         = $this->detectProvider($request);
+
+        if ($provider !== $previousProvider) {
+            StaticContainer::get(LoggerInterface::class)->debug(
+                'Existing visit detected, but creating new visit because AI agent information is different than last action.'
+            );
+
+            return true;
+        }
+
+        return false;
+    }
+
+    /**
+     * @return false
+     */
+    public function onExistingVisit(Request $request, Visitor $visitor, $action)
+    {
+        // function implementation required to have the column available in shouldForceNewVisit.
+        return false;
+    }
+
+    /**
+     * @return false|string
+     */
     public function onNewVisit(Request $request, Visitor $visitor, $action)
+    {
+        return $this->detectProvider($request);
+    }
+
+    private function detectProvider(Request $request): ?string
     {
         $providers = AIAgents::getAvailableAgentProviders();
 
@@ -48,6 +84,6 @@ public function onNewVisit(Request $request, Visitor $visitor, $action)
             }
         }
 
-        return false;
+        return null;
     }
 }

plugins/AIAgents/tests/Integration/Columns/AIAgentNameTest.php

@@ -59,7 +59,7 @@ public function testOnNewVisitShouldBeAbleToNotDetectAIAgent(): void
 
         $result = $this->aiAgentName->onNewVisit($request, $visitor, null);
 
-        self::assertFalse($result);
+        self::assertNull($result);
     }
 
     /**

plugins/AIAgents/tests/Integration/ForceNewVisitTest.php

@@ -0,0 +1,114 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license http://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+namespace Piwik\Plugins\AIAgents\tests\Integration;
+
+use MatomoTracker;
+use Piwik\Date;
+use Piwik\Plugins\AIAgents\Providers\ChatGPT as ChatGPTAgent;
+use Piwik\Plugins\Live\API as LiveAPI;
+use Piwik\Tests\Framework\Fixture;
+use Piwik\Tests\Framework\TestCase\IntegrationTestCase;
+
+/**
+ * @group AIAgents
+ * @group Plugins
+ */
+class ForceNewVisitTest extends IntegrationTestCase
+{
+    /**
+     * @var int
+     */
+    private $idSite = null;
+
+    /**
+     * @var Date
+     */
+    private $testDate;
+
+    /**
+     * @var MatomoTracker
+     */
+    protected $tracker = null;
+
+    public function setUp(): void
+    {
+        parent::setUp();
+
+        $this->testDate = Date::factory('now')->setTime('12:00:00');
+
+        $this->idSite  = Fixture::createWebsite('2025-07-18 00:00:00');
+        $this->tracker = Fixture::getTracker($this->idSite, $this->testDate->getDatetime());
+    }
+
+    public function testTrackingWithChangedAgentCausesNewVisits(): void
+    {
+        $this->trackAgentPageView();
+        $this->assertVisits(1, 1);
+        $this->moveTimeForward(0.05);
+        $this->trackAgentPageView();
+        $this->assertVisits(1, 2);
+
+        $this->moveTimeForward(0.1);
+        $this->trackHumanPageView();
+        $this->assertVisits(2, 3);
+        $this->moveTimeForward(0.15);
+        $this->trackHumanPageView();
+        $this->assertVisits(2, 4);
+
+        $this->moveTimeForward(0.2);
+        $this->trackAgentPageView();
+        $this->assertVisits(3, 5);
+        $this->moveTimeForward(0.25);
+        $this->trackAgentPageView();
+        $this->assertVisits(3, 6);
+    }
+
+    private function assertVisits(int $visitsExpected, int $actionsExpected): void
+    {
+        $counters = LiveAPI::getInstance()->getCounters(
+            $this->idSite,
+            2880,
+            false,
+            ['visits', 'actions']
+        );
+
+        self::assertEquals($visitsExpected, $counters[0]['visits']);
+        self::assertEquals($actionsExpected, $counters[0]['actions']);
+    }
+
+    private function moveTimeForward(float $hoursForward): void
+    {
+        $this->tracker->setForceVisitDateTime(
+            $this->testDate->addHour($hoursForward)->getDatetime()
+        );
+    }
+
+    private function trackAgentPageView(): void
+    {
+        $this->tracker->setCustomTrackingParameter(ChatGPTAgent::PARAM_SIGNATURE, 'value irrelevant');
+        $this->tracker->setCustomTrackingParameter(ChatGPTAgent::PARAM_SIGNATURE_AGENT, '"https://chatgpt.com"');
+        $this->tracker->setCustomTrackingParameter(ChatGPTAgent::PARAM_SIGNATURE_INPUT, 'value irrelevant');
+
+        $this->tracker->setUrl('http://www.example.org/agent');
+
+        Fixture::checkResponse(
+            $this->tracker->doTrackPageView('Agent - ' . $this->testDate->getDatetime())
+        );
+    }
+
+    private function trackHumanPageView(): void
+    {
+        $this->tracker->setUrl('http://www.example.org/human');
+
+        Fixture::checkResponse(
+            $this->tracker->doTrackPageView('Human - ' . $this->testDate->getDatetime())
+        );
+    }
+}