Gatsby Installation

Installing TrackFox on your Gatsby website is simple. You can use our CLI for automatic installation or manually add the tracking script to your Gatsby config.

Quick Install with CLI

The fastest way to get started is using the TrackFox CLI:

npx trackfox add

The CLI will automatically detect your Gatsby setup and install the tracking script in the right place. Learn more →

Manual Installation

Step 1: Get Your Tracking Script

1. Log in to your TrackFox dashboard
2. Click on the website dropdown in the top navigation
3. Select "Site Settings" from the dropdown menu
4. In the General tab, copy your unique tracking script

Your tracking script will look like this:

<script
  defer
  src="https://trackfox.app/script.js"
  data-website-id="your-website-id-here"
  data-domain="yourdomain.com"
></script>

Step 2: Add Script to gatsby-ssr.js

Create or update gatsby-ssr.js in your project root:

// gatsby-ssr.js
import React from "react";

export const onRenderBody = ({ setHeadComponents }) => {
  setHeadComponents([
    <script
      key="trackfox-analytics"
      defer
      src="https://trackfox.app/script.js"
      data-website-id="your-website-id-here"
      data-domain="yourdomain.com"
    />,
  ]);
};

Alternative: Using gatsby-browser.js

If you want to add the script on the client side only:

// gatsby-browser.js
export const onClientEntry = () => {
  const script = document.createElement("script");
  script.defer = true;
  script.src = "https://trackfox.app/script.js";
  script.setAttribute("data-website-id", "your-website-id-here");
  script.setAttribute("data-domain", "yourdomain.com");
  document.head.appendChild(script);
};

Step 3: Verify Installation

1. Save your changes and restart your Gatsby development server
2. Visit your website in a browser
3. Return to your TrackFox dashboard
4. Use the "Verify Installation" button in Site Settings
5. Confirm that page views are being tracked in your dashboard

Custom Event Tracking

Once the base script is installed, you can track custom events:

import React from 'react'

export default function SignupPage() {
  const handleSignup = () => {
    window?.trackfox('signup', {
      email: 'user@example.com'
    })
  }

  const handlePurchase = (amount: number, email: string) => {
    window?.trackfox('payment', {
      email: email,
      amnt: amount // Amount in cents
    })
  }

  return (
    <div>
      <button onClick={handleSignup}>Sign Up</button>
    </div>
  )
}

Environment Variables

Create a .env.production file with your TrackFox configuration:

GATSBY_TRACKFOX_WEBSITE_ID=your_website_id
GATSBY_TRACKFOX_DOMAIN=your_domain.com

Then use them in your gatsby-ssr.js:

import React from "react";

export const onRenderBody = ({ setHeadComponents }) => {
  if (process.env.GATSBY_TRACKFOX_WEBSITE_ID) {
    setHeadComponents([
      <script
        key="trackfox-analytics"
        defer
        src="https://trackfox.app/script.js"
        data-website-id={process.env.GATSBY_TRACKFOX_WEBSITE_ID}
        data-domain={process.env.GATSBY_TRACKFOX_DOMAIN}
      />,
    ]);
  }
};

TypeScript Support

Add type definitions for better TypeScript support:

// src/types/window.d.ts
declare global {
  interface Window {
    trackfox: (action: string, ...args: any[]) => void;
  }
}

export {};

Using Gatsby Plugin (Alternative)

You can also use the React Helmet plugin if you're already using it:

import React from "react";
import { Helmet } from "react-helmet";

export default function Layout({ children }) {
  return (
    <>
      <Helmet>
        <script
          defer
          src="https://trackfox.app/script.js"
          data-website-id="your-website-id-here"
          data-domain="yourdomain.com"
        />
      </Helmet>
      {children}
    </>
  );
}

Testing

Test your installation by:

1. Opening your website in a browser
2. Checking the Network tab for requests to trackfox.app
3. Verifying data appears in your TrackFox dashboard

Troubleshooting

Common issues and solutions:

• Script not loading: Check your website ID and domain configuration
• No data appearing: Ensure the script is loaded before page navigation
• TypeScript errors: Add the type definitions above
• Build errors: Make sure gatsby-ssr.js is in your project root

Important Notes

Important: Make sure to replace your-website-id-here and yourdomain.com with your actual website ID and domain from the TrackFox dashboard.

Next Steps

Now that you have TrackFox installed on your Gatsby website:

• Learn about custom event tracking
• Set up revenue tracking
• Explore the API reference