WordPress

The Grain plugin installs the Grain Tag, adds WordPress context to every page view, and tracks WooCommerce events. This page installs the plugin first. A second method adds the script by hand. The plugin method takes about 5 minutes.

Before you start

You need three things:

Admin access to WordPress.
Your tenant alias from the dashboard. It is the alias shown at the top of the dashboard, not the UUID.
5 minutes.

1. Install the plugin

Download grain-tag-4.4.0.zip.
In the WordPress admin, go to Plugins, then Add New.
Click Upload Plugin at the top.
Click Choose File and select the downloaded zip file.
Click Install Now, then Activate.

The dashboard also offers the plugin. When you add a new site in the dashboard, select “WordPress”. The guided setup downloads the plugin for you.

2. Configure the plugin

Go to Settings, then Grain Analytics.
Enter your tenant alias.
Make sure that tracking is enabled. It is on by default.
If WooCommerce is installed, select the WooCommerce events to track.
Click Save Settings.

The plugin works with optimization plugins such as WP Rocket and Autoptimize. The settings page also holds these options:

Option	What it does
Exclude Admin Users	Does not track visits by logged-in administrators.
Debug mode	Writes detailed logs to the browser console. Turn it off before you go live.
Async Loading	Loads the script asynchronously. Not every plugin version has this option.

3. Test the plugin

On the same settings page, click Send Test Event at the bottom.
Open the dashboard and make sure that the test event is there.
Open a few pages of your site. The dashboard shows the page views as they arrive.

What the plugin tracks

The plugin sends these events without more configuration:

Event	Properties
Page view	Post type, categories, tags, author
Blog post engagement	Post ID, title, author, categories
Search	Search query
Comment submission	Post ID
User registration and login

The Grain Tag itself also records clicks, scroll depth, and heatmaps. Read Automatic tracking.

WooCommerce

The plugin detects WooCommerce and tracks these events without more configuration:

Event	Detail
Product view	Product ID, name, price, categories
Add to cart	Standard and AJAX add to cart
Remove from cart
Cart view
Checkout started
Order completed	Order details. This is the conversion event.
Coupon applied and coupon removed
Quantity change

To send a WooCommerce event that the plugin does not track, add code to the functions.php file of your child theme. This example sends an event when a visitor adds a product to a wishlist:

function grain_track_custom_product_event() {
  if (!is_product()) return;
  global $product;
  ?>
  <script>
    jQuery(document).on('click', '.add-to-wishlist', function() {
      grainTrack('product_added_to_wishlist', {
        product_id: <?php echo $product->get_id(); ?>,
        product_name: '<?php echo esc_js($product->get_name()); ?>',
        price: <?php echo $product->get_price(); ?>
      });
    });
  </script>
  <?php
}
add_action('wp_footer', 'grain_track_custom_product_event');

Track custom events

The plugin defines a global grainTrack function. The first argument is the event name, the second holds the properties, and the third can hold { flush: true }. Use flush for an event that must leave the browser before the page changes, for example a form that redirects.

grainTrack('button_clicked', {
  button_name: 'Subscribe',
  page: window.location.pathname
});

grainTrack('lead_form_submitted', {
  form_id: 'contact-form'
}, { flush: true });

Read Name events for the naming convention.

Form submissions

Each form plugin fires its own browser event. Add the snippet for your form plugin. Contact Form 7:

document.addEventListener('wpcf7mailsent', function(event) {
  grainTrack('contact_form_submitted', {
    form_id: event.detail.contactFormId,
    form_name: 'Contact Form 7'
  }, { flush: true });
});

Gravity Forms:

jQuery(document).on('gform_confirmation_loaded', function(event, formId){
  grainTrack('gravity_form_submitted', {
    form_id: formId
  }, { flush: true });
});

WPForms:

wpforms.ready(function() {
  wpforms.on('submit', function(event) {
    grainTrack('wpforms_submitted', {
      form_id: event.detail.formId
    }, { flush: true });
  });
});

Install the script by hand

Use this method when you cannot install the plugin. It installs the Grain Tag only. WordPress context and WooCommerce events are not added.

Do not edit the files of your parent theme. A theme update deletes the edit. Use a header and footer plugin, or a child theme.

