WP Statistics Administrators Manual Version 10.0














WP Statistics




Administrator Manual




Version 10.0

Table of Contents

Introduction 3

Features 4

Requirements 5

Frequently Asked Questions 6

Support 12

Installation 13

Removal 13

Manual Removal 14

Main Interface 15

Dashboard Widgets 17

Manual Page 18

Settings Page 19

Optimization Page 38

Overview Page 47

Browsers Page 50

Countries Page 51

Exclusions Page 52

Hits Page 53

Online Page 54

Pages Page 55

Referrers Page 57

Searches Page 58

Search Words Page 59

Top Visitors Today 60

Visitors Page 61

Multi-Site 62

The Widget 64

Shortcodes 65

Function API 67



Introduction

Welcome to WP Statistics!

This plug-in is designed to track your visitor statistics in WordPress, completely locally without any external services.

You can find us on the web at http://wp-statistics.com.

There are several key items to note about WP Statistics:



This document will use a couple of conventions you should be aware of:

Features

WP Statistics has many features:

Requirements

WP Statistics requires a few things to work:



WP Statistics might work on older versions of the above software, but then again, it might not (it does NOT function on any PHP versions before 5.3).



The GeoIP support also requires a few additional items to function:



WP Statistics requires a significant amount of RAM for the statistics pages, especially the overview page, make sure to set your PHP memory limit high enough to support it. While every site has different memory requirements, a reasonable rule of thumb is at least 36 megabytes and significantly higher is not unreasonable (128-256 megabytes).

Frequently Asked Questions

Where's the Admin Manual?

The admin manual is installed as part of the plugin, simply go to Statistics->Manual to view it. At the top of the page will also be two icons that will allow you to download it in either ODT or HTML formats.

What do I do if the plug does not work?

Disable / Enable the plugin. You may also want to remove and re-install it.

All visitors are being set to unknown for their location?

Make sure you've downloaded the GeoIP database and the GeoIP code is enabled.

Also, if your running an internal test site with non-routable IP addresses (like 192.168.x.x or 172.28.x.x or 10.x.x.x), these addresses will come up as unknown always.

GeoIP is enabled but no hits are being counted?

The GeoIP code requires several things to function, PHP 5.3 or above, the bcmath extension, the cURL extension and PHP cannot be running in safe mode. All of these conditions are checked for but there may be additional items required. Check your PHP log files and see if there are any fatal errors listed.

How much memory does PHP Statistics require?

This depends on how many hits your site gets. The data collection code is very light weight, however the reporting and statistics code can take a lot of memory to process. The longer you collect data for the more memory you will need to process it. At a bare minimum, a basic WordPress site with WP Statistics should have at least 32 meg of RAM available for a page load. Sites with lots of plugins and high traffic should look at significantly increasing that (128 to 256 meg is not unreasonable).


I've enabled IP subnet exclusions and now no visitors are recorded?

Be very careful to set the subnet mask correctly on the subnet list, it is very easy to catch too much traffic. Likewise if you are excluding a single IP address make sure to include a subnet mask of 32 or 255.255.255.255 otherwise the default subnet of 0 will be used, catching all ip addresses.

I'm not receiving e-mail reports?

Make sure you have WordPress configured correctly for SMTP and also check your WP Cron is working correctly. You can use Cron View to examine your WP Cron table and see if there are any issues.

Does WP Statistics support multi-site?

WP Statistics doesn't officially support multi-site however it does have limited functionally associated with it and should function without issue. However no support is provided at this time.

Version 8.8 is the first release that should install, upgrade and remove correctly on mutli-site as well as have some very basic support for the network admin menu. This should not be taken as an indication that WP Statistics fully support for multi-site, but only as a very preliminary first step.

Does WP Statistics report on post hits?

Yes, version 6.0 has introduced page hit statistics!

Does WP Statistics track the time of the hits?

No.



The GeoIP database isn't downloading and when I force a download through the settings page I get the following error: "Error downloading GeoIP database from: http://geolite.maxmind.com/download/geoip/database/GeoLite2-Country.mmdb.gz – Forbidden"

This means that MaxMind has block the IP address of your webserver, this is often the case if it has been blacklisted in the past due to abuse.

You have two options:


To manually download the database and install it take the following steps:



You can also ask MaxMind to unblock your host. Note that automatic updates will not function until you can successfully download the database from your web server.




I've activated the plugin but the menus don't show up and nothing happens?

WP Statistics requires PHP 5.3, if it has detected an older version of PHP installed it will active but it will display an error on your plugin list just below the WP Statistics entry to let you know.

If there is no error message there may be something else wrong, your first thing to try is disabling your other plugins as they can sometimes cause conflicts.

If you still don't see the menus, go to the support forums and open a new thread and we'll try to help out.

I'm using another statistics plugin/service and get different numbers for them, why?


Pretty much every plugin/service is going to give you different results for visits and vistors, there are several reasons for this:


Services that use centralized databases, like Google Analytics, for spam and robot detection have better detection than WP Statistics can. The trade off of course is relaying on an external service.

Something has gone horribly wrong and my site no longer loads, how can I disable the plugin without access to the admin area?


You can manually disable plugins in WordPress by simply renaming the folder they are installed in. Using FTP or your hosting providers file manager, go to your WordPress directory, from ther go to wp-content/plugins and rename or delete the wp-statistics folder.


I'm getting an error in my PHP log like: Fatal error: Call to undefined method Composer\Autoload\ClassLoader::set()


We use several libraries and use a utility called Composer to manage the dependencies between them. We try and keep our Composer library up to date but not all plugins do and sometimes we find conflicts with other plugins. Try disabling your other plugins until the error goes away and then contact that plugin developer to update their Composer files.

The search words and search engine referrals are zero or very low, what's wrong?


Search Engine Referrals and Words are highly dependent on the search engine providing the information to us and that often is not the case. Unfortunately there is nothing we can do about this, we report on everything we receive.


Why did my visits suddenly jump way up today?


