Settings Reference

This page documents every configuration field available in Burst Statistics v3.3.0. Fields are organized by the menu tab and group in which they appear in the WordPress admin dashboard.

Required capability: manage_burst_statistics to access Settings. view_burst_statistics for the Dashboard and Insights views.

---

Settings Structure

The settings UI is organized into tabs. Each tab contains one or more groups:

Tab	Groups
General	General, Anonymous Usage Data
Goals	Goals
Data	Archiving, Archived Data, Manage Settings
Advanced	Tracking Exclusions, Tracking Behavior, Scripts
Reporting	Reports, Customization, Logs

---

General Tab

General Group

enable_turbo_mode

Property	Value
Type	checkbox
Default	false
Recommended when	enable_cookieless_tracking is true

Load the tracking script later in the page lifecycle for better PageSpeed scores. Visitors who leave the page very quickly may not be recorded.

---

enable_cookieless_tracking

Property	Value
Type	checkbox
Default	false

Track visitors without setting cookies by using browser and device fingerprinting signals. Useful for GDPR-compliant tracking without a cookie consent banner.

---

enable_do_not_track

Property	Value
Type	checkbox
Default	false

When enabled, Burst will not record pageviews from visitors whose browser sends a DNT: 1 (Do Not Track) HTTP header.

---

dismiss_non_error_notices

Property	Value
Type	checkbox
Default	false

Suppress all non-critical admin notices produced by Burst Statistics. Critical error notices are still shown regardless of this setting.

---

theme_toggle

Property	Value
Type	theme_toggle
Default	"" (system default)

Switch the Burst Statistics dashboard between light and dark mode. This setting affects only the Burst admin UI, not the front end of the site.

---

Internal / Hidden Fields (General Group)

The following fields are present in the settings schema but rendered as hidden inputs. They are managed programmatically and do not appear in the settings UI.

Field ID	Default	Purpose
review_notice_shown	false	Tracks whether the review prompt notice has been shown.
burst_tour_shown_once	false	Tracks whether the onboarding tour has been shown.
not_writable	false	Set to true when the uploads directory is not writable.
tips_tricks_mailinglist	""	Internal field for mailing-list opt-in state.

---

Anonymous Usage Data Group

anonymous_usage_data

Property	Value
Type	anonymous_usage_data (custom component)
Default	false

Controls opt-in to sharing anonymous diagnostic and usage data with the Burst Statistics development team.

---

Goals Tab

Goals Group

goals

Property	Value
Type	goals (custom component)
Default	[]

Manage conversion goals. A goal represents a key action you want visitors to take (e.g., form submission, button click, page visit). Goals are stored as a serialized array.

Each goal tracks: title, type, and goal-specific configuration. Progress toward goals is visible in the Dashboard.

Note: To set effective goals, identify the primary purpose of your site and the measurable actions visitors should complete. See How to set goals for guidance.

---

Data Tab

Archiving Group

archive_data

Property	Value
Type	select
Default	false (none)
Options	none, archive, delete

⭐ Pro

The archive option requires Burst Statistics Pro. Learn more about automated reporting and data management

Controls how Burst handles statistics data older than the retention period defined by archive_after_months.

Option	Behavior
none	Data is never automatically managed.
archive	Data older than the retention period is moved to archive tables. (Pro)
delete	Data older than the retention period is permanently deleted.

Note: The archive option is disabled (visible but not selectable) without Burst Statistics Pro.

---

archive_after_months

Property	Value
Type	number
Default	24
Minimum	12 (filterable — see burst_minimum_archive_months)
Visible when	archive_data is archive or delete

The number of months after which statistics data is archived or deleted, depending on the archive_data setting.

Filter:

/**
 * Adjust the minimum allowed data retention period.
 *
 * @param int $months Minimum number of months. Default 12.
 * @return int
 */
add_filter( 'burst_minimum_archive_months', function( $months ) {
    return 6; // Allow archiving after as few as 6 months.
} );

---

confirm_delete_data

Property	Value
Type	checkbox
Default	false
Visible when	archive_data is delete

