WordPress: The World's Most Popular Open-Source CMS | OpsBlu Docs

WordPress: The World's Most Popular Open-Source CMS

WordPress powers over 40% of the web with thousands of plugins, customizable themes, Gutenberg block editing, and full-site editing.

WordPress runs on PHP and serves pages through a well-defined lifecycle of hooks and filters. Understanding that lifecycle is the key to placing analytics code correctly, avoiding plugin conflicts, and getting clean data into your measurement tools.

This page covers how analytics and tracking work within the WordPress architecture. For platform-specific integration guides, see the links in the Related Guides section at the bottom.

Analytics Architecture on WordPress

Every WordPress page load executes hooks in a predictable order. The hooks that matter for analytics are:

  1. plugins_loaded -- all active plugins are initialized
  2. init -- WordPress core is fully loaded
  3. wp_enqueue_scripts -- where scripts and stylesheets are registered and queued
  4. wp_head -- fires inside the <head> tag (priority 1 fires first, default is 10)
  5. wp_body_open -- fires immediately after the opening <body> tag (added in WP 5.2)
  6. wp_footer -- fires before the closing </body> tag
  7. shutdown -- request complete

Analytics scripts typically go in wp_head (for early loading) or wp_footer (for deferred loading). The wp_enqueue_scripts hook is the proper WordPress API for adding external scripts, while wp_head and wp_footer are used for inline code like data layer initialization or pixel base codes.

The critical detail: wp_head fires with a priority system. A script enqueued at priority 1 executes before one at priority 10. Google Tag Manager needs to load as early as possible in <head>, so it should be injected at a low priority number. Data layer variables must be pushed before GTM loads, so they go at an even lower priority.

// Priority order matters:
// Priority 1: dataLayer initialization
// Priority 2: GTM container snippet
// Priority 10 (default): everything else

add_action('wp_head', 'opsblu_datalayer_init', 1);
add_action('wp_head', 'opsblu_gtm_head', 2);
add_action('wp_body_open', 'opsblu_gtm_body', 1);

Installing Tracking Scripts

Via wp_enqueue_script

The wp_enqueue_script function is the WordPress-approved method for loading external JavaScript. It handles dependency resolution, version cache-busting, and placement (header vs footer).

// In your theme's functions.php or a custom plugin

add_action('wp_enqueue_scripts', 'opsblu_enqueue_analytics');

