Introduction to Burst Statistics shortcodes
Shortcodes in WordPress are small, reusable snippets of code, enclosed in square brackets like [this], that perform a dedicated function or display specific content on your website. Burst Statistics utilizes shortcodes to offer you a simple yet powerful way to display your privacy-respecting analytics data directly on your posts, pages, or widget areas. Burst Statistics is continuously optimized for performance, with features like lazy loading for shortcodes to ensure your site remains fast, especially on pages where statistics aren’t displayed.
By using Burst Statistics shortcodes, you can easily share insights like page views, device usage, or popular content with your visitors (if you choose to) or simply have key metrics readily available for your own reference on the front-end. True to our core values, these shortcodes allow you to display data gathered with a focus on privacy by design, data minimization, and local data hosting, giving you full control and transparency.
Activating the shortcodes in Burst
For performance reasons the shortcodes code is not loaded by default: we want to keep the plugin as lightweight as possible!
For versions below 3.1.3: You can enable a hidden setting by going to your burst settings page, and change to url to #/settings/secret
You can then enable the setting you will find there.
As of version 3.1.4: Go to settings / advanced, end toggle “enable shortcodes”.
Available shortcodes & examples
Burst Statistics uses a unified shortcode, [burst_statistics], to display various types of analytics data. You can customize what data is shown by using different parameters within this single shortcode, allowing for flexible data presentation across your site.
Basic Usage:
[burst_statistics type="pageviews"]This basic example will display the total number of pageviews for your entire site over the default period (last 30 days).
Common parameters
The [burst_statistics] shortcode accepts several parameters to customize its output. Here are the most common ones:
| Parameter | Description | Default | Example |
|---|---|---|---|
type | The type of statistic to display. | pageviews | visitors, sessions, bounce_rate, avg_time_on_page, top_pages, device_breakdown, etc. |
period | The time period for which to fetch statistics. | 30days | today, yesterday, 7days, this_month, last_month, all_time |
start_date | A specific start date for the statistics period. Format: YYYY-MM-DD. Overrides period if end_date is also set. | (empty) | 2024-01-01 |
end_date | A specific end date for the statistics period. Format: YYYY-MM-DD. Overrides period if start_date is also set. | (empty) | 2024-01-31 |
post_id | A specific post ID to fetch statistics for. Use current for the current post/page. | (empty) | 123, current |
page_url | A specific page URL (relative) to fetch statistics for (e.g., /about-us/). Takes precedence over post_id if both are provided. | (empty) | /my-page/, / |
format | The display format for the statistic. | number | text (e.g., “1,234 views” instead of just “1234”) |
label | A custom label to display before the statistic. | (empty) | Total views: |
empty_message | A message to display if no data is available for the selected criteria. | (empty) | No data available yet. |
cache_duration | How long (in seconds) the shortcode output should be cached. | 3600 (1 hour) | 86400 (24 hours), 0 (disable) |
limit | The number of items to display for list-based statistics (e.g., top pages, top referrers). | 5 | 10 |
Statistic types
You can display various kinds of data by changing the type parameter.
Single value statistics
These types display a single numerical value (or text if format="text" is used):
pageviews: Total number of page views.visitors: Total number of unique visitors.sessions: Total number of sessions.bounce_rate: The bounce rate percentage.avg_time_on_page: The average time users spend on a page.first_time_visitors: Total number of first-time visitors.
Example:
[burst_statistics type="visitors" period="7days" label="Visitors this week: "]Listing statistics
These types display a list of items:
top_pages: A list of your most viewed pages.top_referrers: A list of top referring websites.
Example: Display the top 3 most visited pages in the current month.
[burst_statistics type="top_pages" period="this_month" limit="3"]Device Breakdown Statistics
This type displays a percentage breakdown of visitors by device type:
device_breakdown: Shows percentage breakdown of visitors by device type (e.g., Desktop, Tablet, Mobile, Other). This can be for the entire site or filtered for a specific page using thepage_urlparameter.
Example: Display device breakdown for the entire site.
[burst_statistics type="device_breakdown"]Example: Display device breakdown for the homepage.
[burst_statistics type="device_breakdown" page_url="/"]Content-Specific Statistics
To display statistics for a specific post, page, or URL, you can use either the post_id or the page_url parameter. The page_url parameter takes precedence if both are provided.
Using post_id:
[burst_statistics type="pageviews" post_id="123"]Replace 123 with the actual ID of the post or page. To dynamically show statistics for the current post or page being viewed (e.g., if you place the shortcode in a post template or directly within post content), use post_id="current":
[burst_statistics type="pageviews" post_id="current" label="This page has been viewed: " format="text"]Using page_url:
Provide a relative URL to target a specific page. This is useful if you know the URL slug but not the ID, or for pages not tied to a specific post object.
[burst_statistics type="pageviews" page_url="/your-specific-page-slug/"]Example: Display visitors for the contact page over the last 7 days.
[burst_statistics type="visitors" page_url="/contact/" period="7days"]Most visited posts list
To display a list of your most visited posts (or any custom post type), use type="most_visited". This type has its own specific parameters in addition to the common ones:
[burst_statistics type="most_visited" limit="5" post_type="post" show_count="true"]Specific parameters for type="most_visited":
limit: Number of posts to display (Default:5).post_type: The post type to include (e.g.,post,page, or a custom post type slug. Default:post).show_count: Whether to display the view count next to each post title (trueorfalse. Default:false).
Deprecated shortcodes
The following shortcode has been deprecated but is still supported for backward compatibility:
[burst-most-visited count="5" post_type="post" show_count="true"]We strongly recommend updating to the new unified shortcode for future compatibility and access to more features:
[burst_statistics type="most_visited" limit="5" post_type="post" show_count="true"]Practical examples
Here are a few more examples to illustrate how you can combine parameters:
1. Display pageviews for the current post with a custom label and text format:
[burst_statistics type="pageviews" post_id="current" label="Views for this article: " format="text"]2. Display pageviews for a specific blog post using its URL:
[burst_statistics type="pageviews" page_url="/my-blog-post/" label="Views for this article: " format="text"]3. Display top 10 pages in the last 7 days:
[burst_statistics type="top_pages" period="7days" limit="10"]4. Display top 5 referrers for the current month:
[burst_statistics type="top_referrers" period="this_month" limit="5"]5. Display bounce rate with a custom message if no data is available:
[burst_statistics type="bounce_rate" empty_message="Bounce rate data is not yet available."]6. Display a list of the 3 most visited ‘portfolio’ custom post type entries, showing view counts:
[burst_statistics type="most_visited" limit="3" post_type="portfolio" show_count="true"]7. Display device breakdown (Desktop, Tablet, Mobile, Other) for the entire site:
[burst_statistics type="device_breakdown"]8. Display device breakdown for a specific page (e.g., the homepage):
[burst_statistics type="device_breakdown" page_url="/"]General usage instructions
How to add shortcodes to your WordPress site
You can place Burst Statistics shortcodes in various locations on your WordPress site:
- WordPress Block Editor (Gutenberg): Use the “Shortcode” block and paste your
[burst_statistics ...]shortcode into it. - WordPress Classic Editor: Switch to the “Text” tab (or directly in the “Visual” tab) and paste the shortcode where you want it to appear.
- Page builders: Most page builders (like Elementor, Beaver Builder, Divi, etc.) have a “Shortcode” element/module or a “Text/HTML” module where you can insert the shortcode.
- Widgets: Navigate to Appearance > Widgets. You can add a “Shortcode” widget (if available from your theme or another plugin), a “Text” widget, or an “HTML” widget and paste the shortcode into it. Ensure the widget area processes shortcodes.
- Theme template files (advanced): If you’re comfortable editing PHP, you can use the
do_shortcode()WordPress function:<?php echo do_shortcode('[burst_statistics type="pageviews"]'); ?>.
Styling your shortcode output
All shortcode outputs include specific CSS classes that you can target with your theme’s custom CSS (usually found in Appearance > Customize > Additional CSS) to match the look and feel of your site.
Key CSS classes include:
.burst-statistics-block: The main wrapper for all shortcode outputs..burst-statistics-label: Applied to the label text if you use thelabelparameter..burst-statistics-value: Applied to the actual statistic value..burst-statistics-number: For basic numeric displays..burst-statistics-text: For text format displays..burst-statistics-list: For list displays (e.g.,top_pages,top_referrers,device_breakdown). Each item in the list will be an<li>element..burst-posts-list: Specifically for the output oftype="most_visited"..burst-statistics-empty: Applied to the message whenempty_messageis displayed.
For example, to change the color of the statistic value, you might add CSS like:
.burst-statistics-value {
color: #0073aa; /* Example color */
font-weight: bold;
}Troubleshooting / common questions
empty_message. Double-check the shortcode syntax for any typos in the shortcode itself or its parameters (e.g., [burst_statistiks] instead of [burst_statistics]).
Ensure there is actually analytics data recorded for the specific type, period, post_id, or page_url you’ve selected. For new sites or seldom-visited pages, data might be sparse.
Verify that Burst Statistics is active and collecting data.
[burst_statistics type="pageviews"]). Make sure you’re adding the shortcode to a location that processes shortcodes. In the Block Editor, use the “Shortcode” block. In the Classic Editor, it should generally work in both Visual and Text tabs. For widgets, use the Text, HTML, or a dedicated Shortcode widget.
Some page builder modules might require a specific “shortcode” or “HTML” element to correctly interpret and render the shortcode. Avoid pasting it into regular paragraph or heading modules unless they explicitly support shortcodes.
Shortcode data is cached to improve performance. The default cache duration is 1 hour (3600 seconds). You can adjust this using the cache_duration parameter in the shortcode. Setting it to 0 will disable caching for that specific shortcode instance, but this may impact page load times if used excessively.
Also, consider any page caching mechanisms active on your site (e.g., caching plugins, server-side caching), as these can also affect how frequently the displayed data updates. Burst Statistics itself uses lazy loading for shortcodes, meaning they only process when visible, which helps with initial page load but the displayed data relies on its own cache or fresh data retrieval as configured.
We hope this guide helps you make the most of Burst Statistics shortcodes! Displaying your privacy-friendly analytics can be a great way to showcase popular content, understand user behavior, and add social proof.
If you have further questions, please check our other support documentation or feel free to contact support. For more information on all functionalities, see the main Burst Statistics features page.
Have an idea for a new shortcode feature or another improvement? We’d love to hear it! Please suggest a new feature on our feature requests board.
