Skip to main content

Settings reference

This page documents every configuration field available in Burst Statistics v3.4.3. 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:

TabGroups
GeneralGeneral, Anonymous Usage Data
GoalsGoals
DataArchiving, Archived Data, Manage Settings
AdvancedTracking Exclusions, Tracking Behavior, Scripts
ReportingReports, Customization, Logs

Each tab and menu item now exposes an icon property used by the admin SPA to render a matching icon next to the label.


General tab

General group

enable_turbo_mode

PropertyValue
Typecheckbox
Defaultfalse
Recommended whenenable_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

PropertyValue
Typecheckbox
Defaultfalse

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

PropertyValue
Typecheckbox
Defaultfalse

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


dismiss_non_error_notices

PropertyValue
Typecheckbox
Defaultfalse

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


theme_toggle

PropertyValue
Typetheme_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)

There are currently no hidden fields registered in the General group.


Anonymous usage data group

anonymous_usage_data

PropertyValue
Typeanonymous_usage_data (custom component)
Defaultfalse

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

When enabled, Burst sends a snapshot of plugin settings and environment data to the Burst telemetry endpoint. The snapshot includes onboarding state read from the dedicated telemetry options burst_telemetry_completed_onboarding and burst_telemetry_skipped_onboarding (added in v3.4.3). These options are seeded from the legacy burst_completed_onboarding and burst_skipped_onboarding options during Pro activation and when BURST_FORCE_ONBOARDING is defined, so onboarding telemetry state survives the legacy options being cleared at the start of a new onboarding run.


Goals tab

Goals group

goals