A confirmation checkbox that must be checked before automatic data deletion is activated. This prevents accidental permanent data loss.

---

reset

Property	Value
Type	button
Action	reset
Warning type	danger

caution

Irreversible action. Clicking "Reset statistics" permanently deletes all recorded pageviews, goals, and goal statistics. This cannot be undone.

Presents a confirmation dialog before executing. The dialog displays:

• Title: "Are you sure?"
• Message: "This will permanently delete all statistics, goals, and goal statistics. This action can not be undone."

---

Archived Data Group

⭐ Pro

The Archived Data section requires Burst Statistics Pro. Learn more about data management

restore_archives

Property	Value
Type	restore_archives (custom component)
Default	false
Visible when	archive_data is archive

Displays a list of archived data periods that can be restored back into the active statistics tables. Allows recovering historical data without losing current records.

---

Manage Settings Group

export_settings

Property	Value
Type	export_settings (custom component)
Button text	"Download settings file"
Default	false

Generates and downloads a JSON file containing all current Burst Statistics settings. Use this to migrate or copy your configuration to another site.

---

import_settings

Property	Value
Type	upload
Default	false

⭐ Pro

Importing settings requires Burst Statistics Pro. Upgrade to Burst Pro

Upload a previously exported settings file to overwrite the current configuration. The file must be a valid settings export produced by the export_settings feature.

---

Advanced Tab

Tracking Exclusions Group

user_role_blocklist

Property	Value
Type	checkbox_group
Default	false
Options	Dynamically generated from get_user_roles()

Select one or more WordPress user roles whose pageviews should not be recorded. For example, exclude Administrators or Editors to avoid inflating statistics with internal traffic.

Note: Changes to this setting affect new data only. Previously recorded pageviews are not retroactively removed.

---

ip_blocklist

Property	Value
Type	ip_blocklist (custom component)
Default	""
Recommended	true

A newline-delimited list of IP addresses to exclude from tracking. Supports individual IPv4 and IPv6 addresses.

Note: Changes affect new data only.

---

custom_block_rules

Property	Value
Type	textarea
Default	""

A newline-delimited list of strings or regex patterns. A pageview hit is blocked if any entry matches the request's URL, HTTP referrer, or user-agent string.

Supports standard regex syntax. Example patterns:

badbot.example.com
/facebook(externalhit|bot|crawler|preview)/i
staging.mysite.com

---

enable_shortcodes

Property	Value
Type	checkbox
Default	false

Enable Burst Statistics shortcodes so that statistics data can be embedded in posts, pages, and widgets. See Burst Statistics Shortcodes for available shortcodes.

---

Tracking Behavior Group

geo_ip_database_type

Property	Value
Type	radio
Default	city

⭐ Pro

City & Region detail level requires Burst Statistics Pro. Learn more about geographic insights

Controls the granularity of visitor geolocation data collected.

Option	Label	Description
city (recommended)	Country, City & Region	Provides city and region in addition to country. Uses a larger GeoIP database; may slightly increase tracking overhead.
country	Country only	Provides country-level data only. Uses a smaller database for faster tracking and lower storage usage.

---

filtering_by_domain

Property	Value
Type	checkbox (visible only on multi-domain installs)
Default	false
Disabled	true (Pro required)

⭐ Pro

Domain filtering requires Burst Statistics Pro. Upgrade to Burst Pro

When your WordPress installation serves multiple domains, enabling this option causes the domain to be stored alongside each pageview. This allows the Insights view to be filtered per domain.

Note: This field is only rendered when the burst_is_multi_domain WordPress option is true. On single-domain installs the field is hidden.

---

track_url_change

Property	Value
Type	checkbox
Default	false

When enabled, client-side URL changes (query string updates, hash/fragment changes) are recorded as separate pageviews. Useful for Single-Page Applications (SPAs) or dynamic sites that update the URL without a full page reload.

---

Scripts Group

combine_vars_and_script

Property	Value
Type	checkbox
Default	false
Disabled when	The WordPress uploads directory is not writable (burst_js_write_error option is set)