There can be many reasons for this, but the most common reason is a botnet has decided to visit your site and we have been unable to filter it out. You usually see your visits spike for a few days and then they give up.


What’s the difference between Visits and Visitors?


Visits is the number of page hits your site has received.

Visitors is the number of unique users that have visited your site.

Visits should always be greater than Visitors (though there are a few times when this won’t be true on very low usage sites due to how the exclusion code works).

The average number of pages a visitor views on your site is Visits/Visitors.



My overview screen is blank, what's wrong?


This is usually caused by a PHP fatal error, check the page source and PHP logs.

The most common fatal error is an out of memory error. Check the Statistics->Optimization page and see how much memory is currently assigned to PHP and how much the overview is using.

If it is a memory issue you have two choices:
- Increase PHP's memory allocation
- Delete some of your historical data.

See http://php.net/manual/en/ini.core.php#ini.memory-limit for information about PHP's memory limit.

To remove historical data you can use the Statistics->Optimization->Purging->Purge records older than.

Not all referrals are showing up in the search words list, why?


Unfortunate we're completely dependent on the search engine sending use the search parameters as part of the referrer header, which they do not always do.

Does WP Statistics work with caching plugins?


Probably not, most caching plugins don't execute the standard WordPress loop for a page it has already cached (by design of course) which means the WP Statistics code never runs for that page.

This means WP Statistics can't record the page hit or visitor information, which defeats the purpose of WP Statistics.

We do not recommend using a caching plugin along with WP Statistics.



I get an error message like "PHP Fatal error: Function name must be a string in /../parse-user-agent.php"


Do you have eAccelerator installed? If so this is a known issue with eAccelerator and PHP's "anonymous" functions, which are used in the user agent parsing library. As no new versions of eAccelerator have been released for over 3 years, you should look to replace it or disable it.


I've installed WP Statistics for the first time on a site and when I go to the statistics pages I get an error saying like "The following plugin table(s) do not exist in the database"


This is because something has gone wrong during the installation.

At the end of the message will be a list of tables that are missing, you can use the provided link to re-run the installation routine. If that does not resolve the issue and the visitors table is the only table listed, you may want to check your MySQL version. Some older versions of MySQL (in the 5.0.x series) have issues with complex compound indexes, which we use on the visitors table. If this is the case, check with your hosting provider and see if they can upgrade to a newer version of MySQL.

If you still have issues open a new thread on the support forum and we'll try and resolve it for you.


Support

We're sorry you're having problem with WP Statistics and we're happy to help out. Here are a few things to do before contacting us:

And a few things to double-check:

Still not having any luck? Open a new thread on one of the support forums and we'll respond as soon as possible.

Installation

Installation is straight forward, you can either use WordPress' built in installation process or manually upload the files to the WordPress plugin directory.

Once installed, go to the WordPress plugin page and activate WP Statistics.

You should then configure the settings found in the following sections, at a minimum, check the sections on the GeoIP, browscap and exclusions.

Removal

If you wish to remove WP Statistics, you can do so using the standard WordPress tools, however WP Statistics will NOT delete the statistical data or settings from the database using this method.

You can remove the data and settings by going in to the Statistics->Settings->Removal tab and checking the “Remove data and settings” option. This will delete all tables and settings and effectively disable the plugin.

You can then go to WordPress plugins page and disable/delete it completely from your site.



Manual Removal

If you have to manually delete the plugin you can do so if you have access to phpMyAdmin or another SQL management tool on your hosting provider.

NOTE: You should not attempt to manually remove the plugin unless it is absolutely necessary and only if you understand all the steps involved.

First, delete the plugin files which can be found in your WordPress/wp-content/plugins/wp-statistics folder.

Next remove the data from the database, for this example we will assume you have not changed your WordPress database prefix and are not running multi-site. If your prefix is different or you are running multi-site you will need to run each of the commands with the appropriate database table names.

Execute the following SQL commands:

Main Interface

WP Statistics adds a top level menu to your admin interface in PHP, you should see like this in your main admin page:





The Statistics menu will be located near the bottom of the list, clicking on it should bring up the following additional items:


Each of these options will be discussed in the following sections.

In addition, if you've enabled the option, you may also see the WP Statistics menu icon in the main admin bar of your site as such:




This menu gives you a quick summary of what is going on with your site and direct access to the overview page of WP Statistics.





Dashboard Widgets

WP Statistics includes a number of dashboard widgets you can add if you have read access to WP Statistics.

By default, the dashboard widgets are not displayed, with the exception of the Quick Stats widget. Users can individually enable them through the “Screen Options” drop down in the WordPress dashboard.

The dashboard widgets mirror the Overview page widgets with the following exceptions/notes:



Widget

Description

Quick Stats

This combines the visit/visitor stats from the summary widget and the hits graph for the last ten days.

About

This widget is not available on the dashboard.

Manual Page

The manual page gives you access to the release version of this document.




You will be given access to the online version of the document which you can read, or the two icons at the top of the page will allow you to download a copy of the manual to read offline or print for your reference.

There are two formats available to download, the first is a OpenOffice/LibreOffice ODT file and the second is an HTML file.



Settings Page

The first thing you should do after installing WP Statistics is configure the plug-in, this is accomplished through the settings page.

Simply go to Statistics->Settings to get there. The main settings page looks like this:




At the top are nine tabs, each one will be addressed separately.



General Settings

The General Settings page has 9 subsections to it; Users Online, Visits, Visitors, Pages, Miscellaneous, Search Engines, Charts, Map and Statistical reporting.

IP Addresses

The IP Addresses section contains the configuration items IP storage in WP Statistics. Note has a long term impact to your site.

Setting

Values

Description

Hash IP Addresses

On/Off

This feature will not store IP addresses in the database but instead used a unique hash. The "Store entire user agent string" setting will be disabled if this is selected.


You will not be able to recover the IP addresses in the future to recover location information if this is enabled.


Once enabled all new visitors to your site will have their IP addresses stored as a hash, however previous visits will not be converted and you may want to purge your old data.


You can also got to Statistics->Optimization->Updates and select “Hash IP Addresses” to update old entires in the database.

