Installation

How to install Burst Statistics (free and pro), system requirements, and what happens during plugin initialisation.

---

System requirements

Requirement	Minimum
WordPress	6.6
PHP	8.0

---

Installing Burst Statistics (free)

1. In your WordPress admin, go to Plugins → Add New.
2. Search for Burst Statistics.
3. Click Install Now, then Activate.
4. You are redirected to the Burst onboarding wizard automatically.

---

Installing Burst Pro

ProAvailable in Burst Pro

Burst Pro is the commercial version of Burst Statistics. It requires a valid licence key and either an existing free installation or a fresh install. Learn more about Burst Pro

Option A — fresh install (no free version present)

1. Download burst-pro.zip from your account at burst-statistics.com.
2. In your WordPress admin, go to Plugins → Add New → Upload Plugin.
3. Choose the zip file and click Install Now, then Activate.
4. You are redirected to the onboarding wizard, where you will be prompted to enter your licence key.

Option B — upgrade from free to pro

1. Keep the free plugin active.
2. Upload and activate Burst Pro as described above.
3. The compatibility layer (class-compatibility.php) prevents conflicts during the transition; the free plugin is deactivated automatically.
4. The onboarding wizard restarts so you can configure your licence key.

Option C — auto-installer (from the dashboard)

When the install_pro query parameter is present in an admin request, Burst triggers its built-in Auto_Installer class to download and activate the Pro plugin without leaving the dashboard.

---

Headless installation

Burst supports headless WordPress setups where tracking data is collected from a decoupled frontend (e.g. a Next.js or Nuxt site) and stored in a WordPress backend.

Prerequisites

• A WordPress site running Burst Pro (the analytics backend)
• A separate frontend domain that will be tracked
• Ability to define PHP constants in wp-config.php on the WordPress backend

Configuration

Define the BURST_HEADLESS_DOMAIN constant in wp-config.php on your WordPress backend, pointing to the frontend domain you want to track:

define( 'BURST_HEADLESS_DOMAIN', 'https://example.com' );

When BURST_HEADLESS_DOMAIN is defined, Burst applies the following behaviour:

• The frontend tracking script is not enqueued on the WordPress site itself.
• The tracking endpoint accepts requests from the configured domain (added automatically to the allowed origins list).
• The onboarding tracking step is skipped, because tracking is installed on a separate site.
• A Download Burst Client plugin button appears under Settings → Advanced → Scripts. This generates a zip that can be installed as a companion plugin on the frontend (or used as a reference for a custom integration).
• The ghost_mode and combine_vars_and_script fields are hidden, since they do not apply to a decoupled frontend.
• For hook-based goals, the hook option is removed from the goal type selector when cookieless tracking is enabled, as hook triggers require a UID that is only available through client-side tracking in that mode.

Allowed origins

The tracking endpoint (endpoint.php) accepts cross-origin requests from:

• The domain defined in BURST_HEADLESS_DOMAIN.
• Any additional domains listed in the BURST_ALLOWED_ORIGINS constant (comma-separated).

Both constants can be used together. The endpoint strips the protocol from each entry, so https://example.com and example.com are treated as equivalent.

define( 'BURST_HEADLESS_DOMAIN', 'https://example.com' );
define( 'BURST_ALLOWED_ORIGINS', 'https://staging.example.com,https://preview.example.com' );

---

Tracker-only mode

Define the BURST_TRACK_ONLY constant in wp-config.php to run the plugin as a pure tracker on a site where no one will ever open the Burst dashboard. This is intended for nodes in a multi-site fleet whose statistics are consumed elsewhere (for example via MainWP or a headless backend).

define( 'BURST_TRACK_ONLY', true );

When BURST_TRACK_ONLY is truthy:

• Frontend_Admin is not instantiated, so the admin bar additions and front-end admin UI are skipped.
• Inside Admin::init(), only the recalculation cron handlers (last-statistic data, known UIDs, bounces, first-time visits) are wired up. The settings UI, onboarding, capability filters, deactivation popup, dashboard widget, share manager, and all other admin-facing hooks are not registered.
• has_admin_access() returns false for normal callers. The Burst::init() bootstrap calls has_admin_access( true ) so that the tracker-only Admin instance can still be created for its cron handlers — see the parameter note below.

Tracker-only mode is mutually compatible with BURST_HEADLESS_DOMAIN: a backend can be both headless and tracker-only if statistics are consumed exclusively through the REST API or a remote dashboard.

---

What happens on activation

Free plugin