function opsblu_enqueue_analytics() {
    // GA4 gtag.js -- loaded async in the header
    wp_enqueue_script(
        'google-gtag',                                          // handle
        'https://www.googletagmanager.com/gtag/js?id=G-XXXXXXX', // src
        array(),                                                 // dependencies
        null,                                                    // version (null = no version string)
        array(
            'strategy' => 'async',    // WP 6.3+ supports 'async' and 'defer'
            'in_footer' => false,     // load in <head>, not footer
        )
    );

    // Inline gtag config -- depends on gtag.js being loaded first
    wp_add_inline_script('google-gtag', "
        window.dataLayer = window.dataLayer || [];
        function gtag(){dataLayer.push(arguments);}
        gtag('js', new Date());
        gtag('config', 'G-XXXXXXX');
    ");
}

The strategy parameter was introduced in WordPress 6.3. On older versions, you need to add async/defer manually via the script_loader_tag filter:

add_filter('script_loader_tag', 'opsblu_add_async_attribute', 10, 2);

function opsblu_add_async_attribute($tag, $handle) {
    if ('google-gtag' === $handle) {
        return str_replace(' src', ' async src', $tag);
    }
    return $tag;
}

Via wp_head Hook

For inline tracking snippets like the Meta Pixel base code, use wp_head directly. This is appropriate when the code is not an external file but rather an inline <script> block.

add_action('wp_head', 'opsblu_meta_pixel_base', 5);

function opsblu_meta_pixel_base() {
    ?>
    <script>
    !function(f,b,e,v,n,t,s)
    {if(f.fbq)return;n=f.fbq=function(){n.callMethod?
    n.callMethod.apply(n,arguments):n.queue.push(arguments)};
    if(!f._fbq)f._fbq=n;n.push=n;n.loaded=!0;n.version='2.0';
    n.queue=[];t=b.createElement(e);t.async=!0;
    t.src=v;s=b.getElementsByTagName(e)[0];
    s.parentNode.insertBefore(t,s)}(window, document,'script',
    'https://connect.facebook.net/en_US/fbevents.js');
    fbq('init', 'YOUR_PIXEL_ID');
    fbq('track', 'PageView');
    </script>
    <noscript><img height="1" width="1" style="display:none"
    src="https://www.facebook.com/tr?id=YOUR_PIXEL_ID&ev=PageView&noscript=1"
    /></noscript>
    <?php
}

Via a Plugin

Three plugins dominate WordPress analytics installation. Each serves a different use case.

Insert Headers and Footers (WPCode) is the simplest option. It provides a code editor in the WordPress admin where you paste tracking snippets, injected via wp_head and wp_footer. Use this when a non-developer manages tracking codes. The downside is zero data layer integration -- it only pastes static code.

GTM4WP (Google Tag Manager for WordPress) handles GTM container installation, pushes structured data layer variables automatically, and has built-in WooCommerce ecommerce data layer support. More on this below.

Site Kit by Google connects GA4, Search Console, AdSense, and PageSpeed Insights into the WordPress admin. Useful for dashboard reporting, but it offers limited control over implementation details -- no custom data layer pushes or advanced GTM configurations.

For serious analytics work, GTM4WP combined with a properly configured GTM container is the strongest approach.

Google Tag Manager Setup

GTM4WP Plugin Configuration

After installing and activating GTM4WP from the WordPress plugin repository:

  1. Navigate to Settings > Google Tag Manager
  2. Enter your GTM container ID (format: GTM-XXXXXXX)
  3. Set Container code placement to "Codeless injection" (this uses wp_head and wp_body_open hooks automatically)
  4. Under the Integration tab, enable the data layer variables you need

GTM4WP automatically pushes these variables to dataLayer on every page:

// What GTM4WP pushes to dataLayer automatically:
dataLayer.push({
    'pagePostType': 'post',           // post, page, product, custom_type
    'pagePostType2': 'single-post',   // more specific: single-post, archive, search, etc.
    'pageCategory': ['analytics', 'wordpress'],  // post categories
    'pageAttributes': ['tutorial'],   // post tags
    'pagePostAuthor': 'Josh',         // display name of the post author
    'pagePostDate': '2026-03-04',     // publish date
    'pagePostDateYear': '2026',
    'pagePostDateMonth': '03',
    'pagePostDateDay': '04',
    'pageTitle': 'WordPress Analytics Guide',
    'pageID': 1234,                   // WordPress post ID
    'wordCount': 2500,                // word count of the post content
    'loggedIn': false,                // whether the visitor is logged in
    'userRole': '',                   // empty if logged out, 'administrator'/'editor'/etc. if logged in
});

These become available as Data Layer Variables in GTM, which you can use in triggers and tag configurations without writing any additional code.

Manual GTM Installation

When you need tighter control over loading or cannot use a plugin (locked-down enterprise environments, custom themes that conflict with GTM4WP), install GTM manually:

// In functions.php or a site-specific plugin

// GTM head snippet -- must go as high in <head> as possible
add_action('wp_head', 'opsblu_gtm_head_snippet', 1);
function opsblu_gtm_head_snippet() {
    ?>
    <!-- Google Tag Manager -->
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
    new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
    j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
    'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
    })(window,document,'script','dataLayer','GTM-XXXXXXX');</script>
    <!-- End Google Tag Manager -->
    <?php
}

// GTM noscript fallback -- immediately after <body>
add_action('wp_body_open', 'opsblu_gtm_body_snippet', 1);
function opsblu_gtm_body_snippet() {
    ?>
    <!-- Google Tag Manager (noscript) -->
    <noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-XXXXXXX"
    height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <!-- End Google Tag Manager (noscript) -->
    <?php
}

Manual installation is better when your theme does not call wp_body_open() (pre-WP 5.2 themes), you need server-side GTM with a custom domain, or you are running a headless WordPress setup. If your theme lacks wp_body_open, edit header.php directly and place the noscript iframe right after the <body> tag.

