SVAL Analytics

English · فارسی

Lightweight, self-hosted visitor analytics for WordPress. All data stays in your own database: no third-party service, no cookies, no IP addresses stored.

Features

• Pageviews, visitors, sessions, new vs. returning visitors, average time on page
• Top pages, referrers, languages, devices, browsers
• UTM campaign report (utm_source, utm_medium, utm_campaign)
• Country estimate from the browser timezone (no GeoIP database needed)
• Admin dashboard with charts (Chart.js)
• Privacy controls: Do Not Track, optional consent mode, data retention, raw user-agent off by default
• Bots are ignored, administrators are excluded by default
• Works with page caching (the tracker config is identical on every page)
• Clean uninstall (table, options and cron are removed)

Requirements

WordPress 5.8+ and PHP 7.4+.

Installation

1. Download this repository as a ZIP (or clone it) and make sure the folder is named sval-analytics.
2. Copy it to wp-content/plugins/ and activate SVAL Analytics.
3. Open SVAL Analytics → Settings to review the options, then visit your site to generate data.

Settings

Consent mode

If you enable Require consent, call these from your cookie/consent banner:

window.SVAL.grant();   // start tracking, remember the choice
window.SVAL.revoke();  // stop tracking, delete the stored visitor id

Developer hooks

// Don't track certain pages/users.
add_filter( 'sval_should_track', function ( $track ) {
    return is_page( 'private' ) ? false : $track;
} );

// Add or override timezone => country mappings.
add_filter( 'sval_timezone_map', function ( $map ) {
    $map['Asia/Tehran'] = array( 'code' => 'IR', 'name' => 'Iran' );
    return $map;
} );

// Accept extra hostnames in tracked URLs (e.g. a www alias).
add_filter( 'sval_allowed_hosts', function ( $hosts ) {
    $hosts[] = 'www.example.com';
    return $hosts;
} );

// Rate limit (events per client per minute, default 120; 0 disables).
add_filter( 'sval_rate_limit_per_minute', fn() => 300 );

// Client IP used only for rate limiting, e.g. behind a trusted proxy.
add_filter( 'sval_client_ip', fn( $ip ) => $_SERVER['HTTP_X_FORWARDED_FOR'] ?? $ip );

Privacy

• Stored per event: page URL and title, referrer, UTM tags, browser timezone, language, screen size, device/browser/OS, a random visitor id (browser local storage) and a session id.
• IP addresses are never stored. The client IP is only hashed (with a site-specific salt) for a one-minute rate-limit counter.
• A suggested privacy-policy paragraph is added under Settings → Privacy → Policy Guide.
• Depending on your jurisdiction (e.g. GDPR/ePrivacy), a persistent visitor id may require consent. Use Require consent if in doubt. This is not legal advice.

Limitations

• Country is estimated from the browser timezone. VPN users, travellers and unusual timezones can be misattributed; unknown zones show as "Unknown".
• The dashboard loads Chart.js from the jsDelivr CDN. If you need zero third-party requests, download Chart.js into assets/ and change the wp_enqueue_script call in includes/admin.php.
• Single-site only (multisite is not supported yet).
• Raw data lives in one table ({prefix}sval_visits); very high-traffic sites should use a dedicated analytics tool.

Contributing

Issues and pull requests are welcome. Please follow the WordPress coding standards.

License

GPL-2.0-or-later. See LICENSE.