The activation hook runs the following steps the first time the plugin is activated:

Action	Option / transient written
Record activation timestamp	burst_activation_time
Schedule redirect to settings	burst_redirect_to_settings_page (transient, 5 min)
Flag onboarding to start	burst_start_onboarding
Flag defaults to be written	burst_set_defaults

Pro plugin

The activation hook (burst_on_activation_premium) runs additional steps:

Action	Option written
Flag premium upgrade routine	burst_run_premium_upgrade
Flag activation	burst_run_activation
Record pro activation timestamp	burst_activation_time_pro
Restart onboarding (first pro activation only)	deletes burst_skipped_onboarding, burst_completed_onboarding

caution

If the constant BURST_FORCE_ONBOARDING is defined (e.g. in wp-config.php), the onboarding is forced to restart on every pro activation, and the options burst_skipped_onboarding, burst_completed_onboarding, and burst_onboarding_free_completed are deleted.

---

What happens on deactivation

When either plugin is deactivated, all scheduled cron events are cleared:

Cron hook cleared
burst_every_ten_minutes
burst_every_hour
burst_daily
burst_weekly

No data or options are deleted on deactivation. Use Settings → Reset inside the dashboard if you want to remove stored data.

---

Plugin initialisation sequence

Both the free and pro plugins hook into plugins_loaded. The priority order is:

Priority	What runs
1	burst_loader() called — creates the Burst singleton
9	Burst::init() executes inside the singleton

Inside Burst::init()

The following components are initialised in order:

1. Constants — defines all BURST_* constants (paths, URLs, version, etc.).
2. Auto-Installer — instantiated only when ?install_pro is present in the request.
3. Integrations — third-party plugin integrations (e.g. WooCommerce, WPML).
4. Frontend_Admin — loaded only when a user is logged in and BURST_TRACK_ONLY is falsy; handles admin-bar and front-end admin UI.
5. Admin + Capability — loaded for users who pass the has_admin_access( true ) check; registers the dashboard, settings, and role capabilities. The true argument lets the Admin class instantiate on tracker-only deployments so its recalculation cron handlers remain wired up, while Admin::init() itself short-circuits the settings UI, tasks, and other admin hooks when BURST_TRACK_ONLY is truthy.
6. Pro — loaded only when the constant BURST_PRO_FILE is defined (i.e. the pro plugin is active).
7. Frontend — always loaded; handles visitor tracking on the public-facing site.

---

Constants defined at runtime

The following PHP constants are defined during every request after plugins_loaded fires.

Constant	Description
BURST_FILE	Absolute path to the active plugin's main file
BURST_PATH	Absolute path to the plugin directory (with trailing slash)
BURST_URL	Full URL to the plugin directory, scheme-aware
BURST_DASHBOARD_URL	URL to the Burst admin page (admin.php?page=burst)
BURST_PLUGIN	Plugin basename (e.g. burst-pro/burst-pro.php)
BURST_PLUGIN_NAME	Display name: Burst Pro or Burst Statistics
BURST_VERSION	Current plugin version (3.4.2.1)
BURST_PRO	true when the pro plugin is active (undefined otherwise)
BURST_PRO_FILE	Absolute path to burst-pro.php (pro only; undefined otherwise)
BURST_TRACK_ONLY	Defaults to false if not pre-defined in wp-config.php. See tracker-only mode. Added in v3.4.2.1.

caution

The constants burst_version and burst_pro (lowercase) are deprecated aliases kept for backward compatibility. Do not use them in new code.

Optional configuration constants

These constants are not defined by Burst itself. Define them in wp-config.php to change plugin behaviour.

Constant	Purpose
BURST_HEADLESS_DOMAIN	Enables headless mode and whitelists the frontend origin for the tracking endpoint. Added in v3.4.0, replaces BURST_HEADLESS.
BURST_ALLOWED_ORIGINS	Comma-separated list of additional origins allowed to send tracking requests.
BURST_TRACK_ONLY	When truthy, runs the plugin in tracker-only mode: skips Frontend_Admin and most admin hooks while keeping tracking and recalculation crons active. Added in v3.4.2.1.
BURST_FORCE_ONBOARDING	When truthy, restarts onboarding on every pro activation.
BURST_DO_NOT_UPDATE_GEO_IP	When truthy, disables automatic GeoIP database updates.
BURST_DONT_USE_SUMMARY_TABLE	When truthy, bypasses the summary table and queries raw statistics tables directly.

---

Admin access check

Most admin-facing code in Burst is gated behind the has_admin_access() helper. The signature is:

