WP Statistics Administrators Manual Version 6.0














WP Statistics




Administrator Manual




Version 6.0

Table of Contents

Introduction 3

Features 4

Requirements 5

Main Interface 6

Manual Page 8

Settings Page 9

General Settings 10

Access/Exclusions 15

GeoIP 18

Maintenance 18

Optimization Page 19

Resources/Information 20

Export 21

Purging 22

Updates 22

Overview Page 23

Browsers Page 26

Countries Page 27

Hits Page 28

Exclusions Page 29

Referrers Page 30

Searches Page 31

Search Words Page 32

Visitors Page 33

Pages Page 34

The Widget 36

Shortcodes 37

Function API 39



Introduction

Welcome to WP Statistics!

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

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.



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 approximately 36 megabytes.

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.



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

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.

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.



Search Engines

The Search Engines section contains the options for which search engines you want to track. 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

Baidu

On/Off

Enable/disable Baidu.

Bing

On/Off

Enable/disable Bing.

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

Chart type

Line/Spline/Area/Area Spline/Column/Bar/Scatter

This lets you select the type of chart that is displayed for some of the statistics pages. Some items ignore this setting as only one chart type makes sense in those instances.

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.


Map

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

Setting

Values

Description

Disable map

On/Off

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

Alternate map location

On/Off

The map's default location is at the top of the overview page, this option if enabled, will move it to above the “Recent Visitors” section.

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.



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.

Time send

Hourly/Twice Daily/Daily

How often to send the report.

Send Statistical reporting to

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.

Send Content Report

Text

This is the report text which will be sent, you can use the following variables in the report:


User Online: %user_online%

Today Visitor: %today_visitor%

Today Visit: %today_visit%

Yesterday Visitor: %yesterday_visitor%

Yesterday Visit: %yesterday_visit%

Total Visitor: %total_visitor%

Total Visit: %total_visit%





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

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.



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.

GeoIP

The GeoIP page contains the settings to control the GeoIP data collection.



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

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.

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.

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.



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 four tabs; Resources/Information, Export, Purging and Updates.

Resources/Information

The Resources/Information page has 3 subsections to it; Resources, Version 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.

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.



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 required for the GeoIP code, if it is not installed GeoIP will be disabled.



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.

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:

Excel, XML, CSV, TSV

The format to export to.


Excel will export an XML formatted XLS file (you may see a warning from Excel about the file not being in the correct format, you can ignore it).


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.



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.

Updates

The Updates page allows you to update the GeoIP data in the database for visitors that are missing the information. It also provides the current database size and file time.

Setting

Values

Description

File Date

Date/Time

This is the file date/time of the current database.

File Size

Bytes

This is the size, in bytes of the current database.

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.



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 three areas:




The title (Browsers in the above example), a “more” link (if applicable) and a “Minimize/Maximize” control (on the far right).



The “more” link will take you to a separate page with additional or more comprehensive statistics on the related items.



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

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.

Browsers

This displays a pie chart (not configurable) of the different 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 on map

This displays your visitors today on a Google map. This requires the GeoIP code to be enabled.

Hits Statistical Chart

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

Search Engine Referrals Statistical Chart

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 Pages Visited

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.

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.

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.



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.



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.

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

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



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]

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 (bing/duckduckgo/google/yahoo/yandex).




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.




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 41 of 43