Hooks & Filters
Reference for all WordPress actions and filters provided by Burst Statistics v3.3.0. Use these to extend or modify plugin behaviour without editing core files.
Actions
burst_after_save_field
Fires immediately after a Burst settings field is saved.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$name | string | The sanitized option name. |
$value | mixed | The new (sanitized) value. |
$prev_value | mixed | The previous value before saving. |
$type | string | The field type (e.g. checkbox, text). |
Example:
add_action( 'burst_after_save_field', function( $name, $value, $prev_value, $type ) {
if ( $name === 'cookieless_tracking' ) {
my_plugin_handle_cookieless_change( $value, $prev_value );
}
}, 10, 4 );
burst_every_ten_minutes
Cron action that fires every 10 minutes.
Parameters: none
Example:
add_action( 'burst_every_ten_minutes', function() {
// Run your task every 10 minutes.
} );
burst_every_hour
Cron action that fires every hour.
Parameters: none
Example:
add_action( 'burst_every_hour', function() {
// Run your task every hour.
} );
burst_daily
Cron action that fires once per day.
Parameters: none
Example:
add_action( 'burst_daily', function() {
// Run your daily task.
} );
burst_weekly
Cron action that fires once per week.
Parameters: none
Example:
add_action( 'burst_weekly', function() {
// Run your weekly task.
} );
burst_monthly
Cron action that fires once per month.
Parameters: none
Example:
add_action( 'burst_monthly', function() {
// Run your monthly task.
} );
burst_before_create_statistic
Fires immediately before a new row is inserted into burst_statistics.
Changed in v3.3.0: $statistic no longer contains session-level fields (bounce, browser_id, browser_version_id, platform_id, device_id, first_time_visit). These fields are now stored exclusively in burst_sessions. Code that read or modified those keys on $statistic inside this action must be updated.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$statistic | array | Sanitized data array containing only burst_statistics column fields. |
Example:
add_action( 'burst_before_create_statistic', function( $statistic ) {
// $statistic no longer contains bounce, browser_id, device_id, etc.
if ( ! empty( $statistic['page_url'] ) ) {
my_plugin_log_page( $statistic['page_url'] );
}
} );
burst_after_create_statistic
Fires immediately after a new row is inserted into burst_statistics.
Changed in v3.3.0: $statistic no longer contains session-level fields (bounce, browser_id, browser_version_id, platform_id, device_id, first_time_visit). These fields are now stored exclusively in burst_sessions. Code that read those keys on $statistic inside this action must be updated.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$insert_id | int | The ID of the newly created burst_statistics row (0 on failure). |
$statistic | array | Sanitized data array containing only burst_statistics column fields. |
Example:
add_action( 'burst_after_create_statistic', function( $insert_id, $statistic ) {
if ( $insert_id > 0 ) {
my_plugin_post_process( $insert_id, $statistic['page_url'] );
}
}, 10, 2 );
Filters
burst_option_{name}
Filters the value of any individual Burst option retrieved via burst_get_option(). Replace {name} with the sanitized option name (e.g. burst_option_cookieless_tracking).
Parameters:
| Parameter | Type | Description |
|---|---|---|
$value | mixed | The stored option value. |
$name | string | The sanitized option name. |
Example:
add_filter( 'burst_option_cookieless_tracking', function( $value, $name ) {
return true; // Force cookieless tracking on.
}, 10, 2 );
burst_before_track_hit
Filters the sanitized tracking data array before any hit processing (session lookup, statistic insert/update) takes place.
Changed in v3.3.0: After this filter returns, the session-level fields (bounce, browser_id, browser_version_id, platform_id, device_id, first_time_visit) are extracted from $sanitized_data and written to burst_sessions rather than burst_statistics. Those columns no longer exist in burst_statistics. Modifications to these fields via this filter still take effect, but they are applied to the session row — not to the statistics row.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$sanitized_data | array | Sanitized tracking data, including session-level fields at this point in the flow. |
$hit_type | string | 'create' for a new page-view or 'update' for an existing one. |
$previous_hit | array | The most recent statistic row for this visitor, or an empty array if none. |
Example:
add_filter( 'burst_before_track_hit', function( $sanitized_data, $hit_type, $previous_hit ) {
// Modify statistic-level fields only; session-level fields (bounce, browser_id, etc.)
// will be routed to burst_sessions after this filter returns.
if ( $hit_type === 'create' ) {
$sanitized_data['page_url'] = my_plugin_normalize_url( $sanitized_data['page_url'] );
}
return $sanitized_data;
}, 10, 3 );
burst_fieldvalue
Filters a settings field value just before it is written to the database.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$value | mixed | The sanitized value about to be saved. |
$name | string | The sanitized field name. |
$type | string | The field type (e.g. checkbox, text). |
Example:
add_filter( 'burst_fieldvalue', function( $value, $name, $type ) {
if ( $name === 'sample_rate' && (int) $value > 100 ) {
return 100;
}
return $value;
}, 10, 3 );
burst_obfuscate_filename
Filters whether the frontend tracking script filename should be obfuscated. When true, the filename is replaced with an 8-character hash derived from the site URL instead of burst.min.js.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$obfuscate | bool | true to obfuscate, false to use default name. |
Example:
// Always obfuscate the tracking script filename.
add_filter( 'burst_obfuscate_filename', '__return_true' );
burst_upload_dir
Filters the base filesystem path used for Burst file uploads (e.g. GeoIP database).
Parameters:
| Parameter | Type | Description |
|---|---|---|
$basedir | string | The base upload directory path (no trailing slash). |
Example:
add_filter( 'burst_upload_dir', function( $basedir ) {
return '/mnt/persistent-storage';
} );
burst_upload_url
Filters the base URL corresponding to the Burst upload directory.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$upload_url | string | The base upload URL (no trailing slash). |
Example:
add_filter( 'burst_upload_url', function( $upload_url ) {
return 'https://cdn.example.com/uploads';
} );
burst_is_preview
Filters whether the current request is a page-builder preview. When true, tracking is suppressed.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$preview | bool | true if a known page-builder preview parameter is detected. |
Example:
add_filter( 'burst_is_preview', function( $preview ) {
if ( isset( $_GET['my_preview_mode'] ) ) {
return true;
}
return $preview;
} );
burst_enable_logging
Filters whether Burst writes debug messages to the PHP error log. Only active when WP_DEBUG is true.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$enabled | bool | true to enable logging, false to suppress it. |
Example:
// Disable Burst debug logging even when WP_DEBUG is on.
add_filter( 'burst_enable_logging', '__return_false' );
burst_max_shared_link_requests
Filters the maximum number of REST API requests allowed per shared-link token within a one-minute window. Requests beyond this limit are rejected.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$max | int | Maximum requests per minute per token (default: 100). |
Example:
add_filter( 'burst_max_shared_link_requests', function( $max ) {
return 50;
} );
burst_share_link_permissions
Filters the permission flags sent to the frontend for shared-link viewers.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$permissions | array | Associative array of permission flags (see keys below). |
$permissions keys:
| Key | Type | Description |
|---|---|---|
can_change_date | bool | Whether the viewer may change the date range. |
can_filter | bool | Whether the viewer may apply dashboard filters. |
is_shareable_link_viewer | bool | true when the current user has the burst_viewer role. |
Example:
add_filter( 'burst_share_link_permissions', function( $permissions ) {
$permissions['can_change_date'] = true;
return $permissions;
} );
burst_localize_script
Filters the entire data object passed to the Burst dashboard JavaScript. Use this to expose additional values or override existing ones.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$data | array | Associative array of localised settings. |
Example:
add_filter( 'burst_localize_script', function( $data ) {
$data['my_custom_key'] = 'my_value';
return $data;
} );
burst_date_ranges
Filters the list of date-range options available in the Burst dashboard date picker.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$ranges | array | Indexed array of date-range identifier strings. |
Default values: today, yesterday, last-7-days, last-30-days, last-90-days, last-month, last-year, week-to-date, month-to-date, year-to-date
Example:
add_filter( 'burst_date_ranges', function( $ranges ) {
return array_values( array_diff( $ranges, [ 'last-90-days' ] ) );
} );
burst_verify_nonce
Filters the result of Burst's internal nonce verification.
Returning true unconditionally from this filter bypasses CSRF protection. Only use this in controlled, trusted contexts such as automated test suites.
Changed in v3.3.0: Fixed a bug where wp_verify_nonce() was called twice. $valid is now the cached result of the single wp_verify_nonce() call made before the filter fires.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$valid | int|false | Result of wp_verify_nonce() (1, 2, or false). |
$nonce | string | The nonce string that was verified. |
$action | string | The nonce action name. |
Example:
add_filter( 'burst_verify_nonce', function( $valid, $nonce, $action ) {
if ( defined( 'BURST_STAGING' ) && BURST_STAGING && $action === 'burst_nonce' ) {
return 1;
}
return $valid;
}, 10, 3 );
burst_checkout_page_id
Pro
This filter is only relevant when the Burst Pro ecommerce tracking feature is active. See WooCommerce Funnel Analytics.
Filters the WordPress page ID treated as the checkout page. The resolved value is cached for 24 hours.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$page_id | int | The checkout page ID. Defaults to -1 (not set). |
Example:
add_filter( 'burst_checkout_page_id', function( $page_id ) {
if ( function_exists( 'wc_get_page_id' ) ) {
return (int) wc_get_page_id( 'checkout' );
}
return $page_id;
} );
burst_products_page_id
Pro
This filter is only relevant when the Burst Pro ecommerce tracking feature is active. See WooCommerce Funnel Analytics.
Filters the WordPress page ID treated as the main products/shop page. The resolved value is cached for 24 hours.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$page_id | int | The products page ID. Defaults to -1 (not set). |
Example:
add_filter( 'burst_products_page_id', function( $page_id ) {
if ( function_exists( 'wc_get_page_id' ) ) {
return (int) wc_get_page_id( 'shop' );
}
return $page_id;
} );
burst_base_currency
Pro
This filter is only relevant when the Burst Pro ecommerce tracking feature is active. Learn more about revenue and sales tracking.
Filters the ISO 4217 currency code used for revenue reporting. The resolved value is cached for 24 hours.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$currency | string | ISO 4217 currency code. Defaults to USD. |
Example:
add_filter( 'burst_base_currency', function( $currency ) {
if ( function_exists( 'get_woocommerce_currency' ) ) {
return get_woocommerce_currency();
}
return $currency;
} );