Analytics on WordPress

Installation

1. 1Option 1: paste the snippet with WPCode

   Install the free WPCode plugin (formerly "Insert Headers and Footers"). Go to Code Snippets → Header & Footer, paste the snippet in the Header box and click Save Changes.

   <script src="https://cdn.jsdelivr.net/npm/@racoelho/analytics@0.2/dist/index.global.js"></script>
   <script>window.analytics = new Analytics.Analytics({ siteKey: 'YOUR_SITE_KEY' })</script>

2. 2Option 2: your child theme’s functions.php

   If you’d rather not install a plugin, use the wp_head hook. Do it in a child theme — the parent theme’s functions.php is overwritten on updates.

   <?php
   // load the SDK in the <head> of every page
   add_action('wp_head', function () {
     echo '<script src="https://cdn.jsdelivr.net/npm/@racoelho/analytics@0.2/dist/index.global.js"></script>';
     echo "<script>window.analytics = new Analytics.Analytics({ siteKey: 'YOUR_SITE_KEY' })</script>";
   });

3. 3Clear the cache

   If the site uses a cache plugin (WP Rocket, LiteSpeed Cache, W3 Total Cache…) or a CDN, purge it so pages go out with the new script.

Events and goals

Any script on the site can call window.analytics. Two common cases: Contact Form 7 forms and WooCommerce purchases. window.analytics && avoids an error if the SDK is blocked.

<script>
  // Contact Form 7: fires when the message was sent successfully
  document.addEventListener('wpcf7mailsent', function (event) {
    window.analytics && window.analytics.formSubmit(String(event.detail.contactFormId), 'contact')
  })
</script>

<?php
// WooCommerce: order received page
add_action('woocommerce_thankyou', function ($order_id) {
  $order = wc_get_order($order_id);
  if (!$order) return;
  printf(
    '<script>window.analytics && window.analytics.purchase(%s, %s, %s)</script>',
    wp_json_encode((string) $order->get_order_number()),
    wp_json_encode((float) $order->get_total()),
    wp_json_encode($order->get_currency())
  );
});

In the dashboard, create form_submit and purchase event goals. For fixed pages (like /thank-you), a path goal works with no code. WooCommerce’s order URL changes with every order, hence the event.

Page navigation

WordPress sites reload the page on every click, and each load counts its own pageview. Nothing to configure.

Check that it works

1. Open the published site in a normal window, with no ad blocker.
2. In your browser devtools, Network tab, filter by v1/i: you should see a POST with status 200 within 3 seconds (or when you leave the page).
3. In the dashboard, events show up in about 30 seconds.
4. View the page source (Ctrl+U) and search for index.global.js — if it’s missing, the cache is still serving the old version.

Troubleshooting

An optimization plugin broke the script

Plugins that delay or combine JavaScript can change the order of the two lines. Exclude index.global.js and the script containing new Analytics.Analytics from optimization ("delay/defer JS").

The request returns 403 (origin_not_allowed)

Your domain isn’t in Allowed origins in the site settings. Add the exact origin — with https://, with and without www, plus test addresses like http://localhost:3000 if you want to measure in development.

No request shows up in the Network tab

The SDK honors Do Not Track by default: if your browser sends DNT, nothing is sent. Test in another browser or profile. Ad blockers can also block the script.

Pageviews show up twice

The SDK was initialized twice (for example, pasted in the theme and also added by a plugin). Keep a single instance per page.