Download the PHP package t3g/analytics without Composer

TYPO3 Analytics Extension

A TYPO3 backend extension that integrates TYPO3 Analytics into the TYPO3 site management panel. It lets editors register TYPO3 sites with the TYPO3 Analytics API, monitor registration status, and open the analytics dashboard — all without leaving the TYPO3 backend.

Contents

• Requirements
• What the extension does
• Installation
• Configuration reference
  • Development settings
  • Dashboard settings
• Modules and widgets
  • Backend module — Sites → Analytics
  • Dashboard widgets
  • Page Performance Bar
  • Dashboard preset
  • Access control
• Local development with DDEV
• Compatibility notes

Requirements

What the extension does

The extension adds a Sites → Analytics module to the TYPO3 backend. For each configured TYPO3 site it provides:

• Registration — enter an e-mail address and register the site with the TYPO3 Analytics API.
• Status display — shows the current analytics status fetched via HMAC-authenticated API calls (cached for 24 h, manually refreshable).
• Dashboard — opens the TYPO3 Analytics dashboard as an embedded iframe inside the TYPO3 backend.
• Tracking code injection — once a site is registered, the TYPO3 Analytics tracking script is automatically injected into every frontend HTML response for that site.

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.

Module icon

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

Installation

Composer (recommended)

Activate the extension in the TYPO3 Extension Manager or via:

TER / Classic mode

In a non-Composer TYPO3 installation, search for analytics in Admin Tools → Extensions and install it from there. Make sure the Dashboard system extension is active before installing.

Deployment note

Site-specific data written by the extension (credentials, tracking code, API keys) is stored in each site's config/sites/<identifier>/settings.yaml. This file contains sensitive values and must not be committed to the repository. In a deployment setup, keep settings.yaml in a shared folder outside the release directory and symlink or copy it on each deploy.

Configuration reference

Development settings

Dashboard settings

Example — custom period options:

Cache settings

Example — longer cache lifetime:

Modules and widgets

Backend module — Sites → Analytics

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

The module overview page shows:

• Plans — a responsive card grid of all available Analytics plans, loaded via AJAX. Each card shows the plan name, price (monthly / yearly toggle), credit volume, API access, and custom-dashboard availability. A Custom plan card is always appended at the end with a "Contact us" button for enterprise inquiries.
• Active / inactive sites — all configured TYPO3 sites grouped by registration status.

Per-site views offer:

• 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:

Top Pages widget

Displays a ranked list of the most-visited pages for a configured site. Each row shows the page title, URL, and view count. Results are sorted by page views descending; a configurable limit controls how many rows are shown. A "Show all" link leads to the pages view of the analytics dashboard.

Widget settings (v14+): Site, Period (days), Limit (number of pages shown), plus the common settings above.

AJAX endpoint (v13): TopPagesAjaxController — registered as backend route analytics_top_pages_content.

Site Performance widget

Displays four colored metric tiles for a configured site — Visits, Visitors, Bounce rate, and Avg. visit duration — each showing the current value and a trend arrow compared to the previous period of equal length.

Widget settings (v14+): Site, Period (days), plus the common settings above.

AJAX endpoint (v13): SitePerformanceAjaxController — registered as backend route analytics_site_performance_content.

Traffic Graph widget

Displays a full-width line chart of daily visit counts for a configured site over the selected period. The chart makes traffic trends immediately visible — spikes, dips, and patterns across the chosen date range. A "Show all" link opens the main analytics dashboard.

Widget settings (v14+): Site, Period (days), plus the common settings above.

AJAX endpoint (v13): TrafficGraphAjaxController — registered as backend route analytics_traffic_graph_content.

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 settings (v14+):

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).

Local development with DDEV

The repository ships a fully automated DDEV environment that spins up a dummy TYPO3 installation with five sub-domain sites.

Prerequisites

• DDEV installed
• Docker running

Start the environment

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

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

Reset everything

Documentation preview

The ddev-typo3-docs add-on renders the .rst files in Documentation/ with the same renderer used by docs.typo3.org. It starts automatically with ddev start/ddev restart and watches for changes.

Open https://analytics.ddev.site:1337 and edit files under Documentation/ — the preview re-renders automatically on save.

Code quality

Tests

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.

Compatibility notes

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.