DEPRECATION WARNING

This documentation is not using the current rendering mechanism and is probably outdated. The extension maintainer should switch to the new system. Details on how to use the rendering mechanism can be found here.

EXT: Statistics

Author:Christian Bülter
Created:2009-10-20T14:14:05.620000000
Changed by:Christian Bülter
Changed:2013-04-08T17:28:14
Email:buelter@kennziffer.com
Info 2:
Info 3:
Info 4:

EXT: Statistics

Extension Key: ke_stats

Copyright 2007-2011, Christian Bülter, < buelter@kennziffer.com >

This document is published under the Open Content License

available from http://www.opencontent.org/opl.shtml

The content of this document is related to TYPO3

- a GNU/GPL CMS/Framework available from www.typo3.com

Table of Contents

EXT: Statistics 1

Introduction 1

Screenshots 2

Installation / Quickstart 3

How to analyze visits 3

Backend module documentation 3

Configuration 3

Frontend Extension Support 5

API 6

File access counting 7

FAQ 8

Known problems 9

To-Do list 9

Changelog 9

Credits 12

Introduction

This extension provides statistics for TYPO3.

Main features are:

  • Supports Extension statistics. Support for tt_news, ke_troubletickets, ke_yac, and commerce is built in. Easy to adapt for other extensions. To make this clear: You not only know how often a singleview-page has been called, but also how often a certain news- element or shop-product has been viewed.
  • Integrates well into TYPO3: Supports frontend users, different languages and page types.
  • Detailed reports for each page and subpages.
  • Adaptable for other extension by typoscriptand PHP-API.

