How to add analytics to a Gatsby site

gatsby-ssr runs at build time for every page, which makes it the one place a site-wide tag belongs. The per-page Gatsby Head API is meant for page-specific tags; using it for analytics means remembering it on every template.

How to install VisitTrack on Gatsby

1. 1

   Step 1: Copy your site id

   Copy your snippet from VisitTrack's install step. Replace SITE_ID below.

2. 2

   Step 2: Add onRenderBody to gatsby-ssr

   Create gatsby-ssr.js (or .tsx) at the project root if it doesn't exist. React needs a key on elements passed in an array.

   gatsby-ssr.jsCopy

   import * as React from "react";
   
   export const onRenderBody = ({ setHeadComponents }) => {
     setHeadComponents([
       <script
         key="visitrack"
         defer
         data-site="SITE_ID"
         src="https://visitrack.app/tracker.js"
       />,
     ]);
   };

3. 3

   Step 3: Build and deploy

   Run gatsby build and deploy public/ (Netlify, Cloudflare Pages, Vercel or any static host). Restart gatsby develop after editing gatsby-ssr if you want to see the tag locally.

How to check VisitTrack is working on Gatsby

1. Search public/index.html for tracker.js after the build.
2. On the deployed site, move between pages with your nav; the VisitTrack live view and Pages tab update for each page.
3. DevTools → Network shows one POST to visitrack.app/api/collect per navigation.

Does VisitTrack track Gatsby page navigation?

Gatsby's router changes the URL with history.pushState when visitors follow a <Link> or you call navigate(). The tracker wraps pushState and listens for popstate, so you don't need onRouteUpdate in gatsby-browser — adding a manual pageview there would double-count.

Prefetching (Gatsby loads page data when links enter the viewport) doesn't change the URL, so it never creates pageviews.

How to track custom events and goals in Gatsby

Call window.visitrack() in event handlers after the action succeeds; it only runs in the browser, so it's safe from Gatsby's build-time rendering as long as it isn't called during render.

export default function Newsletter() {
  async function onSubmit(e) {
    e.preventDefault();
    const res = await fetch("/api/subscribe", { method: "POST", body: new FormData(e.currentTarget) });
    if (res.ok) window.visitrack?.("newsletter_signup", { location: "footer" });
  }
  return (
    <form onSubmit={onSubmit}>
      <input name="email" type="email" required />
      <button data-vt-goal="newsletter_click">Subscribe</button>
    </form>
  );
}

data-vt-goal (clicks) and data-vt-scroll (sections scrolled into view) work as plain JSX attributes, and are re-scanned after client-side navigations.

Script options you might need on Gatsby

All optional — add them to the same tag. Full reference: script configuration.

Gatsby troubleshooting

Not on Gatsby? See all 29 integration guides.