WordPress

​

What You’ll Need

• Admin access to WordPress
• Your Grain tenant ID from grainql.com/dashboard
• 5 minutes

​

Method 1: Official Plugin (Recommended)

​

Features

• ✅ Automatic page view tracking with rich WordPress context (post type, categories, tags, author)
• ✅ WooCommerce e-commerce tracking - product views, add to cart, checkout, purchases
• ✅ Zero configuration - just add your Tenant ID and start tracking
• ✅ Privacy-first - GDPR-compliant cookieless tracking
• ✅ Optimization plugin compatible - works with WP Rocket, Autoptimize, and others
• ✅ Lightweight - minimal performance impact

​

Download and Install

1. Download the plugin: grain-analytics-4.0.2.zip
2. Go to Plugins → Add New in WordPress admin
3. Click Upload Plugin at the top
4. Click Choose File and select the downloaded zip file
5. Click Install Now → Activate

​

Configure the Plugin

1. Go to Settings → Grain Analytics in your WordPress admin
2. Enter your Tenant ID from grainql.com/dashboard
3. Enable tracking (on by default)
4. Choose which WooCommerce events to track (if WooCommerce is installed)
5. Click Save Settings
6. Use the Send Test Event button to verify integration

​

What Gets Tracked Automatically

• Page views with context (post type, categories, tags, author)
• Blog post engagement
• Search queries
• Comment submissions
• User registration/login

• Product views with full details
• Add to cart / Remove from cart
• Cart views
• Checkout started
• Order completed
• Coupon applied/removed

​

Method 2: Manual Script Installation (Advanced)

​

Option A: Header/Footer Plugin

1. Install a plugin like “Insert Headers and Footers” or “WP Code”
2. Go to Settings → Insert Headers and Footers
3. In Scripts in Header, paste:

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

4. Click Save

​

Option B: Child Theme Functions.php

function grain_analytics_header() {
  $tenant_id = 'your-tenant-id'; // Replace with your actual 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');

​

Custom Event Tracking

​

Track Custom Events

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

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

​

Track Blog Posts

<?php if (is_single()) : ?>
<script>
  // Track custom engagement events
  grainTrack('blog_post_engagement', {
    post_id: <?php echo get_the_ID(); ?>,
    post_title: '<?php echo esc_js(get_the_title()); ?>',
    author: '<?php echo esc_js(get_the_author()); ?>',
    categories: <?php echo json_encode(wp_get_post_categories(get_the_ID(), array('fields' => 'names'))); ?>
  });
</script>
<?php endif; ?>

​

Track Form Submissions

document.addEventListener('wpcf7mailsent', function(event) {
  grainTrack('contact_form_submitted', {
    form_id: event.detail.contactFormId,
    form_name: 'Contact Form 7'
  }, { flush: true }); // Flush to ensure event is sent before page redirect
});

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

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

​

Track Search Queries

<?php if (is_search()) : ?>
<script>
  grainTrack('search_performed', {
    query: '<?php echo esc_js(get_search_query()); ?>',
    results_count: <?php echo $wp_query->found_posts; ?>
  });
</script>
<?php endif; ?>

​

Track Comments

function grain_track_comment() {
  ?>
  <script>
    document.addEventListener('DOMContentLoaded', function() {
      const commentForm = document.getElementById('commentform');
      if (commentForm) {
        commentForm.addEventListener('submit', function() {
          grainTrack('comment_submitted', {
            post_id: <?php echo get_the_ID(); ?>
          }, { flush: true });
        });
      }
    });
  </script>
  <?php
}
add_action('comment_form_after', 'grain_track_comment');

​

WooCommerce Integration

​

Automatic WooCommerce Tracking (Plugin)

• ✅ Product views - with product ID, name, price, categories
• ✅ Add to cart - both standard and AJAX add to cart
• ✅ Remove from cart
• ✅ Cart views
• ✅ Checkout started
• ✅ Order completed - critical conversion event with order details
• ✅ Coupon applied/removed
• ✅ Quantity changes

​

Manual WooCommerce Tracking (Advanced)

function grain_track_custom_product_event() {
  if (!is_product()) return;
  global $product;
  ?>
  <script>
    // Track product wishlist add
    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');

​

Test Your Integration

​

Using the Plugin

1. Go to Settings → Grain Analytics in WordPress admin
2. Click Send Test Event button at the bottom
3. Check your Grain dashboard for the test event
4. Navigate your site and verify events appear in real-time

​

Manual Testing

1. Open your site in incognito/private window
2. Open browser console (F12 → Console)
3. Type grainTrack — you should see the function
4. Navigate a few pages
5. Check your Grain dashboard

​

Troubleshooting

​

Plugin Not Tracking

• Verify “Enable Tracking” is ON in Settings → Grain Analytics
• Check that your Tenant ID is correct
• Use the “Send Test Event” button to verify connection
• Clear your site cache (if using WP Rocket, W3 Total Cache, etc.)
• Check browser console for errors (F12 → Console)

• Enable “Exclude Admin Users” in plugin settings
• Log out and test in incognito mode

​

Script Not Loading

• Check PHP syntax (missing semicolons or quotes)
• Clear cache plugins
• Verify code is in <head> section
• Check theme.liquid or functions.php for errors

• Deactivate and reactivate the plugin
• Check for JavaScript conflicts with other plugins
• Ensure your site isn’t blocking the Grain CDN

​

Events Not in Dashboard

• Wait 1-2 minutes (slight processing delay is normal)
• Verify grainTrack function exists in browser console
• Check Network tab (F12) for outgoing requests to *.grainql.com
• Disable ad blockers and privacy extensions temporarily
• Verify your Tenant ID matches your dashboard

​

WooCommerce Events Missing

• Ensure WooCommerce is active and up to date
• Check that WooCommerce events are enabled in plugin settings
• Test add to cart and checkout in incognito mode
• Check browser console for JavaScript errors

​

Performance Issues

• Enable “Async Loading” in plugin settings (if available)
• Ensure you’re using the latest plugin version
• Check for conflicts with optimization plugins (try excluding Grain script from optimization)
• Contact support if issues persist

​

What’s Next?

​

Plugin Support

• Plugin Issues: GitHub Issues
• Documentation: docs.grainql.com
• Dashboard: grainql.com/dashboard
• Email Support: [email protected]