Creating and using events
Note: As of Oct 25, 2023, we no longer support
trackGoal
for new goals/events. If you’re usingtrackGoal
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
- Required: the event name (set in code on your site; see below examples)
- 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.