Data Layer Implementation

WordPress Data Layer Variables

The data layer should be initialized before GTM loads. This means the dataLayer.push() call must happen at a lower wp_head priority than the GTM container snippet.

add_action('wp_head', 'opsblu_push_wp_datalayer', 1);

function opsblu_push_wp_datalayer() {
    global $post;

    $data = array(
        'siteType'     => 'wordpress',
        'wpVersion'    => get_bloginfo('version'),
        'isLoggedIn'   => is_user_logged_in(),
        'userRole'     => is_user_logged_in() ? wp_get_current_user()->roles[0] : 'visitor',
        'pageTemplate' => is_singular() ? get_page_template_slug($post) : '',
    );

    // Page/post-specific data
    if (is_singular()) {
        $data['pageType']      = get_post_type();
        $data['pageID']        = $post->ID;
        $data['pageTitle']     = get_the_title($post);
        $data['pageAuthor']    = get_the_author_meta('display_name', $post->post_author);
        $data['publishDate']   = get_the_date('Y-m-d', $post);
        $data['modifiedDate']  = get_the_modified_date('Y-m-d', $post);

        // Categories (posts only)
        $categories = get_the_category($post->ID);
        if ($categories) {
            $data['pageCategory'] = array_map(function($cat) {
                return $cat->slug;
            }, $categories);
        }

        // Tags
        $tags = get_the_tags($post->ID);
        if ($tags) {
            $data['pageTags'] = array_map(function($tag) {
                return $tag->slug;
            }, $tags);
        }

        // Custom fields (ACF or native)
        if (function_exists('get_field')) {
            $content_group = get_field('content_group', $post->ID);
            if ($content_group) {
                $data['contentGroup'] = $content_group;
            }
        }
    } elseif (is_archive()) {
        $data['pageType'] = 'archive';
        if (is_category()) {
            $data['archiveType'] = 'category';
            $data['archiveName'] = single_cat_title('', false);
        } elseif (is_tag()) {
            $data['archiveType'] = 'tag';
            $data['archiveName'] = single_tag_title('', false);
        } elseif (is_author()) {
            $data['archiveType'] = 'author';
            $data['archiveName'] = get_the_author();
        }
    } elseif (is_search()) {
        $data['pageType']    = 'search';
        $data['searchQuery'] = get_search_query();
        $data['resultCount'] = $GLOBALS['wp_query']->found_posts;
    } elseif (is_404()) {
        $data['pageType'] = '404';
    } else {
        $data['pageType'] = 'other';
    }

    echo '<script>window.dataLayer = window.dataLayer || []; dataLayer.push(' . wp_json_encode($data) . ');</script>' . "\n";
}

Use wp_json_encode() instead of json_encode() -- it handles UTF-8 encoding correctly for WordPress content with special characters.

WooCommerce Data Layer

WooCommerce ecommerce tracking requires its own data layer for product impressions, add-to-cart events, checkout steps, and purchase confirmation. GTM4WP handles this automatically when you enable its WooCommerce integration tab. For manual implementation, see the WooCommerce analytics guide.

Plugin Conflicts and Loading Order

Analytics breakage on WordPress almost always comes down to plugin conflicts. The three most common sources:

Caching Plugins

WP Rocket, W3 Total Cache, LiteSpeed Cache, and WP Super Cache all modify how JavaScript is delivered to the browser. The optimizations that break analytics are:

Minification and combination: When a caching plugin combines multiple JS files into one bundle, it can break gtag() or fbq() function calls that depend on their parent scripts being loaded first. The concatenation changes execution order.

Page caching: Full-page caching serves a static HTML snapshot to visitors. If your data layer variables are generated dynamically per user (logged-in status, user role), cached pages serve stale values. A logged-in admin sees the same data layer as an anonymous visitor because the cache does not distinguish between them.

