Creating and using events

Note: As of Oct 25, 2023, we no longer support trackGoal for new goals/events. If you’re using trackGoal currently, it’ll continue to work, but the new way of doing events is below.

Events (or goals) allow you to track actions that visitors take on your site. For example, button clicks, form submissions, newsletter sign-ups, and even e-commerce events like starting a free trial or buying a product could all be events you create.

Events currently include one required variable (the event name) and then support 3 optional parameters

1. Required: the event name (set in code on your site; see below examples)
2. Optional: options object (supported values are _site_id and _value)

Always make sure that you add the event code after your embed code. We also do not track events locally, as they require https/http to function.

You also cannot rename an event once it’s been created and fired off to your dashboard but you can easily change the event name you're sending us from your code.

Allowed event names

You can name your event any name you want, but avoid special characters and emojis. Event names can be anything, but most importantly, they need to be something you (and your team) can easily and instantly recognize - so you know what each event conversion means.

Example code for events

Here’s an example of how events are programmed into your site:

fathom.trackEvent('cart add', {
  _value: 100, // Value in cents
});

Here’s an example of a simple event without a value or overriding Site ID:

fathom.trackEvent('newsletter signup');

Events as links

There are two ways to fire off an event when a person clicks a link on your site. The first is to add an onclick to the ahref tag, like so:

<a href="/about" onclick="fathom.trackEvent('button click');">About Us</a>

The second way is used if you want to target any/all elements on a page with a specific ID or CLASS. In this method, ensure the javascript code for your events appears after any/all IDs or CLASSES.

Let’s say you want to fire off an event when a customer clicks a link that looks like this:

<a href="/about" id="about-us-link">About us</a>

To do this, you’d add the following script somewhere below the link above (typically just above the </body> element).

<script>
window.addEventListener('load', (event) => {
  document.getElementById('about-us-link').addEventListener('click', () => {
    fathom.trackEvent('about click');
  });
});
</script>

You’d change about-us-link to the ID you’ve used in your code and also change about click to an Event name of your choosing. That Event name will then show up on your dashboard when someone clicks the “About us” link.

If you instead want to fire off an event based on a CLASS (instead of an ID), you’d use the following code. CLASSES are useful as they can be used infinite times on a single page, whereas IDs should only be used once per page (per HTML spec). In this example, we have a series of files that a user can download and we want to see how often these are downloaded.

<a href="file1.pdf" class="download-link">File 1</a>
<a href="file2.pdf" class="download-link">File 2</a>
<a href="file3.pdf" class="download-link">File 3</a>

<script>
window.addEventListener('load', (event) => {
  document.querySelectorAll('.download-link').forEach(item => {
    item.addEventListener('click', event => {
      fathom.trackEvent('file download');
    });
  });
});
</script>

Where .download-link is the class used by your link(s) in your code, and file download is an Event name that’ll then show up on your dashboard when it’s fired off.

In addition to this, you can also get fancy and have dynamic names for your file downloads. Let's do another example:

<a href="file1.pdf" class="download-link">Download File 1</a>
<a href="file2.pdf" class="download-link">Download File 2</a>
<a href="file3.pdf" class="download-link">Download File 3</a>

<script>
window.addEventListener('load', (event) => {
  document.querySelectorAll('.download-link').forEach(item => {
    item.addEventListener('click', event => {
      let fileName = item.getAttribute('href');
      fathom.trackEvent(`file download: ${fileName}`);
    });
  });
});
</script>

If you didn't want to send over the full href value, you could easily add data-filename="File X", for example, to the links and then use getAttribute('data-filename') instead of grabbing the href.

Events as external clicks

If you want to track a few key external links that people could click on from your site to somewhere on the internet, you could do something like this:

<a href="https://amazon.com/x" class="sponsored">Link to Amazon</a>
<a href="https://bestbuy.com/x" class="sponsored">Link to Bestbuy</a>

Where you'd add sponsored as a class to each link you wanted to collect data for. And then you'd add the following javascript to generate the events:

<script>
window.addEventListener('load', (event) => {
  document.querySelectorAll('.sponsored').forEach(item => {
    item.addEventListener('click', event => {
      let url = new URL(item.getAttribute('href'));
      let domainParts = url.hostname.split('.');
      let domainName = domainParts.length > 1 ? domainParts[domainParts.length - 2] : domainParts[0];
 
      fathom.trackEvent(`Sponsor clicked: ${domainName}`);
    });
  });
});
</script>

