Grain Tag (Script)

The primary way to install Grain. Perfect for any website — landing pages, static sites, CMSs, or full web apps. No build tools required. Grain Tag automatically tracks page views, clicks, scroll depth, heatmaps, and DOM snapshots with zero code. Just add the script and you’re collecting data.

Using React or Next.js? Try React Quick Start or Next.js Quick Start for framework-specific integration.

Add the Script Tag

Add this to your HTML <head>:

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

Replace your-tenant-id with your tenant identifier (not UUID) from your dashboard. That’s it! Grain is now loaded and tracking page views, heatmap clicks, scroll depth, and DOM snapshots automatically.

Complete HTML Example

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My Landing Page</title>

  <!-- Grain Tag (auto-initializes) -->
  <script src="https://tag.grainql.com/v4/your-tenant-id.js"></script>
</head>
<body>
  <h1>Welcome!</h1>
  <button id="signup-btn">Get Started</button>

  <script>
    // Get SDK instance (already initialized)
    const grain = GrainTag.getInstance();

    // Track button clicks
    document.getElementById('signup-btn').addEventListener('click', function() {
      grain.track('signup_clicked', {
        location: 'hero'
      });

      // Your signup logic...
      window.location.href = '/signup';
    });
  </script>
</body>
</html>

Track Custom Events

const grain = GrainTag.getInstance();

grain.track('button_clicked', {
  button_name: 'signup',
  location: 'hero'
});

You can also use the top-level shortcut:

GrainTag.track('button_clicked', {
  button_name: 'signup',
  location: 'hero'
});

Events are automatically batched and sent. No manual flushing needed.

Track Form Submissions

<form id="contact-form">
  <input type="text" name="name" required>
  <input type="email" name="email" required>
  <button type="submit">Submit</button>
</form>

<script>
  const grain = GrainTag.getInstance();

  document.getElementById('contact-form').addEventListener('submit', function(e) {
    e.preventDefault();

    // Track the submission
    grain.track('form_submitted', {
      form_name: 'contact',
      page: window.location.pathname
    });

    // Your form submission logic...
  });
</script>

Track Link Clicks

<a href="/pricing" id="pricing-link">View Pricing</a>

<script>
  const grain = GrainTag.getInstance();

  document.getElementById('pricing-link').addEventListener('click', function() {
    grain.track('link_clicked', {
      link_text: 'View Pricing',
      destination: '/pricing'
    });
  });
</script>

Identify Users

Track logged-in users:

<script>
  const grain = GrainTag.getInstance();

  // When user logs in — pass only the user ID
  function handleLogin(userId) {
    grain.identify(userId);

    // Track login event
    grain.track('user_logged_in', {
      method: 'email'
    });
  }
</script>

Grain is cookieless by default with daily rotating IDs. When you need explicit consent handling:

<script>
  const grain = GrainTag.getInstance();

  // Grant consent (enables persistent tracking)
  grain.consent.grant();

  // Revoke consent
  grain.consent.revoke();

  // Check consent status
  const status = grain.consent.status();
</script>

Grain Tag automatically tracks page views on initial load and hooks into the History API (pushState / replaceState) to track navigation in single-page apps. No manual page view tracking is needed for most SPAs. If your app uses custom routing that does not go through the History API, you can track navigation manually:

<script>
  const grain = GrainTag.getInstance();

  // Only needed for custom routing that bypasses the History API
  function navigateTo(url) {
    // Your custom navigation logic...
    grain.track('page_viewed', {
      page: url
    });
  }
</script>

Performance Tips

Do: Place Grain in the <head> for early initialization

Do: Use one script tag per page — Grain handles everything

Don’t: Load Grain multiple times — once per page is enough

What’s Next?

Core API Reference

See all available methods and options

Event Tracking Guide

Learn what to track and best practices

Trackers

Track element clicks without code

Vanilla JS, Vue & Svelte

Integration with other frameworks

Using Google Tag Manager instead? Check out the GTM Integration Guide for a no-code setup.

Need remote configuration or feature flags? See @grainql/analytics-web for remote config support.

Getting Started

Integrations

Tracking & Events

Dashboard

MCP Server

Guides

React SDK

Advanced

Add the Script Tag

Complete HTML Example

Track Custom Events

Track Form Submissions

Track Link Clicks

Identify Users

SPA Navigation

Performance Tips

What’s Next?

Core API Reference

Event Tracking Guide

Trackers

Vanilla JS, Vue & Svelte

​Add the Script Tag

​Complete HTML Example

​Track Custom Events

​Track Form Submissions

​Track Link Clicks

​Identify Users

​Consent Management

​SPA Navigation

​Performance Tips

​What’s Next?

Core API Reference

Event Tracking Guide

Trackers

Vanilla JS, Vue & Svelte

Add the Script Tag

Complete HTML Example

Track Custom Events

Track Form Submissions

Track Link Clicks

Identify Users

Consent Management

SPA Navigation

Performance Tips

What’s Next?