Delayed JavaScript execution: Some caching plugins (WP Rocket's "Delay JavaScript execution" feature) defer all JS until user interaction. This means no tracking fires on passive pageviews until the visitor scrolls or clicks.

Exclude analytics scripts from caching optimizations:

// WP Rocket: exclude analytics scripts from minification and combination
add_filter('rocket_exclude_js', function($excluded_js) {
    $excluded_js[] = 'googletagmanager.com/gtm.js';
    $excluded_js[] = 'googletagmanager.com/gtag/js';
    $excluded_js[] = 'connect.facebook.net/en_US/fbevents.js';
    $excluded_js[] = 'snap.licdn.com/li.lms-analytics';
    $excluded_js[] = 'analytics.tiktok.com';
    return $excluded_js;
});

// WP Rocket: exclude from delay JS execution
add_filter('rocket_delay_js_exclusions', function($exclusions) {
    $exclusions[] = 'gtag';
    $exclusions[] = 'dataLayer';
    $exclusions[] = 'fbq';
    $exclusions[] = 'gtm.js';
    return $exclusions;
});

For LiteSpeed Cache, add exclusions in the LiteSpeed Cache > Page Optimization > JS settings. Add each analytics domain on a separate line in the "JS Excludes" field.

For W3 Total Cache, go to Performance > Minify > JS and add the analytics script URLs to the "Never minify the following JS files" list.

Security Plugins

Wordfence, Sucuri, and iThemes Security can block outbound requests to analytics domains or add CSP headers that prevent tracking scripts from loading. If analytics stops working after installing a security plugin, check the plugin's firewall logs.

Complianz, CookieYes, and Cookie Notice conditionally load tracking scripts based on user consent. They block all tracking on initial load, wait for cookie acceptance, then dynamically inject the scripts. If tracking is missing for a large percentage of users, verify the consent plugin is correctly re-enabling scripts after acceptance -- this is often working as intended under GDPR.

Security Headers and CSP

WordPress sites that implement Content-Security-Policy headers (via a plugin like HTTP Headers, or in .htaccess) frequently break analytics without realizing it. Analytics requires connections to multiple external domains.

A working CSP for a site using GA4 through GTM with Meta Pixel:

# .htaccess CSP that allows analytics
Header set Content-Security-Policy "\
    default-src 'self'; \
    script-src 'self' 'unsafe-inline' https://www.googletagmanager.com https://www.google-analytics.com https://connect.facebook.net; \
    img-src 'self' data: https://www.google-analytics.com https://www.facebook.com https://googleads.g.doubleclick.net; \
    connect-src 'self' https://www.google-analytics.com https://analytics.google.com https://region1.google-analytics.com https://*.facebook.com; \
    frame-src https://www.googletagmanager.com; \
    font-src 'self' data:; \
    style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; \
"

You can also set CSP headers via the send_headers action in functions.php using PHP's header() function with the same directives.

When adding new tracking platforms, check the browser console for Refused to load the script errors. Each blocked domain needs to be added to the appropriate CSP directive.

Common Errors

These are the exact error messages WordPress developers encounter when working with analytics and tracking:

Error Cause Fix
wp_enqueue_script was called incorrectly Calling wp_enqueue_script() outside of a proper hook, typically before wp_enqueue_scripts fires Move the call inside an add_action('wp_enqueue_scripts', ...) callback
gtag is not defined Code calls gtag() before the gtag.js library has loaded, usually due to async loading or wrong script order Ensure the inline config runs after gtag.js loads, or use wp_add_inline_script() with the gtag handle to guarantee order
fbq is not defined Meta Pixel base code failed to load -- blocked by CSP, ad blocker, or script was deferred past the point where fbq() is called Check CSP headers for connect.facebook.net, verify script is not excluded by caching plugin, test without ad blocker
Cannot read properties of undefined (reading 'push') dataLayer.push() called before dataLayer array exists, common when GTM loads before data layer initialization Add window.dataLayer = window.dataLayer || []; at wp_head priority 1, before the GTM snippet
Refused to load the script 'https://www.googletagmanager.com/...' Content-Security-Policy header blocks the GTM domain Add https://www.googletagmanager.com to the script-src directive in your CSP configuration
Warning: Cannot modify header information - headers already sent PHP output (whitespace, BOM, echo) happens before wp_head, preventing header-based operations Check functions.php and plugin files for whitespace before the opening <?php tag, or a UTF-8 BOM character
REST API request failed: rest_no_route Site Kit or another analytics plugin cannot reach the WordPress REST API, often caused by custom permalink settings or security plugin blocking REST routes Go to Settings > Permalinks and click Save (flushes rewrite rules). Check if a security plugin is blocking /wp-json/
The tag on this page is sending hits with the wrong Measurement ID Multiple GA4 installations are present -- a theme, a plugin, and manual code all loading gtag.js with different measurement IDs Audit all active plugins and theme files for duplicate gtag installations; use a single source of truth
Tag Assistant: No Google tags found on this page GTM or gtag.js failed to load, is blocked, or was placed in the wrong location in the HTML Verify the container snippet is present in page source (View Source, not Inspect), check for JavaScript errors that halt execution before GTM loads
Refused to frame 'https://www.googletagmanager.com/' CSP frame-src directive does not include GTM, which blocks the GTM preview/debug mode iframe Add https://www.googletagmanager.com to the frame-src CSP directive

Performance Impact

WordPress sites often stack multiple tracking scripts that compound Core Web Vitals problems.

LCP (Largest Contentful Paint)

Each tracking script that loads synchronously in <head> competes with critical resources for bandwidth and main thread time, delaying content rendering.

Mitigation: load analytics scripts with async (for gtag.js) and add preconnect hints for analytics domains so the browser establishes connections early:

add_action('wp_head', 'opsblu_preconnect_analytics', 1);

function opsblu_preconnect_analytics() {
    echo '<link rel="preconnect" href="https://www.googletagmanager.com" />' . "\n";
    echo '<link rel="preconnect" href="https://www.google-analytics.com" />' . "\n";
}

CLS (Cumulative Layout Shift)

Consent banners are the primary CLS offender on WordPress analytics sites. A banner that renders after the page is visible pushes content down. Fix by reserving space in CSS for the banner, or using a bottom-of-screen overlay that does not displace content.

INP (Interaction to Next Paint)

Heavy event listeners from analytics code increase input delay. The most common offender is unbounded scroll tracking:

// Bad: fires on every scroll pixel, blocks main thread
window.addEventListener('scroll', function() {
    dataLayer.push({'event': 'scroll', 'scrollDepth': window.scrollY});
});

// Better: debounced, fires at 25/50/75/100% thresholds only
(function() {
    var thresholds = [25, 50, 75, 100];
    var fired = {};
    window.addEventListener('scroll', function() {
        var scrollPercent = Math.round(
            (window.scrollY / (document.body.scrollHeight - window.innerHeight)) * 100
        );
        thresholds.forEach(function(t) {
            if (scrollPercent >= t && !fired[t]) {
                fired[t] = true;
                dataLayer.push({'event': 'scroll_depth', 'scrollThreshold': t});
            }
        });
    }, {passive: true});
})();

The {passive: true} option tells the browser the handler will not call preventDefault(), allowing smooth scrolling without waiting for the handler.

WordPress Multisite Considerations

WordPress Multisite introduces additional tracking decisions. If each subsite is a distinct business, use separate GA4 properties. If subsites are sections of one brand (blog.example.com, shop.example.com), use a single GA4 property with cross-domain tracking. Subdirectory installations (example.com/blog, example.com/shop) share the same domain and do not need cross-domain setup.

For GTM, network-activating GTM4WP gives every subsite the same container. For separate containers, activate GTM4WP per site individually. A middle ground is a single GTM container with site-specific triggers based on hostname or page path variables.

// mu-plugin: push Multisite-specific data layer variables
add_action('wp_head', function() {
    $data = array(
        'multisiteBlogId' => get_current_blog_id(),
        'multisiteName'   => get_bloginfo('name'),
        'multisiteDomain' => wp_parse_url(get_site_url(), PHP_URL_HOST),
    );
    echo '<script>window.dataLayer = window.dataLayer || []; dataLayer.push(' . wp_json_encode($data) . ');</script>' . "\n";
}, 1);
返回顶部