devotox/fathom-client

A Fathom Analytics library to help with client-side routing

Fathom Client

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 and trackGoal) that you can import and safely call anywhere (even if the Fathom script has not yet finished loading).

Installation

Run the following to install in your project:

npm install fathom-client

Motivation

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);
};

API Reference

load(siteId: string, opts?: object)

Injects the Fathom script into the DOM and loads the script asynchronously.

Arguments

• siteId - The site ID provided in the Fathom UI.
• opts - An Object of options:
  • url - The URL of the tracking script (defaults to https://cdn.usefathom.com/script.js). If you're using custom domains then you change this parameter.
  • auto - When false, skips automatically tracking page views on script load (defaults to true).
  • honorDNT - When true, honors the DNT header in the visitor's browser
  • canonical - When false, ignores the canonical tag if present (defaults to true).
  • 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, or hash (see advanced docs).

Example

import { load } from 'fathom-client';

load('MY_FATHOM_ID', {
  includedDomains: ['example.com']
});

trackPageview(opts?: object)

Tracks a pageview.

Arguments

• opts - An Object of options:
  • url - When set, overrides window.location.
  • referrer - When set, overrides document.referrer.

Example

import { trackPageview } from 'fathom-client';

trackPageview();

trackGoal(code: string, cents: number)

Tracks a goal.

Arguments

• code - the code provided in the Fathom UI.
• cents - the value of the goal conversion.

Example

import { trackGoal } from 'fathom-client';

trackGoal('MY_GOAL_CODE', 100);

Usage

This library is JavaScript framework-agnostic. Below are some usage examples with popular frameworks.

Next.js

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', () => {
  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;

Upgrading to 3.x

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.

Releasing

Run the following to publish a new version:

npm run release