TYPO3 Analytics Extension 

Encryption 

Credentials are encrypted using XChaCha20-Poly1305 via libsodium. On TYPO3 v14+ the built-in TYPO3\CMS\Core\Crypto\Cipher\CipherService is used automatically; on v13 an equivalent custom implementation is used, ensuring values remain decryptable after an upgrade.

Content Security Policy 

The extension automatically extends the backend CSP (frame-src) to allow the analytics dashboard to be embedded as an iframe inside the TYPO3 backend. The production dashboard origin is always included:

Additional origins can be added via the additionalFrameSrc extension setting without touching the code — see API settings.

Module icon 

Two icon variants are shipped and selected automatically at runtime based on the installed TYPO3 version:

API settings 

Appearance settings 

Development settings 

Dashboard settings 

Example — custom period options:

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['analytics']['dashboardPeriods'] = '7,30,90';
$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['analytics']['dashboardDefaultPeriod'] = 30;

Backend module — Sites → Analytics 

Registered as site_analytics (route prefix site_analytics.*). Visible in the Sites section of the backend module menu.

The module offers per-site views for:

• Registration — enter an e-mail address to register a site with the TYPO3 Analytics API.
• Status — shows registration status, website ID and API key, with a manual refresh button.
• Dashboard — embeds the TYPO3 Analytics web dashboard as an iframe.

The registration form, plan management button, and status refresh button are only visible to backend administrators and users who hold the Analytics Manager custom option (see Access control below).

Dashboard widgets 

The extension registers four dashboard widget types, each available in a TYPO3 v13 variant (inline dropdowns, AJAX-driven) and a TYPO3 v14+ variant (native widget settings panel).

All v14+ widgets share two common settings in addition to their widget-specific ones:

Traffic Sources widget 

Displays a breakdown of incoming traffic by channel, browser, device type, or country. Each entry shows a label, share as a percentage, and a horizontal progress bar. Channel and channel entries also display a trend indicator compared to the previous period. Entries outside the top results are aggregated into an "Others" row.

The two TYPO3 version variants differ significantly in how sections are displayed:

v13 — TrafficSourcesWidget / dashboard.widget.analyticsTrafficSources / ^13.4

All four sections (Channel, Devices, Browser, Countries) are rendered inside a single widget, stacked vertically. Site and period are selected via inline dropdowns; the chart is always a progress-bar list. No chart-type configuration is available.

AJAX endpoint: TrafficSourcesAjaxController — registered as backend route analytics_traffic_sources_content.

v14+ — TrafficSourcesWidgetV14 / ^14.0

A DI compiler pass registers four separate widget types, one per section, each with a fixed section and a pre-configured default chart type. The section cannot be changed by the user at runtime.

Widget ID	Section	Default chart type
dashboard.widget.analyticsTrafficSourcesChannel	Channel	list
dashboard.widget.analyticsTrafficSourcesDevices	Devices	donut
dashboard.widget.analyticsTrafficSourcesBrowser	Browser	donut
dashboard.widget.analyticsTrafficSourcesCountries	Countries	list

Channel	Browser	Devices	Countries

Widget settings (v14+):

Setting	Type	Default	Description
Site	string	first registered site	Site to display data for.
Period	int	dashboardDefaultPeriod	Time window in days.
Chart type	enum	(per widget)	Display as list (progress bars) or donut (SVG donut chart, top 5 + aggregated "Other").

Plus the common settings above.

Page Performance Bar 

An event listener (PagePerformanceBarListener) on ModifyPageLayoutContentEvent that injects an analytics bar above the page content in the Page module.

The bar loads asynchronously: on page render, only a lightweight skeleton with a loading spinner is injected into the page header. The JavaScript in page-performance.js then fetches the actual analytics data via AJAX (PagePerformanceAjaxController, route analytics_page_performance_content) and replaces the skeleton with the fully rendered bar.

The bar shows per-page metrics for the currently viewed page:

• Page views with sparkline and trend
• Bounce rate with sparkline and trend
• Average time on page with sparkline and trend
• Continuation rate (100 − bounce rate) with sparkline and trend

A period selector (values from dashboardPeriods) and a link to the full site analytics dashboard are included. The bar is hidden in language-comparison mode (viewMode = 2).

Dashboard preset 

The extension ships a ready-made Analytics Overview dashboard preset (analyticsOverview) that can be selected when creating a new TYPO3 dashboard. It pre-populates the dashboard with all four widget types:

• Traffic Graph
• Site Performance
• Top Pages
• Traffic Sources (channel, devices, browser, countries — one widget per section)

The preset is registered in Configuration/Backend/DashboardPresets.php and shown in the dashboard creation wizard (showInWizard: true).

Access control 

The Sites → Analytics module is accessible to all backend users. However, the following actions are restricted to administrators and users who hold the tx_analytics:manager custom option:

• Registering a new site with the Analytics API
• Subscribing to or managing a plan
• Manually refreshing the registration status

The custom option is configured via Backend Groups → Custom Options → Analytics → Analytics Manager (TCA value: tx_analytics:manager).

Prerequisites 

• DDEV installed
• Docker running

Start the environment 

ddev start

On first start DDEV automatically runs the setup script. You will be prompted to choose the TYPO3 major version:

TYPO3 version to install (13/14) [13]:

The script will:

1. Create a fresh TYPO3 project in .Build/dummy-typo3/ using typo3/cms-base-distribution
2. Drop and recreate the database for a clean slate
3. Require and symlink this extension from the repository root
4. Run vendor/bin/typo3 setup non-interactively
5. Create five root pages (Site 1–5)
6. Write site configurations for five subdomains
7. Remove the FIRST_INSTALL flag so the backend is immediately accessible

Available URLs after setup 

Backend credentials: admin / Admin1234!

Re-run setup manually 

ddev exec composer dummy-typo3

Reset everything 

# Remove the dummy installation (keeps DDEV containers)
rm -rf .Build/dummy-typo3

# Then restart — setup runs automatically
ddev restart

Code quality 

# PHP CS Fixer (dry-run)
composer t3g:cgl

# PHP CS Fixer (fix)
composer t3g:cgl:fix

# PHPStan
composer t3g:phpstan

# Rector (dry-run)
composer t3g:rector:dry-run

# Rector (apply)
composer t3g:rector:fix

Tests 

# All tests
composer t3g:test

# Unit tests only
composer t3g:test:unit

# Functional tests (SQLite, no external DB required)
composer t3g:test:functional

Unit tests use the TYPO3 testing framework with an in-process bootstrap. Functional tests use SQLite via pdo_sqlite — no external database server is required.

TYPO3 v13 

• ext_emconf.php is required and evaluated by TYPO3.
• The custom sodium-based cipher is used for credential encryption.
• Module access is controlled via 'access' => 'user'.
• The Material Design icon (Extension-v13.svg) is used automatically.

TYPO3 v14 

• ext_emconf.php is deprecated (Feature #108345). Extension metadata is read from composer.json (extra.typo3/cms).
• The built-in TYPO3\CMS\Core\Crypto\Cipher\CipherService is used automatically.
• Module access uses the gate-registry pattern; 'user,group' is no longer valid — 'user' is used instead.
• The adaptive theme icon (Extension.svg) is used automatically.