This library is a JavaScript client for Fathom Analytics.
- Asynchronous script loading. We provide a
load
function that will asynchronously inject the Fathom<script>
tag (great for single-page app environments). import
-able tracking functions. We provide tracking functions (trackPageview
andtrackGoal
) that you can import and safely call anywhere (even if the Fathom script has not yet finished loading).
Maintained with
Run the following to install in your project:
npm install fathom-client
The standard installation flow for Fathom is to drop their snippet on your page, which will automatically load the library and track a pageview. This approach works great for server-rendered sites with full page refreshes, but gets tricky when:
- Routing happens on the client-side (e.g. an SPA)
- The DOM is abstracted away (e.g. Next.js)
This library provides an interface you can use to orchestrate Fathom calls at various points in your page lifecycle:
import * as Fathom from 'fathom-client';
// Upon initial page load...
Fathom.load('MY_FATHOM_ID');
// In the route changed event handler...
const onRouteChangeComplete = () => {
Fathom.trackPageview();
};
// In an event handler where a goal is achieved...
const onSignUp = () => {
Fathom.trackGoal('Sign Up', 100);
};
Injects the Fathom script into the DOM and loads the script asynchronously.
siteId
- The site ID provided in the Fathom UI.opts
- An Object of options:url
- The URL of the tracking script (defaults tohttps://cdn.usefathom.com/script.js
). If you're using a custom domain then you should change this parameter to use it (examplehttps://parrot.yourwebsite.com/script.js
).auto
- Whenfalse
, skips automatically tracking page views on script load (defaults totrue
).honorDNT
- Whentrue
, honors the DNT header in the visitor's browsercanonical
- Whenfalse
, ignores the canonical tag if present (defaults totrue
).includedDomains
- Only tracks when on one of these domains.excludedDomains
- Only tracks when NOT on one of these domains.spa
- Accepts one of the following values:auto
,history
, orhash
(see advanced docs).
import { load } from 'fathom-client';
load('MY_FATHOM_ID', {
includedDomains: ['example.com']
});
Tracks a pageview.
opts
- An Object of options:url
- When set, overrideswindow.location
.referrer
- When set, overridesdocument.referrer
.
import { trackPageview } from 'fathom-client';
trackPageview();
Tracks a goal.
code
- the code provided in the Fathom UI.cents
- the value of the goal conversion.
import { trackGoal } from 'fathom-client';
trackGoal('MY_GOAL_CODE', 100);
Enables tracking for the current visitor.
See https://usefathom.com/docs/features/exclude.
None.
import { enableTrackingForMe } from 'fathom-client';
enableTrackingForMe();
Blocks tracking for the current visitor.
See https://usefathom.com/docs/features/exclude.
None.
import { blockTrackingForMe } from 'fathom-client';
blockTrackingForMe();
Checks if tracking is enabled for the current visitor.
See https://usefathom.com/docs/features/exclude.
None.
Boolean.
import { isTrackingEnabled } from 'fathom-client';
const check = isTrackingEnabled(); // `true` by default
Sets the site ID for tracking (overrides the ID used when loading Fathom).
id
- The site ID provided in the Fathom UI.
import { load, setSite } from 'fathom-client';
load('MY_FATHOM_ID');
setSite('A_DIFFERENT_FATHOM_ID');
This library is JavaScript framework-agnostic. Below are some usage examples with popular frameworks.
Create an _app.js
file in your pages
directory, like this:
import React, { useEffect } from 'react';
import Router from 'next/router';
import * as Fathom from 'fathom-client';
// Record a pageview when route changes
Router.events.on('routeChangeComplete', (as, routeProps) => {
if (!routeProps.shallow) {
Fathom.trackPageview();
}
});
function App({ Component, pageProps }) {
// Initialize Fathom when the app loads
useEffect(() => {
Fathom.load('MY_FATHOM_ID', {
includedDomains: ['yourwebsite.com']
});
}, []);
return <Component {...pageProps} />;
}
export default App;
The 3.0 release comes with a new way to load Fathom:
- Fathom.load();
- Fathom.setSiteId('MY_FATHOM_ID');
+ Fathom.load('MY_FATHOM_ID');
The load
function also accepts an object of options:
Fathom.load('MY_FATHOM_ID', {
includedDomains: ['yourwebsite.com']
});
See advanced options for tracking.
Run the following to publish a new version:
npm run release