Merge the Burst tracking configuration variables into the main Burst JavaScript file, reducing the number of HTTP requests. Requires write access to wp-content/uploads/burst/.

When the uploads directory is not writable, this option is disabled and the following note is displayed:

"This option is only available when WordPress can write to the uploads directory. Please ensure that the WordPress installation has write permissions to wp-content/uploads/burst/."

---

ghost_mode

Property	Value
Type	checkbox
Default	false
Visible/enabled when	combine_vars_and_script is true

When active, the generated JavaScript filename no longer contains the word "burst", making it less identifiable to ad blockers or privacy tools that block tracking scripts by filename pattern.

Note: This field is visible at all times but is disabled unless combine_vars_and_script is enabled. Enabling ghost mode without the merged script has no effect.

---

Internal / Hidden Fields (Advanced Group)

Field ID	Default	Purpose
burst_update_to_city_geo_database_time	1751328000	Unix timestamp controlling when a scheduled upgrade to the city-level GeoIP database should occur. Managed internally.

---

Reporting Tab

The Reporting section is accessible from the separate Reporting menu item and requires the manage_burst_statistics capability.

Reports Group

email_reports_mailinglist

Property	Value
Type	email_reports (custom component)
Default	""

Manage the list of email addresses that receive scheduled Burst Statistics email reports. The component provides an interface to add, remove, and configure report recipients.

---

Customization Group

logo_attachment_id

Property	Value
Type	logo_editor (custom component)
Default	false

⭐ Pro

Custom logo in email reports requires Burst Statistics Pro. Learn more about custom reports

Select or upload a logo image to display in the header of outgoing email reports. Recommended dimensions: 200 × 70 pixels, file size under 200 KB.

The value stored is the WordPress media attachment ID (int) of the chosen image.

---

Logs Group

report_logs

Property	Value
Type	report_logs (custom component)
Default	false

Displays a log viewer showing the history of sent email reports, including:

• Delivery status (success / failure)
• Error messages, if any
• Cron execution timestamps and results

---

Conditional Field Visibility

Several fields are shown or hidden based on the value of other fields. The rules are evaluated reactively in the UI (before saving).

Field	Condition	Behavior
ghost_mode	combine_vars_and_script = true	Disabled (visible but inactive) when condition is not met
archive_after_months	archive_data = archive or delete	Hidden when condition is not met
confirm_delete_data	archive_data = delete	Hidden when condition is not met
restore_archives	archive_data = archive	Hidden when condition is not met

---

Recommended Badge Conditions

The UI shows a "Recommended" badge next to a field reactively when the following conditions are met, before the user saves:

Field	Recommended when
enable_turbo_mode	enable_cookieless_tracking is true

---

Field Types Reference

Type	Description
checkbox	Single boolean toggle
checkbox_group	Multiple checkboxes from a dynamic option list
radio	Single-choice selection rendered as radio buttons
select	Dropdown single-choice selection
number	Numeric input with optional min constraint
text	Single-line text input
textarea	Multi-line text input
button	Action button, optionally with a confirmation dialog
hidden	Not rendered in the UI; value managed programmatically
email_reports	Custom component for managing report recipients
logo_editor	Custom component for uploading/selecting a logo
goals	Custom component for managing conversion goals
ip_blocklist	Custom component for managing IP exclusion list
restore_archives	Custom component for browsing and restoring archived data
export_settings	Custom component that triggers a settings file download
upload	File upload input for importing settings
theme_toggle	Custom toggle for light/dark mode
anonymous_usage_data	Custom component for usage data opt-in
report_logs	Custom component for viewing email report logs

---

Pro Features Summary

The following settings or options require Burst Statistics Pro:

Setting	Pro Feature
geo_ip_database_type — city option	City & Region visitor location detail
archive_data — archive option	Automatic data archiving
restore_archives	Restoring archived data
import_settings	Importing a settings file
filtering_by_domain	Filtering analytics by domain
logo_attachment_id	Custom logo in email reports