Advanced embed script settings

These are the advanced options we offer with our embed script. Our standard script installation (pasting a single line of code into your site) works great for most customers.

Change when the script is loaded

By default, our script is deferred, meaning our script loads once your HTML has finished loading. That means our script doesn’t affect your site load time or speed in any way (fast sites == better search engine rankings).

You can also swap out defer with async or just load it without either, but we don’t advise this. Instead, this is how our code should be most commonly used:

<script src="https://cdn.usefathom.com/script.js" data-site="ABCDEFG" defer></script>

Honouring Do Not Track (DNT)

By default, we collect data on every visitor to your website, regardless of them having DNT turned on or not. That’s because Fathom is privacy-focused analytics, so nothing personal or identifiable is ever “tracked.” Plus, DNT is deprecated and no longer recommended by any browser.

That said, if you would like to honor DNT then update your code to include data-honor-dnt="true":

<script src="https://cdn.usefathom.com/script.js" data-site="ABCDEFG" data-honor-dnt="true" defer></script>

Disable automatic tracking

By default, we collect a page view every time a visitor to your website loads a page with our script on it. If you don’t want that functionality, you can turn it off by using data-auto="false":

<script src="https://cdn.usefathom.com/script.js" data-site="ABCDEFG" data-auto="false" defer></script>

Ignore canonicals

If there’s a canonical URL in place, we use it instead of the current URL. This is what most customers want, and it’s why it’s the default. If you want to use the current URL, even if there’s canonical (ignoring the canonical), then use data-canonical="false":

<script src="https://cdn.usefathom.com/script.js" data-site="ABCDEFG" data-canonical="false" defer></script>

Single-page applications

If there’s no Fathom integration for your specific javascript system, you can use our generic SPA mode. Most applications use HTML5 History API, so the following code will typically work as-is. This code checks if the History API is available, and if it’s not, it falls back to listening to hash changes:

<script src="https://cdn.usefathom.com/script.js" data-site="ABCDEFG" data-spa="auto" defer></script>

Note: this code will still collect data about the initial load. See Disable automatic tracking above if you don’t want this.

If you want to explicitly say, “We are using only HTML5 History API” or “We only use hash-based routing,” you can use one of the following snippets:

<script src="https://cdn.usefathom.com/script.js" data-site="ABCDEFG" data-spa="history" defer></script>

Or:

<script src="https://cdn.usefathom.com/script.js" data-site="ABCDEFG" data-spa="hash" defer></script>

It’s unlikely that you’ll be using hash-based routing, but some people do (we do in our dashboard).

Client-side API functions

Some functions can be called once the Fathom script has been loaded.

Track pageview

The typical use case for using this would be for someone handling routing manually themselves. Perhaps they have their own SPA / AJAX page loading or want more control over the data they send to Fathom.

fathom.trackPageview();

In addition to this, you can also go more complex and set your own parameters (when using this method, the canonical will not be used, as this becomes the source of truth):

fathom.trackPageview({
        url: 'https://yoursite.com/about',
        referrer: 'https://referrer.com/yoursite-link'
});

You do not have to send both of these properties. If you send just the referrer, the URL will be established using the default method (canonical or current URL).

Track an event

Events are useful for collecting data on elements that visitors can interact with on your site, such as button clicks, form submissions, etc.

// Required: Event Name (string), descriptive name used to identify the event data in your dashboard
// Optional: Value (integer), the value is in cents. The below example equals $1.00
fathom.trackEvent('Your Event Name Here' {
    _value: 100
});

Check out our events documentation for more code examples.