README

xrowpiwik connects an Exponential site to a Piwik web analytics server. Piwik is the open source analytics platform that is known as Matomo today. Because the visitor data stays on a server you run yourself, it is a privacy-friendly alternative to hosted analytics services, and it was originally written as an alternative to eZ Odoscope.

The extension does three things:

Tracks page views. It adds the Piwik JavaScript tracker and a small tracking snippet to the public site's script bundle (through ezjscore), so every page view is sent to your Piwik server. Up to four Piwik sites can be tracked per page.
Shows your statistics in the admin. It adds an xrow Piwik tab, with a bar chart icon (bar-chart-line), to the admin top menu. The tab opens your Piwik dashboard inside the admin interface.
Optionally records clicks for heat maps. The click_tracker() template operator writes the script for the Piwik ClickHeat plugin.

It is meant for site administrators who already run, or want to run, their own Piwik or Matomo server and want the statistics next to their content.

Requirements
Installation
Setting up the Piwik server
Configuration
Usage
Permissions
Cron jobs
Upgrading
Known limits
Troubleshooting
Contributing
License
Credits and history

Requirements

Exponential 6.x (legacy kernel) on PHP 8.0 or later.
The ezjscore extension, active. It ships with Exponential and delivers the tracking script.
jQuery on the public site's pages. The tracking snippet and the ClickHeat snippet run inside jQuery(document).ready() and do nothing without it.
A Piwik or Matomo server reachable over HTTPS by your visitors. See Setting up the Piwik server.

Installation

With Composer

From the root of your Exponential installation:

composer require se7enxweb/xrowpiwik

The package type is ezpublish-legacy-extension, so the installer (se7enxweb/ezpublish-legacy-installer) places it in extension/xrowpiwik.

If Composer reports that it cannot find the package, add the GitHub repository first and run the same command again:

composer config repositories.xrowpiwik vcs https://github.com/se7enxweb/xrowpiwik
composer require se7enxweb/xrowpiwik

By hand

Download the latest release or clone the repository, and put it in extension/xrowpiwik:

cd /path/to/exponential
git clone https://github.com/se7enxweb/xrowpiwik.git extension/xrowpiwik

Activate the extension

Both installation methods need these steps.

Activate the extension in settings/override/site.ini.append.php:

[ExtensionSettings]
ActiveExtensions[]=ezjscore
ActiveExtensions[]=xrowpiwik

Regenerate the extension autoloads, so the xrowPiwikServerCallFunctions class is found:
```
php bin/php/ezpgenerateautoloads.php -e
```
Clear the caches:
```
php bin/php/ezcache.php --clear-all
```
Configure the server address (next sections), then clear the INI and template caches again:
```
php bin/php/ezcache.php --clear-tag=ini
php bin/php/ezcache.php --clear-tag=template
```

Setting up the Piwik server

xrowpiwik does not contain Piwik itself. The repository only carries the Piwik JavaScript tracker (src/piwik/piwik.js), which it sends to the browser. You need a Piwik or Matomo server; there are two ways to run one.

A separate Matomo server (recommended)

Install a current Matomo on its own host name, for example https://stats.example.com, by following the Matomo installation guide. Create one website in Matomo for each site you want to track and note its site ID (Administration, Websites, Manage). Then set URL in xrowpiwik.ini (see below) to the server's address.

This keeps the analytics software and its updates apart from your Exponential installation, and works for every feature except ClickHeat.

Piwik inside the extension (the original setup)

The extension was first written for a Piwik installed in extension/xrowpiwik/src/piwik/, served by the same web server as the site. This setup is needed for ClickHeat, whose script address is fixed to https://<your host>/extension/xrowpiwik/src/piwik/plugins/ClickHeat/libs/click.php. The files kept from that setup are:

settings/config.ini.append.php: a template for Piwik's own config/config.ini.php (it is a Piwik file, not an Exponential INI file). Its database and super user values are placeholders: change all of them before you use it.
doc/mysql_schema/xrowpiwik_clean.sql: an empty database for Piwik 1.8.4, the version of the original setup.

The steps of the original setup were:

# 1. Put Piwik in extension/xrowpiwik/src/piwik/ and let the web server serve it:
#    Apache:  RewriteRule ^extension/xrowpiwik/src/piwik/.* - [L]
#    IIS:     <add input="{URL}" pattern="extension/xrowpiwik/src/piwik/" ignoreCase="false" />

# 2. Create Piwik's writable directories
mkdir -p extension/xrowpiwik/src/piwik/tmp/{assets,cache,tcpdf,templates_c}
mkdir -p extension/xrowpiwik/src/piwik/tmp/cache/tracker

# 3. Link your own Piwik configuration into place
ln -s ../../../../../settings/override/config.ini.append.php \
      extension/xrowpiwik/src/piwik/config/config.ini.php

