Big news! The walker is now open-source. Open GitHub

How-to GuideHow to set up tracking on Gatsby with walker.js

This guide will explain how you can implement and use walker.js on single-page applications. We will demonstrate the implementation on our own website that uses gatsby.js without using plugins. 🤓

Getting started

First, make a plan of what events you want to measure. Those can be business-related conversion goals or usage events you want to keep track of. Secondly, add the walker to your website.

To set up the walker.js for a project using gatsby.js you have to do the following steps:

1. In gatsby-ssr.js:

We want to load the walker.js on every page by default. Use the gatsby-ssr.js to add it to the head of your page statically.

We also want the small helper function walker that can be used to configure the walker.js. We'll use it to push new events to the elbLayer, on a new page view e.g.

import React from 'react';

export const onRenderBody = ({ setHeadComponents }) => {
  setHeadComponents([
    <script
    key="walker"
    async
    className="elbwalker"
    // data-project="RQGM6XJ"
    src="https://cdn.jsdelivr.net/npm/@elbwalker/walker.js@1.3/dist/walker.js"
    />
  ],
  [
    <script
      key="walker_function"
      dangerouslySetInnerHTML={{
        __html: 
        function walker(...args: unknown[]) {
          (window.elbLayer = window.elbLayer || []).push(...args);}
        ,
      }}
    />
  ]);
};

2. In gatsby-browser.js:

Triggering a new page load each time the route changes is necessary. Pushing the "walker run" event will tell the walker.js to reinitialize and trigger all load-actions on a page.

export function walker(...args) {
    (window.elbLayer = window.elbLayer || []).push(...args);
  }
  
  export const onRouteUpdate = () => {
      walker('walker run');
    }

3. (TypeScript only) Add walker markup to your definitions

To support elb-attributes without getting warnings you can either change the default prefix to e.g. data-elb or you can add the declaration.

import { DOMAttributes } from 'react';

declare module 'react' {
  interface HTMLAttributes<T> extends DOMAttributes<T> {
    elb?: string;
    elbaction?: string;
    elbglobals?: string;
  }
}

Is the walker.js working?

You can quickly check whether the setup is working or not by typing “elbLayer” in the browser console once you have opened your site.

Tagging your site

In this example we keep it simple and only want to tag some basic click events on our homepage:

  1. Clicks on our Github repo
  2. Clicks on our Login button
  3. Clicks on our “schedule call” button (hero, cta)

Tagging GitHub repo buttons

First, we want to tag some outbound-clicks to the walker.js GitHub repository. There are multiple ways how users are getting redirected to the repository.. for example, through a banner, hero, navigation, cta, and footer. In the following example, the banner, as well as the hero banner, is getting tagged.

It makes sense to tag all these different positions and pages where the click event could be fired. Afterwards, it is possible to see precisely which button was used and how many times. This leads to a clean data output.

position: banner

As seen in the picture you only have to set three HTML attributes to collect the banner click triggered by a user. Check out our docs if you are not too familiar with how the walker.js works.

<Banner>
<p
  elb="github"
  elb-github="position: banner"
  className="font-medium text-white"
>
  <span className="md:hidden">
    Big news! The walker is now open-source.
  </span>
  <span className="hidden md:inline">
    Big news! The walker is now open-source.
  </span>
  <span className="block sm:ml-2 sm:inline-block">
    <a
      href="https://github.com/elbwalker/walker.js"
      target="_blank"
      className="font-bold text-white underline"
      elbaction="click"
    >
      {' '}
      Open GitHub <span aria-hidden="true">&rarr;</span>
    </a>
  </span>
</p>
</Banner>

position: cta

The entity and the trigger stay the same.

Using “cta” instead of “banner” as position on the elb-attribute will lead to an event with a respective property (banner or hero) in the analytics tool since we can now differ between a GitHub redirect clicked through either the banner or hero section

<div
className="inline-flex rounded-md shadow"
elb="github"
elb-github="position:cta"
>
<a
  href="https://github.com/elbwalker/walker.js"
  target="_blank"
  className="inline-flex items-center justify-center rounded-md border border-transparent bg-elbwalker-600 px-5 py-3 text-base font-medium text-white hover:bg-elbwalker-700 md:text-lg"
  elbaction="click"
>
  Go to GitHub
</a>
</div>

Tagging Login button

Tagging the login button used on our homepage is as easy as tagging the GitHub click. Since there is only one login button on the entire page, it is not necessary to specify the position.

<div
elb="login"
className="hidden md:absolute md:inset-y-0 md:right-0 md:flex md:items-center md:justify-end"
>
<span className="inline-flex rounded-md shadow">
<a
  href="https://app.elbwalker.com/login"
  className="inline-flex items-center rounded-md border border-transparent bg-white px-4 py-2 text-base font-medium text-elbwalker-600 hover:bg-gray-300"
  elbaction="click"
>
  Log in
</a>
</span>
</div>

Tagging schedule call button

<div
elb="call"
elb-call="position: hero"
className="mt-3 rounded-md shadow sm:mt-0 sm:ml-3"
>
  <a
    href="https://calendly.com/elbwalker-demo/30min"
    target="_blank"
    className="inline-flex items-center justify-center rounded-md border border-transparent bg-white px-8 py-3 text-base font-medium text-elbwalker-600 hover:bg-gray-50 md:py-4 md:px-10 md:text-lg"
    elbaction="click"
  >
    Schedule a free discovery call{' '}
  </a>
</div>

Elbglobals

Summing up the used tagging delivers information of three click events incl. position property(e.g. banner, cta, footer).

But we are still missing important information: On which page the event was fired. That's what elbglobals are used for!

Elbglobals can be defined anywhere on a page and will be collected once, right before the first event is fired.

export default function Layout({ children, pagetype }) {
    return (
      <div
        className="relative overflow-hidden bg-gray-900"
        elbglobals={pagetype: {pagetype}}
      >

dataLayer

We can now exactly track where our event was fired. In this example, the GitHub click event was fired on the company page.

action: 'click'
count: 2
data: {position: 'banner'}
entity: "github"
event: "github click"
globals: {pagetype: 'company'}
group: '01b5e2'
id: '1647968113641-b4b9h9-5'
nested: []
timestamp: 1647968113641
timing: 13.37
trigger: "click"
user: {}
version: {walker: 1.3, config: 1},
walker: true

Elbglobals are an excellent way to specify the context of an event flexibly without limitation. They are so powerful that we will dedicate another single blog post to them.

Looking for more?

Looking for more examples of how to use walker.js for your specific use case and product? Get Inspired by our Template Gallery

Want to learn more about the walker.js? Got feedback?
Check out our GitHub repo (and give us a star if you like what we do), leave us a comment on LinkedIn or write to us at hello@elbwalker.com.

Ready to dive in?Set up elbwalker in under 30 minutes.

Company name

Simplifying Data Collection. Enabling Growth.

© 2022 elbwalker GmbH | crafted in Hamburg, Germany