Users Online

The Users Online section contains the configuration items tracking online users in WP Statistics.

Setting

Values

Description

User Online

On/Off

This enables/disables the tracking of users that are online for your site.

Check for online users every

Number

If you have enabled Users Online tracking, this is how often they are checked for. If a user has not visited a page within this number of seconds, they will be considered offline.



Visits

The Visits section contains the configuration items for tracking visits (hits) to your site.

Setting

Values

Description

Visits

On/Off

This enables/disables the tracking of visits (hits) for your site.



Visitors

The Visitors section contains the configuration items for the visitor tracking for your site.

Setting

Values

Description

Visitors

On/Off

This enables/disables the tracking of visitors for your site.

Store entire user agent string

On/Off

If you have enabled Visitors, by default it stores the browser make, version and platform in the database by parsing the user agent (UA) string. However UA strings are very complex and parsing sometimes does not work correctly. You can store the entire UA string in the database so that it can used to troubleshoot issues.

Coefficient per visitor

Number

This is the number of hits each visitor records for. Usually is 1, however if you have another plug-in that causes visitors to effectively connect to to your site more than once for each page view, this can be set to a lower value to account for that.





Pages

The Pages section contains the configuration items for the page tracking code.

Setting

Values

Description

Pages

On/Off

This enables/disables the tracking of individual page hits.

Track all pages

On/Off

By default, page tracking only tracks WordPress pages and posts, however you can enabled tracking of all pages (like category pages, RSS feeds, etc.) with this option.


Note: this will significantly increase the pages table and may make the top pages chart less useful as many system pages will likely be near the top.

Strip parameters from URI

On/Off

By default the page tracking code tracks every unique URI, including the parameters after the ?. This can cause the same page to be tracked as multiple unique URI's which may not be appropriate.


This option cannot be activated if you are using the default setting for permalinks in WordPress. Likewise if your permalink setting contains a ? then this option will not be available.


You should only enable this option if you fully understand the consequences. For example, the default behaviour of WP Statistics is to track multi-page posts separately so you can see if a user reads more than one page. Enabling this option will not track these pages separately.

Disable hits column in post/pages list

On/Off

By default, if Pages is enabled, WP Statistics will add a column to the post and pages lists in WordPress and display the number of hits each one has had. This does have a performance impact and this option will disable this behaviour.





Miscellaneous

The Miscellaneous section contains configuration items for WP Statistics.

Setting

Values

Description

Show stats in menu bar

Yes/No

This enables/disables the admin menu bar for WP Statistics.


Note: As the WP Statistics menu bar displays visitor stats, it adds load to your database for each admin page load.

Hide admin notices about non active features

On/Off

By default, WP Statistics will warn you about any primary features that have been disabled (Online Users, Visits, Visitors, Pages and GeoIP). If you have disabled a feature on purpose or cannot support the GeoIP code, this option will remove the warning.

Delete the manual

On/Off

By default WP Statistics stores the admin manual in the plugin directory (~5 meg), if this option is enabled it will be deleted now and during upgrades in the future.



Search Engines

The Search Engines section contains the options for which search engines you want to track as well as controlling search quires that do not contain any values. By default all supported search engines are enabled, you may disable individual ones as required.

Note however that disabling all search engines is not allowed, doing so will result in all search engines being active.

Setting

Values

Description

Add page title to empty search words

On/Off

If a search engine is identified as the referrer but it does not include the search query this option will substitute the page title in quotes preceded by "~:" as the search query to help identify what the user may have been searching for.

Baidu

On/Off

Enable/disable Baidu.

Bing

On/Off

Enable/disable Bing.

clearch.org

On/Off

Enable/disable clearch.org.

DuckDuckGo

On/Off

Enable/disable DuckDuckGo.

Google

On/Off

Enable/disable Google.

Yahoo!

On/Off

Enable/disable Yahoo!.

Yandex

On/Off

Enable/disable Yandex.



Also note that geographic versions of the search engines are supported, so Google will include google.com as well as google.ca and other variations.

Developers Note:

The search engine list can be found in wp-statistics\includes\functions\functions.php in the function called wp_statistics_searchengine_list() (should be around line 297). You can add additional search engines by editing the $engines array, details are contained in the comments above the function. All other aspects of the search engine code relies on this array and no other aspects of WP Statistics needs to be changed to support the addition or removal of search engines.

Charts

The Charts section contains the options for the display of charts in WP Statistics.

Setting

Values

Description

Include totals

On/Off

By default WP Statistics does not include totals in charts that have multiple values in them, this options enables a total value on any chart that supports them.


Languages

The Languages section contains the options for the language used in WP Statistics.

Setting

Values

Description

Force English

On/Off

By default WP Statistics uses the language that the WordPress administrative console is set to to display all strings. This setting will override that behaviour and instead use English.


Notifications

Common Report Options

The Common Report Options section contains options that are common to all of the sections that follow.

Setting

Values

Description

E-mail addresses

Comma separated list

This is a comma separated list of e-mail addresses to send the report too if e-mail was selected in the option above. By default this will be the WordPress admin e-mail address.


Update Reports

The Update Reports section contains options for when to send e-mail notifications when various update actions occur.

Setting

Values

Description

Browscap

On/Off

Send a report whenever the browscap.ini is updated. See the browscap tab to enable automatic updates.

GeoIP

On/Off

Send a report whenever the GeoIP database is updated. See the GeoIP tab to enable automatic updates.

Pruning

On/Off

Send a report whenever the pruning of database is run. See the Maintenance tab to enable automatic pruning.

Upgrade

On/Off

Send a report whenever the plugin is upgraded.




Statistical Reporting

The Statistical Reporting section contains the options to email the administrators the statistics.

Note if reporting is disabled, all other related fields will be hidden in the user interface.

Setting

Values

Description

Statistical reporting

On/Off

Enable/disable the reporting.

Schedule

Hourly/

Twice Daily/

Daily/

Weekly/

Bi-Weekly/

Every 4 Weeks

How often to send the report.

Send reports via

