Fathom Analytics Playbook

This is the standard for using Selah Tools' existing Fathom setup across all current and future products.

Use this guide when you add:

• new apps or web properties
• new badges, embeds, QR flows, and share links
• outbound links (email, social, paid, partner)
• custom event tracking

Goals

1. Track attribution consistently across all Selah surfaces.
2. Keep analytics privacy-safe and aligned with Fathom requirements.
3. Make attribution readable in one place without ad hoc naming.

What already exists in Selah

• Route Bible loads Fathom with a runtime-configurable site id and host allowlist.
• Route Bible URL flows support pass-through for utm_* query parameters.
• Route Bible badge.js can add attribution tags for badge-driven traffic.
• Selah badges across apps append UTM parameters to https://selah.tools links.

Required query parameter standard

Every outbound link that we want attribution for should include:

• utm_source: machine-friendly source tag for traffic origin.
• utm_medium: channel type.

Canonical taxonomy

utm_source

Use lowercase snake case:

• allowed chars: a-z, 0-9, _
• normalize separators (-, /, spaces) to _
• max length: 64 chars
• examples:
  • route_bible_builder
  • everyones_scripture_header
  • badge_example_org_post_alpha

utm_medium

Use one of:

• badge
• qr
• share
• email
• social
• paid
• api
• referral

Privacy and compliance rules

Never send personal data in any UTM value.

Do not include:

• names
• email addresses
• phone numbers
• postal addresses
• IP addresses
• identifiers that can single out a person

If a value can identify a person, do not track it.

Implementation pattern (copy/paste)

function normalizeSourceTag(input: string): string {
  return input
    .trim()
    .toLowerCase()
    .replace(/[^a-z0-9]+/g, "_")
    .replace(/_+/g, "_")
    .replace(/^_+|_+$/g, "")
    .slice(0, 64);
}

function withSelahTracking(
  baseUrl: string,
  sourceBase: string,
  medium: string,
): string {
  const source = normalizeSourceTag(sourceBase);
  const url = new URL(baseUrl);
  url.searchParams.set("utm_source", source);
  url.searchParams.set("utm_medium", medium);
  return url.toString();
}

Fathom script setup pattern

Use this for new surfaces that need pageview tracking:

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

For SPAs, keep data-spa="auto" unless there is a concrete reason to change.

Event tracking pattern

Use events only for meaningful outcomes (not every click). Typical examples:

• signup_started
• signup_completed
• copy_snippet
• open_in_app
• checkout_started
• checkout_completed

Safe helper:

function trackFathomEvent(eventName: string, value?: number): void {
  const fathom = (window as unknown as { fathom?: { trackEvent?: (name: string, value?: number) => void } }).fathom;
  if (!fathom?.trackEvent) return;
  if (typeof value === "number") {
    fathom.trackEvent(eventName, value);
    return;
  }
  fathom.trackEvent(eventName);
}

Standard use-case recipes

1) Selah badge on a product page

• utm_medium=badge

2) QR link from slides or print

• utm_medium=qr

3) Share-target and embedded badge flows

• add utm_source and utm_medium where outbound links are generated
• preserve pass-through parameters across redirects and resolver flows

4) Email newsletters

• utm_medium=email

5) Paid and partner traffic

• utm_medium=paid or utm_medium=referral

QA checklist before shipping

1. Click the tagged link and verify URL contains utm_source + utm_medium.
2. Confirm redirect/resolver paths preserve attribution parameters.
3. Confirm no personal data appears in any tracking parameter.
4. Validate values follow naming conventions (lowercase snake case).
5. Confirm Fathom dashboard shows expected UTM breakdown after traffic lands.

Change management

When adding new tracking:

1. Reuse this taxonomy and helper pattern.
2. Add or update tests if link-generation behavior changed.
3. Document any new utm_medium or event names in this page.
4. Avoid one-off conventions per app.

This page is the source of truth for analytics tagging in Selah Tools.