Amazing WP Analytics Documentation

Requirements

Installation and quick start

1. Upload the plugin folder to wp-content/plugins/, or install its ZIP through Plugins → Add New → Upload Plugin.
2. Activate Amazing WP Analytics. Required tables and conservative defaults are created automatically.
3. Open AWP Analytics → License, enter the purchased license key, and activate it.
4. Open AWP Analytics and review Settings. The default 356-day retention and role exclusions suit many sites.
5. Add a custom URL goal or enable only the automated goals your site needs.
6. Visit the public site in a non-excluded browser, stay beyond the tracker delay, then return to the dashboard.

Collection flow

1. Page finishes loading
2. The quiet delay elapses
3. The small tracker loads
4. A beacon records the view
5. The dashboard reads compact roll-ups

License activation and updates

Open AWP Analytics → License, enter the purchased license key, and select Activate License.

• A valid license unlocks the dashboard, Live visitors, Import reports and plugin updates.
• Tracking remains active while reports are locked by an invalid or inactive license.
• WordPress performs daily license validation and licensed update checks.
• The License page includes a manual update check.

How tracking works

The public page receives a tiny delayed loader. After page load and an eight-second quiet window, it requests the roughly 1 KB core tracker and sends one fire-and-forget page-view beacon. Public page rendering performs no analytics report queries.

Dashboard

The main Amazing WP Analytics page supports From and To date filters. Headline values compare the selected range with the immediately preceding equal-length range: green indicates an increase and red indicates a decrease.

Available report panels

Top pages and unique views, referrers, channels, devices, countries, browsers and operating systems, screen resolutions, landing pages, exit pages, detected bots, goal conversions, routes to goals, traffic hours, weekdays, languages, UTM campaigns, content types, 404 views, conversion entry pages, and optional engagement reports.

Metrics reference

Live visitors

Open AWP Analytics → Live to see the latest access for each hashed connection IP active during the most recent five minutes.

• Filter by All, Human, or Bot.
• A numbered world map groups filtered live visitors by country, with Unknown in the legend.
• Hover or keyboard-focus a badge for the full country name and separate human and bot totals.
• Zoom from 1× to 4× and drag to pan. Badge size remains visually stable and anchored.
• The dashboard country map uses the selected date range and the same top-25 values as the Countries panel.
• The Live page refreshes every 20 seconds and pauses while hidden.
• The default limit is 200 current rows with a hard maximum of 500; the activity window defaults to five minutes.

Bots and AI crawlers

Bot detection examines the reported user agent and maps recognized signatures to bounded crawler-family names. Raw user-agent strings are not stored. Families include major search crawlers, SEO crawlers, social previews, performance tools, headless browsers, command-line clients, and common AI crawler or user-fetch agents.

Goals

Custom URL goals

Create a goal name, choose URL contains or URL exactly matches, and enter a normalized path such as /thank-you/ or /order-received/.

Automated server-side goals

Automated goals are disabled by default, add no public script, and run only on a supported plugin’s completion hook. Each source event is irreversibly hashed and deduplicated.

Existing historical orders, purchases, submissions, memberships, and completions are not imported retroactively. Automated conversions appear in Goal conversions but have no browser route.

Enhanced engagement

Enhanced engagement is optional and disabled by default. It listens for scroll milestones, visibility and active time, outbound links, downloads, telephone and email links, and form start or submission state.

Settings reference

Legacy analytics import

In order to import statistics data from your previous stats plugin to Amazing WP Analytics, open AWP Analytics → Import to copy compatible aggregate history. Imports run only on this administration page, use short resumable AJAX batches, and never modify or delete source tables.

Only equivalent metrics are copied. Missing sessions, bounce information, devices, routes, geography, or engagement are not estimated. Matomo page and referrer detail requires retained raw Matomo tables.

Privacy and data storage

The plugin adds suggested wording to WordPress’s Privacy Policy Guide. Site owners remain responsible for adapting their privacy notice, lawful basis, consent configuration, and retention policy.

Performance and server load

• The core tracker loads after page load and an eight-second quiet window.
• Collection uses sendBeacon where available and does not block navigation.
• Public page rendering performs no analytics report queries.
• Most reports read compact indexed daily roll-ups.
• Native canvas charts avoid a third-party charting library.
• Dashboard and Live polling run only while their administration tabs are visible.
• Database-size calculation is cached for three hours.
• Cleanup uses bounded batches and schedules continuation when needed.

Developer hooks

Consent

add_filter( 'awa_tracking_allowed', function () {
	return ! empty( $_COOKIE['analytics_consent'] );
} );

Trusted proxy connection address

Live hashes REMOTE_ADDR by default. Override it only when the hosting configuration guarantees the selected proxy header cannot be supplied directly by a visitor.

add_filter( 'awa_connection_ip', function ( $address ) {
	if ( isset( $_SERVER['HTTP_CF_CONNECTING_IP'] ) ) {
		return sanitize_text_field( wp_unslash( $_SERVER['HTTP_CF_CONNECTING_IP'] ) );
	}
	return $address;
} );

Live report limits

add_filter( 'awa_live_window_minutes', function () {
	return 10;
} );

add_filter( 'awa_live_visitor_limit', function () {
	return 300;
} );

AI crawler families

add_filter( 'awa_ai_bot_names', function ( $names ) {
	$names[] = 'My AI crawler';
	return $names;
} );

Custom automated goal

add_filter( 'awa_automated_goal_integrations', function ( $definitions ) {
	$definitions['my_integration'] = array(
		'name'        => 'My completed event',
		'description' => 'Counts a completed event from My Plugin.',
		'detected'    => class_exists( 'My_Plugin' ),
	);
	return $definitions;
} );

do_action( 'awa_record_automated_conversion', 'my_integration', $private_event_id );

Primary filters

awa_tracking_allowed, awa_excluded_roles, awa_tracker_delay, awa_tracker_config, awa_collection_max_body_bytes, awa_token_grace_weeks, awa_require_same_origin, awa_collection_rate_limit, awa_query_parameter_allowlist, awa_normalized_path, awa_country_code, awa_connection_ip, awa_is_bot, awa_bot_name, awa_ai_bot_names, awa_track_bots, awa_live_window_minutes, awa_live_visitor_limit, awa_automated_goal_integrations, awa_enabled_automated_goals, awa_automated_conversion_allowed, awa_retention_days, awa_cleanup_batch_size, awa_cleanup_time_limit, awa_top_pages_limit, awa_database_size_cache_ttl, awa_import_sources, awa_import_batch_days, and awa_import_day_data.

Lifecycle actions

awa_before_tracking_enqueue, awa_after_tracking_enqueue, awa_collection_rejected, awa_before_collect, awa_after_collect, awa_after_engagement_collect, awa_bot_recorded, awa_record_automated_conversion, awa_automated_conversion_recorded, awa_automated_goals_saved, awa_database_error, awa_after_cleanup, awa_schema_upgraded, awa_goal_saved, awa_goal_deleted, awa_settings_saved, awa_import_started, awa_imported_day, awa_import_completed, awa_best_months_updated, and awa_best_months_invalidated.

Troubleshooting

Changelog