protected function has_admin_access( bool $allow_track_only = false ): bool;

Parameter	Type	Default	Description
$allow_track_only	bool	false	When true, the check returns based on user capabilities even if BURST_TRACK_ONLY is truthy. Use this only for code paths that must keep working on tracker-only deployments — for example, registering tracking-related cron handlers.

Changed in v3.4.2.1: added the $allow_track_only parameter. With the default value, has_admin_access() returns false whenever BURST_TRACK_ONLY is truthy, regardless of the current user's capabilities. Pass true only when you are certain the code path must remain active on tracker-only sites.

Show code

// Standard gate — refuses on tracker-only sites.
if ( $this->has_admin_access() ) {
    // Register the settings page, dashboard widget, etc.
}

// Tracker-tolerant gate — still works when BURST_TRACK_ONLY is true.
if ( $this->has_admin_access( true ) ) {
    add_action( 'burst_recalculate_bounces_cron', [ $this, 'recalculate_bounces' ] );
}

---

Upgrade routine

Burst hooks its version check on every request during init, but the upgrade routine itself returns early unless the current request has Burst admin access. When the stored burst-current-version option differs from BURST_VERSION, the upgrade routine runs:

1. Action burst_upgrade_before fires.
2. Version-specific migration methods run sequentially up to the currently installed plugin version.
3. Database tables are created or altered via run_table_init_hook().
4. Action burst_upgrade_after fires.
5. burst-current-version is updated to BURST_VERSION.

burst_upgrade_before

Fires immediately before any upgrade migration runs.

Parameters:

Parameter	Type	Description
$current_version	string	The version stored in the database before the upgrade

Example:

add_action( 'burst_upgrade_before', function( $current_version ) {
    // e.g. back up custom data before a migration
} );

burst_upgrade_after

Fires immediately after all upgrade migrations have completed and the version option has been updated.

Parameters:

Parameter	Type	Description
$new_version	string	The version the plugin has just upgraded to

Example:

add_action( 'burst_upgrade_after', function( $new_version ) {
    // e.g. flush a cache after upgrade
} );

burst_activation

Fires after Burst finishes its standard activation/bootstrap flow.

Use this action for one-time initialization that should happen when the plugin becomes active on a site.

burst_on_premium_upgrade

Fires when the Pro plugin detects that it should run the premium-upgrade path after replacing or deactivating the free plugin.

This is the correct action to hook into when you need post-upgrade logic specifically for the free-to-pro transition.

burst_possible_capability_types

Filters the capability types that Burst recognizes when assigning custom capabilities to roles.

Default values: view, manage.

burst_add_{$type}_capability

Dynamic filter used when Burst assigns a capability type to roles.

For example, burst_add_view_capability filters the roles that should receive view_burst_statistics.

Example:

Show code

add_filter( 'burst_add_view_capability', function( array $roles ): array {
    $roles[] = 'shop_manager';
    return array_values( array_unique( $roles ) );
} );

---

Database tables

Burst creates and manages the following custom database tables on activation and upgrade. All tables use the site's configured $wpdb->prefix.

Table	Purpose
burst_statistics	Raw visitor page-view records
burst_sessions	Session-level data
burst_goals	Goal definitions
burst_goal_statistics	Goal conversion records
burst_browsers	Browser lookup table
burst_browser_versions	Browser version lookup table
burst_platforms	OS/platform lookup table
burst_devices	Device-type lookup table
burst_referrers	Referrer URL storage
burst_known_uids	Unique visitor UID tracking
burst_query_stats	Search query statistics

---

Error handling during load

If a fatal error occurs while the plugin bootstraps (e.g. a missing dependency or incompatible PHP version), Burst catches the Throwable, logs it via error_log, and records the following options:

Option	Content
burst_php_error_time	Unix timestamp of the last error
burst_php_error_count	Cumulative error count
burst_php_error_detected	Concatenated error messages (newline-separated)

An admin notice is displayed in the WordPress dashboard until the error is resolved:

Urgent action required
Burst can not load due to the following error: …

---

Multisite

Burst Statistics supports WordPress Multisite.

It can be activated per site or network-activated. When it is network-activated, Burst still uses the regular site admin screen rather than a separate network settings page.

On the main site of a network-activated install, Burst exposes a track_network_wide setting labelled Track all hits networkwide, and view them on the dashboard of your main site. When that setting is enabled, Burst routes tracking to the main site's endpoint and shows the dashboard only on the main site. When it is disabled, each site continues to track separately with its own prefixed tables.