Option A: header and footer plugin

Install a plugin such as “Insert Headers and Footers” or “WP Code”.
Go to Settings, then Insert Headers and Footers.
In Scripts in Header, paste this code:

<script src="https://tag.grainql.com/v4/your-tenant-id.js"></script>

Replace your-tenant-id with your tenant alias.
Click Save.

Option B: child theme

Add this code to the functions.php file of your child theme:

function grain_analytics_header() {
  $tenant_id = 'your-tenant-id';
  ?>
  <script src="https://tag.grainql.com/v4/<?php echo esc_js($tenant_id); ?>.js"></script>
  <?php
}
add_action('wp_head', 'grain_analytics_header');

Test the script

Open your site in a private (incognito) window.
Open the browser console (F12, then Console).
Type window.GrainTag. The console shows the GrainTag object.
Open a few pages, then open the dashboard and make sure that the page views are there.

With this method, send a custom event with GrainTag.track(eventName, properties) instead of grainTrack. Read Track an event.

Troubleshooting

Symptom	Cause	What to do
The plugin does not track	Tracking is off	In Settings, then Grain Analytics, make sure that “Enable Tracking” is on.
The plugin does not track	The tenant alias is wrong	Compare the alias with the one at the top of the dashboard. Click Send Test Event.
The plugin does not track	A cache plugin serves an old page	Clear the site cache in WP Rocket, W3 Total Cache, or your cache plugin.
The plugin does not track	A JavaScript error stops the script	Open the console (F12, then Console) and read the errors. Deactivate and reactivate the plugin.
The plugin does not track	Another plugin conflicts with the script	Deactivate other plugins one at a time. Make sure that your site does not block the Grain CDN.
Administrators appear in the data	”Exclude Admin Users” is off	Turn it on in the plugin settings. Log out and test in a private window.
The script does not load (manual method)	A PHP syntax error, for example a missing semicolon or quote	Read `functions.php` again. Make sure that the code is in the `<head>` section.
The script does not load (manual method)	A cache plugin serves an old page	Clear the site cache.
Events are not in the dashboard	Events arrive after a delay of up to 30 seconds	Wait 30 seconds, then reload the dashboard.
Events are not in the dashboard	The script did not load	Type `grainTrack` (plugin) or `window.GrainTag` (manual) in the console. Open the Network tab (F12) and look for requests to `*.grainql.com`.
Events are not in the dashboard	An ad blocker or privacy extension blocks the request	Turn the extension off for the test.
WooCommerce events are missing	WooCommerce is inactive or out of date	Update WooCommerce. Make sure that the WooCommerce events are on in the plugin settings. Test add to cart and checkout in a private window.
The site is slow	An optimization plugin processes the Grain script	Exclude the Grain script from optimization. Turn on “Async Loading” if the option exists. Update the plugin.

Read Troubleshooting for cases that are not specific to WordPress.

Next steps

Trackers

Track clicks on specific elements from the dashboard, without code.

Heatmaps

See where visitors click and how far they scroll.

Tracks

Build funnels and paths through your content.

Privacy and consent

What Grain stores, cookieless mode, and consent modes.

Start here

Install without code

Install with code

Track events

Dashboard

Remote configuration

Guides

React

Advanced

Before you start

1. Install the plugin

2. Configure the plugin

3. Test the plugin

What the plugin tracks

WooCommerce

Track custom events

Form submissions

Install the script by hand

Option A: header and footer plugin

Option B: child theme

Test the script

Troubleshooting

Next steps

Trackers

Heatmaps

Tracks

Privacy and consent

​Before you start

​1. Install the plugin

​2. Configure the plugin

​3. Test the plugin

​What the plugin tracks

​WooCommerce

​Track custom events

​Form submissions

​Install the script by hand

​Option A: header and footer plugin

​Option B: child theme

​Test the script

​Troubleshooting

​Next steps

Trackers

Heatmaps

Tracks

Privacy and consent

Before you start

1. Install the plugin

2. Configure the plugin

3. Test the plugin

What the plugin tracks

WooCommerce

Track custom events

Form submissions

Install the script by hand

Option A: header and footer plugin

Option B: child theme

Test the script

Troubleshooting

Next steps