Fathom Analytics
Get started with Fathom Analytics
$10 credit
Fathom Analytics is a great privacy analytics solution for your Nuxt app. It doesn't gather personal data from your visitors, yet provides detailed insights into how your site is used.
Script Stats
Nuxt Config Setup
The simplest way to load Fathom Analytics globally in your Nuxt App is to use Nuxt config. Alternatively you can directly use the useScriptFathomAnalytics composable.
export default defineNuxtConfig({
scripts: {
registry: {
fathomAnalytics: {
site: 'ABCDE'
}
}
}
})useScriptFathomAnalytics
The useScriptFathomAnalytics composable lets you have fine-grain control over when and how Fathom Analytics is loaded on your site.
const { proxy } = useScriptFathomAnalytics()
proxy.trackGoal('GOAL_ID', 100)Please follow the Registry Scripts guide to learn more about advanced usage.
First-Party Mode
This script supports First-Party Mode which routes all traffic through your domain for improved privacy and ad blocker bypass.
export default defineNuxtConfig({
scripts: {
firstParty: true,
registry: {
fathomAnalytics: { site: 'ABCDE'}
}
}
})To opt-out for this specific script:
useScriptFathomAnalytics({
site: 'ABCDE',
scriptOptions: {
firstParty: false
}
})Example
Using Fathom Analytics only in production while using the proxy to send events.
<script setup lang="ts">
const { proxy } = useScriptFathomAnalytics()
// noop in development, ssr
// just works in production, client
function handleAction() {
proxy.trackGoal('GOAL_ID', 100)
}
</script>
<template>
<div>
<button @click="handleAction">
Send Event
</button>
</div>
</template>Defaults
- Trigger: Script will load when Nuxt is hydrated.
Options
export const FathomAnalyticsOptions = object({
/**
* The Fathom Analytics site ID.
*/
site: string(),
/**
* The Fathom Analytics tracking mode.
*/
spa: optional(union([literal('auto'), literal('history'), literal('hash')])),
/**
* Automatically track page views.
*/
auto: optional(boolean()),
/**
* Enable canonical URL tracking.
*/
canonical: optional(boolean()),
/**
* Honor Do Not Track requests.
*/
honorDnt: optional(boolean()),
})
Additionally like all registry scripts you can provide extra configuration:
scriptInput- HTML attributes to add to the script tag.scriptOptions- See Script Options. Bundling is not supported,bundle: truewill not do anything.
Return values
The Fathom Analytics composable injects a window.fathom object into the global scope.
export interface FathomAnalyticsApi {
beacon: (ctx: { url: string, referrer?: string }) => void
blockTrackingForMe: () => void
enableTrackingForMe: () => void
isTrackingEnabled: () => boolean
send: (type: string, data: unknown) => void
setSite: (siteId: string) => void
sideId: string
trackPageview: (ctx?: { url: string, referrer?: string }) => void
trackGoal: (goalId: string, cents: number) => void
trackEvent: (eventName: string, value: { _value: number }) => void
}
You can access the fathom object as a proxy directly or await the $script promise to access the object. It's recommended
to use the proxy for any void functions.
const { proxy } = useScriptFathomAnalytics()
function trackMyGoal() {
proxy.trackGoal('MY_GOAL_ID', 100)
}
const { onLoaded } = useScriptFathomAnalytics()
onLoaded(({ trackGoal }) => {
trackGoal('MY_GOAL_ID', 100)
})
Example
Loading Fathom Analytics through the app.vue when Nuxt is ready.
<script setup>
useScriptFathomAnalytics({
site: 'YOUR_SITE_ID',
scriptOptions: {
trigger: 'onNuxtReady'
}
})
</script>