Skip to content

πŸ“ˆ 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!

Final polishing touches for Swetrix Data importer

Blue Mouse1e7bdd3c1d54
diff --git a/.gitignore b/.gitignore
index 25d9e41dd..b05fe8575 100644
--- a/.gitignore
+++ b/.gitignore
@@ -73,3 +73,5 @@ docs/.cache-loader
.cursorrules
.cursor
+
+next-env.d.ts
diff --git a/backend/apps/cloud/src/data-import/data-import.processor.ts b/backend/apps/cloud/src/data-import/data-import.processor.ts
index e7f0bdf9c..488b060b1 100644
--- a/backend/apps/cloud/src/data-import/data-import.processor.ts
+++ b/backend/apps/cloud/src/data-import/data-import.processor.ts
@@ -5,6 +5,7 @@ import { Job } from 'bullmq'
import { DataImportService } from './data-import.service'
import { getMapper } from './mappers'
+import { ImportError } from './mappers/mapper.interface'
import { clickhouse } from '../common/integrations/clickhouse'
const CLICKHOUSE_DB = process.env.CLICKHOUSE_DATABASE || 'analytics'
@@ -126,7 +127,12 @@ export class DataImportProcessor extends WorkerHost {
)
}
- await this.dataImportService.markFailed(id, error.message)
+ const userMessage =
+ error instanceof ImportError
+ ? error.message
+ : 'An unexpected error occurred while processing the import. Please try again or contact support.'
+
+ await this.dataImportService.markFailed(id, userMessage)
}
} finally {
this.cleanupFile(filePath)
diff --git a/backend/apps/cloud/src/data-import/mappers/mapper.interface.ts b/backend/apps/cloud/src/data-import/mappers/mapper.interface.ts
index 68cc5c3e8..b7bdc9bf0 100644
--- a/backend/apps/cloud/src/data-import/mappers/mapper.interface.ts
+++ b/backend/apps/cloud/src/data-import/mappers/mapper.interface.ts
@@ -1,3 +1,10 @@
+export class ImportError extends Error {
+ constructor(message: string) {
+ super(message)
+ this.name = 'ImportError'
+ }
+}
+
export interface AnalyticsImportRow {
table: 'analytics' | 'customEV'
data: Record<string, unknown>
diff --git a/backend/apps/cloud/src/data-import/mappers/umami.mapper.ts b/backend/apps/cloud/src/data-import/mappers/umami.mapper.ts
index a1158230b..99fc7a3fd 100644
--- a/backend/apps/cloud/src/data-import/mappers/umami.mapper.ts
+++ b/backend/apps/cloud/src/data-import/mappers/umami.mapper.ts
@@ -5,7 +5,11 @@ import * as crypto from 'crypto'
import { Unzip, UnzipInflate } from 'fflate'
import { parse } from 'csv-parse'
-import { ImportMapper, AnalyticsImportRow } from './mapper.interface'
+import {
+ ImportMapper,
+ ImportError,
+ AnalyticsImportRow,
+} from './mapper.interface'
const WEBSITE_EVENT_CSV = 'website_event.csv'
const MAX_UMAMI_CSV_BYTES = 512 * 1024 * 1024
@@ -207,7 +211,7 @@ export class UmamiMapper implements ImportMapper {
!Number.isFinite(file.originalSize)
) {
fail(
- new Error(
+ new ImportError(
`Unable to validate ${WEBSITE_EVENT_CSV} size in the ZIP archive.`,
),
)
@@ -216,7 +220,7 @@ export class UmamiMapper implements ImportMapper {
if (file.originalSize > MAX_UMAMI_CSV_BYTES) {
fail(
- new Error(
+ new ImportError(
`${WEBSITE_EVENT_CSV} exceeds the ${MAX_UMAMI_CSV_BYTES} byte limit.`,
),
)
@@ -241,7 +245,7 @@ export class UmamiMapper implements ImportMapper {
extractedBytes += chunk.length
if (extractedBytes > MAX_UMAMI_CSV_BYTES) {
fail(
- new Error(
+ new ImportError(
`${WEBSITE_EVENT_CSV} exceeds the ${MAX_UMAMI_CSV_BYTES} byte limit.`,
),
)
@@ -291,7 +295,7 @@ export class UmamiMapper implements ImportMapper {
if (!foundEntry) {
fail(
- new Error(
+ new ImportError(
`ZIP does not contain ${WEBSITE_EVENT_CSV}. Please upload the export ZIP from Umami.`,
),
)
diff --git a/docs/content/docs/data-import.mdx b/docs/content/docs/data-import.mdx
index 346367800..cce446950 100644
--- a/docs/content/docs/data-import.mdx
+++ b/docs/content/docs/data-import.mdx
@@ -5,51 +5,54 @@ description: Import historical analytics data from third-party platforms into Sw
# Data Import
-Swetrix allows you to import historical analytics data from other platforms so you can switch without losing your history. Imported data appears alongside your live-tracked data in dashboards, charts, and reports.
+Swetrix allows you to import historical analytics data from other platforms so you can switch without losing your history. Imported data appears alongside your live-tracked data in dashboards, charts, and reports. It's tagged internally so it can be identified and, if needed, removed later without affecting your live-tracked data.
## Supported Providers
-| Provider | File Format | Status |
-|----------|------------|--------|
-| Umami | ZIP | Available |
-| Plausible | ZIP (CSV) | Coming soon |
-| Fathom | CSV | Coming soon |
-| Simple Analytics | CSV | Coming soon |
-
-## How It Works
-
-1. **Export** your data from the source platform
-2. **Upload** the exported file to Swetrix
-3. **Swetrix processes** the data in the background
-4. **Imported data** appears in your analytics dashboards
-
-Imported data is tagged internally so it can be identified and, if needed, removed later without affecting your live-tracked data.
+- Umami
## Importing from Umami
-### Step 1: Export Your Data from Umami
+<Steps>
+<Step>
+### Export Your Data from Umami
1. Log in to your Umami instance
-2. Go to **Settings** β†’ **Websites**
-3. Click on the website you want to export
-4. Navigate to the **Data** section
-5. Click **Export** to download a ZIP archive (`.zip`)
+2. Go to **Settings** β†’ **Data**
+3. Click on the export button
+4. Select a website you want to export and a date range, then click export - Umami will email you a ZIP file with the exported data
-[SCREENSHOT: Umami export data page]
+<img alt="Umami export data page" src="/docs/img/sitesettings/data-import/umami-export-data.png" />
-### Step 2: Import into Swetrix
+You can learn more on how to export your data from Umami on their [data export documentation](https://docs.umami.is/docs/cloud/export-data).
+
+</Step>
+<Step>
+### Import into Swetrix
1. Go to your project's **Settings** page in Swetrix
2. Click the **Import data** tab
+
+<img
+ alt="Swetrix import data tab"
+ src="/docs/img/sitesettings/data-import/swetrix-import-data-tab.png"
+/>
+
3. Click the **Umami** provider card
+
+<img
+ alt="Swetrix import data tab with provider cards"
+ src="/docs/img/sitesettings/data-import/swetrix-umami-upload-modal.png"
+/>
+
4. In the upload modal, either drag and drop the `.zip` file or click to browse
5. Wait for the upload and processing to complete
-[SCREENSHOT: Swetrix import data tab with provider cards]
-
-[SCREENSHOT: Swetrix upload modal]
+<Callout type="warn">Upload the `.zip` file from Umami directly - do not extract it first.</Callout>
-### Step 3: Monitor Progress
+</Step>
+<Step>
+### Monitor Progress
After uploading, the import will appear in the **Import history** table below the provider cards. You can see:
@@ -59,13 +62,17 @@ After uploading, the import will appear in the **Import history** table below th
The page auto-refreshes while an import is processing. You can navigate away and come back later.
-[SCREENSHOT: Import history table showing a completed import]
+</Step>
+</Steps>
## Viewing Imported Data
Once 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.
-[SCREENSHOT: Dashboard with imported data indicator badge]
+<img
+ alt="Dashboard with imported data indicator badge"
+ src="/docs/img/sitesettings/data-import/imported-data-tooltip.png"
+/>
## Deleting an Import
@@ -78,30 +85,17 @@ If you want to remove imported data:
This permanently removes all analytics rows associated with that import. Your live-tracked data is not affected.
-## Data Mapping
-
-When importing from Umami, Swetrix maps field names and values to match its internal format:
-
-- **Browsers** β€” Umami's lowercase identifiers (e.g., `chrome`, `firefox`, `fxios`) are mapped to Swetrix display names (e.g., `Chrome`, `Firefox`, `Mobile Firefox`)
-- **Operating systems** β€” Names are normalized (e.g., `Mac OS` β†’ `macOS`, `Android OS` β†’ `Android`)
-- **Devices** β€” Categories are mapped (e.g., `laptop` β†’ `desktop`)
-- **UTM parameters** β€” Imported directly (`utm_source`, `utm_medium`, `utm_campaign`, etc.)
-- **Geolocation** β€” Country codes, region codes, and city names are imported as-is
-- **Custom events** β€” Umami event type `2` rows are imported as custom events
-
## Limitations
- **File size**: Maximum 100 MB per upload
- **One at a time**: Only one import can be active (pending or processing) per project at a time
-- **ZIP format**: Upload the `.zip` file from Umami directly β€” Swetrix extracts `website_event.csv` from it automatically (session and event metadata files are not used)
-- **No performance data**: Web Vitals from Umami (LCP, FCP, etc.) are not imported as they use a different measurement schema
- **Timestamps**: Events with invalid timestamps are skipped during import
## Troubleshooting
### Import stuck in "Processing"
-Large files may take several minutes to process. If an import seems stuck, wait up to 30 minutes. If it still hasn't completed, the import may have failed β€” check for error messages in the import history.
+Large files may take several minutes to process. If an import seems stuck, wait up to 30 minutes. If it still hasn't completed, the import may have failed - check for error messages in the import history.
### "An import is already in progress"
@@ -109,7 +103,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 from the export directly β€” do not extract it first.
+Make sure you're uploading the correct file format for your provider. For Umami, upload the `.zip` file from the export directly - do not extract it first.
### Data not appearing in charts
diff --git a/docs/next-env.d.ts b/docs/next-env.d.ts
deleted file mode 100644
index 9edff1c7c..000000000
--- a/docs/next-env.d.ts
+++ /dev/null
@@ -1,6 +0,0 @@
-/// <reference types="next" />
-/// <reference types="next/image-types/global" />
-import "./.next/types/routes.d.ts";
-
-// NOTE: This file should not be edited
-// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.
diff --git a/docs/public/img/sitesettings/data-import/imported-data-tooltip.png b/docs/public/img/sitesettings/data-import/imported-data-tooltip.png
new file mode 100644
index 000000000..45b1235f5
Binary files /dev/null and b/docs/public/img/sitesettings/data-import/imported-data-tooltip.png differ
diff --git a/docs/public/img/sitesettings/data-import/swetrix-import-data-tab.png b/docs/public/img/sitesettings/data-import/swetrix-import-data-tab.png
new file mode 100644
index 000000000..a90fbcc5a
Binary files /dev/null and b/docs/public/img/sitesettings/data-import/swetrix-import-data-tab.png differ
diff --git a/docs/public/img/sitesettings/data-import/swetrix-umami-upload-modal.png b/docs/public/img/sitesettings/data-import/swetrix-umami-upload-modal.png
new file mode 100644
index 000000000..17824bfb0
Binary files /dev/null and b/docs/public/img/sitesettings/data-import/swetrix-umami-upload-modal.png differ
diff --git a/docs/public/img/sitesettings/data-import/umami-export-data.png b/docs/public/img/sitesettings/data-import/umami-export-data.png
new file mode 100644
index 000000000..a3430cedb
Binary files /dev/null and b/docs/public/img/sitesettings/data-import/umami-export-data.png differ
diff --git a/web/app/pages/Project/Settings/components/DataImportTab.tsx b/web/app/pages/Project/Settings/components/DataImportTab.tsx
index cad78861a..be2ae570f 100644
--- a/web/app/pages/Project/Settings/components/DataImportTab.tsx
+++ b/web/app/pages/Project/Settings/components/DataImportTab.tsx
@@ -11,7 +11,7 @@ import {
import cx from 'clsx'
import { toast } from 'sonner'
import dayjs from 'dayjs'
-import { useTranslation } from 'react-i18next'
+import { Trans, useTranslation } from 'react-i18next'
import { useFetcher } from 'react-router'
import { DataImport } from '~/lib/models/Project'
@@ -202,9 +202,6 @@ export default function DataImportTab({ projectId }: DataImportTabProps) {
const providerFileType = selectedProvider
? t(`project.settings.dataImport.${selectedProvider}.fileType`)
: ''
- const providerExportGuide = selectedProvider
- ? t(`project.settings.dataImport.${selectedProvider}.exportGuide`)
- : ''
return (
<div className='space-y-8'>
@@ -229,9 +226,6 @@ export default function DataImportTab({ projectId }: DataImportTabProps) {
)
const name =
providerId.charAt(0).toUpperCase() + providerId.slice(1)
- const description = t(
- `project.settings.dataImport.${providerId}.description`,
- )
const fileType = t(
`project.settings.dataImport.${providerId}.fileType`,
)
@@ -243,7 +237,7 @@ export default function DataImportTab({ projectId }: DataImportTabProps) {
disabled={hasActive}
onClick={() => setSelectedProvider(providerId)}
className={cx(
- 'group relative flex flex-col items-start rounded-xl border p-4 text-left transition-all',
+ 'group relative flex flex-col items-start rounded-lg border p-4 text-left transition-all',
hasActive
? 'cursor-not-allowed border-gray-200 opacity-50 dark:border-slate-800'
: 'cursor-pointer border-gray-200 hover:border-gray-300 hover:bg-gray-50 dark:border-slate-700/80 dark:hover:border-slate-600 dark:hover:bg-slate-900/50',
@@ -273,7 +267,7 @@ export default function DataImportTab({ projectId }: DataImportTabProps) {
colour='inherit'
className='mt-2 text-gray-500 dark:text-gray-400'
>
- {description}
+ {t(`project.settings.dataImport.${providerId}.description`)}
</Text>
</button>
)
@@ -388,14 +382,18 @@ export default function DataImportTab({ projectId }: DataImportTabProps) {
<td className='px-4 py-3 text-right text-sm whitespace-nowrap'>
{(imp.status === 'completed' ||
imp.status === 'failed') && (
- <button
- type='button'
- onClick={() => setDeleteTarget(imp)}
- className='text-gray-400 transition-colors hover:text-red-500 dark:text-gray-500 dark:hover:text-red-400'
- title={t('project.settings.dataImport.deleteImport')}
- >
- <TrashIcon className='size-4' />
- </button>
+ <div className='flex items-center justify-end'>
+ <button
+ type='button'
+ onClick={() => setDeleteTarget(imp)}
+ className='rounded p-1.5 text-red-500 transition-colors hover:bg-red-50 hover:text-red-700 dark:text-red-400 dark:hover:bg-red-900/20 dark:hover:text-red-300'
+ title={t(
+ 'project.settings.dataImport.deleteImport',
+ )}
+ >
+ <TrashIcon className='size-4' />
+ </button>
+ </div>
)}
</td>
</tr>
@@ -420,25 +418,27 @@ export default function DataImportTab({ projectId }: DataImportTabProps) {
size='medium'
message={
<div className='space-y-4'>
- <div className='rounded-lg border border-gray-200 bg-gray-50 p-3 dark:border-slate-700 dark:bg-slate-800/50'>
- <Text
- as='p'
- size='sm'
- weight='medium'
- colour='inherit'
- className='text-gray-700 dark:text-gray-300'
- >
- {t('project.settings.dataImport.howToExport')}
- </Text>
- <Text
- as='p'
- size='sm'
- colour='inherit'
- className='mt-1 text-gray-500 dark:text-gray-400'
- >
- {providerExportGuide}
- </Text>
- </div>
+ <Text
+ as='p'
+ size='sm'
+ colour='inherit'
+ className='text-gray-600 dark:text-gray-400'
+ >
+ <Trans
+ i18nKey='project.settings.dataImport.uploadInstructions'
+ t={t}
+ components={{
+ 1: (
+ <a
+ href='https://swetrix.com/docs/data-import'
+ target='_blank'
+ rel='noreferrer'
+ className='text-indigo-600 hover:text-indigo-500 dark:text-slate-300 dark:hover:text-white'
+ />
+ ),
+ }}
+ />
+ </Text>
<FileUpload
accept={providerFileType}
@@ -471,6 +471,7 @@ export default function DataImportTab({ projectId }: DataImportTabProps) {
? undefined
: t('project.settings.dataImport.maxFileSize', {
fileType: providerFileType.toUpperCase(),
+ maxSize: 100,
})
}
/>
diff --git a/web/app/pages/Project/View/ViewProject.tsx b/web/app/pages/Project/View/ViewProject.tsx
index 60187dc3b..e2e0a66dc 100644
--- a/web/app/pages/Project/View/ViewProject.tsx
+++ b/web/app/pages/Project/View/ViewProject.tsx
@@ -38,7 +38,6 @@ import { useTranslation } from 'react-i18next'
import {
useNavigate,
useSearchParams,
- useLoaderData,
LinkProps,
useFetcher,
} from 'react-router'
@@ -72,10 +71,7 @@ import {
import ViewProjectHotkeys from '~/modals/ViewProjectHotkeys'
import { useAuth } from '~/providers/AuthProvider'
import { useTheme } from '~/providers/ThemeProvider'
-import {
- ProjectViewActionData,
- type ProjectLoaderData,
-} from '~/routes/projects.$id'
+import { ProjectViewActionData } from '~/routes/projects.$id'
import Dropdown from '~/ui/Dropdown'
import Flag from '~/ui/Flag'
import Loader from '~/ui/Loader'
@@ -168,8 +164,6 @@ interface ViewProjectContextType {
resetDateRange: () => void
refreshStats: (isManual?: boolean) => Promise<void>
- hasImportedData: boolean
-
refCalendar: React.RefObject<any>
refCalendarCompare: React.RefObject<any>
@@ -231,7 +225,6 @@ const defaultViewProjectContext: ViewProjectContextType = {
setShowFiltersSearch: () => {},
resetDateRange: () => {},
refreshStats: async () => {},
- hasImportedData: false,
refCalendar: { current: null } as any,
refCalendarCompare: { current: null } as any,
@@ -427,19 +420,6 @@ const ViewProjectContent = () => {
return null
}, [period, searchParams])
- const loaderData = useLoaderData<ProjectLoaderData>()
- const [hasImportedData, setHasImportedData] = useState(false)
-
- useEffect(() => {
- if (loaderData?.hasImportedData instanceof Promise) {
- loaderData.hasImportedData
- .then((value) => setHasImportedData(value))
- .catch(() => setHasImportedData(false))
- } else {
- setHasImportedData(false)
- }
- }, [loaderData?.hasImportedData])
-
const periodPairs = useMemo<TBPeriodPairsProps[]>(() => {
let tbs = null
@@ -1212,8 +1192,6 @@ const ViewProjectContent = () => {
resetDateRange,
refreshStats,
- hasImportedData,
-
refCalendar,
refCalendarCompare,
fullscreenMapRef,
@@ -1255,7 +1233,6 @@ const ViewProjectContent = () => {
setShowFiltersSearch,
resetDateRange,
refreshStats,
- hasImportedData,
refCalendar,
refCalendarCompare,
fullscreenMapRef,
diff --git a/web/app/pages/Project/tabs/Traffic/TrafficView.tsx b/web/app/pages/Project/tabs/Traffic/TrafficView.tsx
index af949c75e..c303b529b 100644
--- a/web/app/pages/Project/tabs/Traffic/TrafficView.tsx
+++ b/web/app/pages/Project/tabs/Traffic/TrafficView.tsx
@@ -141,6 +141,7 @@ interface DeferredTrafficData {
trafficCompareData: ServerTrafficLogResponse | null
overallCompareStats: Record<string, ServerOverallObject> | null
customEventsData: { chart?: { events?: Record<string, unknown> } } | null
+ hasImportedData?: boolean
}
interface TrafficErrorBoundaryState {
@@ -198,6 +199,7 @@ function TrafficDataResolver({
trafficCompareData: trafficComparePromise,
overallCompareStats: overallComparePromise,
customEventsData: customEventsPromise,
+ hasImportedData: hasImportedDataPromise,
} = useLoaderData<ProjectLoaderData>()
const trafficData = trafficDataPromise ? use(trafficDataPromise) : null
@@ -209,6 +211,9 @@ function TrafficDataResolver({
? use(overallComparePromise)
: null
const customEventsData = customEventsPromise ? use(customEventsPromise) : null
+ const hasImportedData = hasImportedDataPromise
+ ? use(hasImportedDataPromise)
+ : false
return (
<>
@@ -218,6 +223,7 @@ function TrafficDataResolver({
trafficCompareData,
overallCompareStats,
customEventsData,
+ hasImportedData,
})}
</>
)
@@ -286,7 +292,6 @@ const TrafficViewInner = ({
isMapFullscreen,
setIsMapFullscreen,
fullscreenMapRef,
- hasImportedData,
} = useViewProjectContext()
const {
t,
@@ -1057,7 +1062,7 @@ const TrafficViewInner = ({
onSwitch={setChartTypeOnClick}
type={chartType}
/>
- {hasImportedData ? (
+ {deferredData.hasImportedData ? (
<Tooltip
text={t('project.settings.dataImport.statsIncludeImported')}
tooltipNode={
diff --git a/web/public/locales/en.json b/web/public/locales/en.json
index 195f4a86f..6d414cea4 100644
--- a/web/public/locales/en.json
+++ b/web/public/locales/en.json
@@ -1754,9 +1754,8 @@
"deleteFailed": "Failed to delete import",
"clickToUpload": "Click to upload",
"orDragDrop": "or drag and drop",
- "maxFileSize": "{{fileType}} file, max 100 MB",
+ "maxFileSize": "{{fileType}} file, max {{maxSize}} MB",
"uploadingProcessing": "Uploading and processing...",
- "howToExport": "How to export your data",
"importFromProvider": "Import from {{provider}}",
"statsIncludeImported": "Stats include imported data",
"imported": "Imported",
@@ -1764,10 +1763,10 @@
"statusProcessing": "Processing",
"statusCompleted": "Completed",
"statusFailed": "Failed",
+ "uploadInstructions": "Please select your export file. Once started, the data will be imported in the background. Please allow for some time to complete. To learn more how to export 3rd party providers data, <1>see our docs</1>.",
"umami": {
"description": "Import pageviews and custom events from Umami export",
- "fileType": ".zip",
- "exportGuide": "In Umami, go to Settings β†’ Websites β†’ click your site β†’ Data β†’ Export. Upload the resulting .zip file directly."
+ "fileType": ".zip"
}
},
"captcha": {