Gatsby

Gatsby is a static-site React framework. vTilt initialises in the browser — either through gatsby-browser.js (npm) or an injected stub via gatsby-ssr.js (inline script).

#1. Add your environment variables

# .env.development / .env.production
GATSBY_VTILT_TOKEN=YOUR_PROJECT_TOKEN
GATSBY_VTILT_HOST=https://www.vtilt.com

#2. Install & initialise

Choose how you load the Browser SDK. npm boots the SDK in gatsby-browser.js; the inline script injects a stub via gatsby-ssr.js with no package to install. Both expose the same window.vt global — the rest of this guide is identical either way.

npm install @v-tilt/browser

// gatsby-browser.js
import { vt } from '@v-tilt/browser'

export const onClientEntry = () => {
  vt.init(process.env.GATSBY_VTILT_TOKEN, {
    api_host: process.env.GATSBY_VTILT_HOST,
    autocapture: true,
    capture_pageview: false,
    capture_pageleave: true,
  })
}

export const onRouteUpdate = ({ location, prevLocation }) => {
  vt.capture('$pageview', {
    $current_url: window.location.href,
    $pathname: location.pathname + location.search,
    $referrer: prevLocation?.pathname,
  })
}

#3. Identify users

Wrap your app with a small client component that watches your auth state and calls vt.identify() whenever a user is known.

// gatsby-browser.js (continued)
import { vt } from '@v-tilt/browser'
import React, { useEffect } from 'react'
import { useAuth } from './src/auth'

const Identify = ({ children }) => {
  const { user } = useAuth()
  useEffect(() => {
    if (user) vt.identify(user.id, { email: user.email })
  }, [user])
  return children
}

export const wrapRootElement = ({ element }) => <Identify>{element}</Identify>

#4. Capture custom events

import { vt } from '@v-tilt/browser'

export default function CtaButton() {
  return (
    <button onClick={() => vt.capture('cta_clicked', { location: 'hero' })}>
      Get started
    </button>
  )
}

#Next steps

• Identify & alias — anonymous → known user merge, page-load identify pattern.
• Autocapture — what's captured automatically.
• Reverse proxy — block-resistant ingestion.
• Common mistakes — integration pitfalls to avoid before you ship.