Adding Site Analytics with Google GTag

There are a few key components of a personal website that need to be set up right out of the gate. Initial pages, styling, standard deployment and a custom domain are all great places to get started.

Once all that is in place, however, I found myself asking the natural follow up questions: “I got my site working, but is anyone coming to visit? Who are they? Are they reading the articles? Maybe they enjoy the projects?” The point is, I had no way to answer any of these. In my initial setup, I didn’t even have the ability to track things as simple as page views.

Below, I will walk through the process of adding analytic capabilities to a site built with Gatsby. Fortunately, with Gatsby this is a well-worn path which should make for a short guide.

Create a Google Analytics Property

First things first, we need to set up an account and a resource inside of Google Analytics that will track all of our relevant metrics. To do so, visit the Google Analytics site and sign in or create a new account.

Once you have an account, you should create a new property in Analytics. A property represents a way of storing the collection of monitoring data coming from your application(s). You can group as many or as few sites or apps into each property as you like, but all the data for that property will get aggregated and reported on as a group. Thus, it is useful to be mindful of separation of concerns as well as which data is related and which should be kept separate. In my case, I want to monitor a single site, so just one property will do.

Complete instructions for setting up the property can be found here. At the end of this process, you should see a TrackingID value in the format G-XXXXXXXXXX. Make a note of this value, as you will need it later.

Now that we have set up our property and a Google Analytics dashboard for reporting on our site data, we can turn to our actual implementation.

Install the GTag Plugin for Gatsby

When it comes to Gatsby+GTag, it turns out “there’s an app for that.” (Actually, it’s an NPM package, but that didn’t have the same ring.) Our next step is to install this package. From the directory containing your Gatsby app and its package.json file, run:

Copycopy code to clipboard
1npm install gatsby-plugin-google-gtag

Once the package installs, it's time to add it to our Gatsby configuration.

Add GTag to Gatsby Config

The final change we have to make is in our gatsby-config.js file. The plugin gives a whole host of options, but we can keep things simple to start. Add the highlighted plugin object to your config file, replacing GA-TRACKING_ID with your tracking ID noted earlier:

Copygatsby-config.js: copy code to clipboard
1module.exports = {
2  plugins: [
3    ...
4    {
5      resolve: `gatsby-plugin-google-gtag`,
6      options: {
7        // You can add multiple tracking ids and a pageview event will be fired for all of them.
8        trackingIds: [
9          "GA-TRACKING_ID", // Google Analytics / GA
10        ],
11      },
12    },
13  ],
14}

Of course, you can customize the plugin in a variety of ways including excluding certain pages, setting your own origin in the tracking header, and more. To see the full list of options with brief descriptions visit the plugin docs.

Deploy Your App and See the Results!

It is important to note, this plugin ONLY works for apps built in production mode. Because of this, you will not see any analytics data when running and visiting your site locally in development mode. In order to send tracking data, we need to run gatsby build && gatsby serve, or deploy to our hosting service of choice (for me Azure Static Web Apps).

Now with the site built in production, we can visit the home page and in just a few mintues see the visit data propogated to our Google Analytics dashboard. This dashboard shows our total number of users along with information about their visits, page views, and even geographies! If we want to see our traffic in realtime, simply flip over to the 'Realtime' dashboard option to view recent history.

By default, the plugin automatically sends a “pageview” event on every Gatsby route change. While this gets us off to a great start, it is only the tip of the iceberg. We can add custom events that fire on all sorts of user triggers. To get more information on custom events, check out these docs.

Monitoring is a powerful tool and one of the best ways to shorten the feedback loop between an application in production and you and your backlog. In my case, I wanted some rudimentary analytics to understand traffic on a small personal site, but the flexibility of even simple analytics tools like this is endless. Between pre-built analysis and custom events and formulas, any website can easily have an understanding of traffic, usage, and performance patterns.