PropertyValue
Typegoals (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.

Changed in v3.4.0: when the BURST_HEADLESS_DOMAIN constant is defined and enable_cookieless_tracking is true, the hook goal type is no longer available because server-side hook triggers require a client-provided UID that is not available in that configuration. Use pageview, click, or form goal types instead.


Data tab

Archiving group

archive_data

PropertyValue
Typeselect
Defaultfalse (none)
Optionsnone, archive, delete

Pro - CreatorAvailable in the Creator tier

The archive option requires Burst 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.

OptionBehavior
noneData is never automatically managed
archiveData older than the retention period is moved to archive tables. (Pro)
deleteData older than the retention period is permanently deleted

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


archive_after_months

PropertyValue
Typenumber
Default24
Minimum12 (filterable — see burst_minimum_archive_months)
Visible whenarchive_data is archive or delete

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

Filter:

Show code
/**
* 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

PropertyValue
Typecheckbox
Defaultfalse
Visible whenarchive_data is delete

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


reset

PropertyValue
Typebutton
Actionreset
Warning typedanger
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 - CreatorAvailable in the Creator tier

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

restore_archives

PropertyValue
Typerestore_archives (custom component)
Defaultfalse
Visible whenarchive_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

PropertyValue
Typeexport_settings (custom component)
Button text"Download settings file"
Defaultfalse

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

PropertyValue
Typeupload
Defaultfalse

Pro - CreatorAvailable in the Creator tier

Importing settings requires Burst 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

PropertyValue
Typecheckbox_group
Defaultfalse
OptionsDynamically 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

PropertyValue
Typeip_blocklist (custom component)
Default""
Recommendedtrue

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

PropertyValue
Typetextarea
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

PropertyValue
Typecheckbox
Defaultfalse

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

PropertyValue
Typeradio
Defaultcity

Pro - CreatorAvailable in the Creator tier

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

Controls the granularity of visitor geolocation data collected.

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

filtering_by_domain

PropertyValue
Typecheckbox (visible only on multi-domain installs)
Defaultfalse
Disabledtrue (Pro required)

Pro - CreatorAvailable in the Creator tier

Domain filtering requires Burst 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

PropertyValue
Typecheckbox
Defaultfalse

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

PropertyValue
Typecheckbox
Defaultfalse
Disabled whenThe 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/."

:::caution Breaking change Changed in v3.4.0: when the BURST_HEADLESS_DOMAIN constant is defined, combine_vars_and_script is removed from the settings schema entirely (along with ghost_mode) and is replaced by the download_client_plugin button described below. Do not rely on this field being present on headless installs. :::


ghost_mode

PropertyValue
Typecheckbox
Defaultfalse
Visible/enabled whencombine_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.

:::caution Breaking change Changed in v3.4.0: when the BURST_HEADLESS_DOMAIN constant is defined, ghost_mode is removed from the settings schema entirely along with combine_vars_and_script. It is not applicable to headless installs because tracking runs on a separate frontend via the client plugin. :::


download_client_plugin

PropertyValue
Typebutton
Button text"Download"
Label"Download Burst Client plugin"
Defaultfalse
Visible whenThe BURST_HEADLESS_DOMAIN PHP constant is defined

Added in v3.4.0. Generates a downloadable zip containing the Burst Client plugin, preconfigured for the current Burst install. The client plugin is installed on the headless frontend (for example, a separate WordPress or non-WordPress site) and forwards tracking events back to this Burst install.

The download URL is nonce-protected using the download_burst_client action:

Show code
add_action( 'admin_menu', function () {
// The button is registered automatically when BURST_HEADLESS_DOMAIN is defined.
// To trigger the same download programmatically, use:
$download_url = add_query_arg(
[
'action' => 'download_client',
'token' => wp_create_nonce( 'download_burst_client' ),
],
BURST_URL . 'includes/Pro/Admin/Headless/download.php'
);
} );

To define the constant, add the following to wp-config.php on the Burst install that stores the data:

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

When this constant is defined, Burst adapts the settings schema and the onboarding flow:

  • The combine_vars_and_script and ghost_mode fields are removed from the Scripts group.
  • The download_client_plugin button is added to the Scripts group.
  • In the Goals group, the hook goal type is hidden when enable_cookieless_tracking is also true.
  • The onboarding step with id tracking is removed, since the tracking target is now the frontend site.

enable_abilities_api

PropertyValue
Typecheckbox (or hidden when WordPress does not provide wp_register_ability())
Defaultfalse
Label"Enable Abilities API (for AI agents and automation)"

Added in v3.4.1. Opts the site into the WordPress Abilities API integration, exposing a set of read-only Burst abilities that trusted AI agents and automation tools can call via the Abilities API runtime. The setting only renders as a visible checkbox when the active WordPress build provides the wp_register_ability() function; on older builds it falls back to a hidden field and the abilities are not registered.

When enabled, Burst registers the burst-statistics ability category and the following abilities:

AbilityDescriptionPro only
burst/live-visitorsCurrent number of live visitorsNo
burst/live-trafficActive visitors and pages from the live traffic feed (accepts optional limit, 1–100)No
burst/today-summaryRead-only summary of key metrics for a date rangeNo
burst/tasksCurrent Burst task list and statusNo
burst/tracking-statusTracking transport status and last test timestampNo
burst/license-noticesLicense state and noticesNo
burst/dataInsights timeseries or datatable rows for requested metrics, filters, and groupingNo
burst/sales-dataEcommerce sales metrics (requires Burst Pro)Yes
burst/subscriptions-dataEcommerce subscriptions metrics (requires Burst Pro)Yes

All abilities are registered with readonly: true, destructive: false, and idempotent: true annotations. The permission callback requires the caller to satisfy view_burst_statistics. Pro-only abilities additionally require the BURST_PRO constant to be defined and return 503 with code burst_abilities_pro_required otherwise.

A simple per-user, per-ability rate limit is applied. The defaults are 30 requests per 60-second window and can be tuned with the following filters:

Show code
/**
* Adjust the rate-limit window (in seconds) per user, per ability.
*
* @param int $window Window length in seconds. Default 60.
* @param string $ability Ability slug, e.g. 'live-visitors'.
* @return int
*/
add_filter( 'burst_abilities_rate_limit_window', function ( int $window, string $ability ): int {
return $ability === 'live-traffic' ? 30 : $window;
}, 10, 2 );

/**
* Adjust the maximum number of calls allowed per window.
*
* @param int $max Maximum calls per window. Default 30.
* @param string $ability Ability slug.
* @return int
*/
add_filter( 'burst_abilities_rate_limit_max', function ( int $max, string $ability ): int {
return $ability === 'data' ? 10 : $max;
}, 10, 2 );

Exceeding the limit returns 429 with code burst_abilities_rate_limited. Unauthenticated callers receive 403 with code burst_abilities_forbidden. Invalid input returns 400 with code burst_abilities_invalid_input. Internal failures return 500 with code burst_abilities_execution_failed.

Pro - BusinessAvailable in the Business tier

The burst/sales-data and burst/subscriptions-data abilities require the Business tier. Learn more about revenue and sales tracking


enable_mainwp_integration

PropertyValue
Typecheckbox when the MainWP Child plugin file is present at wp-content/plugins/mainwp-child/mainwp-child.php, otherwise hidden
Defaultfalse
Label"Enable MainWP Dashboard Integration"

Added in v3.4.2. Controls whether the MainWP integration on the child site is initialized. When enabled, the child site exposes the signed REST endpoints used by the MainWP dashboard to read Burst statistics from this site. When disabled, the MainWP_Proxy class is not loaded and no MainWP-specific routes are registered, completely preventing MainWP integration regardless of whether the MainWP Child plugin is active.

Changed in v3.4.2.1: the field type is now resolved conditionally based on whether the MainWP Child plugin file exists on disk. When wp-content/plugins/mainwp-child/mainwp-child.php is present the field renders as a visible checkbox; otherwise the field falls back to hidden and is not exposed in the Scripts group UI. The detection is file-based, so the field becomes visible as soon as the MainWP Child plugin is installed even before it is activated.

Pro - AgencyAvailable in the Agency tier

The MainWP integration is an Agency tier feature. Upgrade to Burst Pro

Disable this setting if you do not use MainWP, or if you want to ensure the Burst-side MainWP proxy cannot be reached even when the MainWP Child plugin is installed for unrelated purposes.


Internal / hidden fields (Advanced group)

Field IDDefaultPurpose
burst_update_to_city_geo_database_time1751328000Unix 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.

Changed in v3.4.0: the Reporting menu item now uses location: 'left' instead of 'right', so it is rendered on the left side of the Burst admin top-level navigation. Each Reporting menu item also declares an icon property used by the admin SPA:

Menu itemIcon
Reportsgraph
Customizationpencil
Logsfile

The Settings menu item declares a top-level cog icon, and its sub-items declare their own icons:

Settings sub-itemIcon
Generalcog
Goalsgoals
Datahard-drive
Advancedsliders-vertical
Licensekey

Third-party code that modifies the admin menu via burst_menu should preserve these icon keys when cloning menu items. Missing icons fall back to the default rendering in the admin SPA.

Reports group

email_reports_mailinglist

PropertyValue
Typeemail_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

PropertyValue
Typelogo_editor (custom component)
Defaultfalse

Pro - AgencyAvailable in the Agency tier

Custom logo in email reports requires Burst 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

PropertyValue
Typereport_logs (custom component)
Defaultfalse

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

Changed in v3.4.0: the context helper text previously shown under this field has been removed from the schema. The field renders without inline context text; the admin UI may still provide help text via other components.


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).