More Features:

  • Counts pageviews and visits for TYPO3 pages.
  • Counts search engines, search words, browsers, operating systems etc.
  • Shows a live visitor tracking (disabled by default for performance reasons).
  • Does not count if a backend user is logged in (configuration option).
  • Counts correctly even if you use a TYPO3 page as a ajax page. (That means, that these pages aren't counted.)
  • Chart rendering (at least for the overview page at the moment).
  • Can count file accesses.

Since Version 1.1.1 PHP 5.3 is required since it is compatible with TYPO3 6.0 and makes use of the namespacing feature.

Screenshots

img-1

Overview Page

img-2

List of robots

Installation / Quickstart

Step 1

Search for “ke_stats” in the extension manager and install the extension.

Step 2

Go to you main typoscript template and insert the plugin into the page header like this:

page.headerData.100 < plugin.tx_kestats_pi1

*Note: This assumes, that your page object is called “page”, that means, that you have a line “page = PAGE” in your template. If you use an other name, you have to change it in the configuration accordingly. The “100” ist randomly picked. Of course, you may change this number.*

*Note: There's a bug in TYPO3 6.0, please see “Known Problems” in this document.*

You're done.

The extension should be up and running.

How to analyze visits

A word on visits:

A visit is counted on the page the visitor first appears. So if you want a qualified number of how many visitors you have, you should always select your homepage in the pagetree.

For pageviews you may also select subpages of your pagetree if you want to analyze only the pageviews of certain subtrees.

Backend module documentation

You can find a german documentation of the backend module here:

http://www.kennziffer.com/typo3howto/extensions/statistik/

Configuration

The main configuration is done in the extension manager. Some things can be configured via typoscript.

Options in the extension manager:

Use Caching in backend module (Default: true)

Caching speeds up displaying your statistics tables, but can lead to a really big cache table on bigger sites. If that happens, you may want to disable caching.

enableIpLogging, enableTracking (Default: false)

In the extension manager you may enable IP-Logging and Live-Tracking. These options are disabled by default (IP-Logging for legal reasons, tracking for performance reasons). Just go to the extension manager and click on the name of the extension. Then you may enable these options by activating the checkboxes.

IgnoreBackendUsers (Default: true)

If set, ke_stats doesn't count count visits, pageviews ect. of a logged in backend user.

asynchronousDataRefreshing (Default: false)

This is a bit more complicated. Normally, the results table gets updated on each page view. If the table gets bigger (on big websites or after years of usage), this may slow down your website.

If you activate asynchronousDataRefreshing, the statistical informatione will be stored in a queue and the results table will get updated afterwards (asynchronous.)

To activate this, enable the option in the extension manager and set up a cronjob which calls typo3conf/ext/ke_stats/cli/update.cli.php every five minutes or so.

Since version 1.1.2 you can simply use a simple scheduler task to automatically update the statistics table.

For the cronjob the following things are important:

  • the file update.cli.php has to be executable
  • a backend user _cli_kestats must exist (without admin rights or any special rights, the password doesn't matter)
  • the script must be called by it's absolute path. If you expierence problems with this, set the constant PATH_thisScript manually in the script update.cli.php.
  • The script expects php in /usr/bin/php, if your php binary file is somewhere else, you will have to adapt the first line of the script.

If asynchronousDataRefreshing is enabled, you will see an information about until when the results table has been updated below each table in the backend module.

IgnoreRobots (Default: false)

On big sites, robots cause a lot of traffic resulting in a big statistics table. You may want not to include them in your statistics in order to reduce database size.

logfileDir (Default:empty)

If set to a directory (e.g. "fileadmin/ke_stats_log/"), ke_stats writes a logfile for each day. This option is mainly for debugging purposes and should normally be empty.

Page where to count file accesses (Default: empty)

If you use ke_stats to count file accesses, the date will be written to the page uid you define here.

Typoscript options:

Example, You may disable page statistics like this:

plugin.tx_kestats_pi1.enableStatisticsPages = 0

Available options for the typoscript setup are:

Option

a

Option

b

Description

c

default

enableStatisticsPages

a

enableStatisticsPages

b

Disable or enable page statistics

c

1

enableStatisticsExtensions

a

enableStatisticsExtensions

b

Disable or enable extension statistics

c

1

ignorePages

a

ignorePages

b

Comma-separated list of pages to ignore in the statistics.You should use this option for your “404”-page.

There are bots out there which look like a browser but aren't. So you at least don't count them on all the pages which are not existent. And even more important: Depending on the setting of $TYPO3_CONF_VARS['FE']['pageNotFound_handling'], TYPO3 reads the 404 page internally. In this case, this is counted as pageview.

c

maxRefererNameLength

a

maxRefererNameLength

b

Maximum length of the referer string

c

50

Frontend Extension Support

Support for tt_news is already built in. You may adapt the statistics to other extensions using this configuration as an example:

plugin.tx_kestats_pi1 {

# format: registerExtension.EXTENSIONKEY = EXTENSIONNAME

registerExtension.tt_news = News

# name of the table

# the table has to be defined in TCA (all tables in TYPO3 normally are)

registerExtension.tt_news.table = tt_news

# name of the db field containing the title of the element

registerExtension.tt_news.titleField = title

# name of the db field containing the uid of the element

registerExtension.tt_news.uidField = uid

# name of the db field containing the pid of the element

registerExtension.tt_news.pidField = pid

# GET-parameter given in the frontend to display the singleview of the element

registerExtension.tt_news.uidParameter = tt_news

# wrap the uidParameter into this piVar array name

# example for tt_news: index.php?id=99&tx_ttnews[tt_news]=99

registerExtension.tt_news.uidParameterWrap = tx_ttnews

}

Important: Make sure, that you enter this code BEFORE you insert the plugin into your page, that means before you enter the line found above under Installation.

API

You may call ke_stats from your own extensions and count whatever you like, for example calls to AJAX-functions.

This is how it works:

$keStatsObj = t3lib_div::getUserObj('EXT:ke_stats/pi1/class.tx_kest ats_pi1.php:tx_kestats_pi1');

$keStatsObj->initApi();

$keStatsObj->increaseCounter($category,$compareFieldList,$element_tit le,$element_uid,$element_pid,$element_language,$element_type,$stat _type,$parent_uid);

unset($keStatsObj);

Explanation:

  • $category: string, your choice, the tab in the backend module will be named like this
  • $compareFieldList: normaly it is 'element_uid,year,month'
  • $element_title: Single element title
  • $element_uid: Should be clear, uid of your element you want to count
  • $element_pid: Should be clear, pid of your element you want to count
  • $element_language: integer according to sys_language_uid
  • $element_type: for example page type, should be 0 for extensions
  • $stat_type: should be 'extension' for extensions
  • $parent_uid: can be empty, default is 0
  • $additionalData: Only need if you invoke a custom hook.
  • $counter: By what number should the statistic counter be increased? Default is 1.

Example (last three parameters left out), fill in at least something for “My on extension” and the two “myData”-values:

if (t3lib_extMgm::isLoaded('ke_stats')) {

$keStatsObj = t3lib_div::getUserObj('EXT:ke_stats/pi1/class.tx_kest ats_pi1.php:tx_kestats_pi1');

$keStatsObj->initApi();

$keStatsObj->increaseCounter('My own extension','element_uid,year,mon th',$myData['title'],$myData['uid'],$GLOBALS['TSFE']->id,$GLOBALS['TSF E']->sys_page->sys_language_uid,0,'extension');

unset($keStatsObj);

}

*Note:*

You can find another example in

ke_statsfilecounterclass.tx_kestats_filecounter.php

File access counting

You may use ke_stats to count accesses to certain files in order count downloads of for example pdf or word files.

This is how to do it:

  1. You will need a .htaccess file in your root directory.

Add this lines to your .htaccess file:

# ke_stats file counter

RewriteRule .*.(doc|odt|pdf)$ index.php?eID=tx_kestats_filecounter [L]

For “index.php” you will have to use the same address as in your commands you use for RealURL. In some cases this will be “/index.php”.

You can add or remove file types to count in “(doc|odt|pdf)”.

If you use the default .htaccess file provided with TYPO3, make sure your RewriteRule command appears BEFORE the line

RewriteRule ^(typo3|t3lib|tslib|fileadmin|typo3conf|typo3temp|up loads|showpic.php|favicon.ico)/ - [L]

  1. Create a sysfolder, for example “Download counter”.

3. Go to the extension manager and enter the pid of that sysfolder in the field “Page where to count file accesses”.

img-3

Notes:

  • Only the file name is taken into account. If you have files with equal names in different folders, they will be counted as one file.
  • Search engine access is filtered. That means accesses from robots will not be counted.
  • If you use TYPO3 4.5 or above, you will have to disable the “jumpurl” feature in order to use the file access counting with ke-stats:

styles.content.uploads {

jumpurl = 0

jumpurl_secure = 0

}

FAQ

It seems that not all of the visits are being counted. Why is that?

Visits will be counted only on the page they appear first. That means only the number on your rootpage is really meaningful, because then all the subpages will be taken into account.

It seems that the displayed number of visits does not take into account the visits which start on a page outside the current page (and subtree), but end up on the current page (and subtree).

Question:

The manual states that visits are counted for the page where the visit (session) starts.It seems that the displayed number of visits does not take into account the visits which start on a page outside the current page (and subtree), but end up on the current page (and subtree).Usually visits for a page means: number of page views where multiple views within a visit (session) are counted as one.

For a page with no subpages the visits count only shows the number of sessions which started on this page.

The result is that the figure "page views/visit" is rather meaningless.

Answer:

Yes, that's true. Maybe you can call visits “visitor entries” because the visits are only counted on the page where a visitor enters your site. The figure “page views/visit” is only meaningful on the root page!

Known problems

No results in TYPO3 6.0.X

There is a known Core-Bug in TYPO3 6.0.X ( http://forge.typo3.org/issues/44825 ) which prevents ke_stats from working.

A workaround is to put the plugin into the page instead of the page header, use

page.100 < plugin.tx_kestats_pi1

to include the plugin instead of

page.headerData.100 < plugin.tx_kestats_pi1

Counting 404 pages results in visits

If you use the TYPO3 “pageNotFoundHandling” in a way that you read a TYPO3 page and show this page to your visitors in order to inform them that the page they requested page hasn't been found, each of those pageviews will be counted as a visit! You may solve this by excluding your 404 page from your statistic (see typoscript options).

Performance

ke_stats saves it's statistical information in the TYPO3 database. That means the table can grow quite big. Depending on your server, this may not be the ideal solution on high traffic sites (let's say several hundred thousand pageviews per month). On the other hand it runs flawlessly on a website served by a powerful dedicated server with about one million pageviews per month. Make sure you use “asynchronousDataRefreshing” in these cases. You can also disable caching for the backend module in order to save database space (in the extension manager).

To-Do list

Some ideas for improvements are:

  • Chart Rendering for more pages than the overview page.
  • Special 404 Handling.
  • Improved Localization.
  • Link to the corresponding frontend elements from the backend (for example to a single view of tt_news elements).
  • Performance improvements for backend module.

Changelog

Please see file “Changelog” in the extension folder, can also be found at

http://forge.typo3.org/projects/extension- ke_stats/repository/changes/trunk/ChangeLog

Credits

Icon taken from http://www.famfamfam.com/lab/icons/silk/

img-4 EXT: Statistics - 9