=== HitCounters Analytics ===
Contributors: hitcounters
Tags: analytics, statistics, visitors, real-time, tracking
Requires at least: 5.0
Tested up to: 6.9
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Real-time visitor analytics for WordPress. Live visitors, AI traffic detection, engagement scoring — no GA4 complexity, no cookie banner.

== Description ==

**HitCounters** is a simple, real-time alternative to Google Analytics 4 for WordPress site owners who want useful visitor logs without the GA4 learning curve. This plugin connects your WordPress site to the HitCounters service with one tracking code.

After saving your tracking code, you get:

* **Real-time visitor list** — see live visits with location, referrer, browser, and pages viewed (not just numbers)
* **Engagement scoring** — visitors who viewed 2+ pages vs bounced, with average time and scroll depth
* **AI traffic detection** — ChatGPT, Claude, Perplexity, Gemini, and Microsoft Copilot surfaced as their own traffic source
* **Bot filtering** — quality scores 0-100 per visit so you can filter junk traffic
* **URL goals and custom events** — track conversions without writing event code (URL goals work automatically; events via `hcEvent()` JS API)
* **Email digest reports** — weekly or monthly traffic summaries to your inbox
* **Traffic-spike and bot-spike alerts** — opt-in per site
* **No third-party cookies** — tracker uses scoped first-party `localStorage`; no cookie banner required for analytics use

The plugin itself is lightweight: it just adds an async `<script>` tag to your site's `<head>` (or footer if you prefer). The actual tracker is under 25 KB and loads asynchronously, so it has no measurable impact on page speed.

A free [HitCounters](https://hitcounters.com/) account is required to get a tracking code. The free tier covers unlimited page views and stores your most recent 500 sessions per site — suitable for personal sites and small blogs indefinitely.

== Installation ==

1. In WordPress, go to **Plugins → Add New → Upload Plugin** and choose the plugin .zip, or unzip into `wp-content/plugins/` manually.
2. Activate the plugin through the **Plugins** menu.
3. Go to **Settings → HitCounters**.
4. Sign up at [hitcounters.com](https://hitcounters.com/register.php), add your WordPress site, and copy your 16-character tracking code.
5. Paste the tracking code into the plugin settings and click **Save Settings**.
6. Open the front of your site in a private window, then return to your [HitCounters dashboard](https://hitcounters.com/dashboard/sites.php) and click **Verify** next to your site.

== Frequently Asked Questions ==

= Is HitCounters free? =

Yes. The free plan supports unlimited page views and stores your most recent 500 sessions per site, with daily aggregates kept forever. No credit card required.

= Does this plugin slow down my site? =

No. The plugin only outputs a single `<script async>` tag pointing at hitcounters.com. The actual tracker is under 25 KB and is loaded asynchronously, so it never blocks page rendering. PageSpeed and Lighthouse will not flag it.

= Does this plugin set cookies? =

No. The tracker uses scoped first-party `localStorage` (visible only to your own site's origin) instead of cookies. No third-party identifiers, no cross-site tracking, no advertising sync. A cookie banner is not required for analytics use.

= Will logged-in admins be counted? =

Not by default. The plugin has an "Exclude admins" option that is enabled by default and skips the tracking snippet for users with the `manage_options` capability. Untick it if you want admins counted.

= Can I exclude specific IPs (e.g. my office network)? =

Yes — in your HitCounters dashboard, open your site's settings and add IPs to the "Exclude my own visits" list. Server-side filtering applies regardless of which device the visit comes from.

= How do I track conversions? =

In your HitCounters dashboard, go to **Goals**. Two types are supported:

* **URL goals** — fire automatically when a visitor reaches a matching URL (e.g. `/thank-you`). No code required.
* **Event goals** — fire when your site calls `hcEvent('event_name')`. Add the call from your theme or another plugin (for example, on a form-submit success handler).

= Does it work with Multisite? =

Each subsite needs its own tracking code, configured under that subsite's **Settings → HitCounters**. Network activation is supported, but the settings are per-site.

= Does it work with caching plugins (WP Rocket, W3 Total Cache, etc.)? =

Yes. The plugin outputs a static `<script>` tag, which is cache-safe. Make sure your cache plugin doesn't strip async script tags.

= What about GDPR / CCPA? =

The tracker collects pseudonymous visit data only (URL, referrer, browser, country, screen size). No personally identifiable information is collected. We don't share data with third parties or use it for advertising. See our [Privacy Policy](https://hitcounters.com/privacy.php) for the full details, and the **External Services** section below for a complete list of what's sent and where.

= Can my visitors opt out? =

Yes. Any visitor can opt out for their browser by appending `?hc_optout=1` to any URL on your site. A persistent flag is set in their browser and the tracker skips on that device until they revisit with `?hc_optout=0`.

== External Services ==

This plugin connects your site to **HitCounters.com** (operated by HitCounters) to record visitor analytics. Per WordPress.org guidelines, here's exactly what is sent, when, and to whom.

**Service:** HitCounters.com

**Provider:** HitCounters — [https://hitcounters.com](https://hitcounters.com)

**Provider Terms / Privacy:**
[Terms of Service](https://hitcounters.com/terms.php) · [Privacy Policy](https://hitcounters.com/privacy.php)

**What this plugin sends, when:**

* **When:** On every page load on the front end of your site (not in the WP admin).
* **Endpoint:** `https://hitcounters.com/api/tracker.js` (loaded as an external script)
* **Endpoint:** `https://hitcounters.com/api/track.php` and `/api/beacon.php` (called by the loaded script when a visitor browses, scrolls, or leaves a page)
* **Data:** Your tracking code (so HitCounters knows which site the visit is for); the visitor's page URL, page title, referrer URL, browser user-agent, screen and viewport size, country/region/city (geo-resolved from IP), time spent on page, scroll depth, and any UTM parameters present in the URL.
* **NOT sent:** No personally identifiable information (no names, emails, form contents, or post bodies). No cookies are set on visitors' browsers by the tracker.

**Why this plugin sends it:**

To populate the visitor analytics dashboard at your HitCounters account, which only you (and any team members you invite) can see.

**Required for the plugin to work:** Yes. The plugin's sole purpose is to load this script, so disabling the request would defeat the plugin entirely. If you don't want this, simply deactivate the plugin.

**Account requirement:** Yes — a free HitCounters account is required to obtain a tracking code. Sign up at [hitcounters.com/register.php](https://hitcounters.com/register.php).

== Privacy Policy ==

This plugin does not collect any data on its own. The script it loads is owned and operated by HitCounters. For full details on what HitCounters collects, how it is stored, and your visitors' rights, see [https://hitcounters.com/privacy.php](https://hitcounters.com/privacy.php).

== Screenshots ==

1. The plugin settings screen under **Settings → HitCounters** — one field for your tracking code plus head/footer and admin-exclusion toggles.
2. The HitCounters real-time visitor dashboard your visits will populate.
3. The Goals page where you define URL or event-based conversions.

== Changelog ==

= 1.0.0 =
* Initial release.
* Settings page with tracking code field, head/footer placement toggle, exclude-admins toggle.
* Filter `hitcounters_skip_tracking` lets other plugins skip the tracker on specific requests.
* Full translation support (`__()` / `_e()` / `esc_html__()`); all output escaped.
* Privacy section on the settings page describing what data is collected.
* Goals page link in plugin settings opens the correct site directly.

== Upgrade Notice ==

= 1.0.0 =
Initial release.