FieldConditionBehavior
ghost_modecombine_vars_and_script = trueDisabled (visible but inactive) when condition is not met
archive_after_monthsarchive_data = archive or deleteHidden when condition is not met
confirm_delete_dataarchive_data = deleteHidden when condition is not met
restore_archivesarchive_data = archiveHidden when condition is not met
download_client_pluginBURST_HEADLESS_DOMAIN is definedHidden when the constant is not defined
combine_vars_and_script, ghost_modeBURST_HEADLESS_DOMAIN is definedRemoved from schema when the constant is defined
goals[].type=hookBURST_HEADLESS_DOMAIN is defined and enable_cookieless_tracking is trueHidden goal type option when both conditions are met
enable_abilities_apiwp_register_ability() is not availableRendered as hidden instead of checkbox
enable_mainwp_integrationwp-content/plugins/mainwp-child/mainwp-child.php does not existRendered as hidden instead of checkbox

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

FieldRecommended when
enable_turbo_modeenable_cookieless_tracking is true

Field types reference

TypeDescription
checkboxSingle boolean toggle
checkbox_groupMultiple checkboxes from a dynamic option list
radioSingle-choice selection rendered as radio buttons
selectDropdown single-choice selection
numberNumeric input with optional min constraint
textSingle-line text input
textareaMulti-line text input
buttonAction button, optionally with a confirmation dialog
hiddenNot rendered in the UI; value managed programmatically
email_reportsCustom component for managing report recipients
logo_editorCustom component for uploading/selecting a logo
goalsCustom component for managing conversion goals
ip_blocklistCustom component for managing IP exclusion list
restore_archivesCustom component for browsing and restoring archived data
export_settingsCustom component that triggers a settings file download
uploadFile upload input for importing settings
theme_toggleCustom toggle for light/dark mode
anonymous_usage_dataCustom component for usage data opt-in
report_logsCustom component for viewing email report logs

Internal options reference

These WordPress options are managed by Burst outside of the settings schema. They do not appear in the settings UI and are documented here for developers who need to reason about telemetry, upgrade behavior, or the REST API optimizer.

