Migrate to Netlify Today

Netlify announces the next evolution of Gatsby Cloud. Learn more

ContactSign Up
Community Plugin
View plugin on GitHub

gatsby-plugin-segment-analytics

A Gatsby plugin to add Segment’s Analytics.js integration.

This is designed to work with Gatsby versions ≥ 2.0.0.

Installation

Install with yarn…

yarn add gatsby-plugin-segment-analytics

or NPM…

npm i gatsby-plugin-segment-analytics

Configure

In your gatsby-config.js, add the gatsby-plugin-segment-analytics plugin and provide your Segment Analytics.js write key as an option:

module.exports = {
  plugins: [
    {
      resolve: "gatsby-plugin-segment-analytics",
      options: {
        writeKey: "YOUR WRITE KEY",

        // Optional page name to send with page events; not set by default
        eventName: "YOUR PAGE EVENT NAME",
      },
    },
  ],
}

Usage

The latest version of the Segment tracking snippet will automatically be generated and injected into the <head> of your layout using Gatsby’s SSR API hooks. When a page is loaded, and Gatsby’s onRouteUpdate API is called, analytics.page will be fired.

In development, window.analytics is a shim that simply logs calls to the console rather than sending noise to Segment.

To make it easy to track clicks on outbound links, this plugin provides an OutboundLink component similar to the one provided by gatsby-plugin-google-analytics.

To use it, simply import it and use it like you would the <a> element e.g.

import React
import { OutboundLink } from "gatsby-plugin-segment-analytics"

export default () => {

  <div>
    <OutboundLink
      href="https://www.gatsbyjs.org/packages/gatsby-plugin-segment-analytics/"
    >
      Visit the Segment Analytics plugin page!
    </OutboundLink>
  </div>
}

You can optionally provide an eventName and categoryName prop to OutboundLink. This will change the segment event name (which is defaulted to “Click”), and the category name (which is a property of the segment event), respectively. More information on the segment page event can be found here

<OutboundLink
  href="https://www.gatsbyjs.org/packages/gatsby-plugin-segment-analytics/"
  eventName="Visit External Link"
  categoryName="Gatsby Resource"
>
  Visit the Segment Analytics plugin page!
</OutboundLink>

Special Thanks

This plugin was inspired by work from Stephen Mathieson.

License

MIT

© 2023 Gatsby, Inc.