Skip to content

derrickreimer/fathom-client

master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
src
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Fathom Client CircleCI

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).

Maintained with ♥️ by the SavvyCal team

sc-sticker

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 a custom domain then you should change this parameter to use it (example https://parrot.yourwebsite.com/script.js).
    • 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);

enableTrackingForMe()

Enables tracking for the current visitor.

See https://usefathom.com/docs/features/exclude.

Arguments

None.

Example

import { enableTrackingForMe } from 'fathom-client';

enableTrackingForMe();

blockTrackingForMe()

Blocks tracking for the current visitor.

See https://usefathom.com/docs/features/exclude.

Arguments

None.

Example

import { blockTrackingForMe } from 'fathom-client';

blockTrackingForMe();

isTrackingEnabled()

Checks if tracking is enabled for the current visitor.

See https://usefathom.com/docs/features/exclude.

Arguments

None.

Returns

Boolean.

Example

import { isTrackingEnabled } from 'fathom-client';

const check = isTrackingEnabled(); // `true` by default

setSite(id: string)

Sets the site ID for tracking (overrides the ID used when loading Fathom).

Arguments

  • id - The site ID provided in the Fathom UI.

Example

import { load, setSite } from 'fathom-client';

load('MY_FATHOM_ID');

setSite('A_DIFFERENT_FATHOM_ID');

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

or if using the experimental appDir option, add a client component to your root layout.tsx file.

// layout.tsx

import Fathom from "./Fathom" 

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <head>
      </head>
      <body>
        <Fathom />
        <Page>{children}</Page>
      </body>
    </html>
  )
}

and create a client component like so

// Fathom.tsx
'use client'

import { load, trackPageview } from 'fathom-client'
import { useEffect } from 'react'
import { usePathname, useSearchParams } from 'next/navigation'

export default function Fathom() {
  const pathname = usePathname()
  const searchParams = useSearchParams()
  useEffect(() => {
    load('MY_FATHOM_ID', {
      includedDomains: ['yourwebsite.com']
    })
  }, [])
  
  useEffect(() => {
    trackPageview()

    // Record a pageview when route changes
  }, [pathname, searchParams])

  return null
}

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