Setup

Steps 1 and 2 are required: without the snippet there is no data, without cron it never gets into the statistics. Everything else is optional.

1. Snippet in templates

Call the snippet in all site templates before the closing </body> tag. The call must be uncached. The second variant is for Fenom templates (pdoTools):

[[!Stats3x]]
{'Stats3x' | snippet}

The &replay=1 parameter enables session recording on pages with this call (see step 6).

A custom visitor action (category, action, label, number) is sent from any script on the page:

_st3x.e("form", "submit", "callback");

If the page code calls _st3x.e() before the snippet output, put a stub in <head>: the calls are queued and sent after the script loads.

<script>window._st3x=window._st3x||{q:[],e:function(){this.q.push(arguments)}};</script>

File downloads, outbound links, tel: and mailto: links and form submissions are tracked without any setup. Clicks on your own elements are set with CSS selectors in the stats3x.click_selectors setting.

2. Cron

Add a cron job that runs every minute as the site user (the same user PHP runs as):

* * * * * php /path/to/site/core/components/stats3x/cron.php > /dev/null 2>&1

Two copies never run at the same time: if the previous run is still working, the new one exits immediately. Whether cron works is shown on the State tab; if it has not run for longer than stats3x.cron_alert_minutes minutes, the component and the widget show a warning.

Run it manually to see what happens: -v - print progress, --task=parse - only these tasks (comma-separated), --force - all tasks now.

php /path/to/site/core/components/stats3x/cron.php -v --task=parse
php /path/to/site/core/components/stats3x/cron.php -v --force

Visit dates are recorded in the time zone from the date_timezone system setting, or from php.ini if it is empty. Set date_timezone (for example, Europe/London), otherwise days in the statistics will not start at midnight of your time.

3. Data folder

By default the data folder is here:

/path/to/site/core/components/stats3x/data/

The folder is inside the site root. In Apache it is closed by the .htaccess file the component creates itself. For nginx add a rule to the site configuration:

location ^~ /core/stats3x_data/ {
    deny all;
}

The component checks itself whether the folder is closed - see the State tab. It is safer to move the folder outside the site root: set the new path in the stats3x.data_path system setting.

4. Geography (optional)

To detect the visitor country, region and city, you need the free IP2Location LITE databases. Without them the statistics work, only geography stays empty. How to connect:

1. Sign up for free: ip2location.com/register?id=lite. The free databases page: ip2location.com/database/lite.
2. Log in to your account, open the Download section and copy the Download Token.
3. Paste the token into the stats3x.geo_token system setting. The cron task "IP2Location databases update" downloads the database into core/components/stats3x/geo_ip/ within an hour and then updates it once a month. By default it is DB11LITEBINIPV6: country, region, city, coordinates and time zone for IPv4 and IPv6 in one file. To download right away: php core/components/stats3x/cron.php --task=geo -v
4. Or manually: in the Download section get IP2LOCATION-LITE-DB11.IPV6.BIN.ZIP (DB11.BIN - IPv4 only), unpack the .BIN file into the folder from the stats3x.geo_ipv4_path and stats3x.geo_ipv6_path settings (core/components/stats3x/geo_ip/ by default) and update it once a month.

The databases weigh hundreds of megabytes and are not included in the component: one folder can serve several sites if open_basedir allows it. Do not put them in the site root - they could be downloaded from there. Whether a database is found is shown on the State tab.

5. Goals (optional)

Goals are set up on the Goals tab: page visit, element click, form submission or a custom action. Conversions are counted when the data is parsed, starting from the moment the goal is created. Details and examples are in the Goals subtab of this documentation. For an action with a value pass a number as the fourth argument - it becomes the conversion value:

_st3x.e("order", "paid", "", 2500);

6. Session recording (optional)

Enable the stats3x.replay_enabled setting and call the snippet with the replay parameter on the pages you want to record. The share of recorded visits is the stats3x.replay_sample setting. Recordings and the click map are available to users with the stats3x_replay permission on the Recordings tab. If the site images and styles are on a CDN, add its domain to stats3x.replay_hosts, otherwise the player will not show them.

[[!Stats3x? &replay=`1`]]

Session recordings are personal data of visitors: mention them in your privacy policy. Field input is hidden by the stats3x.replay_mask_inputs setting, passwords always. Mark a block that must not be recorded (for example, personal data in an account area) with the st3x-block class, and text with the st3x-mask class.

7. Site behind a proxy or CDN

If Cloudflare, another CDN or nginx in front of Apache stands before the site, REMOTE_ADDR contains the proxy address and all visitors look like one IP: geography and IP exclusion stop working. Set the header with the real visitor address in stats3x.ip_header (CF-Connecting-IP for Cloudflare) and the proxy addresses in stats3x.ip_proxies (empty - trust only internal addresses: the same server and the local network). Without a proxy leave both settings empty: any visitor can forge the header.

8. Access permissions

The component permissions are in the Stats3xUserPolicy access policy: stats3x_view - view statistics, stats3x_save - goals and sending the email report, stats3x_remove - delete goals and recordings, stats3x_replay - session recordings and the click map. On installation the policy is assigned to the Administrator group in the mgr context if it has not been assigned to anyone yet. Sudo users do not need the permissions.

To open the statistics to another manager group: Access Control Lists → User Groups → the group → Access Permissions → Context Access → add the mgr context with the Stats3xUserPolicy policy. If this group should not see session recordings, create your own policy on the Stats3xUserPolicyTemplate template without the stats3x_replay permission. After changing permissions managers need to log in again or clear the cache.

9. Email reports (optional)

A traffic report once a day, week or month is sent via the Vestnik component. How to set it up - see the Email reports tab of this documentation.