OptionTypePurpose
burst_plugin_slugstringThe validated plugin directory slug (e.g. burst-statistics or burst-pro). Used by the MU REST API optimizer to locate includes/Integrations/integrations.php via WP_PLUGIN_DIR + slug. Refreshed daily by the burst_daily cron and on Pro activation. Added in v3.4.3.
burst_telemetry_completed_onboardingboolTelemetry copy of the legacy burst_completed_onboarding state. Seeded from burst_completed_onboarding during Pro activation and when BURST_FORCE_ONBOARDING is defined, so anonymous usage data retains onboarding completion state after the legacy option is cleared at the start of a new onboarding run. Added in v3.4.3.
burst_telemetry_skipped_onboardingboolTelemetry copy of the legacy burst_skipped_onboarding state. Seeded the same way as burst_telemetry_completed_onboarding. Added in v3.4.3.

:::caution Breaking change Renamed in v3.4.3: the burst_plugin_path option has been removed and replaced by burst_plugin_slug. The previous option stored an absolute filesystem path; the new option stores only the plugin directory slug, validated against /^[a-zA-Z0-9_-]+$/. The Burst upgrade routine deletes burst_plugin_path and writes burst_plugin_slug automatically when upgrading from a version below 3.4.3, then reinstalls the MU REST API optimizer so the on-disk loader matches the new logic. Third-party code that read burst_plugin_path to locate the Burst install must be updated to read burst_plugin_slug and combine it with WP_PLUGIN_DIR. :::


Pro features summary

The following settings or options require Burst Pro:

SettingPro Feature
geo_ip_database_typecity optionCity & Region visitor location detail
archive_dataarchive optionAutomatic data archiving
restore_archivesRestoring archived data
import_settingsImporting a settings file
filtering_by_domainFiltering analytics by domain
logo_attachment_idCustom logo in email reports
enable_mainwp_integrationMainWP dashboard integration (Agency tier)

Developer extension points

These hooks belong to the settings and admin-app layer. Use them when you want to alter the settings schema, adjust saved values, or extend the Burst admin UI.

burst_before_save_option (action)

Fires before a settings value is sanitized and saved. This is a legacy pre-save hook kept for backward compatibility.

ParameterTypeDescription
$field_idstringField ID being saved
$raw_valuemixedRaw value from the request
$prev_valuemixedPreviously stored value
$typestringDeclared field type

burst_before_save_field (action)

Fires after a field value has been sanitized, but before the updated options array is written.

ParameterTypeDescription
$field_idstringField ID being saved
$sanitized_valuemixedSanitized value that will be stored
$prev_valuemixedPreviously stored value
$typestringDeclared field type

burst_after_saved_fields (action)

Fires once after a batch settings save succeeds.

ParameterTypeDescription
$updated_fieldsarrayAssociative array of field_id => saved_value pairs

Example:

Show code
add_action( 'burst_after_saved_fields', function( array $updated_fields ): void {
if ( array_key_exists( 'combine_vars_and_script', $updated_fields ) ) {
my_plugin_purge_asset_cache();
}
} );

burst_fields

Filters the main settings field definitions before values are loaded.

Use this to add, remove, or modify fields in the standard settings UI.

burst_field

Filters a single resolved field definition after its current value has been loaded.

The second parameter is the field ID.

burst_field_value_{id}

Dynamic filter applied to an individual field value before it is exposed to the UI.

For example, burst_field_value_archive_after_months lets you alter the displayed value for that specific field.

burst_fields_values

Filters the final array of resolved settings fields after all per-field processing has completed.

burst_reporting_fields

Filters the reporting settings field schema loaded from reporting-fields.php.

Use this when you want to extend the dedicated Reporting settings screen rather than the general settings screen.

burst_reporting_fields_values

Filters the final resolved reporting fields array after values are loaded.

burst_menu

Filters the full Burst admin menu structure before it is returned to the app.

This is the correct hook for adding, removing, or altering top-level tabs and groups in the admin SPA.

Changed in v3.4.0: menu items and menu entries may include an optional icon string (for example graph, pencil, file, cog, goals, hard-drive, sliders-vertical, key). When extending the menu, preserve existing icon keys and set a matching icon on new entries to stay visually consistent. The Reporting top-level item now uses location: 'left' by default.

burst_menu_position

Filters the WordPress admin menu position used when Burst registers its main menu item.

Default value: 3.

burst_archive_after_months

Filters the effective archive/delete retention threshold used by the archive process.

This affects the runtime archive job, not just the field schema minimum.

burst_archive_rows_per_batch

Filters the number of rows processed per archive batch.

Use this to tune archive throughput for large sites or constrained hosting.

burst_abilities_rate_limit_window

Filters the per-user, per-ability rate-limit window (in seconds) used by the Abilities API integration.

Default value: 60.

burst_abilities_rate_limit_max

Filters the maximum number of Abilities API calls allowed per window, per user, per ability.

Default value: 30.