Email/SMS

How to send the report, the blog's admin email address is used if email is selected.


To support SMS you must have WordPress SMS (http://wordpress.org/plug-ins/wp-sms/) installed as well.

Report body

Text

This is the report text which will be sent, you can use any short codes supported by your installation of WordPress, including the ones from WP Statistics.


As of WP Statistics 8.0 the old variables have been removed and the upgrade process will automatically replace them with the appropriate short codes.



Dashboard/Overview

The Overview page has 3 subsections to it; Map, Post/Page Editor and Widgets to Display.

Dashboard

The Dashboard section contains the options for the display of the dashboard widgets.

Setting

Values

Description

Disable dashboard widgets

On/Off

If you wish to disable the dashboard widgets for all users, you can do so by enabling this option.

Post/Page Editor

The Post/Page Editor section contains the option for the widget on the post/page editor in WordPress.

Setting

Values

Description

Disable post/page editor widget

On/Off

WP Statistics will include a 20 days page hit chart on the post and page editor screens in WordPress. This option will disable this for your site.

Map

The Maps section contains the options for the display of the GeoIP map in the overview page of WP Statistics.

Setting

Values

Description

Map type

Google/

JQVMap

There are two mapping libraries available, Google and JQVMap. Use of the Google map library will access the Google servers to get the library and create push pins with details for each country on it. JQVMap is a self contained mapping library that makes no external connections and provides a heat map style display with details.

Disable map

On/Off

By default the map is displayed in the overview page, however it can be disabled with this option.

Get country location from Google

On/Off

By default, the location of IP addresses for the map display are generated from the MaxMind database, however this can sometimes be out of date and this option will allow you to use Google instead. However this is MUCH slower as each address to be plotted requires a remote call to Google.



Access/Exclusions

The Access/Exclusions page has 5 subsections to it; Access Levels, Exclusions, Excluded User Roles, IP/Robot Exclusions and Site URL Exclusions.

Access Levels

The Access Levels section contains the settings to control who can view and manage the WP Statistics plug-in.

What roles are available to set is dependent on your installation of WordPress, some plug-ins add roles.

The default roles in WordPress map as follows:

Note, each of the above cascades the rights upwards in the default WordPress configuration. So for example selecting publish_posts grants the right to Authors, Editors, Admins and Super Admins.

For more information about WordPress roles, you can visit the “WordPress Roles and Capabilities” page at http://codex.wordpress.org/Roles_and_Capabilities.

There are also several good plug-ins to extend the roles and capabilities of WordPress, one such plug-in is Capability Manager Enhanced (http://wordpress.org/plug-ins/capability-manager-enhanced/).

Setting

Values

Description

Required user level to view WP Statistics

WordPress Role

This will be the minimum role required to access the statistics pages. This will not provide access to the settings or optimization pages.

Required user level to manage WP Statistics

WordPress Role

This will be the minimum role required to fully administrate WP Statistics.



Exclusions

The Exclusions page has 6 subsections to it; Exclusions, Excluded User Roles, IP/Robot Exclusions, GeoIP Exclusions, Host Exclusions and Site URL Exclusions.

Exclusions

The Exclusions section contains the settings to control if exclusions are recorded or not.

Setting

Values

Description

Record exclusions

On/Off

If a page hit is excluded for any of the settings in the next several sections it is dropped silently by default. This setting will enable aggregate recording of these exclusions so you can track spikes in the different types of exclusions.

Exclude User Roles

The Exclude User Roles section contains the settings to control if different user roles are excluded from the statistics.



Note, by default WordPress comes with the following roles, however plug-ins can extend the roles available so you may see a different list in your installation. Also, the Everyone role is excluded from this list as excluding it would effectively disable WP Statistics.

Setting

Values

Description

Administrator

On/Off

The Administrator role.

Editor

On/Off

The Editor role.

Author

On/Off

The Author role.

Contributor

On/Off

The Contributor role.

Subscriber

On/Off

The Subscriber role.


Developers Note:


WP Statistics builds this list dynamically, if you are writing a plug-in that adds a role to WordPress you do not need to make any changes to WP Statistics to have it supported.



IP/Robot Exclusions

The IP/Robot Exclusions section contains the settings to control if IP subnets and Robots are excluded from the statistics.

Setting

Values

Description

Robot list

Text

A list of words (one per line) to match against to detect robots. Entries must be at least 4 characters long or they will be ignored.


By default, when WP Statistics is upgraded, if this list has not been altered, new robots will be automatically added. However if you have added your own robots to the list, you will have to manually add any new entries (which can be found in the upgrade section of the readme) to this list.

Force robot list update after upgrades

On/Off

Force the robot list to be reset to the default after an update to WP Statistics takes place.


Note if this option is enabled any custom robots you have added to the list will be lost.

Robot visit threshold

Number

Treat visitors with more than this number of visits per day as robots. 0 = disabled.


Be careful of setting this number too low as you may exclude too many people from the statistics.

Excluded IP address list

Text

A list of IP addresses and subnet masks (one per line) to exclude from statistics collection (both 192.168.0.0/24 and 192.168.0.0/255.255.255.0 formats are accepted). To specify an IP address only, use a subnet value of 32 or 255.255.255.255.


WARNING: This is a VERY powerful feature which can be miss configured to exclude too many hits. Be careful to use the right subnet for the addresses you want to exclude.


Note that only IP v4 addresses are supported at this time.




Use honey pot

On/Off

WP Statistics can use a honey pot trap page which normal visitors will never visit to identify robots and crawlers. Once identified, hits from these visitors will be excluded for the rest of the day.

Honey pot post id

Number

The post ID of the page/post you wish to use as the honey pot, a hidden link will be added near the bottom of each page on your site. Users will not see this link but crawlers which simply parse the HTML will and then follow it.


WP Statistics can create a new honey pot post by simply checking the “Create a new honey pot page” option.

Treat corrupt browser info as a bot

On/Off

If WP Statistics finds corrupt or missing information for the IP address or User Agent string, enabling this option will exclude the visitor/visit from the statistics.



GeoIP Exclusions

The GeoIP Exclusions section contains the settings to control if hits are excluded based on their GeoIP information from the statistics.

Setting

Values

Description

Excluded countries list

Text

A list of country codes (one per line, two letters each) to exclude from statistics collection.


Use "000" (three zeros) to exclude unknown countries.

Included countries list

Text

A list of country codes (one per line, two letters each) to include in statistics collection, if this list is not empty, only visitors from the included countries will be recorded.


Use "000" (three zeros) to exclude unknown countries.



Host Exclusions

The Host Exclusions section contains the settings to control if hits are excluded based on their host name information.

Setting

Values

Description

Excluded countries list

Text

A list of fully qualified host names (ie. server.example.com, one per line) to exclude from statistics collection.


Note: this option will NOT perform a reverse DNS lookup on each page load but instead cache the IP address for the provided hostnames for one hour. If you are excluding dynamically assigned hosts you may find some degree of overlap when the host changes it's IP address and when the cache is updated resulting in some hits recorded.

Site URL Exclusions

The Site URL Exclusions section contains the settings to control if some of the WordPress pages are excluded from the statistics.

Note, self referrals from your own site are ALWAYS excluded from the stats. These are most commonly ajax requests by WordPress.

Setting

Values

Description

Excluded Login Page

On/Off

Exclude the login page.

Excluded Admin Pages

On/Off

Exclude all admin pages.

Excluded RSS feeds

On/Off

Exclude all RSS pages from the statistics. This includes the primary site feed as well as individual post comment feeds. It should also include any custom RSS feeds that have been configured for your WordPress install.

Excluded 404 pages

On/Off

Exclude any URL that returns a "404 - Not Found" message.

Excluded URLs list

Text

A list of URL's (one per line) to exclude from the statistics collection.


These should NOT include any GET parameters they may not match the URL you expect.

Externals

The Externals page contains the settings to control the optional third party services, including GeoIP data collection, browscap robot exclusions and Piwik Referrer Spam Blacklist.

GeoIP Settings

The GeoIP settings allow you to configure the recording of country information for your visitors. This requires the download and use of an external database and is disabled by default.


Note: IP location services provided by GeoLite2 data created by MaxMind, available from http://www.maxmind.com.

Note: Referrer spam blacklist is provided by Piwik, available from https://github.com/piwik/referrer-spam-blacklist.

Setting

Values

Description

GeoIP collection

On/Off

Enable/disable the collection of GeoIP information.

Update GeoIP Info

On/Off

The GeoIP database is updated monthly by MaxMind, checking this option and saving the settings will download the latest database. If you want to manually download the database, you can do so and store it in wordpress/wp-content/upload/wp-statistics. Make sure to decompress it.

Schedule monthly update of GeoIP DB

On/Off

WP Statistics can automatically download the new database each month by enabling this option.


Download of the GeoIP database will be scheduled for 2 days after the first Tuesday of the month (which is when the new database is released by MaxMind).

Populate missing GeoIP after update of GeoIP DB

On/Off

After an update to the database is done, you can have WP Statistics automatically try and find missing geolocation information for visitors in the database.

Country code for private IP addresses

Text

The international standard two letter country code (ie. US = United States, CA = Canada, etc.) for private (non-routable) IP addresses (ie. 10.0.0.1, 192.158.1.1, 127.0.0.1, etc.). Use "000" (three zeros) to use "Unknown" as the country code.



Borwscap Settings

The browscap page contains the settings to control the use of the browscap.ini file for robot detection. More information about browscap.ini can be found at browscap.org.

The browscap.ini database is used to detect robots and crawlers to your site, however the normal distribution is quite large as it can identify any browser, not just robots. To use the normal distribution of browscap would require and additional 5-6 meg of ram per page load.

To avoid this, WP Statistics will process the browscap.ini file and strip out all non-robot based entries. This reduces the overhead to approximately 200k per page load. However there must be enough free disk space available to download and process the complete browscap.ini file.

Setting

Values

Description

browscap usage

On/Off

Enable/disable the use of the browscap.ini file.

Update browscap Info

On/Off

The browscap.ini file is update on an irregular basis, checking this option and saving the settings will download the latest file. Manually downloading the database is not recommended as it is quite large and WP Statistics removes unused items from it for performance reasons.

Schedule weekly update of browscap DB

On/Off

WP Statistics can automatically download the new browscap.ini file on a weekly basis by enabling this option.





Piwik Referrer Spam Blacklist settings

Referrer spam is unwanted hits to your site by robots that impersonate users trying to insert spam links to your statsitcs, Piwik maintains a list of sites that use this technique and WP Statistics can exclude these from the data collection.

Note: Referrer spam blacklist is provided by Piwik, available from https://github.com/piwik/referrer-spam-blacklist.



Setting

Values

Description

Piwik Referrer Spam Blacklist usage

On/Off

Enable/disable the use of the Piwik Referrer Spam Blacklist.

Update Piwik Referrer Spam Blacklist Info

On/Off

The Piwik Referrer Spam Blacklist file is update on a weekly basis, checking this option and saving the settings will download the latest file immediately.

Schedule weekly update of Piwik Referrer Spam Blacklist DB

On/Off

The Piwik Referrer Spam Blacklist file is update on a weekly basis, checking this option and saving the settings will download the latest file each week.

Maintenance

The Database Maintenance page contains the settings to control if the database is pruned of older data.

Setting

Values

Description

Run a daily WP Cron job to prune the databases

On/Off

Enable/disable the running of a daily job to prune the database of old data. Since WP Statistics 8.2 the pruned data will be summarized in to the historical database.

Prune data older than

Number

The number of days to keep statistics for. Minimum value is 30 days. This means a number above 30 must be entered here.


Invalid values will disable the daily maintenance.

Run a daily WP Cron job to prune the databases

On/Off

Enable/disable the running of a daily job to prune the database of visitors with more than a dfined number of hits per day. These hits will be removed and not added to the historical database.

Prune visitors with more than

Number

The number of hits to remove statistics for. Minimum value is 10 hits.


Invalid values will disable the daily maintenance.



Removal

The Removal page allows you to remove the data and settings before uninstalling the plugin.

Setting

Values

Description

Remove data and settings

On/Off

Remove data and settings, this action cannot be undone.

About

The About page contains version information and other details of the plugin you may find useful.


Optimization Page

The Optimization page will allow you to do some basic maintenance tasks related to WP Statistics.



The optimization page looks like this:




It has six tabs; Resources/Information, Export, Purging, Database, Updates and Historical.



Resources/Information

The Resources/Information page has 4 subsections to it; Resources, Version Info, File Info and Client Info.

Resources

The Resources section contains some resource usage information.

Setting

Values

Description

Memory usage in PHP

Bytes

The number of bytes of memory WordPress is currently using. This number is highly transitive and should only be used as a genera guide line. Pages like the overview page use more memory than others.

PHP Memory Limit

N/A

The maximum amount of memory that PHP will allow a script to use before terminating the script. This value is set in the php.ini file and must be set high enough to allow WP Statistics to load and manipulate data in the statistics charts.

Number of rows in the wp_statistics_useronline table

Rows

The number of rows in the users online table.

Number of rows in the wp_statistics_visit table

Rows

The number of rows in the visits table.

Number of rows in the wp_statistics_visitor table

Rows

The number of rows in the visitors table.

Number of rows in the wp_statistics_exclusions table

Rows

The number of rows in the exclusions table.

Number of rows in the wp_statistics_pages table

Rows

The number of rows in the pages table.

Number of rows in the wp_statistics_historical table

Rows

The number of rows in the historical table.





Version Info

The Version Info section contains the various versions of the software installed on your server.

Setting

Values

Description

WP Statistics Version

Version

The version of the plug-in.

PHP Version

Version

The version of PHP.

PHP Safe Mode

Yes/No

Is PHP running in safe mode. Note this is the value in php.ini, so even though PHP 5.4 and above deprecated safe mode, you may still have the value set in php.ini. If you do, you should remove it.

jQuery Version

Version

The version of jQuery.

cURL Version

Version

The PHP cURL Extension version you are running. cURL is required for the GeoIP code, if it is not installed GeoIP will be disabled.

BC Math

Yes/No

If the PHP BC Math Extension is installed. BC Math is no longer required for the GeoIP code and is listed here only for historical reasons.



File Info

The File Info section contains information about the GeoIP and browscap files. Browscap has two files, the raw ini file downloaded from browscap.org and a cache file generated by the browscap library to improve performance on loading and lookups.

Setting

Values

Description

GeoIP Database

Size/Date

The file size and date of the GeoIP database installed on your system.

browscap.ini File

Size/Date

The file size and date of the browscap.ini installed on your system.

browscap Cache File

Size/Date

The file size and date of the browscap cache file installed on your system.



Client Info

The Client Info section contains some information about your current session.

Setting

Values

Description

Client IP

IP Address

The IP address you are currently connected from.

User Agent

String

Your user agent string.

Browser

String

The detected browser you are running.

Version

String

The detected browser version you are running.

Platform

String

The detected platform you have.



Export

The Export page allows you to export the data from the database to a flat file. This is useful if you want to do additional analysis on the data or need to migrate to another statistics plug-in.

Setting

Values

Description

Export from

Table name

You can export from the three primary data tables.

Export To:

XML, CSV, TSV

The format to export to.


XML will export an XML formatted file.


CSV will export a comma separated value file.


TSV will export a tab separated value file.

Include Header Row

On/Off

Include a header row as the first line of the exported file.




Purging

The Purging page has 2 subsections to it; Data and Delete User Agent Types.

Data

The Data section allows you to purge information from the database..

Setting

Values

Description

Empty Table

Table name

This will delete ALL data from the selected tables. Only do this if you are absolutely sure you want to reset all of your statistics.

Purge records older than

Number

Deleted user statistics data older than the selected number of days. Minimum value is 30 days. Since WP Statistics 8.2 the pruned data will be summarized in to the historical database.

Purge visitors with more than

Number

Deleted user statistics data where the user has more than the defined number of hits in a day. This can be useful to clear up old data when your site has been hit by a bot.


This will remove the visitor and their hits to the site, however it will not remove individual page hits as that data is not recorded on a per use basis.


Minimum value is 10 hits.



Delete User Agent Types

The Delete User Agent Types section allows you to delete various user agent types from the database. This can be used to remove robots or other types of agents that are not real users.

Setting

Values

Description

Delete Agents

Agent name

This will delete ALL visitors with the selected agent type.

Delete Platforms

Platform name

This will delete ALL visitors with the selected platform.



Database

The Database page allows you to rerun the install routine or add a unique index to the Visitors table to protect against duplicate entries.

Database Setup

If for some reason you have had to delete one or more tables from the database server (perhaps a corrupt table or recovering from an incomplete backup) WP Statistics will warn you that the tables are missing however it will only run the database install/upgrade code during a version change.

This option will let you re-run the WP Statistics setup routine without having to manipulate the WordPress options table or the WP Statistics code.

This should only be done as a last resort.

Database Index

There are two indexes that older installs of WP Statistics do not have on the tables in the database. Adding these during the setup process can cause timeout's and so they are available to be added manually by the administrator.

If you do not have these indexes you will be presented with a button to add each index to the table.

Search Table

WP Statistics 9.5 added a new table and code to better handle referrers and search words, however converting older installs requires a manual upgrade, presented here if required.



Updates

The Updates page allows you to update data in the database for GeoIP and Hash IP addresses.

GeoIP Options

Setting

Values

Description

Countries

N/A

Selecting the “Update Now!” button will try and update any missing geolocation information in the visitors table. This can also be automated with the Statistics->Settings->GeoIP->Populate missing GeoIP after update of GeoIP DB setting.


Note if you have selected to hash the IP addresses then this will not function for those entires with hashed values.



IP Addresses

Setting

Values

Description

Hash IP Addresses

N/A

Selecting the “Update Now!” button will replace all IP addresses in the database with hash values.


You will not be able to recover the IP addresses in the future to populate location information if this is selected.

Historical

The Historical page allows you to configure the values to add to the total visits and visitors for your site. These values are auto incremented when any purging of data is done. Purging data also records page hits, however there is no user interface available for changing the values for page entries.

Note that if you use the purge function in the optimization page you should reload the page before editing these numbers as they will not be accurate.

Historical Values

Setting

Values

Description

Visitors

Number

A number of visitors to add to the total number of visitors to your site. This is useful if you have migrated from another statistics plugin or have purged data in the past to give an accurate total visitors count for your site.

Visits

Number

A number of visits to add to the total number of visits to your site. This is useful if you have migrated from another statistics plugin or have purged data in the past to give an accurate total visits count for your site.





Overview Page

The Overview page gives you a quick summary of all the statistics available, it looks like this:




It contains several “widgets” to display information, these are; Summary Statistics, Browsers, Top referring sites, Top 10 Countries, About, Top visitors on map, Hits Statistical Chart, Search Engine Referrals Statistical Chart, Latest Search Words, Top Pages Visited and Recent Visitors.

Each widget is comprised of a header bar and a statistical body. The header contains two areas:


The title (Browsers in the above example) and a controls area that has three buttons; details (if applicable), refresh and “Minimize/Maximize”.

The details button will take you to a separate page with additional or more comprehensive statistics on the related items.

The refresh button will reload the widgets contents.

The “Minimize/Maximize” control will collapse/expand the widget. Note that the state of the widget is not saved between page views so they will re-expand the next time you visit the overview page.

The widgets are as follows:

Widget

Description

Quick Statistics

This combines some information from the Summary widget and the Hits widget in to a compact display of activity on your site.

Summary Statistics

This displays today's and yesterday's statistics for the site. This includes the number of users currently online, visits, visitors and search engine referrals.

This widget also displays the current date and time (at page load). WP Statistics relies on the correct date and time as well as timezone being set on the server and in WordPress to display the correct information.

Top 10 Browsers

This displays a pie chart (not configurable) of the top ten browser types that have visited your site.

Top Referring Sites

This displays the top 10 sites that have referred visitors to your site.

Top 10 Countries

This displays the top 10 countries of the visitors to your site.

About

This provides some details about the plug-in and the donation links.

Today Visitors Map

This displays your visitors today on a Google map. This requires the GeoIP code to be enabled. You can use either Google or JQVMap mapping libraries (see Statistics->Settings->Overview->Maps). To keep the maps readable, the last five visitors per country are displayed on the map.

Hits Statistics

This displays your visit and visitor counts in a graph format for the last 20 days.

Search Engine Referrals

This displays the number of referrals you have received from search engines for the last 20 days.

Latest Search Words

This displays the last 10 search words referred to your site by search engines. Note that this is highly dependent on the search engine providing the information, some do not.

Top 10 Pages

This displays the top 10 pages that are visited for your site.

Recent Visitors

This displays the last 10 visitors to your site. This includes options to map their location, what country they came from and what browser they are using.

Top 10 Visitors Today

This displays the top 10 visitors today based on the number of times they have visited the site today. The display includes the visitors location, ip and browser details.

Browsers Page


This page provides details about the browsers users are using to visit your site. This information is presented in a series of pie charts.



The first two pie charts provide details on the browser type and platform used. The rest of the pie charts identify different version of browsers used.

Countries Page

This page provides details about the countries of users that have visited your site.




This chart will list all countries and includes the number of visitors from each.



Exclusions Page

This page provides a trending chart for the exclusion reasons if Statistics->Settings->Record Exclusions is enabled.




The top part of the page allows you to select from

Note that the longer the increment is the more data that is required to be processed. Large site with long increments can take significant time and memory to process.

Hits Page

This page provides a trending chart for the total visitors to your site over a selectable time line.




The top part of the page allows you to select from

Note that the longer the increment is the more data that is required to be processed. Large site with long increments can take significant time and memory to process.



Online Page

This page provides a list of users that are currently online and how long they have been online for.






Pages Page

This page provides trending graph of your top five pages over the last 20 days as well as a complete list of all your page rankings divided up in to groups of 10.




The top part of the page allows you to select from

Note that the longer the increment is the more data that is required to be processed. Large site with long increments can take significant time and memory to process.

The time selection only effects the display of the chart on this page and not the page list at the bottom of the page.

The list of pages contains the rank, page title (not all pages will have titles), the URI of the page and the number of visits. The number of visits is a link to a more detailed trending graph for that page.

The detailed trending page looks like:




The time frame is selectable by the links at the top of the page. This trending view is available to all pages in the pages list as well as, if not disabled, the hits count in the page/posts list and editor in WordPress.

Referrers Page

This page provides a complete list of all referrers to your site.




It is divided up in to pages of 10 entries each for easy browsing.

Searches Page

This page provides a trending graph of all incoming search engine traffic to your site.



The top part of the page allows you to select from



Note that the longer the increment is the more data that is required to be processed. Large site with long increments can take significant time and memory to process.

Search Words Page

This page provides a list of all search words from search engines to your site.




It is divided up in to pages of 20 entries each for easy browsing.

Top Visitors Today

This page provides a list of the top 100 visitors to your site today.




It is divided up in to pages of 20 entries each for easy browsing.

Visitors Page

This page provides a list of all vistors to your site.




It is divided up in to pages of 20 entries each for easy browsing.

Multi-Site

WordPress multi-site allows you to run multiple independent sites from a single WordPress installation.

WP Statistics does not fully support multi-site at this time but does have some basic options available for multi-site installations.

The key areas of support are currently:

Multi-Site Installation

Installing WP Statistics on a multi-site installation is much like on a standalone WordPress setup. Each site will have it's own database tables and options for WP Statistics which can be configured on the site dashboard.

As long as you install WP Statistics with an account that has rights across the network, the database tables will be automatically created for each site. If your installation account does not have rights to one or more of the child sites, you can manually run the installation routine by logging in with an account that does have rights and re-running the install process manually from the Statistics->Settings menu for the site.

Multi-Site Updates

Much like instllation, updates will automatically update any database tables and settings as required as long as the account you are using to upgrade with has rights to the child sites. If your account does not have rights to one or more of the child sites, you can manually run the installation routine by logging in with an account that does have rights and re-running the install process manually from the Statistics->Settings menu for the site.

Removal

Removal is accomplished the same way as for single installs and supports multi-site.

Network Menu

The network admin page looks much like the standard WordPress admin page, however it has some significant differences. WP Statistics has a basic implementation of the network menu to allow an administrator some additional functions that may be of use in multi-site installations.

The primary WP Statistics menu in the network admin page looks like this:


The first entry is the overview page, it will be discussed later.

The next set of entries are each of your sites in the network, up to a maximum of 15. Clicking on any of these menu entries will take you to the overview page on the sites admin page.

The final entry is the manual, if it is installed.

Network Menu Overview Page

The Network Menu Overview Page provides a list of all your sites as well as quick links to the vairous WP Statistics pages for each.




This page is not limited to 15 entries and will show you all of your sites no matter how many you have.

The Widget

WP Statistics comes with a WordPress widget to display some statistical information to your front end. The widget is still supported, however you may find the shortcodes to be more useful as they can be used in an HTML widget with any custom formatting you may like to apply.



The widget is called “Statistics” and the configuration page looks as follows:




The name field at the top will be displayed in the header of the widget on your site. Each option that is enabled will be displayed on a single line in the widget and display the indicated information.

Shortcodes

WP Statistics supports shortcodes in WordPress, these can be used in either a post and page body as well as an HTML widget.

The general shortcode format is:

[wpstatistics stat=xxx time=xxxx provider=xxxx format=xxxxxx id=xxx]

Where:

Item

Description

stat

The statistic you want, see the next table for available options.

time

Is the time frame for the statistic. This value uses the strtotime() PHP function (http://php.net/manual/en/datetime.formats.php) format, some acceptable values include:

  • today

  • yesterday

  • week

  • month

  • year

  • total

  • "-x" (i.e., "-10" for the past 10 days)

Please refer to the PHP manual link above for a complete description.

provider

The search provider to get stats on (ask/bing/clearch/duckduckgo/google/yahoo/yandex).

format

The format to use for numbers, the options are i18n (uses the format of the current country as set in WordPress), english (uses 1,000.00 style formats) or none (the default will return an number without any formating)

Id

The page/post ID to get statistics on. Only used on pagevisits.



The “stat” field can be any of the following:

Stat

Description

usersonline

The number of users online right now.

visits

The number of hits to the site.

visitors

The number of visitors to the site.

pagevisits

The number of times the current page has been visited

searches

The number of search engine referrals.

postcount

The total number of posts on the site.

pagecount

The total number of pages on the site.

commentcount

The total number of comments on the site.

spamcount

The total number of spam comments on the site.

usercount

The total number of users on the site.

postaverage

The average posts per user on the site.

commentaverage

The average comments per user on the site.

useraverage

The average number of users on the site.

lpd

The last post date for the site.


Examples:

Function API

WP Statistics supports several functions for other plug-in and theme authors to use to retrieve statistics about the site. All of the external functions can be found in:

wp-statistics\includes\functions\functions.php


Function

Description

wp_statistics_useronline()

Get the number of users online

wp_statistics_visitor(time)

Get the number of visitors

wp_statistics_visit(time)

Get the number of visits (hits)

wp_statistics_pages(time,uri,id)

Get the page views for a given page

wp_statistics_uri_to_id(uri)

Get the page ID of a given uri

wp_statistics_get_top_pages()

Get all pages sorted by number of hits (high to low)

wp_statistics_get_uri()

Get the current page's uri

wp_statistics_searchengine(provider, time)

Get the number of search engine referrals

wp_statistics_ua_list()

Retrieve a list of all visitors user agents

wp_statistics_useragent(agent)

Retrieve the number of visits from users with a specific user agent

wp_statistics_platform_list()

Retrieve a list of all visitors platforms

wp_statistics_platform(platform)

Retrieve the number of visits from users with a specific platform

wp_statistics_agent_version_list(agent)

Retrieve a list of all visitors agent versions

wp_statistics_agent_version(agent, version)

Retrieve the number of visits from users with a specific agent version

wp_statistics_searchengine_list(all)

Retrieve a list of search engines, by default this only returns search engines that are active, setting all to TRUE will return ALL search engines

wp_statistics_searchword_query (search_engine)

Returns the SQL query portion to find all search word queries for a given search engine

wp_statistics_searchengine_query (search_engine)

Returns the SQL query portion to find all search engine results for a given search engine

wp_statistics_searchengine_regex (search_engine')

Returns the regex to determine if a Referral URL is from a search engine

wp_statistics_countposts()

Total number of posts on your site

wp_statistics_countpages()

Total number of pages on your site

wp_statistics_countcomment()

Total number of comments on your site

wp_statistics_countspam()

Total number of spams items on your site

wp_statistics_countusers()

Total number of users on your site

wp_statistics_lastpostdate()

Last post date

wp_statistics_average_post()

Average number of posts

wp_statistics_average_comment()

Average number of comments

wp_statistics_average_registeruser()

Average number of users


Where:


Item

Description

time

Is the time frame for the statistic. This value uses the strtotime() PHP function (http://php.net/manual/en/datetime.formats.php) format, some acceptable values include:

  • today

  • yesterday

  • week

  • month

  • year

  • total

  • "-x" (i.e., "-10" for the past 10 days)

Please refer to the PHP manual link above for a complete description.

provider

The search provider to get stats on (bing/duckduckgo/google/yahoo/yandex).

uri

The uri of the page you want to get statistics for. This should only be the portion of the URI after your WordPress base directory. So if the full URL of the page you want is:

http://example.com/wordpress/index.php?p=5

then the uri field should be:

/index.php?p=5

id

The post or page id you want to get statistics for.



Page 70 of 70