For another example, if you wanted to track ALL external link clicks, you could use the following javascript:

<script>
window.addEventListener('load', (event) => {
  document.querySelectorAll('a').forEach(item => {
    item.addEventListener('click', event => {
      let linkUrl = new URL(item.getAttribute('href'), window.location.href); // Using the second argument to handle relative URLs
      let currentHostname = window.location.hostname;
 
      if (linkUrl.hostname !== currentHostname) { // If the link's hostname is different from the current page's hostname
        let domainParts = linkUrl.hostname.split('.');
        let domainName = domainParts.length > 1 ? domainParts[domainParts.length - 2] : domainParts[0];
 
        fathom.trackEvent(`External link clicked: ${domainName}`);
      }
    });
  });
});
</script>

Events as a page load

For important pages, if you want to separate them from the “Pages” section of your dashboard, you can fire an event when a page loads:

<script>
window.addEventListener('load', (event) => {
  fathom.trackEvent('checkout completed');
});
</script>

And you’d replace checkout completed with an Event name of your choosing. That Event name will then show up on your dashboard when someone loads the page you place this event on.

Events as e-commerce

With Fathom Analytics, you can send a value with each event completion. That value is in cents, so $1.23 would be 123. You can then assign a currency to it from your site settings in Fathom (on the “Events” tab within your site settings).

To send an event with a value (in this case, a $10 widget), here’s the code:

<script>
window.addEventListener('load', (event) => {
  trackEvent('widget purchase', {
    _value: 1000,
  });
});
</script>

And you’d replace widget purchase an Event name of your choosing. And you'd replace 1000 (which is $10.00) with the value of the event completion.

Say you have e-commerce shopify that has variables for things like product names and product pricing. In that scenario, you can send dynamic values for your event name and values to Fathom Analytics. Here’s an example of code for Shopify (but it can be adapted to any e-commerce software):

<script>
// Set the PRODUCT_NAME and dynamicValue variables using Shopify's Liquid code
{% if product.title %}
  window.PRODUCT_NAME = {{ product.title | escape }};
  window.dynamicValue = {{ product.price | divided_by: 100 }}; // Example: Convert price to a numeric value
{% else %}
  window.PRODUCT_NAME = 'Default Product Name'; // Provide a default name
  window.dynamicValue = 0; // Provide a default value
{% endif %}
</script>
 
<script>
window.addEventListener('load', (event) => {
  const addToCartButtons = document.querySelectorAll('.add-to-cart-button'); // Replace with your actual selector
  addToCartButtons.forEach(button => {
    button.addEventListener('click', (clickEvent) => {
      const dynamicProductName = window.PRODUCT_NAME;
      const eventName = `added to cart: ${dynamicProductName}`;
 
      // Calculate the dynamic value based on your logic
      const dynamicValue = window.dynamicValue;
 
      // Track the event with the dynamic product name and value
      trackEvent(eventName, {
        _value: dynamicValue,
      });
    });
  });
});
</script>

The gist of the above code is to show you that you can dynamically create event names from variables within your site’s software and send them to Fathom with dynamic values as well.

Events as form submissions

If you can edit the HTML of your form, you can fire off an event when a form is submitted:

<form method="post" onsubmit="fathom.trackEvent('form submit');">

And you’d replace form submit with an Event name of your choosing, which would then show up on your dashboard.

If you cannot edit the form code, but the form has an ID (or you can give the form an ID), you can add the following script after/below the form:

<script>
window.addEventListener('load', (event) => {
  document.getElementById('id-of-your-form').addEventListener('submit', () => {
    fathom.trackEvent('form submit');
  });
});
</script>

Where id-of-your-form is the actual ID of your form, and form submit is the Event name you want to use for this event. Again, you could also send over the ID of the form (similar to our example above with sending over the href values of the files being downloaded).

Using events with GTM (Google Tag Manager)

If you're looking for ways to use Fathom events in GTM, take a look at our tailored examples for GTM in our GTM documentation.

If you still have questions or require help with anything, please reach out to us and we'll happily get things sorted out for you.