# 4. Load the database and bring it up to the installed Piwik version
mysql piwik < extension/xrowpiwik/doc/mysql_schema/xrowpiwik_clean.sql
php extension/xrowpiwik/src/piwik/console core:update

Make the tmp directories writable by the web server user only (for example with chown -R www-data extension/xrowpiwik/src/piwik/tmp); the older instructions used chmod 777, which lets every user on the host write there.

src/HowtoinstallPiwik.html forwards to the Piwik installation documentation.

Configuration

All settings live in xrowpiwik.ini. Override them in settings/override/xrowpiwik.ini.append.php (or in a siteaccess's settings directory to use different values per siteaccess):

<?php /* #?ini charset="utf-8"?

[General]
# Address of your Piwik or Matomo server, without a trailing slash. Required.
URL=https://stats.example.com

# The Piwik site ID that click_tracker() records clicks for.
PiwikSiteID=1

# enabled: the trackers do not set cookies (disableCookies()).
DisableCookies=enabled

# enabled: click_tracker() writes the ClickHeat script.
ClickHeatTracking=disabled

[ClickHeatSettings]
# Which devices ClickHeat records: all, or a comma separated list of
# desktop, tablet and mobile.
DoTrackingFor=all

*/ ?>

Setting	Read by	What it does
`[General] URL`	admin view, tracking script	The Piwik server. The admin tab shows this address in a frame; the tracker sends page views to `<URL>/piwik.php`.
`[General] PiwikSiteID`	`click_tracker()`	The site ID ClickHeat records clicks for. It must be a number, or `click_tracker()` writes nothing.
`[General] DisableCookies`	tracking script	`enabled` turns off tracking cookies for every tracker on the page. Useful where cookie consent is required.
`[General] ClickHeatTracking`	`click_tracker()`	`enabled` writes the ClickHeat script; anything else writes nothing. Default `disabled`.
`[ClickHeatSettings] DoTrackingFor`	`click_tracker()`	`all` (default), or `desktop` (window wider than 1109 px), `tablet` (600 to 1109 px), `mobile` (up to 599 px), or two of them separated by a comma.

The extension's own settings files also register what it needs, so you do not have to: the module (module.ini), the admin tab and its icon (menu.ini), the ezjscore server function (ezjscore.ini [ezjscServer_xrowpiwik]), the tracking script in design.ini [JavaScriptSettings] FrontendJavaScriptList[]=xrowpiwik::doPiwikTrack, the template operator (site.ini [TemplateSettings] ExtensionAutoloadPath[]) and the cron job part (cronjob.ini).

The sections [SecondPiwikID], [ThirdPiwikID] and [IndexPiwikID] in the default xrowpiwik.ini are commented examples only: no code reads them. The site IDs come from the page's <body> element instead (next section).

Usage

1. Track page views

The tracking script is added to the public site's script bundle by FrontendJavaScriptList[]=xrowpiwik::doPiwikTrack. A pagelayout that loads the frontend scripts with ezjscore, for example

{ezscript_load( ezini( 'JavaScriptSettings', 'FrontendJavaScriptList', 'design.ini' ) )}

gets it automatically. The script tracks a page only for the site IDs it finds on the <body> element, so tell it which Piwik site the page belongs to:

<body data-piwikmainid="1">

Up to four trackers can run on one page, each with its own Piwik site ID:

`<body>` attribute	Typical use
`data-piwikmainid`	The main site.
`data-piwikID`	A second site, for example a section of the site with its own statistics.
`data-piwik3ID`	A third site.
`data-piwikIndexID`	A site for the home page only.

Each attribute must be a number greater than 0; a missing or empty attribute is skipped. A pagelayout can set them from your own settings or from the current node, for example:

{def $piwik_section_id = cond( eq( $module_result.section_id, 6 ), 3, 0 )}
<body data-piwikmainid="1"{if $piwik_section_id} data-piwikID="{$piwik_section_id}"{/if}>

Open a page of your site, then the Visitors, Real-time (Live) view in Piwik: the visit appears within a few seconds.

2. See the statistics in the admin

Sign in to the admin interface. The top menu shows the xrow Piwik tab with its bar chart icon. It opens xrowpiwik/xrowpiwik, which shows the address in [General] URL in a frame (98% wide, 780 px high). Sign in to Piwik there once; the browser keeps the Piwik session.

The Piwik server must allow being shown in a frame on the admin's host name. In Matomo this is the enable_framed_pages and related settings of its config.ini.php; a Content-Security-Policy or X-Frame-Options header on the Piwik server can also block it.

3. Record clicks for heat maps (optional)

ClickHeat needs Piwik inside the extension with its ClickHeat plugin (see the original setup).

Create the plugin's cache directories:

mkdir -p extension/xrowpiwik/src/piwik/tmp/cache/clickheat/{cache,logs}

Make the plugin's script available to the design and add it to the frontend scripts:

ln -s ../../../src/piwik/plugins/ClickHeat/libs/js/clickheat.js \
      extension/xrowpiwik/design/standard/javascript/clickheat.js

# design.ini.append.php
[JavaScriptSettings]
FrontendJavaScriptList[]=clickheat.js

Set ClickHeatTracking=enabled and a numeric PiwikSiteID in xrowpiwik.ini.
Put the operator just before </body> in your pagelayout:
```
{click_tracker()}
</body>
```
It writes a script that starts ClickHeat with the site ID, the current siteaccess name as the ClickHeat group (so each siteaccess gets its own heat map), a quota of 3 clicks per page and the address https://<host>/extension/xrowpiwik/src/piwik/plugins/ClickHeat/libs/click.php.

On a cluster, keep the ClickHeat logs on storage every node can read, for example:

mkdir /nfs/site/clickheat
ln -s /nfs/site/clickheat extension/xrowpiwik/src/piwik/tmp/cache/clickheat

Permissions

The module xrowpiwik has one policy function:

Module	Function	Gives access to
`xrowpiwik`	`xrowpiwik`	The `xrowpiwik/xrowpiwik` view (the admin tab).

Give it to an editor role in the admin under Setup, Roles and policies: edit the role, add a policy for the module xrowpiwik, function xrowpiwik. Administrators with all rights have it already. The tab itself is shown to every admin user; users without the policy get an access denied page when they open it.

The tracking script and click_tracker() need no permission.

Cron jobs

The extension registers a cron job part named archivepiwik (cronjobs/archivepiwik.php):

php runcronjobs.php archivepiwik

It was written for the original setup and runs Piwik's old misc/cron/archive.sh from ezpublish_legacy/extension/xrowpiwik/src/piwik, using the shell's PWD and HOSTNAME. It also makes Piwik's tmp/climulti directory writable for everybody. For a separate Matomo server, or a current Piwik inside the extension, use Matomo's own archiving instead:

# crontab of the web server user, every hour
5 * * * * php /path/to/matomo/console core:archive --url=https://stats.example.com/ > /dev/null

See How to set up auto-archiving.

Upgrading

With Composer: composer update se7enxweb/xrowpiwik. By hand: replace the extension/xrowpiwik directory with the new release, keeping your own files under src/piwik/ if Piwik lives there.
Then regenerate the autoloads and clear the caches as in Activate the extension.
Your settings in settings/override/ are not touched.

Release notes are in CHANGELOG.md.

Known limits

The bundled src/piwik/piwik.js is an older Piwik tracker. It works with current Matomo servers, which still accept piwik.php requests, but it does not have the newest tracker features.
The tracking snippet and click_tracker() need jQuery on the page.
DoTrackingFor=desktop,mobile records nothing: its condition (wider than 1109 px and narrower than 600 px) can never be true. Use all, or one device per setting.
click_tracker() always uses https:// and the current host name for the ClickHeat address, and ClickHeat only works with Piwik inside the extension.
The archivepiwik cron job assumes the original directory layout (see Cron jobs).
design/standard/templates/xrowpiwik/showxrowpiwik.tpl is left over from another project and is not used by any view.

Troubleshooting

No visits arrive in Piwik. Check in the browser's developer tools that the packed frontend script contains Piwik.getTracker, and that a request goes to <URL>/piwik.php. If the script is missing, clear the caches (php bin/php/ezcache.php --clear-all) and check that your pagelayout loads FrontendJavaScriptList. If no request is sent, check that <body> has data-piwikmainid with a number greater than 0 and that jQuery is loaded.

The admin tab is blank or says the page refused to connect. The Piwik server does not allow being framed (see See the statistics in the admin), URL is empty, or the admin is on HTTPS while URL uses HTTP.

The tab has no icon. The icon is drawn by the admin4 design. Other admin designs show the name only. Clear the INI cache (php bin/php/ezcache.php --clear-tag=ini) after an upgrade.

click_tracker() writes nothing. ClickHeatTracking must be enabled and PiwikSiteID must be a number.

"Class xrowPiwikServerCallFunctions not found" in the error log. Regenerate the autoloads: php bin/php/ezpgenerateautoloads.php -e.

Contributing

Bug reports and pull requests are welcome at https://github.com/se7enxweb/xrowpiwik/issues. Please describe the Exponential and PHP version you use, and test a change with a page view in Piwik before you send it.

License

GNU General Public License v2.0. See LICENSE.txt.

The Piwik JavaScript tracker in src/piwik/piwik.js is licensed by its authors under the BSD-3-Clause license, as its header states.

Credits and history

First published in 2012 for eZ Publish, the content management system that Exponential grew out of, by xrow GmbH (with code from Vincentz Network), and maintained by xrow GmbH until 2017 (releases up to 1.3.5).
Maintained by 7x for Exponential, starting with 1.3.6.

se7enxweb / xrowpiwik

Package info

Security

Fund package maintenance!

Statistics