π Open source, privacy-first web analytics β a cookie-less Google Analytics alternative with built-in error tracking and performance monitoring. Self-host it or use our cloud. Get started for free!
TypeScript chartsclickhousedockergdprgoogle-analyticsmetricsmonitoringmysqlnestjsprivacyredisself-hostedselfhostedstatisticstailwindcssweb-analyticswebanalyticswebsite
feat: Fathom Analytics importer
Blue Mouse1bbd8a4228fe
diff --git a/backend/apps/cloud/src/data-import/mappers/fathom.mapper.ts b/backend/apps/cloud/src/data-import/mappers/fathom.mapper.tsnew file mode 100644index 000000000..2cac3091b--- /dev/null+++ b/backend/apps/cloud/src/data-import/mappers/fathom.mapper.ts@@ -0,0 +1,226 @@+import * as fs from 'fs'+import { parse } from 'csv-parse'++import {+ ImportMapper,+ ImportError,+ AnalyticsImportRow,+} from './mapper.interface'+import {+ normalizeNull,+ truncate,+ sessionIdToPsid,+ MOBILE_BROWSER_VARIANTS,+} from './mapper.utils'++const DATETIME_REGEX =+ /^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01]) ([01]\d|2[0-3]):([0-5]\d):([0-5]\d)$/++const PAGEVIEW_MARKER = 'pageviews'+const EVENT_MARKER = 'event_name'++const COMMON_REQUIRED = ['datetime', 'hostname', 'pathname'] as const++const OS_MAP: Record<string, string> = {+ 'os x': 'macOS',+ macos: 'macOS',+ 'chrome os': 'Chrome OS',+ 'chromium os': 'Chrome OS',+}++const DEVICE_MAP: Record<string, string> = {+ desktop: 'desktop',+ mobile: 'mobile',+ tablet: 'tablet',+ laptop: 'desktop',+}++type FathomFileType = 'pageviews' | 'events'++function detectFileType(headers: string[]): {+ type: FathomFileType+ normalized: string[]+} {+ const normalized = headers.map((h) => h.trim())++ const missing = COMMON_REQUIRED.filter((c) => !normalized.includes(c))+ if (missing.length > 0) {+ throw new ImportError(+ `CSV does not appear to be a Fathom Analytics export. Missing required columns: ${missing.join(', ')}.`,+ )+ }++ if (normalized.includes(PAGEVIEW_MARKER)) {+ return { type: 'pageviews', normalized }+ }++ if (normalized.includes(EVENT_MARKER)) {+ return { type: 'events', normalized }+ }++ throw new ImportError(+ 'CSV does not appear to be a Fathom Analytics export. Expected a pageviews export (with "pageviews" column) or an events export (with "event_name" column).',+ )+}++function mapOS(raw: string | null): string | null {+ if (!raw) return null+ return OS_MAP[raw.toLowerCase()] ?? raw+}++function mapDevice(raw: string | null): string {+ if (!raw) return 'desktop'+ return DEVICE_MAP[raw.toLowerCase()] ?? 'desktop'+}++function mapBrowser(raw: string | null, device: string): string | null {+ if (!raw) return null++ const isMobile = device === 'mobile' || device === 'tablet'+ if (isMobile && MOBILE_BROWSER_VARIANTS[raw]) {+ return MOBILE_BROWSER_VARIANTS[raw]+ }++ return raw+}++function extractHostname(raw: string | null): string | null {+ if (!raw) return null++ try {+ return new URL(raw).hostname+ } catch {+ return raw+ }+}++function buildReferrer(+ hostname: string | null,+ pathname: string | null,+ siteHostname: string | null,+): string | null {+ if (!hostname) return null++ let ref = `https://${hostname}`+ if (pathname) ref += pathname++ if (siteHostname) {+ const cleanRef = hostname.replace(/^www\./, '')+ const cleanSite = siteHostname.replace(/^www\./, '')+ if (cleanRef === cleanSite) return null+ }++ return ref+}++function buildSessionSeed(row: Record<string, string>): string {+ return [+ row.datetime ?? '',+ row.browser ?? '',+ row.country_code ?? '',+ row.city ?? '',+ row.device_type ?? '',+ row.operating_system ?? '',+ ].join('|')+}++export class FathomMapper implements ImportMapper {+ readonly provider = 'fathom'+ readonly expectedFileExtension = '.csv'++ async *createRowStream(+ filePath: string,+ pid: string,+ importID: number,+ ): AsyncIterable<AnalyticsImportRow> {+ let fileType: FathomFileType | null = null+ let headerChecked = false++ const parser = fs.createReadStream(filePath).pipe(+ parse({+ bom: true,+ columns: (headers) => {+ const result = detectFileType(headers)+ fileType = result.type+ headerChecked = true+ return result.normalized+ },+ skip_empty_lines: true,+ trim: true,+ relax_quotes: true,+ relax_column_count: true,+ }),+ )++ for await (const row of parser) {+ const datetime = normalizeNull(row.datetime)+ if (!datetime || !DATETIME_REGEX.test(datetime)) continue++ const count = parseInt(+ fileType === 'pageviews' ? row.pageviews : row.completions,+ 10,+ )+ if (!count || count <= 0) continue++ const device = mapDevice(normalizeNull(row.device_type))+ const browser = mapBrowser(normalizeNull(row.browser), device)+ const os = mapOS(normalizeNull(row.operating_system))+ const siteHost = extractHostname(normalizeNull(row.hostname))++ const cc = normalizeNull(row.country_code)?.toUpperCase() || null+ const validCC = cc && /^[A-Z]{2}$/.test(cc) ? cc : null++ const refHostname = normalizeNull(row.referrer_hostname)+ const refPathname = normalizeNull(row.referrer_pathname)+ const ref = buildReferrer(refHostname, refPathname, siteHost)++ const psid = sessionIdToPsid(buildSessionSeed(row))++ const baseData: Record<string, unknown> = {+ psid,+ profileId: null,+ pid,+ host: truncate(siteHost, 253),+ pg: truncate(normalizeNull(row.pathname), 2048),+ dv: device,+ br: truncate(browser, 30),+ brv: null,+ os: truncate(os, 25),+ osv: null,+ lc: null,+ ref: truncate(ref, 2048),+ so: truncate(normalizeNull(row.utm_source), 256),+ me: truncate(normalizeNull(row.utm_medium), 256),+ ca: truncate(normalizeNull(row.utm_campaign), 256),+ te: truncate(normalizeNull(row.utm_term), 256),+ co: truncate(normalizeNull(row.utm_content), 256),+ cc: validCC,+ rg: null,+ rgc: normalizeNull(row.state)?.slice(0, 10) || null,+ ct: truncate(normalizeNull(row.city), 60),+ 'meta.key': [],+ 'meta.value': [],+ importID,+ created: datetime,+ }++ if (fileType === 'pageviews') {+ for (let i = 0; i < count; i++) {+ yield { table: 'analytics', data: baseData }+ }+ } else {+ const eventName = truncate(normalizeNull(row.event_name), 256) || ''+ const evData = { ...baseData, ev: eventName }+ for (let i = 0; i < count; i++) {+ yield { table: 'customEV', data: evData }+ }+ }+ }++ if (!headerChecked) {+ throw new ImportError(+ 'CSV appears empty or is missing a header row. Please upload a CSV export from Fathom Analytics.',+ )+ }+ }+}diff --git a/backend/apps/cloud/src/data-import/mappers/index.ts b/backend/apps/cloud/src/data-import/mappers/index.tsindex 5bece673a..e967d14c0 100644--- a/backend/apps/cloud/src/data-import/mappers/index.ts+++ b/backend/apps/cloud/src/data-import/mappers/index.ts@@ -1,12 +1,18 @@import { ImportMapper } from './mapper.interface'import { UmamiMapper } from './umami.mapper'import { SimpleAnalyticsMapper } from './simple-analytics.mapper'+import { FathomMapper } from './fathom.mapper'-export const SUPPORTED_PROVIDERS = ['umami', 'simple-analytics'] as const+export const SUPPORTED_PROVIDERS = [+ 'umami',+ 'simple-analytics',+ 'fathom',+] as constconst mappers: Record<string, ImportMapper> = {umami: new UmamiMapper(),'simple-analytics': new SimpleAnalyticsMapper(),+ fathom: new FathomMapper(),}export function getMapper(provider: string): ImportMapper | undefined {diff --git a/backend/apps/community/src/data-import/mappers/fathom.mapper.ts b/backend/apps/community/src/data-import/mappers/fathom.mapper.tsnew file mode 100644index 000000000..2cac3091b--- /dev/null+++ b/backend/apps/community/src/data-import/mappers/fathom.mapper.ts@@ -0,0 +1,226 @@+import * as fs from 'fs'+import { parse } from 'csv-parse'++import {+ ImportMapper,+ ImportError,+ AnalyticsImportRow,+} from './mapper.interface'+import {+ normalizeNull,+ truncate,+ sessionIdToPsid,+ MOBILE_BROWSER_VARIANTS,+} from './mapper.utils'++const DATETIME_REGEX =+ /^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01]) ([01]\d|2[0-3]):([0-5]\d):([0-5]\d)$/++const PAGEVIEW_MARKER = 'pageviews'+const EVENT_MARKER = 'event_name'++const COMMON_REQUIRED = ['datetime', 'hostname', 'pathname'] as const++const OS_MAP: Record<string, string> = {+ 'os x': 'macOS',+ macos: 'macOS',+ 'chrome os': 'Chrome OS',+ 'chromium os': 'Chrome OS',+}++const DEVICE_MAP: Record<string, string> = {+ desktop: 'desktop',+ mobile: 'mobile',+ tablet: 'tablet',+ laptop: 'desktop',+}++type FathomFileType = 'pageviews' | 'events'++function detectFileType(headers: string[]): {+ type: FathomFileType+ normalized: string[]+} {+ const normalized = headers.map((h) => h.trim())++ const missing = COMMON_REQUIRED.filter((c) => !normalized.includes(c))+ if (missing.length > 0) {+ throw new ImportError(+ `CSV does not appear to be a Fathom Analytics export. Missing required columns: ${missing.join(', ')}.`,+ )+ }++ if (normalized.includes(PAGEVIEW_MARKER)) {+ return { type: 'pageviews', normalized }+ }++ if (normalized.includes(EVENT_MARKER)) {+ return { type: 'events', normalized }+ }++ throw new ImportError(+ 'CSV does not appear to be a Fathom Analytics export. Expected a pageviews export (with "pageviews" column) or an events export (with "event_name" column).',+ )+}++function mapOS(raw: string | null): string | null {+ if (!raw) return null+ return OS_MAP[raw.toLowerCase()] ?? raw+}++function mapDevice(raw: string | null): string {+ if (!raw) return 'desktop'+ return DEVICE_MAP[raw.toLowerCase()] ?? 'desktop'+}++function mapBrowser(raw: string | null, device: string): string | null {+ if (!raw) return null++ const isMobile = device === 'mobile' || device === 'tablet'+ if (isMobile && MOBILE_BROWSER_VARIANTS[raw]) {+ return MOBILE_BROWSER_VARIANTS[raw]+ }++ return raw+}++function extractHostname(raw: string | null): string | null {+ if (!raw) return null++ try {+ return new URL(raw).hostname+ } catch {+ return raw+ }+}++function buildReferrer(+ hostname: string | null,+ pathname: string | null,+ siteHostname: string | null,+): string | null {+ if (!hostname) return null++ let ref = `https://${hostname}`+ if (pathname) ref += pathname++ if (siteHostname) {+ const cleanRef = hostname.replace(/^www\./, '')+ const cleanSite = siteHostname.replace(/^www\./, '')+ if (cleanRef === cleanSite) return null+ }++ return ref+}++function buildSessionSeed(row: Record<string, string>): string {+ return [+ row.datetime ?? '',+ row.browser ?? '',+ row.country_code ?? '',+ row.city ?? '',+ row.device_type ?? '',+ row.operating_system ?? '',+ ].join('|')+}++export class FathomMapper implements ImportMapper {+ readonly provider = 'fathom'+ readonly expectedFileExtension = '.csv'++ async *createRowStream(+ filePath: string,+ pid: string,+ importID: number,+ ): AsyncIterable<AnalyticsImportRow> {+ let fileType: FathomFileType | null = null+ let headerChecked = false++ const parser = fs.createReadStream(filePath).pipe(+ parse({+ bom: true,+ columns: (headers) => {+ const result = detectFileType(headers)+ fileType = result.type+ headerChecked = true+ return result.normalized+ },+ skip_empty_lines: true,+ trim: true,+ relax_quotes: true,+ relax_column_count: true,+ }),+ )++ for await (const row of parser) {+ const datetime = normalizeNull(row.datetime)+ if (!datetime || !DATETIME_REGEX.test(datetime)) continue++ const count = parseInt(+ fileType === 'pageviews' ? row.pageviews : row.completions,+ 10,+ )+ if (!count || count <= 0) continue++ const device = mapDevice(normalizeNull(row.device_type))+ const browser = mapBrowser(normalizeNull(row.browser), device)+ const os = mapOS(normalizeNull(row.operating_system))+ const siteHost = extractHostname(normalizeNull(row.hostname))++ const cc = normalizeNull(row.country_code)?.toUpperCase() || null+ const validCC = cc && /^[A-Z]{2}$/.test(cc) ? cc : null++ const refHostname = normalizeNull(row.referrer_hostname)+ const refPathname = normalizeNull(row.referrer_pathname)+ const ref = buildReferrer(refHostname, refPathname, siteHost)++ const psid = sessionIdToPsid(buildSessionSeed(row))++ const baseData: Record<string, unknown> = {+ psid,+ profileId: null,+ pid,+ host: truncate(siteHost, 253),+ pg: truncate(normalizeNull(row.pathname), 2048),+ dv: device,+ br: truncate(browser, 30),+ brv: null,+ os: truncate(os, 25),+ osv: null,+ lc: null,+ ref: truncate(ref, 2048),+ so: truncate(normalizeNull(row.utm_source), 256),+ me: truncate(normalizeNull(row.utm_medium), 256),+ ca: truncate(normalizeNull(row.utm_campaign), 256),+ te: truncate(normalizeNull(row.utm_term), 256),+ co: truncate(normalizeNull(row.utm_content), 256),+ cc: validCC,+ rg: null,+ rgc: normalizeNull(row.state)?.slice(0, 10) || null,+ ct: truncate(normalizeNull(row.city), 60),+ 'meta.key': [],+ 'meta.value': [],+ importID,+ created: datetime,+ }++ if (fileType === 'pageviews') {+ for (let i = 0; i < count; i++) {+ yield { table: 'analytics', data: baseData }+ }+ } else {+ const eventName = truncate(normalizeNull(row.event_name), 256) || ''+ const evData = { ...baseData, ev: eventName }+ for (let i = 0; i < count; i++) {+ yield { table: 'customEV', data: evData }+ }+ }+ }++ if (!headerChecked) {+ throw new ImportError(+ 'CSV appears empty or is missing a header row. Please upload a CSV export from Fathom Analytics.',+ )+ }+ }+}diff --git a/backend/apps/community/src/data-import/mappers/index.ts b/backend/apps/community/src/data-import/mappers/index.tsindex 5bece673a..e967d14c0 100644--- a/backend/apps/community/src/data-import/mappers/index.ts+++ b/backend/apps/community/src/data-import/mappers/index.ts@@ -1,12 +1,18 @@import { ImportMapper } from './mapper.interface'import { UmamiMapper } from './umami.mapper'import { SimpleAnalyticsMapper } from './simple-analytics.mapper'+import { FathomMapper } from './fathom.mapper'-export const SUPPORTED_PROVIDERS = ['umami', 'simple-analytics'] as const+export const SUPPORTED_PROVIDERS = [+ 'umami',+ 'simple-analytics',+ 'fathom',+] as constconst mappers: Record<string, ImportMapper> = {umami: new UmamiMapper(),'simple-analytics': new SimpleAnalyticsMapper(),+ fathom: new FathomMapper(),}export function getMapper(provider: string): ImportMapper | undefined {diff --git a/docs/content/docs/data-import.mdx b/docs/content/docs/data-import.mdxindex 7bdd4d1d1..e5786e4c5 100644--- a/docs/content/docs/data-import.mdx+++ b/docs/content/docs/data-import.mdx@@ -11,6 +11,7 @@ Swetrix allows you to import historical analytics data from other platforms so y- Umami- Simple Analytics+- Fathom Analytics## Importing from Umami@@ -121,6 +122,46 @@ The page auto-refreshes while an import is processing. You can navigate away and</Step></Steps>+## Importing from Fathom Analytics++<Steps>+<Step>+### Export Your Data from Fathom++1. Log in to your [Fathom Analytics](https://usefathom.com) dashboard+2. Go to your site's **Detailed export** page+3. Select the date range and the dimensions you want to export β make sure to include at least **Browser**, **Country**, **City**, **Region**, **Device type**, **UTM parameters**, **Referrer**, **Page**, and **Operating system**+4. Export pageviews and events as separate `.csv` files β Fathom provides separate exports for pageviews and custom events++You can learn more on how to export your data from Fathom on their [export documentation](https://usefathom.com/docs/features/detailed-csv-export).++</Step>+<Step>+### Import into Swetrix++1. Go to your project's **Settings** page in Swetrix+2. Click the **Import data** tab+3. Click the **Fathom Analytics** provider card+4. In the upload modal, either drag and drop your `.csv` file or click to browse+5. Wait for the upload and processing to complete++<Callout type="info">Fathom exports pageviews and events as separate CSV files. Upload them one at a time β you don't need to upload both at once. The imported data will be linked automatically.</Callout>++</Step>+<Step>+### Monitor Progress++After uploading, the import will appear in the **Import history** table below the provider cards. You can see:++- **Status** β Pending, Processing, Completed, or Failed+- **Date range** β The time span of the imported data+- **Rows** β How many analytics events were imported++The page auto-refreshes while an import is processing. You can navigate away and come back later.++</Step>+</Steps>+## Viewing Imported DataOnce an import completes, the data is immediately available in your analytics dashboard. When you select a date range that includes imported data, a small **"Imported"** badge appears near the period selector to let you know.@@ -159,7 +200,7 @@ Only one import can run at a time per project. Wait for the current import to co### Invalid file type error-Make sure you're uploading the correct file format for your provider. For Umami, upload the `.zip` file directly - do not extract it first. For Simple Analytics, upload the `.csv` export file.+Make sure you're uploading the correct file format for your provider. For Umami, upload the `.zip` file directly - do not extract it first. For Simple Analytics and Fathom Analytics, upload the `.csv` export file.### Data not appearing in chartsdiff --git a/web/app/pages/Project/Settings/components/DataImportTab.tsx b/web/app/pages/Project/Settings/components/DataImportTab.tsxindex f849866df..98959b102 100644--- a/web/app/pages/Project/Settings/components/DataImportTab.tsx+++ b/web/app/pages/Project/Settings/components/DataImportTab.tsx@@ -22,8 +22,9 @@ import FileUpload from '~/ui/FileUpload'import { Text } from '~/ui/Text'import UmamiSVG from '~/ui/icons/Umami'import SimpleAnalyticsSVG from '~/ui/icons/SimpleAnalytics'+import FathomSVG from '~/ui/icons/Fathom'-const PROVIDERS = ['umami', 'simple-analytics'] as const+const PROVIDERS = ['fathom', 'simple-analytics', 'umami'] as constconst PROVIDER_ICONS: Record<string,@@ -31,11 +32,13 @@ const PROVIDER_ICONS: Record<> = {umami: UmamiSVG,'simple-analytics': SimpleAnalyticsSVG,+ fathom: FathomSVG,}const PROVIDER_DISPLAY_NAMES: Record<string, string> = {umami: 'Umami','simple-analytics': 'Simple Analytics',+ fathom: 'Fathom Analytics',}const STATUS_ICONS = {diff --git a/web/app/ui/icons/Fathom.tsx b/web/app/ui/icons/Fathom.tsxnew file mode 100644index 000000000..12c84fd38--- /dev/null+++ b/web/app/ui/icons/Fathom.tsx@@ -0,0 +1,23 @@+const FathomSVG = ({ className }: { className?: string }) => (+ <svg className={className} viewBox='0 0 67.851 50'>+ <g transform='translate(11882.544 12524.362)'>+ <path+ d='M81.249,324.048H78.86a1.962,1.962,0,0,0-1.855,1.318l-14.9,42.741a1.963,1.963,0,0,0,1.855,2.61h2.388a1.963,1.963,0,0,0,1.854-1.317l14.9-42.741a1.964,1.964,0,0,0-1.854-2.611'+ transform='translate(-11897.906 -12845.645)'+ fill='hsla(250, 100%, 75%, 1)'+ />+ <path+ d='M14.677,336.886v-1.948a1.964,1.964,0,0,0-1.963-1.964H8.957v-1.805c-.006-2.11.471-3.374.9-3.834l.02-.025a2.2,2.2,0,0,1,1.061-.579,25.624,25.624,0,0,1,4.2-.325h.722a1.964,1.964,0,0,0,1.963-1.964v-1.76a1.96,1.96,0,0,0-1.588-1.928c-.238-.046-.5-.093-.8-.138-.371-.057-2.317-.085-2.7-.086h-.027c-3.163,0-5.856.739-7.66,2.674l0,0c-1.762,1.941-2.4,4.687-2.4,8.023V368A1.964,1.964,0,0,0,4.6,369.962H6.993A1.962,1.962,0,0,0,8.957,368V338.849h3.756a1.962,1.962,0,0,0,1.963-1.963'+ transform='translate(-11885.184 -12844.891)'+ fill='hsla(60, 3%, 20%, 1)'+ />+ <path+ d='M43.125,337.381a14.827,14.827,0,0,0-7.629-1.813,17.368,17.368,0,0,0-7.612,1.546A12.219,12.219,0,0,0,22.7,341.75l-.009.013a1.694,1.694,0,0,0-.254.895,1.792,1.792,0,0,0,1.2,1.684h0l1.927.686a2.748,2.748,0,0,0,3.053-.863,7.86,7.86,0,0,1,.582-.637c1.261-1.224,3.132-1.945,6.044-1.956a10.514,10.514,0,0,1,3.686.574,5.038,5.038,0,0,1,2.175,1.529c1.091,1.339,1.778,3.408,1.842,6.374-2.806.044-5.3.161-7.446.362a34.983,34.983,0,0,0-7.946,1.654h0l-.009,0-.023.006,0,0a12.629,12.629,0,0,0-6.1,3.776,10.233,10.233,0,0,0-2.216,6.72v.064a10.849,10.849,0,0,0,1.67,6.015,10.4,10.4,0,0,0,4.665,3.87,16.69,16.69,0,0,0,6.692,1.232,15.255,15.255,0,0,0,5.159-.965,16.393,16.393,0,0,0,5.07-2.992c.3-.251.573-.52.843-.8a9.263,9.263,0,0,0,1.146,3.251,1.95,1.95,0,0,0,1.673.935h0l1.149-.013a1.964,1.964,0,0,0,1.941-1.963V350.166a18.409,18.409,0,0,0-1.426-7.523,11.334,11.334,0,0,0-4.662-5.262m-1.6,24.9a11.575,11.575,0,0,1-3.878,4.041,9.525,9.525,0,0,1-5.235,1.486,7.992,7.992,0,0,1-5.25-1.5,4.367,4.367,0,0,1-1.228-1.59,5.665,5.665,0,0,1-.42-2.242,5.093,5.093,0,0,1,.655-2.579,5.261,5.261,0,0,1,2.41-1.934,22.124,22.124,0,0,1,6.1-1.587,68.356,68.356,0,0,1,8.281-.581v1.215a10.274,10.274,0,0,1-1.432,5.269'+ transform='translate(-11888.733 -12848.114)'+ fill='hsla(60, 3%, 20%, 1)'+ />+ </g>+ </svg>+)++export default FathomSVGdiff --git a/web/public/locales/en.json b/web/public/locales/en.jsonindex e20ff2d16..14846617b 100644--- a/web/public/locales/en.json+++ b/web/public/locales/en.json@@ -1772,6 +1772,10 @@"simple-analytics": {"description": "Import pageviews and events from Simple Analytics export","fileType": ".csv"+ },+ "fathom": {+ "description": "Import pageviews and events from Fathom Analytics export",+ "fileType": ".csv"}},"captcha": {