Gatsby

Name: Rybbit
Author: Rybbit

This guide explains how to integrate Rybbit with your Gatsby site for analytics tracking. Gatsby is a React-based static site generator that builds fast, optimized websites.

How to Add Rybbit to Your Gatsby Site

The recommended way to add a script that should appear on every page in a Gatsby site is by using the onRenderBody API in gatsby-ssr.js. This ensures the script is included in the HTML generated during the build process.

1. Retrieve Your Tracking Script Details

Navigate to your Rybbit dashboard to obtain your Site ID. The script source will be https://app.rybbit.io/api/script.js.

2. Modify `gatsby-ssr.js`

Create a gatsby-ssr.js file at the root of your Gatsby project if it doesn’t already exist. Add the following code to it:

gatsby-ssr.js


import React from 'react';
 
export const onRenderBody = ({ setHeadComponents }) => {
  const rybbitSiteId = 'YOUR_SITE_ID'; // Replace with your actual Site ID
 
  setHeadComponents([
    <script
      key="rybbit-analytics-script" // A unique key for React
      src="https://app.rybbit.io/api/script.js"
      data-site-id={rybbitSiteId}
      async
      defer
    />,
  ]);
};

Make sure to replace YOUR_SITE_ID with your actual Site ID from your Rybbit dashboard. This will add the Rybbit script to the <head> of every page generated by Gatsby.

3. Verify Installation

After rebuilding and deploying your Gatsby site (e.g., gatsby build and then serve the public folder, or your deployment process), open your Rybbit dashboard to check if data is being received. You can also inspect your browser’s network tab to confirm that script.js is loaded on your pages.

Alternative: Using `gatsby-plugin-script`

Gatsby also offers gatsby-plugin-script for more fine-grained control over script loading. If you prefer this method:

Install the plugin: npm install gatsby-plugin-script or yarn add gatsby-plugin-script.
Add it to your gatsby-config.js:

gatsby-config.js


module.exports = {
  plugins: [
    // ... other plugins
    {
      resolve: `gatsby-plugin-script`,
      options: {
        src: `https://app.rybbit.io/api/script.js`,
        async: true,
        defer: true,
        ['data-site-id']: `YOUR_SITE_ID`, // Replace with your Site ID
        // strategy: 'post-hydrate', // Or 'idle', 'off-main-thread'
      },
    },
  ],
};

The onRenderBody method is generally simpler for a basic async script like Rybbit’s.

Page View Tracking: Gatsby sites behave like Single Page Applications (SPAs) after the initial load. Rybbit’s tracking script is designed to automatically detect route changes (e.g., when using Gatsby’s <Link> component) and track them as page views.

If you find that page views are not being tracked correctly after client-side navigation, you might need to manually trigger page views. You can do this using the onRouteUpdate API in gatsby-browser.js:

gatsby-browser.js


export const onRouteUpdate = ({ location, prevLocation }) => {
  if (typeof window !== 'undefined' && window.rybbit && location.pathname !== prevLocation?.pathname) {
    // Rybbit should auto-track, but if needed:
    // window.rybbit.trackPageview();
    console.log("Rybbit: Route updated to", location.pathname); // For debugging
  }
};

Create gatsby-browser.js at the root of your project if it doesn’t exist. Test the default behavior first, as manual tracking might not be necessary.

Custom Event Tracking

Since Gatsby uses React, you can track custom events from any of your React components.

Example in a Gatsby component:


// src/components/MyInteractiveButton.js
import React from 'react';
 
const MyInteractiveButton = ({ buttonText, eventName, eventData }) => {
  const handleClick = () => {
    if (typeof window !== 'undefined' && window.rybbit) {
      window.rybbit.trackEvent(eventName || 'gatsby_button_click', eventData || {});
    }
  };
 
  return (
    <button onClick={handleClick}>
      {buttonText || "Click Me"}
    </button>
  );
};
 
export default MyInteractiveButton;

You can then use this component in your pages or other components:


// src/pages/my-page.js
import React from "react"
import MyInteractiveButton from "../components/MyInteractiveButton"
 
const MyPage = () => (
  <div>
    <h1>Welcome to My Gatsby Page</h1>
    <MyInteractiveButton
      buttonText="Track Special Action"
      eventName="special_action_taken"
      eventData={{ pageContext: "my-page" }}
    />
  </div>
)
 
export default MyPage

Always ensure window.rybbit is available before calling its methods in client-side scripts.