Skip to content

Move AI Agents reports into their own overview category #23883

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
mneudert merged 2 commits into from
Dec 9, 2025
Merged

Move AI Agents reports into their own overview category #23883

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0d8576b
Move AI Agents reports into their own overview category
sgiehl Dec 9, 2025
9527cba
updates expected UI test files
sgiehl Dec 9, 2025
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
1 change: 1 addition & 0 deletions lang/en.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
"General": {
"12HourClock": "12-hour clock",
"24HourClock": "24-hour clock",
"AIAssistants": "AI Assistants",
"API": "API",
"AbandonedCarts": "Abandoned Carts",
"AboutPiwikX": "About Matomo %s",
Expand Down
30 changes: 30 additions & 0 deletions plugins/AIAgents/Categories/AIAgentsOverviewSubcategory.php
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
<?php

/**
* Matomo - free/libre analytics platform
*
* @link https://matomo.org
* @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
*/

declare(strict_types=1);

namespace Piwik\Plugins\AIAgents\Categories;

use Piwik\Category\Subcategory;
use Piwik\Piwik;

class AIAgentsOverviewSubcategory extends Subcategory
{
protected $categoryId = 'General_AIAssistants';
protected $id = 'AIAgents_AIAgentsOverview';
protected $order = 10;

public function getHelp()
{
return sprintf(
'<p>%1$s</p>',
Piwik::translate('AIAgents_AIAgentsOverviewSubcategoryDescription')
);
}
}
32 changes: 0 additions & 32 deletions plugins/AIAgents/Categories/AIAssistantsOverviewSubcategory.php
View file
Open in desktop

This file was deleted.

4 changes: 2 additions & 2 deletions plugins/AIAgents/Reports/Get.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,8 @@ protected function init()
parent::init();

$this->name = Piwik::translate('AIAgents_AIAgentVisits');
$this->categoryId = 'AIAgents_AIAssistants';
$this->subcategoryId = 'General_Overview';
$this->categoryId = 'General_AIAssistants';
$this->subcategoryId = 'AIAgents_AIAgentsOverview';
$this->order = 10;

$this->processedMetrics = [
Expand Down
3 changes: 2 additions & 1 deletion plugins/AIAgents/lang/en.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,10 @@
{
"AIAgents": {
"AIAgentName": "AI Agent Name",
"AIAgentsOverview": "AI Agents Overview",
"AIAgentVisits": "AI Agent Visits",
"AIAgentVisitsDocumentation": "This is an overview of AI Agent visits. AI agent traffic only includes visits where an AI opens your site in a real browser and behaves like a human visitor. It does not include background requests from ChatGPT or other AI tools that fetch your pages without using a browser.",
"AIAssistants": "AI Assistants",
"AIAgentsOverviewSubcategoryDescription": "Review how AI agents and human visitors engage with your site at a glance. This overview surfaces combined metrics and trends so you can quickly spot changes before exploring detailed reports.",
"AIAssistantsOverviewHelp1": "The AI Assistant Overview page provide insights into website traffic originating from AI Assistants such as ChatGPT and other large language model–based assistants. These reports track key metrics including the number of requests made by these bots, the pages and documents they access, and any errors encountered. They also offer detailed breakdowns showing which bots visit specific page URLs, helping you understand how AI assistants interact with your content and identify opportunities to improve visibility and accessibility for AI-driven users.",
"AIAssistantsOverviewHelp2": "It’s important to note that none of these pages were actually viewed by humans in the traditional way — all requests originate from AI assistants fetching content automatically.",
"AIAssistantsOverviewHelp3": "Currently, these reports exclusively include requests from AI bots that do not execute JavaScript. They do not include traffic from AI crawlers used for training AI models or from AI agents capable of executing JavaScript.",
Expand Down
2 changes: 1 addition & 1 deletion plugins/AIAgents/tests/UI/AIAgents_spec.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
describe('AIAgents', function () {
this.fixture = 'Piwik\\Plugins\\AIAgents\\tests\\Fixtures\\AIAgents';

const url = '?module=CoreHome&action=index&category=AIAgents_AIAssistants&subcategory=General_Overview&idSite=1&period=day&date=2025-07-20';
const url = '?module=CoreHome&action=index&category=General_AIAssistants&subcategory=AIAgents_AIAgentsOverview&idSite=1&period=day&date=2025-07-20';

it('should display the AI agents overview', async function () {
await page.goto(url);
Expand Down
Binary file modified plugins/AIAgents/tests/UI/expected-ui-screenshots/AIAgents_menu.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 2 additions & 2 deletions ...gents/Categories/AIAssistantsCategory.php → ...eHome/Categories/AIAssistantsCategory.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,13 @@

declare(strict_types=1);

namespace Piwik\Plugins\AIAgents\Categories;
namespace Piwik\Plugins\CoreHome\Categories;

use Piwik\Category\Category;

class AIAssistantsCategory extends Category
{
protected $id = 'AIAgents_AIAssistants';
protected $id = 'General_AIAssistants';
protected $order = 80;
protected $icon = 'icon-admin-platform';
}
2 changes: 1 addition & 1 deletion tests/PHPUnit/Integration/Category/CategoryListTest.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ public function testGetAllCategoriesWithSubcategoriesShouldFindCategories()
$list = CategoryList::get();

$this->assertSame(array(
'General_AIAssistants',
'General_Actions',
'General_KpiMetric',
'General_Visitors',
Expand All @@ -55,7 +56,6 @@ public function testGetAllCategoriesWithSubcategoriesShouldFindCategories()
'ProfessionalServices_PromoHeatmaps',
'ProfessionalServices_PromoMediaAnalytics',
'ProfessionalServices_PromoSessionRecording',
'AIAgents_AIAssistants',
'ExampleUI_UiFramework',
'CustomVariables_CustomVariables',
), array_keys($list->getCategories()));
Expand Down
2 changes: 1 addition & 1 deletion tests/PHPUnit/Integration/WidgetsListTest.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ public function testGet()
'Referrers_Referrers' => 11,
'About Matomo' => 11,
'Marketplace_Marketplace' => 3,
'AIAgents_AIAssistants' => 2,
'General_AIAssistants' => 2,

// widgets provided by Professional Services plugin for plugin promos
'ProfessionalServices_PromoAbTesting' => 1,
Expand Down
2 changes: 1 addition & 1 deletion tests/PHPUnit/System/expected/test_apiGetReportMetadata__API.getReportMetadata_day.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3546,7 +3546,7 @@
</row>
<row>
<category>AI Assistants</category>
<subcategory>Overview</subcategory>
<subcategory>AI Agents Overview</subcategory>
<name>AI Agent Visits</name>
<module>AIAgents</module>
<action>get</action>
Expand Down
102 changes: 51 additions & 51 deletions tests/PHPUnit/System/expected/test_apiGetReportMetadata__API.getReportPagesMetadata.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,56 @@
<?xml version="1.0" encoding="utf-8" ?>
<result>
<row>
<uniqueId>General_AIAssistants.AIAgents_AIAgentsOverview</uniqueId>
<category>
<id>General_AIAssistants</id>
<name>AI Assistants</name>
<order>80</order>
<icon>icon-admin-platform</icon>
<help />
<widget />
</category>
<subcategory>
<id>AIAgents_AIAgentsOverview</id>
<name>AI Agents Overview</name>
<order>10</order>
<help>&lt;p&gt;Review how AI agents and human visitors engage with your site at a glance. This overview surfaces combined metrics and trends so you can quickly spot changes before exploring detailed reports.&lt;/p&gt;</help>
</subcategory>
<widgets>
<row>
<name>AI Agents Over Time</name>
<module>AIAgents</module>
<action>getEvolutionGraph</action>
<order>1</order>
<parameters>
<forceView>1</forceView>
<viewDataTable>graphEvolution</viewDataTable>
<module>AIAgents</module>
<action>getEvolutionGraph</action>
</parameters>
<uniqueId>widgetAIAgentsgetEvolutionGraphforceView1viewDataTablegraphEvolution</uniqueId>
<isWide>0</isWide>
<viewDataTable>graphEvolution</viewDataTable>
<isReport>1</isReport>
</row>
<row>
<name>AI Agent Overview</name>
<module>AIAgents</module>
<action>get</action>
<order>2</order>
<parameters>
<forceView>1</forceView>
<viewDataTable>sparklines</viewDataTable>
<module>AIAgents</module>
<action>get</action>
</parameters>
<uniqueId>widgetAIAgentsgetforceView1viewDataTablesparklines</uniqueId>
<isWide>0</isWide>
<viewDataTable>sparklines</viewDataTable>
<isReport>1</isReport>
</row>
</widgets>
</row>
<row>
<uniqueId>General_Actions.VisitorInterest_Engagement</uniqueId>
<category>
Expand Down Expand Up @@ -6713,57 +6764,6 @@
</row>
</widgets>
</row>
<row>
<uniqueId>AIAgents_AIAssistants.General_Overview</uniqueId>
<category>
<id>AIAgents_AIAssistants</id>
<name>AI Assistants</name>
<order>80</order>
<icon>icon-admin-platform</icon>
<help />
<widget />
</category>
<subcategory>
<id>General_Overview</id>
<name>Overview</name>
<order>10</order>
<help>&lt;p&gt;The AI Assistant Overview page provide insights into website traffic originating from AI Assistants such as ChatGPT and other large language model–based assistants. These reports track key metrics including the number of requests made by these bots, the pages and documents they access, and any errors encountered. They also offer detailed breakdowns showing which bots visit specific page URLs, helping you understand how AI assistants interact with your content and identify opportunities to improve visibility and accessibility for AI-driven users.&lt;/p&gt;&lt;p&gt;It’s important to note that none of these pages were actually viewed by humans in the traditional way — all requests originate from AI assistants fetching content automatically.&lt;/p&gt;&lt;p&gt;Currently, these reports exclusively include requests from AI bots that do not execute JavaScript. They do not include traffic from AI crawlers used for training AI models or from AI agents capable of executing JavaScript.&lt;/p&gt;</help>
</subcategory>
<widgets>
<row>
<name>AI Agents Over Time</name>
<module>AIAgents</module>
<action>getEvolutionGraph</action>
<order>1</order>
<parameters>
<forceView>1</forceView>
<viewDataTable>graphEvolution</viewDataTable>
<module>AIAgents</module>
<action>getEvolutionGraph</action>
</parameters>
<uniqueId>widgetAIAgentsgetEvolutionGraphforceView1viewDataTablegraphEvolution</uniqueId>
<isWide>0</isWide>
<viewDataTable>graphEvolution</viewDataTable>
<isReport>1</isReport>
</row>
<row>
<name>AI Agent Overview</name>
<module>AIAgents</module>
<action>get</action>
<order>2</order>
<parameters>
<forceView>1</forceView>
<viewDataTable>sparklines</viewDataTable>
<module>AIAgents</module>
<action>get</action>
</parameters>
<uniqueId>widgetAIAgentsgetforceView1viewDataTablesparklines</uniqueId>
<isWide>0</isWide>
<viewDataTable>sparklines</viewDataTable>
<isReport>1</isReport>
</row>
</widgets>
</row>
<row>
<uniqueId>ExampleUI_UiFramework.ExampleUI_GetTemperaturesDataTable</uniqueId>
<category>
Expand Down
16 changes: 8 additions & 8 deletions tests/PHPUnit/System/expected/test_apiGetReportMetadata__API.getWidgetMetadata.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3651,18 +3651,18 @@
<row>
<name>AI Agents Over Time</name>
<category>
<id>AIAgents_AIAssistants</id>
<id>General_AIAssistants</id>
<name>AI Assistants</name>
<order>80</order>
<icon>icon-admin-platform</icon>
<help />
<widget />
</category>
<subcategory>
<id>General_Overview</id>
<name>Overview</name>
<id>AIAgents_AIAgentsOverview</id>
<name>AI Agents Overview</name>
<order>10</order>
<help>&lt;p&gt;The AI Assistant Overview page provide insights into website traffic originating from AI Assistants such as ChatGPT and other large language model–based assistants. These reports track key metrics including the number of requests made by these bots, the pages and documents they access, and any errors encountered. They also offer detailed breakdowns showing which bots visit specific page URLs, helping you understand how AI assistants interact with your content and identify opportunities to improve visibility and accessibility for AI-driven users.&lt;/p&gt;&lt;p&gt;It’s important to note that none of these pages were actually viewed by humans in the traditional way — all requests originate from AI assistants fetching content automatically.&lt;/p&gt;&lt;p&gt;Currently, these reports exclusively include requests from AI bots that do not execute JavaScript. They do not include traffic from AI crawlers used for training AI models or from AI agents capable of executing JavaScript.&lt;/p&gt;</help>
<help>&lt;p&gt;Review how AI agents and human visitors engage with your site at a glance. This overview surfaces combined metrics and trends so you can quickly spot changes before exploring detailed reports.&lt;/p&gt;</help>
</subcategory>
<module>AIAgents</module>
<action>getEvolutionGraph</action>
Expand All @@ -3681,18 +3681,18 @@
<row>
<name>AI Agent Overview</name>
<category>
<id>AIAgents_AIAssistants</id>
<id>General_AIAssistants</id>
<name>AI Assistants</name>
<order>80</order>
<icon>icon-admin-platform</icon>
<help />
<widget />
</category>
<subcategory>
<id>General_Overview</id>
<name>Overview</name>
<id>AIAgents_AIAgentsOverview</id>
<name>AI Agents Overview</name>
<order>10</order>
<help>&lt;p&gt;The AI Assistant Overview page provide insights into website traffic originating from AI Assistants such as ChatGPT and other large language model–based assistants. These reports track key metrics including the number of requests made by these bots, the pages and documents they access, and any errors encountered. They also offer detailed breakdowns showing which bots visit specific page URLs, helping you understand how AI assistants interact with your content and identify opportunities to improve visibility and accessibility for AI-driven users.&lt;/p&gt;&lt;p&gt;It’s important to note that none of these pages were actually viewed by humans in the traditional way — all requests originate from AI assistants fetching content automatically.&lt;/p&gt;&lt;p&gt;Currently, these reports exclusively include requests from AI bots that do not execute JavaScript. They do not include traffic from AI crawlers used for training AI models or from AI agents capable of executing JavaScript.&lt;/p&gt;</help>
<help>&lt;p&gt;Review how AI agents and human visitors engage with your site at a glance. This overview surfaces combined metrics and trends so you can quickly spot changes before exploring detailed reports.&lt;/p&gt;</help>
</subcategory>
<module>AIAgents</module>
<action>get</action>
Expand Down
4 changes: 2 additions & 2 deletions tests/UI/expected-screenshots/QuickAccess_search_1.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 2 additions & 2 deletions tests/UI/expected-screenshots/QuickAccess_search_2.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 2 additions & 2 deletions tests/UI/expected-screenshots/QuickAccess_search_sites.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
⚡