=== Koko Analytics ===
Contributors: Ibericode, DvanKooten
Donate link: https://wordpress.org/support/plugin/koko-analytics/reviews/#new-post
Tags: analytics, statistics, stats, privacy, counter
Requires at least: 6.0
Tested up to: 6.7
Stable tag: 1.7.3
License: GPL-3.0-or-later
License URI: http://www.gnu.org/licenses/gpl-3.0.html
Requires PHP: 7.4
Privacy-friendly and efficient analytics for your WordPress site
== Description ==
Koko Analytics is a privacy-friendly website analytics plugin for WordPress. It does not use any external services, so no data is shared with any third-party. Nothing specific to any individual visitor is collected, only aggregated counts.
Stop sharing visitor data with third-party companies who also happen to sell ads. Stop slowing down your website with large tracking scripts. Liberate your website analytics!
[Koko Analytics](https://www.kokoanalytics.com/) lets you focus on the important metrics, while respecting the privacy of your visitors.
You can view a [live demo of Koko Analytics here](https://www.kokoanalytics.com/?koko-analytics-dashboard).
### Features
- **Plug and play**: After installing and activating the plugin, stats will automatically be collected.
- **No external services**: Any data never leaves your server.
- **No personal data** or anything visitor specific is tracked.
- **No cookies**: There is an option to not use any cookies.
- **Fast**: Handles hundreds of concurrent pageviews without breaking a sweat.
- **Lightweight**: Adds less than 850 bytes of data to your pages. A year worth of data will take up less than 10 MB of storage.
- **GDPR Compliant** by design.
- **Metrics**: All the essentials: total pageviews, unique pageviews and referral URL's.
- **Referrer spam:** Built-in blocklist to filter out referrer spam.
- **REST API**: You can access your data from anywhere via REST API endpoints.
- **Cached**: Fully compatible with pages served from any kind of cache.
- **Open-Source**: The plugin code is [open-sourced](https://github.com/ibericode/koko-analytics) under the GPL-3.0-or-later license.
- **Tested**: Ready for PHP 8.4, but compatible down to PHP 7.3.
- **AMP**: Tracks AMP powered pages too ([official AMP plugin](https://wordpress.org/plugins/amp/) only).
- **Import data from other plugins**: You can import historical analytics data from Jetpack Stats or Burst Statistics into Koko Analytics.
### Koko Analytics Pro
All of the features listed above are available for free. Some additional features are available through [Koko Analytics Pro](https://www.kokoanalytics.com/pricing):
- [Event Tracking](https://www.kokoanalytics.com/features/custom-event-tracking/): track outbound link clicks, form submissions or any other type of custom event.
- [Email Reports](https://www.kokoanalytics.com/features/email-reports/): Receive a daily, weekly or monthly email summary of your website's most important statistics.
- [CSV Export](https://www.kokoanalytics.com/features/csv-export/): The ability to export your dashboard data to CSV for advanced analysis.
- [Pageviews Column](https://www.kokoanalytics.com/features/pageviews-column/): Shows the number of pageviews over a configurable time period right in your WP Admin posts and pages overview.
- [Admin Bar](https://www.kokoanalytics.com/features/admin-bar/): Shows daily pageviews for a specific page in your WordPress Admin Bar.
- [Traffic Spike Notifications](https://www.kokoanalytics.com/features/traffic-spike-notifications/): receive an email notification when your website experiences a traffic spike.
You can [purchase Koko Analytics Pro here](https://www.kokoanalytics.com/pricing/).
### Contributing
You can help with Koko Analytics in many different ways. For example:
- [Purchase Koko Analytics Pro](https://www.kokoanalytics.com/pricing/)
- Write about the plugin on your blog or share it on social media.
- [Review the plugin here on WordPress.org](https://wordpress.org/support/plugin/koko-analytics/reviews/#new-post)
- [Translate the plugin into your language](https://translate.wordpress.org/projects/wp-plugins/koko-analytics/stable/) using your WordPress.org account.
- [Vote on feature suggestions in our idea board](https://github.com/ibericode/koko-analytics/discussions/categories/ideas?discussions_q=is%3Aopen+sort%3Atop+created%3A%3E%3D2022-10-25+category%3AIdeas)
### About the plugin author
Koko Analytics is developed by [Danny van Kooten](https://www.dannyvankooten.com/) from his home office in Nijmegen, The Netherlands.
== Installation ==
You can install Koko Analytics in multiple ways:
- In your WordPress admin area, go to **Plugins > New Plugin**, search for **Koko Analytics** and click **Install now**.
- [Download the latest version from WordPress.org](https://downloads.wordpress.org/plugin/koko-analytics.zip) and extract the files into your `/wp-content/plugins/` directory.
- [Download the latest release from GitHub](https://github.com/ibericode/koko-analytics/releases) and extract the files into your `/wp-content/plugins/` directory.
After installing and then activating the plugin, statistics will be collected right away.
You can view your analytics dashboard by going to **WP Admin > Dashboard > Analytics**.
== Frequently Asked Questions ==
#### Does this respect my visitor's privacy?
Yes, absolutely. Koko Analytics only stores aggregated counts. Nothing visitor specific is tracked.
#### Does this use any external services?
No external servives are used. All data lives on your server alone.
### Does Koko Analytics set any cookies?
By default yes, but you can disable it.
Koko Analytics sets a single cookie named `_koko_analytics_pages_viewed` with a lifetime of `6 hours`. This cookie is used to reliably detect unique pageviews and returning visitors without having to store any personal information on your server.
You can disable the use of cookies from the plugin's settings page.
[https://www.kokoanalytics.com/kb/does-koko-analytics-use-cookies/](https://www.kokoanalytics.com/kb/does-koko-analytics-use-cookies/)
### Will this slow down my website?
No, the plugin is built in such a way that it never slows down your website for your visitors.
- It only adds a single script of less than 800 bytes to your pages.
- All heavy lifting (like aggregating the statistics) is done in a background process.
- Everything lives on your server, so the plugin doesn't add any additional DNS look-ups and can benefit from your server's cache policy.
[https://www.kokoanalytics.com/kb/will-koko-analytics-slow-down-my-website/](https://www.kokoanalytics.com/kb/will-koko-analytics-slow-down-my-website/)
### Is the code for this plugin on GitHub?
Yes, see [github.com/ibericode/koko-analytics](https://github.com/ibericode/koko-analytics).
### Where can I find more documentation?
Have a look at the [Koko Analytics knowledge base](https://www.kokoanalytics.com/kb/).
### How to show number of visits to a page?
You can use the `[koko_analytics_counter]` shortcode to show the number of visitors to the current page.
It takes 3 optional arguments:
- `days`: Show count over the last N days. Defaults to "3650".
- `global`: Whether to show the global count (for the entire site) or for the current page only. Defaults to "false".
- `metric`: One of "visitors" or "pageviews". Defaults to "visitors".
Example use with arguments:
`
[koko_analytics_counter days="30" metric="pageviews" global="true"]
`
### Why are category and tag archives not tracked?
Koko Analytics is currently only able to track things that have an internal post ID, which is every (custom) post type. This is so that Koko Analytics does not have to store pathnames, which would take up a lot of storage space or an additional pre-processing step to normalize the data.
### How can I help fund Koko Analytics?
You can [purchase Koko Analytics Pro](https://www.kokoanalytics.com/pricing/) to help fund the plugin.
== Screenshots ==
1. Koko Analytics' dashboard to view your website statistics.
2. The dashboard widget to quickly show your site visits over the last 2 weeks.
3. A widget to show your most viewed posts (or any other post type) for a given period.
4. The settings page where you can exclude certain user roles from being counted.
5. Screenshot of settings page showing some features from Koko Analytics Pro.
6. Koko Analytics Pro can show your pageviews over a configurable time period right in your posts overview.
== Changelog ==
### 1.7.3 - Apr 15, 2025
- Explicitly add referrer to settings page form.
- Fix WP CLI command calling old method. Thanks [Oscar Arzola](https://github.com/arzola)!
### 1.7.2 - Mar 24, 2025
- Hide chart group options on dashboard widget chart.
- Run referrer URL's in dashboard widget through href normalizer.
- Very minor performance optimisation for generating chart HTML.
### 1.7.1 - Mar 10, 2025
- Fix chart bars being out of order for some databases in case of gaps in data.
- Include `manifest.json` file in plugin package.
- Check if uploads directory exists before calling `scandir`.
- Fix Query Loop Block from showing all posts in case of no stats.
- Address some W3C validation warnings for the dashboard HTML.
- Aggregate Reddit subdomains into a single referrer entry.
### 1.7.0 - Feb 25, 2025
- Compatibility with sites hosted on WP Engine (which does not allow writing files with the PHP extension to the WP Uploads directory).
- Use relative paths in optimized endpoint file, so that the site itself can be moved around freely on the filesystem.
- Run aggregator on `upgrader_process_complete` hook so that we can change aggregation logic without losing any data.
- Only use optimized endpoint if the file still exists and is verified to be working. This allows removing the file to immediately switch to the default AJAX endpoint.
- Fix a bug in the most viewed posts widget/shortcode that shows all posts instead of an empty result set.
- Add group by option to chart.
- Better align periods for comparisons.
### 1.6.6 - Feb 18, 2025
- Fix same-page referrer detection when not using cookie.
- Preserve page filter when using datepicker to change date period.
- Limit realtime pageviews in dashboard widget to today's pageviews when viewed shortly after midnight.
### 1.6.5 - Feb 10, 2025
- Add importer for data from Burst Statistics.
- Allow passing "false" and "no" to `monthly` query parameter in REST endpoints.
- Optimize PHP execution time for plugin bootstrapping code by aggressively lazy loading code that only runs on very specific requests. From 0.05 ms to 0.03 ms (!) with OPcache or 1.44 ms to 0.54 ms without OPcache for general requests.
- Minor code improvements to classes responsible for aggregating data from buffer file into permanent storage.
### 1.6.4 - Jan 25, 2025
- Fix dashboard data always publicly accessible through REST API endpoints.
### 1.6.3 - Jan 21, 2025
- Schedule missing `koko_analytics_aggregate_stats` event.
- Ensure pageview counts are always added to the correct day, even if WP Cron stalls for more than 24 hours.
- Improved correctness of the realtime visitor count in case of WP Cron stalls.
- Move the temporary buffer file to its own directory inside the uploads directory.
- Fix syntax error on PHP 7.4 introduced in version 1.6.2
- Jetpack Importer: Fix division by zero if importing a single day of data
- Jetpack Importer: Bump HTTP request timeout for Jetpack importer up from 5 seconds to 90 seconds.
- Jetpack Importer: Allow choosing a custom chunk size, which can be useful for sites with a large amount of posts or pages.
- Do not delete database tables on plugin uninstall by default.
### 1.6.1 - Jan 20, 2025
- Show error details in Jetpack Importer when API returns an error response (instead of only writing to error log).
- Register scheduled event for pruning data on plugin activation directly.
- Allow calling `get_realtime_pageview_count()` function with `null` parameter.
### 1.6.0 - Jan 17, 2025
- Bump minimal required PHP version to 7.4 or higher.
- Fix issue with date generation for "this_week" and "last_week" presets.
- Modify chart tooltip position so it's never causing horizontal overflow.
- Hide chart tooltip on scroll.
- Expand column width of pageviews and visitors column on large screens with ample space.
- Fix undefined array key notice introduced in version 1.5.5.
- Make all strings from Jetpack Importer feature translatable. Thanks to [Alex Lion](https://alexclassroom.com/).
- Fix REST API routes returning a HTTP 500 error if called without a `start_date` parameter.
PS. We've started the works on a [standalone version of Koko Analytics](https://github.com/koko-analytics/koko-analytics/) that allows you to track non-WordPress sites.
You can read some more about it on Danny's personal blog: https://www.dannyvankooten.com/blog/2025/building-privacy-friendly-website-analytics/
### 1.5.5 - Jan 10, 2025
Don't use `upgrader_process_complete` for checking pending database migration. This can't be used because this specific hook runs using the old version of the plugin...
Reverting this change from version 1.5.2 fixes an issue with the optimized endpoint file referencing an unexisting function.
#### 1.5.4 - Jan 10, 2025
- Fix optimized endpoint file referencing no-longer existing file on some installations.
#### 1.5.3 - Jan 09, 2025
- Add integration with Query Loop Block.
- Fix date range when viewing "this week" or "last week" on a Sunday.
- Remove non-functional settings example from [Koko Analytics Pro](https://www.kokoanalytics.com/pricing/) from settings page.
- Add one-time notice after at least 30 days of usage asking for a contribution.
#### 1.5.2 - Dec 17, 2024
- Improve logic for running pending database migrations.
#### 1.5.1 - Dec 10, 2024
- Fix date in chart tooltip using default PHP timezone, explicitly use site timezone instead.
- Check for excluded request (by IP address or user role) in unoptimized endpoint.
- Prevent PHP notice on dashboard if page URL does not have query component.
#### 1.5.0 - Nov 27, 2024
- Impose a maximum referrer URL length on data ingestion.
- Replace column header for visitors and pageviews with icon on small screens.
- Speed up `koko_analytics_counter` shortcode by having `Stats::get_total` not automatically pull in previous period.
- Migrations runner now updates the local database version after each individual step.
- Migrations runner now has a simple lock mechanism to ensure it runs atomically.
- Output database size in localized format.
- Output dates in localized format through `wp_date()`. Thanks to [Dominik Schilling](https://dominikschilling.de/).
- Add missing text domain on settings page. Thanks to [Dominik Schilling](https://dominikschilling.de/).
#### 1.4.5 - Nov 14, 2024
- Use localized number formatting for all numbers troughout the dashboard.
- Add feature to export and import data. Can only be used for sites with matching post ID's.
- Highlight weekends in chart by using a slightly darker color for the visitors part of the bar.
#### 1.4.4 - Nov 4, 2024
- Add Jetpack Stats importer to import your historical analytics data into Koko Analytics. Go to the settings page (with Jetpack still enabled) to access it.
- Fix settings page showing proxy IP instead of client IP if using reverse proxy.
- Fix use of PHP 7.4 only feature in thousands separator in source code.
- Auto-reload dashboard every minute if browser tab is active.
- Do not show chart for just a single day of data.
- Handle posts without title a little better by showing URL path instead.
#### 1.4.3 - Oct 29, 2024
- Fix "backtrack limit exhausted" triggering for certain referrer URL's without a subdomain part.
- Gracefully handle missing referrer blocklist file. This fixes an issue when security software on the server flags the blocklist file as suspicious (due to it containing a list of known malware domains) and deleting it.
- Increase width of first table column so rank isn't showing ellipsis.
- Remove light grey border on table header row.
- Right align numbers in dashboard widget. Thanks [Terence Eden](https://shkspr.mobi/blog/), who also did a wonderful post on [liberating your website statistics from Jetpack](https://shkspr.mobi/blog/2024/10/liberate-your-daily-statistics-from-jetpack/)!
- Improved validation of referrer URL's and request parameters at data collection endpoint.
#### 1.4.2 - Oct 25, 2024
- Fix fatal error "invalid string operand" when referrer URL contains `t.co` shortlink.
- Fix potential issue with `preg_match` returning incorrect type in function `get_referrer_url_label`
#### 1.4.1 - Oct 25, 2024
- Limit width of visitors and pageviews column in tables.
- Fix `preg_replace` from returning an invalid type when an error occurs and the log the actual error that occurred.
#### 1.4.0 - Oct 24, 2024
- All HTML for the dashboard is now server-side generated, drastically reducing the amount of JavaScript and generally making the code base easier to maintain and/or extend.
- All dashboard state can now be managed through URL query parameters, allowing you to bookmark or share your favorite views.
- Use actual `
` elements for dashboard tables, for improved screen reader support.
- Add filter hook `koko_analytics_referrer_url_href` to modify link `href` attribute for referrer URL's in dashboard.
- Add filter hook `koko_analytics_referrer_url_label` to modify link labels for referrer URL's in dashboard.
- Fix admin user not getting `view_koko_analytics` capability upon plugin activation.
- Prevent empty referrer URL from being stored.
- Group various Yandex referrer URL's into a single entry.
- Minor memory usage improvements in autoloader implementation.
#### 1.3.15 - Oct 15, 2024
- Fix `href` attribute on hyperlinks in most viewed posts widget/shortcode/function template.
#### 1.3.14 - Sep 23, 2024
- Explicitly call `sprintf` from global namespace to benefit from upcoming sprintf related performance improvements in PHP 8.4.
- Demo settings from [Koko Analytics Pro](https://www.kokoanalytics.com/pricing/) on plugin settings page.
#### 1.3.13 - Sep 17, 2024
- Ensure `Stats::get_totals` always returns a valid object.
- Escape return values from `add_query_arg` to prevent reflected XSS attacks.
- Use correct IP address even if client is behind proxy.
- Various minor template performance improvements.
#### 1.3.12 - Aug 18, 2024
- Fix double pageview counts introduced in version 1.3.11.
- Fix same-site showing up as referrer
#### 1.3.11 - Aug 16, 2024
- Only use referrer detection for determining returning visitors if cookie is disabled.
- Add referrer aggregation rule for Brevo email campaign links.
- Add referrer aggregation rule for Reddit links.
- Add filter hook for easily adding or modifying Koko Analytics settings.
- Add action hook for adding settings to Koko Analytics.
- Explicitly get rid of all ES6 code in tracking script.
#### 1.3.10 - Jun 20, 2024
- Registration for [Koko Analytics Pro](https://www.kokoanalytics.com/pricing/) is open again. Purchase a license if you need custom event tracking or would just like to support the plugin.
- Ignore requests from Facebook link previews and requests without a `User-Agent` HTTP header.
- Update referrer blocklist.
#### 1.3.9 - May 31, 2024
- Fix Webpack issue with tracking script.
#### 1.3.8 - May 29, 2024
- Add setting to exclude views from IP addresses.
- Show exact number of pageviews and visitors on hover.
- Use an optimized custom autoloader.
- Verify shortcode arguments for `[koko_analytics_counter]` shortcode.
- Fix error when using SQLite about ambiguous column name.
- Fix realtime pageview count using wrong duration.
#### 1.3.7 - Feb 26, 2024
- Add `[koko_analytics_counter]` shortcode. Thanks Anil Kulkarni!
- Show time since last aggregation on settings page.
- Validate data collection request more aggressively before writing to buffer file.
- Update referrer blocklist.
#### 1.3.6 - Jan 29, 2024
- Update referrer blocklist.
- Update third-party JS dependencies.
#### 1.3.5 - Jan 8, 2024
- Fix `HOUR_IN_SECONDS` constant not defined when using AMP with cookie enabled.
- Fix days without any data not showing up in chart.
- Improve chart y-axes for numbers just above 100.000.
#### 1.3.4 - Nov 21, 2023
- New feature that allows you to filter by page. Clicking any page in the "top pages" list now updates the totals and chart component to only show visitors and pageviews for that specific page.
- Fix warning that cron event isn't working not showing.
- Fix error when default date period is stuck at removed period.
- Fix API url for sites not using pretty permalinks.
- Performance improvement for rendering chart and tooltips.
#### 1.3.3 - Nov 6, 2023
- Fix quick navigation going forward.
- Add `manifest.json` file so (standalone) dashboard can be installed as a Progressive Web App.
#### 1.3.2 - Nov 2, 2023
- Fix chart tooltip immediately disappearing when viewing the dashboard widget on touch devices.
- Fix fatal error if lacking permissions to read database size from MySQL information tables.
- Fix double encoding of special characters in post titles.
- Fix arrow-key or arrow-icon navigation when viewing a single day of data.
- Automatically refresh dashboard data every 60s.
- Improve dashboard widget by showing a summary of today.
- Added filter hook `koko_analytics_dashboard_widget_number_of_top_items` to [modify or disable the top pages and referrers in the dashboard widget](https://github.com/ibericode/koko-analytics/blob/master/code-snippets/modify-dashboard-widget/README.md).
- The `[koko_analytics_most_viewed_posts]` shortcode now shows a debug message if the arguments did not lead to any results.
#### 1.3.1 - Nov 1, 2023
- Fix new visitors not being counted.
- Fix dashboard issues for users with a large UTC timezone offset.
- Fix date format in chart component if grouping by month.
- Revert to blue colors for the chart. If you want your chart to use different colors, please see this [example code snippet on how to change colors](https://github.com/ibericode/koko-analytics/blob/master/code-snippets/change-chart-colors.php).
- Change dashboard widget to show just a quick summary of today.
- Show some feedback after using the "create optimized endpoint" button.
#### 1.3.0 - Oct 31, 2023
- Major [performance improvements for the dashboard](https://www.kokoanalytics.com/2023/10/31/speeding-up-dashboard-removing-react-vanilla-js/) by removing the dependency on React and further optimizations.
- Added link for loading the dashboard outside of WordPress admin (standalone).
- Added setting to make the analytics dashboard publicly available.
- Only show button to create optimized endpoint file if location is writable.
- Remove `wp_koko_analytics_dates` on plugin uninstall.
- Optimized database query for getting most viewed posts and cache its results.
- Expand dashboard widget to include realtime pageviews and a list of the most viewed posts.
- Use `navigator.sendBeacon` for data collection requests.
#### 1.2.2 - Oct 18, 2023
- Fix link to settings page from plugins overview page.
- Fix pagination not working because `wp_localize_script` turns everything into a string.
- Fix React warning for dashboard widget when toggling visibility more than once.
- Fix chart tooltip not showing on touch devices.
- Minor styling improvements to settings page.
- Install custom endpoint on plugin activation only.
- Add button to settings page to re-attempt custom endpoint installation.
- Move table pagination to bottom of component and add text label.
- Wrap `input[type="radio"]` in `