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!

feat: Google Analytics 4 importer (#509)

Andrii Romasiun252fead63ac4
diff --git a/backend/.env.example b/backend/.env.example
index ea686d386..8a12d2ddb 100644
--- a/backend/.env.example
+++ b/backend/.env.example
@@ -60,6 +60,10 @@ GOOGLE_OAUTH2_CLIENT_SECRET=
GOOGLE_GSC_CLIENT_ID=
GOOGLE_GSC_CLIENT_SECRET=
+# Google Analytics 4 Import
+GOOGLE_GA4_CLIENT_ID=
+GOOGLE_GA4_CLIENT_SECRET=
+
# Github SSO
GITHUB_OAUTH2_CLIENT_ID=
GITHUB_OAUTH2_CLIENT_SECRET=
diff --git a/backend/apps/cloud/src/common/utils.ts b/backend/apps/cloud/src/common/utils.ts
index 3d8c327e3..afe8e896f 100644
--- a/backend/apps/cloud/src/common/utils.ts
+++ b/backend/apps/cloud/src/common/utils.ts
@@ -32,7 +32,12 @@ export const hash = (content: string): string => {
* Derives a key from the SECRET_KEY_BASE environment variable using the HKDF algorithm.
*/
export const deriveKey = (
- purpose: 'refresh-token' | 'access-token' | 'gsc-token' | 'revenue',
+ purpose:
+ | 'refresh-token'
+ | 'access-token'
+ | 'gsc-token'
+ | 'ga4-token'
+ | 'revenue',
length = 32,
) => {
const baseStr = process.env.SECRET_KEY_BASE
diff --git a/backend/apps/cloud/src/data-import/data-import.controller.ts b/backend/apps/cloud/src/data-import/data-import.controller.ts
index b8b812ff5..c08fb0972 100644
--- a/backend/apps/cloud/src/data-import/data-import.controller.ts
+++ b/backend/apps/cloud/src/data-import/data-import.controller.ts
@@ -31,7 +31,8 @@ import { CurrentUserId } from '../auth/decorators/current-user-id.decorator'
import { AuthenticationGuard } from '../auth/guards/authentication.guard'
import { ProjectService } from '../project/project.service'
import { DataImportService } from './data-import.service'
-import { UploadImportDto } from './dto'
+import { Ga4ImportService, Ga4Property } from './ga4-import.service'
+import { UploadImportDto, StartGa4ImportDto } from './dto'
import { getMapper, SUPPORTED_PROVIDERS } from './mappers'
import { DataImportJobData, DATA_IMPORT_QUEUE } from './data-import.processor'
import { trackCustom } from '../common/analytics'
@@ -49,10 +50,120 @@ export class DataImportController {
constructor(
private readonly dataImportService: DataImportService,
private readonly projectService: ProjectService,
+ private readonly ga4ImportService: Ga4ImportService,
@InjectQueue(DATA_IMPORT_QUEUE)
private readonly importQueue: Queue<DataImportJobData>,
) {}
+ @Get('ga4/configured')
+ @Auth()
+ @ApiBearerAuth()
+ async ga4Configured() {
+ return { configured: this.ga4ImportService.isConfigured() }
+ }
+
+ @Post(':projectId/ga4/connect')
+ @Auth()
+ @ApiBearerAuth()
+ async ga4Connect(
+ @Param('projectId') projectId: string,
+ @CurrentUserId() uid: string,
+ ) {
+ return this.ga4ImportService.generateConnectURL(uid, projectId)
+ }
+
+ @Post('ga4/callback')
+ @Auth()
+ @ApiBearerAuth()
+ async ga4Callback(
+ @CurrentUserId() uid: string,
+ @Body() body: { code: string; state: string },
+ ) {
+ if (!body.code || !body.state) {
+ throw new BadRequestException('Missing code or state parameter')
+ }
+ return this.ga4ImportService.handleOAuthCallback(uid, body.code, body.state)
+ }
+
+ @Get(':projectId/ga4/properties')
+ @Auth()
+ @ApiBearerAuth()
+ async ga4Properties(
+ @Param('projectId') projectId: string,
+ @CurrentUserId() uid: string,
+ ): Promise<Ga4Property[]> {
+ return this.ga4ImportService.listProperties(uid, projectId)
+ }
+
+ @Post(':projectId/ga4/start')
+ @Auth()
+ @ApiBearerAuth()
+ async ga4Start(
+ @Param('projectId') projectId: string,
+ @CurrentUserId() uid: string,
+ @Body() dto: StartGa4ImportDto,
+ @Headers() headers: Record<string, string>,
+ @Ip() requestIp: string,
+ ) {
+ const project = await this.projectService.getFullProject(projectId)
+ this.projectService.allowedToManage(project, uid)
+
+ const ip = getIPFromHeaders(headers) || requestIp || ''
+ const userAgent = headers['user-agent'] || ''
+
+ // Create the import record first so we don't consume the OAuth token
+ // if the project already has an active import.
+ const dataImport = await this.dataImportService.create(
+ projectId,
+ 'google-analytics',
+ )
+
+ const { encryptedRefreshToken, clientId, clientSecret } =
+ await this.ga4ImportService.consumeTokenForImport(uid, projectId)
+
+ try {
+ await this.importQueue.add(
+ 'process-import',
+ {
+ id: dataImport.id,
+ importId: dataImport.importId,
+ projectId,
+ provider: 'google-analytics',
+ fileName: '',
+ ip,
+ userAgent,
+ ga4PropertyId: dto.propertyId,
+ encryptedRefreshToken,
+ ga4ClientId: clientId,
+ ga4ClientSecret: clientSecret,
+ },
+ {
+ attempts: 1,
+ removeOnComplete: true,
+ removeOnFail: false,
+ },
+ )
+ } catch (error) {
+ this.logger.error(`Failed to enqueue GA4 import job: ${error.message}`)
+ await this.dataImportService.deleteImportRecord(dataImport.id)
+ await this.ga4ImportService.restoreToken(
+ uid,
+ projectId,
+ encryptedRefreshToken,
+ )
+ throw new ServiceUnavailableException(
+ 'Failed to start import. Please try again later.',
+ )
+ }
+
+ await trackCustom(ip, userAgent, {
+ ev: 'DATA_IMPORT_STARTED',
+ meta: { provider: 'google-analytics' },
+ })
+
+ return dataImport
+ }
+
@Post(':projectId/upload')
@Auth()
@ApiConsumes('multipart/form-data')
@@ -104,6 +215,13 @@ export class DataImportController {
)
}
+ if (!mapper.expectedFileExtension) {
+ this.cleanupFile(file.filename)
+ throw new BadRequestException(
+ `${dto.provider} does not support file uploads. Use the dedicated import endpoint instead.`,
+ )
+ }
+
const ext = path.extname(file.originalname).toLowerCase()
if (ext !== mapper.expectedFileExtension) {
this.cleanupFile(file.filename)
diff --git a/backend/apps/cloud/src/data-import/data-import.module.ts b/backend/apps/cloud/src/data-import/data-import.module.ts
index 593e1c0ee..e36bbd9fd 100644
--- a/backend/apps/cloud/src/data-import/data-import.module.ts
+++ b/backend/apps/cloud/src/data-import/data-import.module.ts
@@ -5,6 +5,7 @@ import { BullModule } from '@nestjs/bullmq'
import { ProjectModule } from '../project/project.module'
import { DataImport } from './entity/data-import.entity'
import { DataImportService } from './data-import.service'
+import { Ga4ImportService } from './ga4-import.service'
import { DataImportController } from './data-import.controller'
import { DataImportProcessor, DATA_IMPORT_QUEUE } from './data-import.processor'
@@ -14,7 +15,7 @@ import { DataImportProcessor, DATA_IMPORT_QUEUE } from './data-import.processor'
BullModule.registerQueue({ name: DATA_IMPORT_QUEUE }),
forwardRef(() => ProjectModule),
],
- providers: [DataImportService, DataImportProcessor],
+ providers: [DataImportService, Ga4ImportService, DataImportProcessor],
controllers: [DataImportController],
exports: [DataImportService],
})
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 783f67973..18799910d 100644
--- a/backend/apps/cloud/src/data-import/data-import.processor.ts
+++ b/backend/apps/cloud/src/data-import/data-import.processor.ts
@@ -26,6 +26,11 @@ export interface DataImportJobData {
fileName: string
ip: string
userAgent: string
+ // GA4-specific (API-based import)
+ ga4PropertyId?: string
+ encryptedRefreshToken?: string
+ ga4ClientId?: string
+ ga4ClientSecret?: string
}
@Processor(DATA_IMPORT_QUEUE, { concurrency: 1 })
@@ -37,9 +42,22 @@ export class DataImportProcessor extends WorkerHost {
}
async process(job: Job<DataImportJobData>): Promise<void> {
- const { id, importId, projectId, provider, fileName, ip, userAgent } =
- job.data
- const filePath = this.getImportFilePath(fileName)
+ const {
+ id,
+ importId,
+ projectId,
+ provider,
+ fileName,
+ ip,
+ userAgent,
+ ga4PropertyId,
+ encryptedRefreshToken,
+ ga4ClientId,
+ ga4ClientSecret,
+ } = job.data
+
+ const isApiBased = provider === 'google-analytics'
+ const filePath = isApiBased ? null : this.getImportFilePath(fileName)
try {
this.logger.log(
@@ -67,7 +85,7 @@ export class DataImportProcessor extends WorkerHost {
await this.dataImportService.markProcessing(id)
- if (!filePath) {
+ if (!isApiBased && !filePath) {
await this.dataImportService.markFailed(
id,
'Invalid import file reference. Please upload the file again.',
@@ -92,11 +110,29 @@ export class DataImportProcessor extends WorkerHost {
const analyticsBatch: Record<string, unknown>[] = []
const customEVBatch: Record<string, unknown>[] = []
+ const context = isApiBased
+ ? {
+ ga4PropertyId,
+ encryptedRefreshToken,
+ ga4ClientId,
+ ga4ClientSecret,
+ }
+ : undefined
+
+ if (isApiBased && (!ga4ClientId || !ga4ClientSecret)) {
+ await this.dataImportService.markFailed(
+ id,
+ 'GA4 import requires valid OAuth client credentials. Please reconnect your Google account.',
+ )
+ return
+ }
+
try {
for await (const row of mapper.createRowStream(
filePath,
projectId,
importId,
+ context,
)) {
totalRows++
@@ -193,7 +229,9 @@ export class DataImportProcessor extends WorkerHost {
})
}
} finally {
- this.cleanupFile(fileName)
+ if (!isApiBased) {
+ this.cleanupFile(fileName)
+ }
}
}
diff --git a/backend/apps/cloud/src/data-import/dto/index.ts b/backend/apps/cloud/src/data-import/dto/index.ts
index 0221d0e71..4eaf9ef6b 100644
--- a/backend/apps/cloud/src/data-import/dto/index.ts
+++ b/backend/apps/cloud/src/data-import/dto/index.ts
@@ -1 +1,2 @@
export { UploadImportDto } from './upload-import.dto'
+export { StartGa4ImportDto } from './start-ga4-import.dto'
diff --git a/backend/apps/cloud/src/data-import/dto/start-ga4-import.dto.ts b/backend/apps/cloud/src/data-import/dto/start-ga4-import.dto.ts
new file mode 100644
index 000000000..a5052a233
--- /dev/null
+++ b/backend/apps/cloud/src/data-import/dto/start-ga4-import.dto.ts
@@ -0,0 +1,12 @@
+import { IsNumberString } from 'class-validator'
+import { ApiProperty } from '@nestjs/swagger'
+
+export class StartGa4ImportDto {
+ @ApiProperty({
+ description:
+ 'GA4 property ID (numeric ID, not the "properties/" prefixed form)',
+ example: '123456789',
+ })
+ @IsNumberString()
+ propertyId: string
+}
diff --git a/backend/apps/cloud/src/data-import/ga4-import.service.ts b/backend/apps/cloud/src/data-import/ga4-import.service.ts
new file mode 100644
index 000000000..0b717317f
--- /dev/null
+++ b/backend/apps/cloud/src/data-import/ga4-import.service.ts
@@ -0,0 +1,276 @@
+import {
+ Injectable,
+ BadRequestException,
+ InternalServerErrorException,
+} from '@nestjs/common'
+import { ConfigService } from '@nestjs/config'
+import { OAuth2Client } from 'google-auth-library'
+import * as crypto from 'crypto'
+
+import { isDevelopment, PRODUCTION_ORIGIN, redis } from '../common/constants'
+import { ProjectService } from '../project/project.service'
+import { deriveKey } from '../common/utils'
+
+const REDIS_STATE_PREFIX = 'ga4-import:state:'
+const REDIS_TOKEN_PREFIX = 'ga4-import:token:'
+const REDIS_TOKEN_TTL = 600 // 10 minutes
+
+const GA4_REDIRECT_URL = isDevelopment
+ ? 'http://localhost:3000/ga4-import-connected'
+ : `${PRODUCTION_ORIGIN}/ga4-import-connected`
+
+const ENCRYPTION_KEY = Buffer.from(deriveKey('ga4-token', 32), 'hex')
+
+function encryptToken(plaintext: string): string {
+ const iv = crypto.randomBytes(12)
+ const cipher = crypto.createCipheriv('aes-256-gcm', ENCRYPTION_KEY, iv)
+ const encrypted = Buffer.concat([
+ cipher.update(plaintext, 'utf8'),
+ cipher.final(),
+ ])
+ const authTag = cipher.getAuthTag()
+ return `${iv.toString('hex')}:${encrypted.toString('hex')}:${authTag.toString('hex')}`
+}
+
+function decryptToken(ciphertext: string): string {
+ const parts = ciphertext.split(':')
+ if (parts.length !== 3) {
+ throw new Error('Invalid encrypted token format')
+ }
+ const [ivHex, encHex, tagHex] = parts
+ const decipher = crypto.createDecipheriv(
+ 'aes-256-gcm',
+ ENCRYPTION_KEY,
+ Buffer.from(ivHex, 'hex'),
+ )
+ decipher.setAuthTag(Buffer.from(tagHex, 'hex'))
+ const decrypted = Buffer.concat([
+ decipher.update(Buffer.from(encHex, 'hex')),
+ decipher.final(),
+ ])
+ return decrypted.toString('utf8')
+}
+
+const GA4_SCOPES = ['https://www.googleapis.com/auth/analytics.readonly']
+
+export interface Ga4Property {
+ propertyId: string
+ displayName: string
+}
+
+@Injectable()
+export class Ga4ImportService {
+ constructor(
+ private readonly configService: ConfigService,
+ private readonly projectService: ProjectService,
+ ) {}
+
+ private getCredentials() {
+ const clientId = this.configService.get<string>('GOOGLE_GA4_CLIENT_ID')
+ const clientSecret = this.configService.get<string>(
+ 'GOOGLE_GA4_CLIENT_SECRET',
+ )
+
+ if (!clientId || !clientSecret) {
+ throw new InternalServerErrorException(
+ 'Google Analytics import is not configured on this instance',
+ )
+ }
+
+ return { clientId, clientSecret }
+ }
+
+ private getOAuthClient() {
+ const { clientId, clientSecret } = this.getCredentials()
+ return new OAuth2Client(clientId, clientSecret, GA4_REDIRECT_URL)
+ }
+
+ async generateConnectURL(uid: string, pid: string): Promise<{ url: string }> {
+ const project = await this.projectService.getFullProject(pid)
+ this.projectService.allowedToManage(project, uid)
+
+ const oauth2Client = this.getOAuthClient()
+
+ const state = `${pid}:${uid}:${Date.now()}`
+ await redis.set(
+ REDIS_STATE_PREFIX + state,
+ JSON.stringify({ uid, pid }),
+ 'EX',
+ REDIS_TOKEN_TTL,
+ )
+
+ const url = oauth2Client.generateAuthUrl({
+ access_type: 'offline',
+ scope: GA4_SCOPES,
+ prompt: 'consent',
+ state,
+ })
+
+ return { url }
+ }
+
+ async handleOAuthCallback(
+ uid: string,
+ code: string,
+ state: string,
+ ): Promise<{ pid: string }> {
+ const cached = await redis.get(REDIS_STATE_PREFIX + state)
+ if (!cached) {
+ throw new BadRequestException('Invalid or expired OAuth state')
+ }
+
+ const { pid, uid: stateUid } = JSON.parse(cached) as {
+ pid: string
+ uid: string
+ }
+
+ if (stateUid !== uid) {
+ throw new BadRequestException('OAuth state mismatch')
+ }
+
+ const project = await this.projectService.getFullProject(pid)
+ this.projectService.allowedToManage(project, uid)
+
+ const oauth2Client = this.getOAuthClient()
+ const { tokens } = await oauth2Client.getToken(code)
+
+ if (!tokens.refresh_token) {
+ throw new BadRequestException(
+ 'Google did not return a refresh token. Please try connecting again.',
+ )
+ }
+
+ const encrypted = encryptToken(tokens.refresh_token)
+
+ await redis.set(
+ REDIS_TOKEN_PREFIX + `${uid}:${pid}`,
+ encrypted,
+ 'EX',
+ REDIS_TOKEN_TTL,
+ )
+
+ await redis.del(REDIS_STATE_PREFIX + state)
+
+ return { pid }
+ }
+
+ async listProperties(uid: string, pid: string): Promise<Ga4Property[]> {
+ const project = await this.projectService.getFullProject(pid)
+ this.projectService.allowedToManage(project, uid)
+
+ const encrypted = await redis.get(REDIS_TOKEN_PREFIX + `${uid}:${pid}`)
+ if (!encrypted) {
+ throw new BadRequestException(
+ 'Google Analytics connection expired. Please connect again.',
+ )
+ }
+
+ const refreshToken = decryptToken(encrypted)
+
+ const oauth2Client = this.getOAuthClient()
+ oauth2Client.setCredentials({ refresh_token: refreshToken })
+
+ const { token } = await oauth2Client.getAccessToken()
+ if (!token) {
+ throw new InternalServerErrorException(
+ 'Failed to obtain access token from Google',
+ )
+ }
+
+ // Refresh the TTL since the user is actively using the connection
+ await redis.expire(REDIS_TOKEN_PREFIX + `${uid}:${pid}`, REDIS_TOKEN_TTL)
+
+ try {
+ const url = new URL(
+ 'https://analyticsadmin.googleapis.com/v1beta/accountSummaries',
+ )
+ url.searchParams.set('pageSize', '200')
+
+ const response = await fetch(url, {
+ headers: { Authorization: `Bearer ${token}` },
+ })
+
+ if (response.status === 403) {
+ const body = await response.json()
+ throw new BadRequestException(
+ body?.error?.message ||
+ 'Access denied by Google. Please ensure the "Google Analytics Admin API" is enabled in your Google Cloud project and that your Google account has access to at least one GA4 property.',
+ )
+ }
+
+ if (!response.ok) {
+ throw new Error(`Google API responded with status ${response.status}`)
+ }
+
+ const data = await response.json()
+ const properties: Ga4Property[] = []
+
+ for (const account of data.accountSummaries || []) {
+ for (const prop of account.propertySummaries || []) {
+ properties.push({
+ propertyId: prop.property?.replace('properties/', '') || '',
+ displayName: prop.displayName || prop.property || 'Unknown',
+ })
+ }
+ }
+
+ return properties
+ } catch (error) {
+ if (error instanceof BadRequestException) throw error
+
+ throw new InternalServerErrorException(
+ 'Failed to fetch Google Analytics properties. Please try again.',
+ )
+ }
+ }
+
+ consumeTokenForImport(
+ uid: string,
+ pid: string,
+ ): Promise<{
+ encryptedRefreshToken: string
+ clientId: string
+ clientSecret: string
+ }> {
+ return this.getAndDeleteToken(uid, pid)
+ }
+
+ async restoreToken(
+ uid: string,
+ pid: string,
+ encryptedRefreshToken: string,
+ ): Promise<void> {
+ const key = REDIS_TOKEN_PREFIX + `${uid}:${pid}`
+ await redis.set(key, encryptedRefreshToken, 'EX', REDIS_TOKEN_TTL)
+ }
+
+ private async getAndDeleteToken(
+ uid: string,
+ pid: string,
+ ): Promise<{
+ encryptedRefreshToken: string
+ clientId: string
+ clientSecret: string
+ }> {
+ const key = REDIS_TOKEN_PREFIX + `${uid}:${pid}`
+ const encrypted = await redis.getdel(key)
+
+ if (!encrypted) {
+ throw new BadRequestException(
+ 'Google Analytics connection expired. Please connect again.',
+ )
+ }
+
+ const { clientId, clientSecret } = this.getCredentials()
+
+ return { encryptedRefreshToken: encrypted, clientId, clientSecret }
+ }
+
+ isConfigured(): boolean {
+ const clientId = this.configService.get<string>('GOOGLE_GA4_CLIENT_ID')
+ const clientSecret = this.configService.get<string>(
+ 'GOOGLE_GA4_CLIENT_SECRET',
+ )
+ return !!(clientId && clientSecret)
+ }
+}
diff --git a/backend/apps/cloud/src/data-import/mappers/ga4.mapper.ts b/backend/apps/cloud/src/data-import/mappers/ga4.mapper.ts
new file mode 100644
index 000000000..5cd625c58
--- /dev/null
+++ b/backend/apps/cloud/src/data-import/mappers/ga4.mapper.ts
@@ -0,0 +1,486 @@
+import { BetaAnalyticsDataClient } from '@google-analytics/data'
+import { OAuth2Client } from 'google-auth-library'
+import * as crypto from 'crypto'
+import dayjs from 'dayjs'
+
+import {
+ ImportMapper,
+ ImportError,
+ AnalyticsImportRow,
+} from './mapper.interface'
+import {
+ truncate,
+ sessionIdToPsid,
+ MOBILE_BROWSER_VARIANTS,
+} from './mapper.utils'
+import { deriveKey } from '../../common/utils'
+
+const ENCRYPTION_KEY = Buffer.from(deriveKey('ga4-token', 32), 'hex')
+
+const PAGE_SIZE = 100_000
+
+const EXCLUDED_EVENTS = new Set([
+ 'page_view',
+ 'session_start',
+ 'first_visit',
+ 'scroll',
+ 'click',
+ 'file_download',
+ 'form_start',
+ 'form_submit',
+ 'view_search_results',
+ 'video_start',
+ 'video_progress',
+ 'video_complete',
+])
+
+const DEVICE_MAP: Record<string, string> = {
+ desktop: 'desktop',
+ mobile: 'mobile',
+ tablet: 'tablet',
+}
+
+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 || raw === '(not set)') return null
+ const isMobile = device === 'mobile' || device === 'tablet'
+ if (isMobile && MOBILE_BROWSER_VARIANTS[raw]) {
+ return MOBILE_BROWSER_VARIANTS[raw]
+ }
+ return raw
+}
+
+function mapOS(raw: string | null): string | null {
+ if (!raw || raw === '(not set)') return null
+ if (raw === 'Macintosh') return 'macOS'
+ return raw
+}
+
+function normalizeGA4Value(val: string | null | undefined): string | null {
+ if (!val || val === '(not set)' || val === '(none)' || val === '(direct)') {
+ return null
+ }
+ return val
+}
+
+function buildReferrer(source: string | null): string | null {
+ if (!source) return null
+ if (source.includes('://')) return source
+ if (source.includes('.')) return `https://${source}`
+ return null
+}
+
+function decryptToken(ciphertext: string): string {
+ const parts = ciphertext.split(':')
+ if (parts.length !== 3) {
+ throw new Error('Invalid encrypted token format')
+ }
+ const [ivHex, encHex, tagHex] = parts
+ const decipher = crypto.createDecipheriv(
+ 'aes-256-gcm',
+ ENCRYPTION_KEY,
+ Buffer.from(ivHex, 'hex'),
+ )
+ decipher.setAuthTag(Buffer.from(tagHex, 'hex'))
+ const decrypted = Buffer.concat([
+ decipher.update(Buffer.from(encHex, 'hex')),
+ decipher.final(),
+ ])
+ return decrypted.toString('utf8')
+}
+
+function getMonthChunks(
+ startDate: string,
+ endDate: string,
+): { start: string; end: string }[] {
+ const chunks: { start: string; end: string }[] = []
+ let current = dayjs(startDate)
+ const end = dayjs(endDate)
+
+ while (current.isBefore(end) || current.isSame(end, 'day')) {
+ const monthEnd = current.endOf('month')
+ const chunkEnd = monthEnd.isAfter(end) ? end : monthEnd
+ chunks.push({
+ start: current.format('YYYY-MM-DD'),
+ end: chunkEnd.format('YYYY-MM-DD'),
+ })
+ current = chunkEnd.add(1, 'day')
+ }
+
+ return chunks
+}
+
+interface SourceInfo {
+ so: string | null
+ me: string | null
+ ca: string | null
+ te: string | null
+ co: string | null
+ ref: string | null
+}
+
+export class Ga4Mapper implements ImportMapper {
+ readonly provider = 'google-analytics'
+ readonly expectedFileExtension = null
+
+ async *createRowStream(
+ _filePath: string | null,
+ pid: string,
+ importID: number,
+ context?: Record<string, unknown>,
+ ): AsyncIterable<AnalyticsImportRow> {
+ if (
+ !context?.encryptedRefreshToken ||
+ !context?.ga4PropertyId ||
+ !context?.ga4ClientId ||
+ !context?.ga4ClientSecret
+ ) {
+ throw new ImportError(
+ 'GA4 import requires OAuth credentials and a property ID.',
+ )
+ }
+
+ const refreshToken = decryptToken(context.encryptedRefreshToken as string)
+ const propertyId = context.ga4PropertyId as string
+ const clientId = context.ga4ClientId as string
+ const clientSecret = context.ga4ClientSecret as string
+
+ const oauth2Client = new OAuth2Client(clientId, clientSecret)
+ oauth2Client.setCredentials({ refresh_token: refreshToken })
+
+ const client = new BetaAnalyticsDataClient({
+ authClient: oauth2Client as any,
+ })
+ const property = propertyId.startsWith('properties/')
+ ? propertyId
+ : `properties/${propertyId}`
+
+ const startDate = (context.startDate as string) || '2020-01-01'
+ const endDate = (context.endDate as string) || dayjs().format('YYYY-MM-DD')
+ const chunks = getMonthChunks(startDate, endDate)
+
+ for (const chunk of chunks) {
+ const sourceLookup = await this.buildSourceLookup(client, property, chunk)
+ yield* this.fetchPageviews(
+ client,
+ property,
+ chunk,
+ pid,
+ importID,
+ sourceLookup,
+ )
+ yield* this.fetchCustomEvents(client, property, chunk, pid, importID)
+ }
+ }
+
+ /**
+ * Fetches source/UTM data into a lookup map keyed by (dateHour|hostName|pagePath).
+ * Kept in memory per monthly chunk -- the map stores only the highest-traffic
+ * source combo for each key, so memory stays bounded.
+ */
+ private async buildSourceLookup(
+ client: BetaAnalyticsDataClient,
+ property: string,
+ dateRange: { start: string; end: string },
+ ): Promise<Map<string, SourceInfo>> {
+ const lookup = new Map<string, SourceInfo & { count: number }>()
+ let offset = 0
+
+ while (true) {
+ const [report] = await client.runReport({
+ property,
+ dateRanges: [{ startDate: dateRange.start, endDate: dateRange.end }],
+ dimensions: [
+ { name: 'dateHour' },
+ { name: 'hostName' },
+ { name: 'pagePath' },
+ { name: 'sessionSource' },
+ { name: 'sessionMedium' },
+ { name: 'sessionCampaignName' },
+ { name: 'sessionManualTerm' },
+ { name: 'sessionManualAdContent' },
+ ],
+ metrics: [{ name: 'screenPageViews' }],
+ limit: PAGE_SIZE,
+ offset,
+ keepEmptyRows: false,
+ })
+
+ const rows = report.rows || []
+ if (rows.length === 0) break
+
+ for (const row of rows) {
+ const dims = row.dimensionValues || []
+ const metrics = row.metricValues || []
+
+ const dateHour = dims[0]?.value || ''
+ const host = normalizeGA4Value(dims[1]?.value)
+ const pagePath = normalizeGA4Value(dims[2]?.value)
+ const source = normalizeGA4Value(dims[3]?.value)
+ const medium = normalizeGA4Value(dims[4]?.value)
+ const campaign = normalizeGA4Value(dims[5]?.value)
+ const term = normalizeGA4Value(dims[6]?.value)
+ const content = normalizeGA4Value(dims[7]?.value)
+
+ const count = parseInt(metrics[0]?.value || '0', 10)
+ if (count <= 0) continue
+
+ const key = `${dateHour}|${host || ''}|${pagePath || ''}`
+ const existing = lookup.get(key)
+
+ if (!existing || count > existing.count) {
+ lookup.set(key, {
+ so: source,
+ me: medium,
+ ca: campaign,
+ te: term,
+ co: content,
+ ref: buildReferrer(source),
+ count,
+ })
+ }
+ }
+
+ if (rows.length < PAGE_SIZE) break
+ offset += PAGE_SIZE
+ }
+
+ return lookup
+ }
+
+ private async *fetchPageviews(
+ client: BetaAnalyticsDataClient,
+ property: string,
+ dateRange: { start: string; end: string },
+ pid: string,
+ importID: number,
+ sourceLookup: Map<string, SourceInfo>,
+ ): AsyncIterable<AnalyticsImportRow> {
+ let offset = 0
+
+ while (true) {
+ const [report] = await client.runReport({
+ property,
+ dateRanges: [{ startDate: dateRange.start, endDate: dateRange.end }],
+ dimensions: [
+ { name: 'dateHour' },
+ { name: 'hostName' },
+ { name: 'pagePath' },
+ { name: 'deviceCategory' },
+ { name: 'browser' },
+ { name: 'operatingSystem' },
+ { name: 'countryId' },
+ { name: 'region' },
+ { name: 'city' },
+ ],
+ metrics: [{ name: 'screenPageViews' }],
+ limit: PAGE_SIZE,
+ offset,
+ keepEmptyRows: false,
+ })
+
+ const rows = report.rows || []
+ if (rows.length === 0) break
+
+ for (const row of rows) {
+ const dims = row.dimensionValues || []
+ const metrics = row.metricValues || []
+
+ const dateHour = dims[0]?.value || ''
+ const host = normalizeGA4Value(dims[1]?.value)
+ const pagePath = normalizeGA4Value(dims[2]?.value)
+ const deviceRaw = dims[3]?.value || null
+ const browserRaw = dims[4]?.value || null
+ const osRaw = dims[5]?.value || null
+ const countryId = normalizeGA4Value(dims[6]?.value)
+ const regionRaw = normalizeGA4Value(dims[7]?.value)
+ const cityRaw = normalizeGA4Value(dims[8]?.value)
+
+ const count = parseInt(metrics[0]?.value || '0', 10)
+ if (count <= 0) continue
+
+ const created = this.parseGA4DateHour(dateHour)
+ if (!created) continue
+
+ const device = mapDevice(deviceRaw)
+ const browser = mapBrowser(browserRaw, device)
+ const os = mapOS(osRaw)
+ const cc = countryId && /^[A-Z]{2}$/.test(countryId) ? countryId : null
+
+ // Enrich with source/UTM data from lookup
+ const sourceKey = `${dateHour}|${host || ''}|${pagePath || ''}`
+ const sourceInfo = sourceLookup.get(sourceKey)
+
+ const sessionSeed = [
+ dateHour,
+ host,
+ pagePath,
+ deviceRaw,
+ browserRaw,
+ osRaw,
+ countryId,
+ regionRaw,
+ cityRaw,
+ ].join('|')
+ const psid = sessionIdToPsid(sessionSeed)
+
+ const data: Record<string, unknown> = {
+ psid,
+ profileId: null,
+ pid,
+ host: truncate(host, 253),
+ pg: truncate(pagePath, 2048),
+ dv: device,
+ br: truncate(browser, 30),
+ brv: null,
+ os: truncate(os, 25),
+ osv: null,
+ lc: null,
+ ref: truncate(sourceInfo?.ref ?? null, 2048),
+ so: truncate(sourceInfo?.so ?? null, 256),
+ me: truncate(sourceInfo?.me ?? null, 256),
+ ca: truncate(sourceInfo?.ca ?? null, 256),
+ te: truncate(sourceInfo?.te ?? null, 256),
+ co: truncate(sourceInfo?.co ?? null, 256),
+ cc,
+ rg: null,
+ rgc: truncate(regionRaw, 100),
+ ct: truncate(cityRaw, 60),
+ 'meta.key': [],
+ 'meta.value': [],
+ importID,
+ created,
+ }
+
+ for (let i = 0; i < count; i++) {
+ yield { table: 'analytics', data }
+ }
+ }
+
+ if (rows.length < PAGE_SIZE) break
+ offset += PAGE_SIZE
+ }
+ }
+
+ private async *fetchCustomEvents(
+ client: BetaAnalyticsDataClient,
+ property: string,
+ dateRange: { start: string; end: string },
+ pid: string,
+ importID: number,
+ ): AsyncIterable<AnalyticsImportRow> {
+ let offset = 0
+
+ while (true) {
+ const [report] = await client.runReport({
+ property,
+ dateRanges: [{ startDate: dateRange.start, endDate: dateRange.end }],
+ dimensions: [
+ { name: 'dateHour' },
+ { name: 'eventName' },
+ { name: 'pagePath' },
+ { name: 'deviceCategory' },
+ { name: 'browser' },
+ { name: 'operatingSystem' },
+ { name: 'countryId' },
+ { name: 'hostName' },
+ ],
+ metrics: [{ name: 'eventCount' }],
+ limit: PAGE_SIZE,
+ offset,
+ keepEmptyRows: false,
+ })
+
+ const rows = report.rows || []
+ if (rows.length === 0) break
+
+ for (const row of rows) {
+ const dims = row.dimensionValues || []
+ const metrics = row.metricValues || []
+
+ const dateHour = dims[0]?.value || ''
+ const eventName = dims[1]?.value || ''
+ const pagePath = normalizeGA4Value(dims[2]?.value)
+ const deviceRaw = dims[3]?.value || null
+ const browserRaw = dims[4]?.value || null
+ const osRaw = dims[5]?.value || null
+ const countryId = normalizeGA4Value(dims[6]?.value)
+ const host = normalizeGA4Value(dims[7]?.value)
+
+ if (EXCLUDED_EVENTS.has(eventName)) continue
+
+ const count = parseInt(metrics[0]?.value || '0', 10)
+ if (count <= 0) continue
+
+ const created = this.parseGA4DateHour(dateHour)
+ if (!created) continue
+
+ const device = mapDevice(deviceRaw)
+ const browser = mapBrowser(browserRaw, device)
+ const os = mapOS(osRaw)
+ const cc = countryId && /^[A-Z]{2}$/.test(countryId) ? countryId : null
+
+ const sessionSeed = [
+ dateHour,
+ eventName,
+ pagePath,
+ deviceRaw,
+ browserRaw,
+ osRaw,
+ countryId,
+ ].join('|')
+ const psid = sessionIdToPsid(sessionSeed)
+
+ const data: Record<string, unknown> = {
+ psid,
+ profileId: null,
+ pid,
+ host: truncate(host, 253),
+ pg: truncate(pagePath, 2048),
+ ev: truncate(eventName, 256),
+ dv: device,
+ br: truncate(browser, 30),
+ brv: null,
+ os: truncate(os, 25),
+ osv: null,
+ lc: null,
+ ref: null,
+ so: null,
+ me: null,
+ ca: null,
+ te: null,
+ co: null,
+ cc,
+ rg: null,
+ rgc: null,
+ ct: null,
+ 'meta.key': [],
+ 'meta.value': [],
+ importID,
+ created,
+ }
+
+ for (let i = 0; i < count; i++) {
+ yield { table: 'customEV', data }
+ }
+ }
+
+ if (rows.length < PAGE_SIZE) break
+ offset += PAGE_SIZE
+ }
+ }
+
+ // GA4 dateHour format: "2024010115" β†’ "2024-01-01 15:00:00"
+ private parseGA4DateHour(raw: string): string | null {
+ if (!raw || raw.length < 10) return null
+ const year = raw.slice(0, 4)
+ const month = raw.slice(4, 6)
+ const day = raw.slice(6, 8)
+ const hour = raw.slice(8, 10)
+ return `${year}-${month}-${day} ${hour}:00:00`
+ }
+}
diff --git a/backend/apps/cloud/src/data-import/mappers/index.ts b/backend/apps/cloud/src/data-import/mappers/index.ts
index e967d14c0..3fadcac89 100644
--- a/backend/apps/cloud/src/data-import/mappers/index.ts
+++ b/backend/apps/cloud/src/data-import/mappers/index.ts
@@ -2,17 +2,20 @@ import { ImportMapper } from './mapper.interface'
import { UmamiMapper } from './umami.mapper'
import { SimpleAnalyticsMapper } from './simple-analytics.mapper'
import { FathomMapper } from './fathom.mapper'
+import { Ga4Mapper } from './ga4.mapper'
export const SUPPORTED_PROVIDERS = [
'umami',
'simple-analytics',
'fathom',
+ 'google-analytics',
] as const
const mappers: Record<string, ImportMapper> = {
umami: new UmamiMapper(),
'simple-analytics': new SimpleAnalyticsMapper(),
fathom: new FathomMapper(),
+ 'google-analytics': new Ga4Mapper(),
}
export function getMapper(provider: string): ImportMapper | undefined {
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 b7bdc9bf0..0351b00b0 100644
--- a/backend/apps/cloud/src/data-import/mappers/mapper.interface.ts
+++ b/backend/apps/cloud/src/data-import/mappers/mapper.interface.ts
@@ -12,11 +12,12 @@ export interface AnalyticsImportRow {
export interface ImportMapper {
readonly provider: string
- readonly expectedFileExtension: string
+ readonly expectedFileExtension: string | null
createRowStream(
- filePath: string,
+ filePath: string | null,
pid: string,
importID: number,
+ context?: Record<string, unknown>,
): AsyncIterable<AnalyticsImportRow>
}
diff --git a/backend/package-lock.json b/backend/package-lock.json
index e2e7a0097..c2ce4ad70 100644
--- a/backend/package-lock.json
+++ b/backend/package-lock.json
@@ -4,12 +4,12 @@
"requires": true,
"packages": {
"": {
- "name": "backend",
"license": "AGPL-3.0",
"dependencies": {
"@ai-sdk/openai": "^3.0.52",
"@clickhouse/client": "^1.18.2",
"@faker-js/faker": "^10.4.0",
+ "@google-analytics/data": "^5.2.1",
"@googleapis/searchconsole": "^6.0.1",
"@nestjs-modules/mailer": "^2.3.4",
"@nestjs/bullmq": "^11.0.4",
@@ -722,6 +722,18 @@
"url": "https://github.com/sponsors/isaacs"
}
},
+ "node_modules/@google-analytics/data": {
+ "version": "5.2.1",
+ "resolved": "https://registry.npmjs.org/@google-analytics/data/-/data-5.2.1.tgz",
+ "integrity": "sha512-JZdRY4OGPx0RnAdsFu0k/mD5x7mVXATKccSi5bB5ncbgaBbfLOz2cCjNna6dHxwDchYYZv1Zm/sISZHKtCclgw==",
+ "license": "Apache-2.0",
+ "dependencies": {
+ "google-gax": "^5.0.0"
+ },
+ "engines": {
+ "node": ">=18"
+ }
+ },
"node_modules/@googleapis/searchconsole": {
"version": "6.0.1",
"resolved": "https://registry.npmjs.org/@googleapis/searchconsole/-/searchconsole-6.0.1.tgz",
@@ -734,6 +746,37 @@
"node": ">=12.0.0"
}
},
+ "node_modules/@grpc/grpc-js": {
+ "version": "1.14.3",
+ "resolved": "https://registry.npmjs.org/@grpc/grpc-js/-/grpc-js-1.14.3.tgz",
+ "integrity": "sha512-Iq8QQQ/7X3Sac15oB6p0FmUg/klxQvXLeileoqrTRGJYLV+/9tubbr9ipz0GKHjmXVsgFPo/+W+2cA8eNcR+XA==",
+ "license": "Apache-2.0",
+ "dependencies": {
+ "@grpc/proto-loader": "^0.8.0",
+ "@js-sdsl/ordered-map": "^4.4.2"
+ },
+ "engines": {
+ "node": ">=12.10.0"
+ }
+ },
+ "node_modules/@grpc/proto-loader": {
+ "version": "0.8.0",
+ "resolved": "https://registry.npmjs.org/@grpc/proto-loader/-/proto-loader-0.8.0.tgz",
+ "integrity": "sha512-rc1hOQtjIWGxcxpb9aHAfLpIctjEnsDehj0DAiVfBlmT84uvR0uUtN2hEi/ecvWVjXUGf5qPF4qEgiLOx1YIMQ==",
+ "license": "Apache-2.0",
+ "dependencies": {
+ "lodash.camelcase": "^4.3.0",
+ "long": "^5.0.0",
+ "protobufjs": "^7.5.3",
+ "yargs": "^17.7.2"
+ },
+ "bin": {
+ "proto-loader-gen-types": "build/bin/proto-loader-gen-types.js"
+ },
+ "engines": {
+ "node": ">=6"
+ }
+ },
"node_modules/@inquirer/ansi": {
"version": "1.0.2",
"resolved": "https://registry.npmjs.org/@inquirer/ansi/-/ansi-1.0.2.tgz",
@@ -1209,6 +1252,16 @@
"@jridgewell/sourcemap-codec": "^1.4.14"
}
},
+ "node_modules/@js-sdsl/ordered-map": {
+ "version": "4.4.2",
+ "resolved": "https://registry.npmjs.org/@js-sdsl/ordered-map/-/ordered-map-4.4.2.tgz",
+ "integrity": "sha512-iUKgm52T8HOE/makSxjqoWhe95ZJA1/G1sYsGev2JDKUSS14KAgg1LHb+Ba+IPow0xflbnSkOsZcO08C7w1gYw==",
+ "license": "MIT",
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/js-sdsl"
+ }
+ },
"node_modules/@lukeed/csprng": {
"version": "1.1.0",
"resolved": "https://registry.npmjs.org/@lukeed/csprng/-/csprng-1.1.0.tgz",
@@ -4036,6 +4089,70 @@
"module-details-from-path": "^1.0.4"
}
},
+ "node_modules/@protobufjs/aspromise": {
+ "version": "1.1.2",
+ "resolved": "https://registry.npmjs.org/@protobufjs/aspromise/-/aspromise-1.1.2.tgz",
+ "integrity": "sha512-j+gKExEuLmKwvz3OgROXtrJ2UG2x8Ch2YZUxahh+s1F2HZ+wAceUNLkvy6zKCPVRkU++ZWQrdxsUeQXmcg4uoQ==",
+ "license": "BSD-3-Clause"
+ },
+ "node_modules/@protobufjs/base64": {
+ "version": "1.1.2",
+ "resolved": "https://registry.npmjs.org/@protobufjs/base64/-/base64-1.1.2.tgz",
+ "integrity": "sha512-AZkcAA5vnN/v4PDqKyMR5lx7hZttPDgClv83E//FMNhR2TMcLUhfRUBHCmSl0oi9zMgDDqRUJkSxO3wm85+XLg==",
+ "license": "BSD-3-Clause"
+ },
+ "node_modules/@protobufjs/codegen": {
+ "version": "2.0.4",
+ "resolved": "https://registry.npmjs.org/@protobufjs/codegen/-/codegen-2.0.4.tgz",
+ "integrity": "sha512-YyFaikqM5sH0ziFZCN3xDC7zeGaB/d0IUb9CATugHWbd1FRFwWwt4ld4OYMPWu5a3Xe01mGAULCdqhMlPl29Jg==",
+ "license": "BSD-3-Clause"
+ },
+ "node_modules/@protobufjs/eventemitter": {
+ "version": "1.1.0",
+ "resolved": "https://registry.npmjs.org/@protobufjs/eventemitter/-/eventemitter-1.1.0.tgz",
+ "integrity": "sha512-j9ednRT81vYJ9OfVuXG6ERSTdEL1xVsNgqpkxMsbIabzSo3goCjDIveeGv5d03om39ML71RdmrGNjG5SReBP/Q==",
+ "license": "BSD-3-Clause"
+ },
+ "node_modules/@protobufjs/fetch": {
+ "version": "1.1.0",
+ "resolved": "https://registry.npmjs.org/@protobufjs/fetch/-/fetch-1.1.0.tgz",
+ "integrity": "sha512-lljVXpqXebpsijW71PZaCYeIcE5on1w5DlQy5WH6GLbFryLUrBD4932W/E2BSpfRJWseIL4v/KPgBFxDOIdKpQ==",
+ "license": "BSD-3-Clause",
+ "dependencies": {
+ "@protobufjs/aspromise": "^1.1.1",
+ "@protobufjs/inquire": "^1.1.0"
+ }
+ },
+ "node_modules/@protobufjs/float": {
+ "version": "1.0.2",
+ "resolved": "https://registry.npmjs.org/@protobufjs/float/-/float-1.0.2.tgz",
+ "integrity": "sha512-Ddb+kVXlXst9d+R9PfTIxh1EdNkgoRe5tOX6t01f1lYWOvJnSPDBlG241QLzcyPdoNTsblLUdujGSE4RzrTZGQ==",
+ "license": "BSD-3-Clause"
+ },
+ "node_modules/@protobufjs/inquire": {
+ "version": "1.1.0",
+ "resolved": "https://registry.npmjs.org/@protobufjs/inquire/-/inquire-1.1.0.tgz",
+ "integrity": "sha512-kdSefcPdruJiFMVSbn801t4vFK7KB/5gd2fYvrxhuJYg8ILrmn9SKSX2tZdV6V+ksulWqS7aXjBcRXl3wHoD9Q==",
+ "license": "BSD-3-Clause"
+ },
+ "node_modules/@protobufjs/path": {
+ "version": "1.1.2",
+ "resolved": "https://registry.npmjs.org/@protobufjs/path/-/path-1.1.2.tgz",
+ "integrity": "sha512-6JOcJ5Tm08dOHAbdR3GrvP+yUUfkjG5ePsHYczMFLq3ZmMkAD98cDgcT2iA1lJ9NVwFd4tH/iSSoe44YWkltEA==",
+ "license": "BSD-3-Clause"
+ },
+ "node_modules/@protobufjs/pool": {
+ "version": "1.1.0",
+ "resolved": "https://registry.npmjs.org/@protobufjs/pool/-/pool-1.1.0.tgz",
+ "integrity": "sha512-0kELaGSIDBKvcgS4zkjz1PeddatrjYcmMWOlAuAPwAeccUrPHdUqo/J6LiymHHEiJT5NrF1UVwxY14f+fy4WQw==",
+ "license": "BSD-3-Clause"
+ },
+ "node_modules/@protobufjs/utf8": {
+ "version": "1.1.0",
+ "resolved": "https://registry.npmjs.org/@protobufjs/utf8/-/utf8-1.1.0.tgz",
+ "integrity": "sha512-Vvn3zZrhQZkkBE8LSuW3em98c0FwgO4nxzv6OdSxPKJIEKY2bGbHn+mhGIPerzI4twdxaP8/0+06HBpwf345Lw==",
+ "license": "BSD-3-Clause"
+ },
"node_modules/@scarf/scarf": {
"version": "1.4.0",
"resolved": "https://registry.npmjs.org/@scarf/scarf/-/scarf-1.4.0.tgz",
@@ -5208,6 +5325,15 @@
"acorn": "^8.14.0"
}
},
+ "node_modules/agent-base": {
+ "version": "7.1.4",
+ "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-7.1.4.tgz",
+ "integrity": "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==",
+ "license": "MIT",
+ "engines": {
+ "node": ">= 14"
+ }
+ },
"node_modules/ai": {
"version": "6.0.153",
"resolved": "https://registry.npmjs.org/ai/-/ai-6.0.153.tgz",
@@ -6694,6 +6820,15 @@
"integrity": "sha512-LRLMV+UCyfMokp8Wb411duBf1gaBKJfOfBWU9eHMJ+b+cJYZsNu3AFmjJf3+yPGd59Exz1TsMjaSFyxnYB9+IQ==",
"license": "MIT"
},
+ "node_modules/data-uri-to-buffer": {
+ "version": "4.0.1",
+ "resolved": "https://registry.npmjs.org/data-uri-to-buffer/-/data-uri-to-buffer-4.0.1.tgz",
+ "integrity": "sha512-0R9ikRb668HB7QDxT1vkpuUBtqc53YyAwMwGeUFKRojY/NWKvdZ+9UYtRfGmhqNbRkTSVpMbmyhXipFFv2cb/A==",
+ "license": "MIT",
+ "engines": {
+ "node": ">= 12"
+ }
+ },
"node_modules/dayjs": {
"version": "1.11.20",
"resolved": "https://registry.npmjs.org/dayjs/-/dayjs-1.11.20.tgz",
@@ -6997,6 +7132,18 @@
"node": ">= 0.4"
}
},
+ "node_modules/duplexify": {
+ "version": "4.1.3",
+ "resolved": "https://registry.npmjs.org/duplexify/-/duplexify-4.1.3.tgz",
+ "integrity": "sha512-M3BmBhwJRZsSx38lZyhE53Csddgzl5R7xGJNk7CVddZD6CcmwMCH8J+7AprIrQKH7TonKxaCjcv27Qmf+sQ+oA==",
+ "license": "MIT",
+ "dependencies": {
+ "end-of-stream": "^1.4.1",
+ "inherits": "^2.0.3",
+ "readable-stream": "^3.1.1",
+ "stream-shift": "^1.0.2"
+ }
+ },
"node_modules/eastasianwidth": {
"version": "0.2.0",
"resolved": "https://registry.npmjs.org/eastasianwidth/-/eastasianwidth-0.2.0.tgz",
@@ -7090,6 +7237,15 @@
"node": ">=0.10.0"
}
},
+ "node_modules/end-of-stream": {
+ "version": "1.4.5",
+ "resolved": "https://registry.npmjs.org/end-of-stream/-/end-of-stream-1.4.5.tgz",
+ "integrity": "sha512-ooEGc6HP26xXq/N+GCGOT0JKCLDGrq2bQUZrQ7gyrJiZANJ/8YDTxTpQBXGMn+WbIQXNVpyWymm7KYVICQnyOg==",
+ "license": "MIT",
+ "dependencies": {
+ "once": "^1.4.0"
+ }
+ },
"node_modules/engine.io": {
"version": "6.6.5",
"resolved": "https://registry.npmjs.org/engine.io/-/engine.io-6.6.5.tgz",
@@ -7867,37 +8023,6 @@
"node": ">=18"
}
},
- "node_modules/gaxios/node_modules/agent-base": {
- "version": "7.1.4",
- "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-7.1.4.tgz",
- "integrity": "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==",
- "license": "MIT",
- "engines": {
- "node": ">= 14"
- }
- },
- "node_modules/gaxios/node_modules/data-uri-to-buffer": {
- "version": "4.0.1",
- "resolved": "https://registry.npmjs.org/data-uri-to-buffer/-/data-uri-to-buffer-4.0.1.tgz",
- "integrity": "sha512-0R9ikRb668HB7QDxT1vkpuUBtqc53YyAwMwGeUFKRojY/NWKvdZ+9UYtRfGmhqNbRkTSVpMbmyhXipFFv2cb/A==",
- "license": "MIT",
- "engines": {
- "node": ">= 12"
- }
- },
- "node_modules/gaxios/node_modules/https-proxy-agent": {
- "version": "7.0.6",
- "resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-7.0.6.tgz",
- "integrity": "sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw==",
- "license": "MIT",
- "dependencies": {
- "agent-base": "^7.1.2",
- "debug": "4"
- },
- "engines": {
- "node": ">= 14"
- }
- },
"node_modules/gaxios/node_modules/node-fetch": {
"version": "3.3.2",
"resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-3.3.2.tgz",
@@ -8081,6 +8206,61 @@
"node": ">=18"
}
},
+ "node_modules/google-gax": {
+ "version": "5.0.6",
+ "resolved": "https://registry.npmjs.org/google-gax/-/google-gax-5.0.6.tgz",
+ "integrity": "sha512-1kGbqVQBZPAAu4+/R1XxPQKP0ydbNYoLAr4l0ZO2bMV0kLyLW4I1gAk++qBLWt7DPORTzmWRMsCZe86gDjShJA==",
+ "license": "Apache-2.0",
+ "dependencies": {
+ "@grpc/grpc-js": "^1.12.6",
+ "@grpc/proto-loader": "^0.8.0",
+ "duplexify": "^4.1.3",
+ "google-auth-library": "^10.1.0",
+ "google-logging-utils": "^1.1.1",
+ "node-fetch": "^3.3.2",
+ "object-hash": "^3.0.0",
+ "proto3-json-serializer": "^3.0.0",
+ "protobufjs": "^7.5.3",
+ "retry-request": "^8.0.0",
+ "rimraf": "^5.0.1"
+ },
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/google-gax/node_modules/node-fetch": {
+ "version": "3.3.2",
+ "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-3.3.2.tgz",
+ "integrity": "sha512-dRB78srN/l6gqWulah9SrxeYnxeddIG30+GOqK/9OlLVyLg3HPnr6SqOWTWOXKRwC2eGYCkZ59NNuSgvSrpgOA==",
+ "license": "MIT",
+ "dependencies": {
+ "data-uri-to-buffer": "^4.0.0",
+ "fetch-blob": "^3.1.4",
+ "formdata-polyfill": "^4.0.10"
+ },
+ "engines": {
+ "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/node-fetch"
+ }
+ },
+ "node_modules/google-gax/node_modules/rimraf": {
+ "version": "5.0.10",
+ "resolved": "https://registry.npmjs.org/rimraf/-/rimraf-5.0.10.tgz",
+ "integrity": "sha512-l0OE8wL34P4nJH/H2ffoaniAokM2qSmrtXHmlpvYr5AVVX8msAyW0l8NVJFDxlSK4u3Uh/f41cQheDVdnYijwQ==",
+ "license": "ISC",
+ "dependencies": {
+ "glob": "^10.3.7"
+ },
+ "bin": {
+ "rimraf": "dist/esm/bin.mjs"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/isaacs"
+ }
+ },
"node_modules/google-logging-utils": {
"version": "1.1.3",
"resolved": "https://registry.npmjs.org/google-logging-utils/-/google-logging-utils-1.1.3.tgz",
@@ -8371,6 +8551,32 @@
"url": "https://opencollective.com/express"
}
},
+ "node_modules/http-proxy-agent": {
+ "version": "7.0.2",
+ "resolved": "https://registry.npmjs.org/http-proxy-agent/-/http-proxy-agent-7.0.2.tgz",
+ "integrity": "sha512-T1gkAiYYDWYx3V5Bmyu7HcfcvL7mUrTWiM6yOfa3PIphViJ/gFPbvidQ+veqSOHci/PxBcDabeUNCzpOODJZig==",
+ "license": "MIT",
+ "dependencies": {
+ "agent-base": "^7.1.0",
+ "debug": "^4.3.4"
+ },
+ "engines": {
+ "node": ">= 14"
+ }
+ },
+ "node_modules/https-proxy-agent": {
+ "version": "7.0.6",
+ "resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-7.0.6.tgz",
+ "integrity": "sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw==",
+ "license": "MIT",
+ "dependencies": {
+ "agent-base": "^7.1.2",
+ "debug": "4"
+ },
+ "engines": {
+ "node": ">= 14"
+ }
+ },
"node_modules/human-signals": {
"version": "2.1.0",
"resolved": "https://registry.npmjs.org/human-signals/-/human-signals-2.1.0.tgz",
@@ -9280,6 +9486,12 @@
"integrity": "sha512-dMInicTPVE8d1e5otfwmmjlxkZoUpiVLwyeTdUsi/Caj/gfzzblBcCE5sRHV/AsjuCmxWrte2TNGSYuCeCq+0Q==",
"license": "MIT"
},
+ "node_modules/lodash.camelcase": {
+ "version": "4.3.0",
+ "resolved": "https://registry.npmjs.org/lodash.camelcase/-/lodash.camelcase-4.3.0.tgz",
+ "integrity": "sha512-TwuEnCnxbc3rAvhf/LbG7tJUDzhqXyFnv3dtzLOPgCG/hODL7WFnsbwktkD7yUV0RrreP/l1PALq/YSg6VvjlA==",
+ "license": "MIT"
+ },
"node_modules/lodash.clonedeep": {
"version": "4.5.0",
"resolved": "https://registry.npmjs.org/lodash.clonedeep/-/lodash.clonedeep-4.5.0.tgz",
@@ -11966,6 +12178,42 @@
"asap": "~2.0.3"
}
},
+ "node_modules/proto3-json-serializer": {
+ "version": "3.0.4",
+ "resolved": "https://registry.npmjs.org/proto3-json-serializer/-/proto3-json-serializer-3.0.4.tgz",
+ "integrity": "sha512-E1sbAYg3aEbXrq0n1ojJkRHQJGE1kaE/O6GLA94y8rnJBfgvOPTOd1b9hOceQK1FFZI9qMh1vBERCyO2ifubcw==",
+ "license": "Apache-2.0",
+ "dependencies": {
+ "protobufjs": "^7.4.0"
+ },
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/protobufjs": {
+ "version": "7.5.4",
+ "resolved": "https://registry.npmjs.org/protobufjs/-/protobufjs-7.5.4.tgz",
+ "integrity": "sha512-CvexbZtbov6jW2eXAvLukXjXUW1TzFaivC46BpWc/3BpcCysb5Vffu+B3XHMm8lVEuy2Mm4XGex8hBSg1yapPg==",
+ "hasInstallScript": true,
+ "license": "BSD-3-Clause",
+ "dependencies": {
+ "@protobufjs/aspromise": "^1.1.2",
+ "@protobufjs/base64": "^1.1.2",
+ "@protobufjs/codegen": "^2.0.4",
+ "@protobufjs/eventemitter": "^1.1.0",
+ "@protobufjs/fetch": "^1.1.0",
+ "@protobufjs/float": "^1.0.2",
+ "@protobufjs/inquire": "^1.1.0",
+ "@protobufjs/path": "^1.1.2",
+ "@protobufjs/pool": "^1.1.0",
+ "@protobufjs/utf8": "^1.1.0",
+ "@types/node": ">=13.7.0",
+ "long": "^5.0.0"
+ },
+ "engines": {
+ "node": ">=12.0.0"
+ }
+ },
"node_modules/proxy-addr": {
"version": "2.0.7",
"resolved": "https://registry.npmjs.org/proxy-addr/-/proxy-addr-2.0.7.tgz",
@@ -12376,6 +12624,19 @@
"dev": true,
"license": "ISC"
},
+ "node_modules/retry-request": {
+ "version": "8.0.2",
+ "resolved": "https://registry.npmjs.org/retry-request/-/retry-request-8.0.2.tgz",
+ "integrity": "sha512-JzFPAfklk1kjR1w76f0QOIhoDkNkSqW8wYKT08n9yysTmZfB+RQ2QoXoTAeOi1HD9ZipTyTAZg3c4pM/jeqgSw==",
+ "license": "MIT",
+ "dependencies": {
+ "extend": "^3.0.2",
+ "teeny-request": "^10.0.0"
+ },
+ "engines": {
+ "node": ">=18"
+ }
+ },
"node_modules/reusify": {
"version": "1.1.0",
"resolved": "https://registry.npmjs.org/reusify/-/reusify-1.1.0.tgz",
@@ -13089,6 +13350,21 @@
"node": ">= 0.8"
}
},
+ "node_modules/stream-events": {
+ "version": "1.0.5",
+ "resolved": "https://registry.npmjs.org/stream-events/-/stream-events-1.0.5.tgz",
+ "integrity": "sha512-E1GUzBSgvct8Jsb3v2X15pjzN1tYebtbLaMg+eBOUOAxgbLoSbT2NS91ckc5lJD1KfLjId+jXJRgo0qnV5Nerg==",
+ "license": "MIT",
+ "dependencies": {
+ "stubs": "^3.0.0"
+ }
+ },
+ "node_modules/stream-shift": {
+ "version": "1.0.3",
+ "resolved": "https://registry.npmjs.org/stream-shift/-/stream-shift-1.0.3.tgz",
+ "integrity": "sha512-76ORR0DO1o1hlKwTbi/DM3EXWGf3ZJYO8cXX5RJwnul2DEg2oyoZyjLNoQM8WsvZiFKCRfC1O0J7iCvie3RZmQ==",
+ "license": "MIT"
+ },
"node_modules/streamsearch": {
"version": "1.1.0",
"resolved": "https://registry.npmjs.org/streamsearch/-/streamsearch-1.1.0.tgz",
@@ -13256,6 +13532,12 @@
"url": "https://github.com/sponsors/Borewit"
}
},
+ "node_modules/stubs": {
+ "version": "3.0.0",
+ "resolved": "https://registry.npmjs.org/stubs/-/stubs-3.0.0.tgz",
+ "integrity": "sha512-PdHt7hHUJKxvTCgbKX9C1V/ftOcjJQgz8BZwNfV5c4B6dcGqlpelTbJ999jBGZ2jYiPAwcX5dP6oBwVlBlUbxw==",
+ "license": "MIT"
+ },
"node_modules/stylehacks": {
"version": "7.0.8",
"resolved": "https://registry.npmjs.org/stylehacks/-/stylehacks-7.0.8.tgz",
@@ -13367,6 +13649,39 @@
"url": "https://opencollective.com/webpack"
}
},
+ "node_modules/teeny-request": {
+ "version": "10.1.2",
+ "resolved": "https://registry.npmjs.org/teeny-request/-/teeny-request-10.1.2.tgz",
+ "integrity": "sha512-Xj0ZAQ0CeuQn6UxCDPLbFRlgcSTUEyO3+wiepr2grjIjyL/lMMs1Z4OwXn8kLvn/V1OuaEP0UY7Na6UDNNsYrQ==",
+ "license": "Apache-2.0",
+ "dependencies": {
+ "http-proxy-agent": "^7.0.0",
+ "https-proxy-agent": "^7.0.1",
+ "node-fetch": "^3.3.2",
+ "stream-events": "^1.0.5"
+ },
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/teeny-request/node_modules/node-fetch": {
+ "version": "3.3.2",
+ "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-3.3.2.tgz",
+ "integrity": "sha512-dRB78srN/l6gqWulah9SrxeYnxeddIG30+GOqK/9OlLVyLg3HPnr6SqOWTWOXKRwC2eGYCkZ59NNuSgvSrpgOA==",
+ "license": "MIT",
+ "dependencies": {
+ "data-uri-to-buffer": "^4.0.0",
+ "fetch-blob": "^3.1.4",
+ "formdata-polyfill": "^4.0.10"
+ },
+ "engines": {
+ "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/node-fetch"
+ }
+ },
"node_modules/telegraf": {
"version": "4.16.3",
"resolved": "https://registry.npmjs.org/telegraf/-/telegraf-4.16.3.tgz",
diff --git a/backend/package.json b/backend/package.json
index f4de4618f..2a6fe789d 100644
--- a/backend/package.json
+++ b/backend/package.json
@@ -30,6 +30,7 @@
"@ai-sdk/openai": "^3.0.52",
"@clickhouse/client": "^1.18.2",
"@faker-js/faker": "^10.4.0",
+ "@google-analytics/data": "^5.2.1",
"@googleapis/searchconsole": "^6.0.1",
"@nestjs-modules/mailer": "^2.3.4",
"@nestjs/bullmq": "^11.0.4",
diff --git a/docs/components/provider-icons.tsx b/docs/components/provider-icons.tsx
new file mode 100644
index 000000000..043b47d0e
--- /dev/null
+++ b/docs/components/provider-icons.tsx
@@ -0,0 +1,63 @@
+export const GoogleAnalyticsIcon = ({ className }: { className?: string }) => (
+ <svg className={className} viewBox="0 0 192 192" width="16" height="16">
+ <g>
+ <path
+ fill="#F9AB00"
+ d="M130,29v132c0,14.77,10.19,23,21,23c10,0,21-7,21-23V30c0-13.54-10-22-21-22S130,17.33,130,29z"
+ />
+ <path
+ fill="#E37400"
+ d="M75,96v65c0,14.77,10.19,23,21,23c10,0,21-7,21-23V97c0-13.54-10-22-21-22S75,84.33,75,96z"
+ />
+ <circle fill="#E37400" cx="41" cy="163" r="21" />
+ </g>
+ </svg>
+);
+
+export const UmamiIcon = ({ className }: { className?: string }) => (
+ <svg className={className} viewBox="0 0 428 389.11" width="16" height="16">
+ <g>
+ <circle
+ cx="214.15"
+ cy="181"
+ r="171"
+ fill="#fff"
+ stroke="#000"
+ strokeMiterlimit="10"
+ strokeWidth="20"
+ />
+ <path d="M413 134.11H15.29a15 15 0 0 0-15 15v15.3C.12 168 0 171.52 0 175.11c0 118.19 95.81 214 214 214 116.4 0 211.1-92.94 213.93-208.67 0-.44.07-.88.07-1.33v-30a15 15 0 0 0-15-15" />
+ </g>
+ </svg>
+);
+
+export const SimpleAnalyticsIcon = ({ className }: { className?: string }) => (
+ <svg className={className} viewBox="0 0 400 400" fill="none" width="16" height="16">
+ <rect width="400" height="400" rx="90" fill="#FF4F64" />
+ <path d="M132.414 201.448H100V298.69H132.414V201.448Z" fill="white" />
+ <path d="M210.206 143.103H177.793V298.69H210.206V143.103Z" fill="white" />
+ <path d="M288 88H255.586V298.69H288V88Z" fill="white" />
+ </svg>
+);
+
+export const FathomIcon = ({ className }: { className?: string }) => (
+ <svg className={className} viewBox="0 0 67.851 50" width="16" height="16">
+ <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>
+);
diff --git a/docs/content/docs/data-import.mdx b/docs/content/docs/data-import.mdx
index 359307f63..4acfa004c 100644
--- a/docs/content/docs/data-import.mdx
+++ b/docs/content/docs/data-import.mdx
@@ -7,17 +7,100 @@ description: Import historical analytics data from third-party platforms into Sw
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
+## Import Instructions
-- Umami
-- Simple Analytics
-- Fathom Analytics
+Select your analytics provider below to see the step-by-step import guide.
-## Importing from Umami
+<Tabs defaultValue="ga4">
+<TabsList>
+ <TabsTrigger value="ga4"><GoogleAnalyticsIcon /> Google Analytics 4</TabsTrigger>
+ <TabsTrigger value="umami"><UmamiIcon /> Umami</TabsTrigger>
+ <TabsTrigger value="simple"><SimpleAnalyticsIcon /> Simple Analytics</TabsTrigger>
+ <TabsTrigger value="fathom"><FathomIcon /> Fathom Analytics</TabsTrigger>
+</TabsList>
+<TabsContent value="ga4">
+
+Unlike file-based imports, GA4 import works by connecting your Google account directly. Swetrix uses the GA4 Data API to pull your historical analytics data automatically.
+
+<Callout type="info">
+ GA4 imports use aggregated data from Google's API. Some dimensions like language and browser/OS
+ versions are not available due to API limitations. Data is imported with hourly precision.
+</Callout>
+
+<Steps>
+<Step>
+<h3>Connect Your Google Account</h3>
+
+1. Go to your project's **Settings** page in Swetrix
+2. Click the **Import data** tab
+3. Click the **Google Analytics 4** provider card
+4. Click **Connect Google Account**
+ <img
+ alt="Google Analytics 4 import connect"
+ src="/docs/img/sitesettings/data-import/ga-import-connect.png"
+ />
+5. You'll be redirected to Google's sign-in page. Sign in and grant Swetrix read-only access to your analytics data
+ <img
+ alt="Google Analytics 4 consent screen"
+ src="/docs/img/sitesettings/data-import/ga-import-access-screen.png"
+ />
+
+</Step>
+<Step>
+<h3>Select a GA4 Property</h3>
+
+After connecting, you'll be redirected back to Swetrix. A dropdown will show all GA4 properties accessible from your Google account.
+
+1. Select the GA4 property you want to import data from
+ <img
+ alt="Google Analytics 4 property select"
+ src="/docs/img/sitesettings/data-import/ga-import-property-select.png"
+ />
+2. Click **Start Import**
+
+</Step>
+<Step>
+<h3>Monitor Progress</h3>
+
+After starting the import, it 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 import fetches data from the GA4 API in monthly chunks. For properties with a lot of historical data, this may take several minutes. The page auto-refreshes while an import is processing.
+
+</Step>
+</Steps>
+
+<h3>What data is imported?</h3>
+
+The following dimensions are imported for **pageviews**:
+
+- Date and hour
+- Hostname and page path
+- Device category (desktop, mobile, tablet)
+- Browser and operating system
+- Country, region, and city
+- Traffic source, medium, campaign, term, and content (UTM parameters)
+
+Source and UTM data is enriched from a separate report and matched by page and hour. For pages with traffic from multiple sources in the same hour, the most common source is used.
+
+For **custom events**, we import all non-standard GA4 events (excluding built-in events like `page_view`, `session_start`, `first_visit`, etc.) with device, browser, OS, country, and page dimensions.
+
+<h3>What's not imported?</h3>
+
+- **Language / locale** is not included (GA4 API dimension limit)
+- **Browser and OS versions** are not available from GA4 aggregate reports
+- **Session duration** cannot be reconstructed from aggregated data
+- **Unique visitors** may differ from GA4 numbers due to day-level aggregation
+
+</TabsContent>
+<TabsContent value="umami">
<Steps>
<Step>
-### Export Your Data from Umami
+<h3>Export Your Data from Umami</h3>
1. Log in to your Umami instance
2. Go to **Settings** β†’ **Data**
@@ -30,7 +113,7 @@ You can learn more on how to export your data from Umami on their [data export d
</Step>
<Step>
-### Import into Swetrix
+<h3>Import into Swetrix</h3>
1. Go to your project's **Settings** page in Swetrix
2. Click the **Import data** tab
@@ -54,7 +137,7 @@ You can learn more on how to export your data from Umami on their [data export d
</Step>
<Step>
-### Monitor Progress
+<h3>Monitor Progress</h3>
After uploading, the import will appear in the **Import history** table below the provider cards. You can see:
@@ -67,11 +150,12 @@ The page auto-refreshes while an import is processing. You can navigate away and
</Step>
</Steps>
-## Importing from Simple Analytics
+</TabsContent>
+<TabsContent value="simple">
<Steps>
<Step>
-### Export Your Data from Simple Analytics
+<h3>Export Your Data from Simple Analytics</h3>
1. Log in to your Simple Analytics dashboard and go to their [Export data](https://dashboard.simpleanalytics.com/select-website/export) page
2. Under the **Select the raw data you want to download** section, select **All** option to include both pageviews and events and the export time period. For type, choose **CSV**.
@@ -87,7 +171,7 @@ You can learn more on how to export your data from Simple Analytics on their [ex
</Step>
<Step>
-### Import into Swetrix
+<h3>Import into Swetrix</h3>
1. Go to your project's **Settings** page in Swetrix
2. Click the **Import data** tab
@@ -109,7 +193,7 @@ You can learn more on how to export your data from Simple Analytics on their [ex
</Step>
<Step>
-### Monitor Progress
+<h3>Monitor Progress</h3>
After uploading, the import will appear in the **Import history** table below the provider cards. You can see:
@@ -122,7 +206,8 @@ The page auto-refreshes while an import is processing. You can navigate away and
</Step>
</Steps>
-## Importing from Fathom Analytics
+</TabsContent>
+<TabsContent value="fathom">
<Callout type="warn">
Because Fathom Analytics does not allow raw data exports, the sessions will be imported with
@@ -132,7 +217,7 @@ The page auto-refreshes while an import is processing. You can navigate away and
<Steps>
<Step>
-### Export Your Data from Fathom
+<h3>Export Your Data from Fathom</h3>
1. Log in to your [Fathom Analytics](https://usefathom.com) dashboard
2. Go to your site's settings and go to the **Exports** tab
@@ -153,7 +238,7 @@ You can learn more on how to export your data from Fathom on their [export docum
</Step>
<Step>
-### Import into Swetrix
+<h3>Import into Swetrix</h3>
1. Go to your project's **Settings** page in Swetrix
2. Click the **Import data** tab
@@ -174,7 +259,7 @@ You can learn more on how to export your data from Fathom on their [export docum
</Step>
<Step>
-### Monitor Progress
+<h3>Monitor Progress</h3>
After uploading, the import will appear in the **Import history** table below the provider cards. You can see:
@@ -187,6 +272,9 @@ The page auto-refreshes while an import is processing. You can navigate away and
</Step>
</Steps>
+</TabsContent>
+</Tabs>
+
## 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.
@@ -209,9 +297,10 @@ This permanently removes all analytics rows associated with that import. Your li
## Limitations
-- **File size**: Maximum 100 MB per upload
+- **File size**: Maximum 100 MB per upload (for file-based imports)
- **One at a time**: Only one import can be active (pending or processing) per project at a time
- **Timestamps**: Events with invalid timestamps are skipped during import
+- **GA4 dimensions**: Google Analytics 4 imports are subject to API limitations β€” see the "What's not imported?" section under the Google Analytics 4 tab for details
## Troubleshooting
diff --git a/docs/mdx-components.tsx b/docs/mdx-components.tsx
index b65e66368..b011c613f 100644
--- a/docs/mdx-components.tsx
+++ b/docs/mdx-components.tsx
@@ -1,7 +1,13 @@
import defaultMdxComponents from "fumadocs-ui/mdx";
import { Callout } from "fumadocs-ui/components/callout";
import { Step, Steps } from "fumadocs-ui/components/steps";
-import { Tab, Tabs } from "fumadocs-ui/components/tabs";
+import { Tab, Tabs, TabsList, TabsTrigger, TabsContent } from "fumadocs-ui/components/tabs";
+import {
+ GoogleAnalyticsIcon,
+ UmamiIcon,
+ SimpleAnalyticsIcon,
+ FathomIcon,
+} from "@/components/provider-icons";
import { Accordion, Accordions } from "fumadocs-ui/components/accordion";
import { File, Folder, Files } from "fumadocs-ui/components/files";
import type { MDXComponents } from "mdx/types";
@@ -14,6 +20,13 @@ export function getMDXComponents(components?: MDXComponents): MDXComponents {
Steps,
Tab,
Tabs,
+ TabsList,
+ TabsTrigger,
+ TabsContent,
+ GoogleAnalyticsIcon,
+ UmamiIcon,
+ SimpleAnalyticsIcon,
+ FathomIcon,
Accordion,
Accordions,
File,
diff --git a/docs/public/img/sitesettings/data-import/ga-import-access-screen.png b/docs/public/img/sitesettings/data-import/ga-import-access-screen.png
new file mode 100644
index 000000000..0f94639af
Binary files /dev/null and b/docs/public/img/sitesettings/data-import/ga-import-access-screen.png differ
diff --git a/docs/public/img/sitesettings/data-import/ga-import-connect.png b/docs/public/img/sitesettings/data-import/ga-import-connect.png
new file mode 100644
index 000000000..f1dd77ffc
Binary files /dev/null and b/docs/public/img/sitesettings/data-import/ga-import-connect.png differ
diff --git a/docs/public/img/sitesettings/data-import/ga-import-property-select.png b/docs/public/img/sitesettings/data-import/ga-import-property-select.png
new file mode 100644
index 000000000..d28d59eba
Binary files /dev/null and b/docs/public/img/sitesettings/data-import/ga-import-property-select.png differ
diff --git a/web/app/api/api.server.ts b/web/app/api/api.server.ts
index 8e0e01630..320e31c3a 100644
--- a/web/app/api/api.server.ts
+++ b/web/app/api/api.server.ts
@@ -2386,6 +2386,21 @@ export async function processGSCTokenServer(
})
}
+// ============================================================================
+// MARK: Google Analytics 4 Import API
+// ============================================================================
+
+export async function processGA4ImportTokenServer(
+ request: Request,
+ code: string,
+ state: string,
+): Promise<ServerFetchResult<{ pid: string }>> {
+ return serverFetch<{ pid: string }>(request, 'data-import/ga4/callback', {
+ method: 'POST',
+ body: { code, state },
+ })
+}
+
interface GSCKeyword {
name: string
count: number
diff --git a/web/app/hooks/useAuthProxy.ts b/web/app/hooks/useAuthProxy.ts
index bb7c2c738..ebefc494a 100644
--- a/web/app/hooks/useAuthProxy.ts
+++ b/web/app/hooks/useAuthProxy.ts
@@ -135,6 +135,22 @@ export function useAuthProxy() {
[],
)
+ const processGA4ImportToken = useCallback(
+ async (code: string, state: string): Promise<{ pid: string }> => {
+ const response = await fetch('/api/auth', {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ action: 'processGA4ImportToken', code, state }),
+ })
+ const result = (await response.json()) as ProxyResponse<{ pid: string }>
+ if (result.error || !result.data) {
+ throw new Error(result.error || 'Failed to process GA4 import token')
+ }
+ return result.data
+ },
+ [],
+ )
+
const authMe = useCallback(
async (signal?: AbortSignal): Promise<AuthMeResponse> => {
const response = await fetch('/api/auth', {
@@ -191,6 +207,7 @@ export function useAuthProxy() {
linkBySSOHash,
processSSOToken,
processGSCToken,
+ processGA4ImportToken,
authMe,
linkSSOWithPassword,
}
diff --git a/web/app/lib/models/Project.ts b/web/app/lib/models/Project.ts
index 6d986c2f2..43dd33a87 100644
--- a/web/app/lib/models/Project.ts
+++ b/web/app/lib/models/Project.ts
@@ -1,3 +1,4 @@
+import { isSelfhosted } from '../constants'
import { Organisation, Role } from './Organisation'
interface OverallPeriodStats {
@@ -174,9 +175,18 @@ export interface AnalyticsFunnel {
topSources: Record<string, number>
}
-export const IMPORT_PROVIDERS = ['umami', 'simple-analytics', 'fathom'] as const
+export type Provider =
+ | 'umami'
+ | 'simple-analytics'
+ | 'fathom'
+ | 'google-analytics'
-export type Provider = (typeof IMPORT_PROVIDERS)[number]
+export const IMPORT_PROVIDERS: Provider[] = [
+ 'fathom',
+ isSelfhosted ? null : 'google-analytics',
+ 'simple-analytics',
+ 'umami',
+].filter((x): x is Provider => !!x)
export interface DataImport {
id: number
diff --git a/web/app/pages/Project/Settings/components/DataImportTab.tsx b/web/app/pages/Project/Settings/components/DataImportTab.tsx
index 1fb9bd5fd..5cd3ee67c 100644
--- a/web/app/pages/Project/Settings/components/DataImportTab.tsx
+++ b/web/app/pages/Project/Settings/components/DataImportTab.tsx
@@ -12,7 +12,7 @@ import cx from 'clsx'
import { toast } from 'sonner'
import dayjs from 'dayjs'
import { Trans, useTranslation } from 'react-i18next'
-import { useFetcher } from 'react-router'
+import { useFetcher, useSearchParams } from 'react-router'
import {
type DataImport,
@@ -23,10 +23,13 @@ import type { ProjectSettingsActionData } from '~/routes/projects.settings.$id'
import Modal from '~/ui/Modal'
import Loader from '~/ui/Loader'
import FileUpload from '~/ui/FileUpload'
+import Button from '~/ui/Button'
+import Select from '~/ui/Select'
import { Text } from '~/ui/Text'
import UmamiSVG from '~/ui/icons/Umami'
import SimpleAnalyticsSVG from '~/ui/icons/SimpleAnalytics'
import FathomSVG from '~/ui/icons/Fathom'
+import GoogleAnalyticsSVG from '~/ui/icons/GoogleAnalytics'
const PROVIDER_ICONS: Record<
string,
@@ -35,19 +38,23 @@ const PROVIDER_ICONS: Record<
umami: UmamiSVG,
'simple-analytics': SimpleAnalyticsSVG,
fathom: FathomSVG,
+ 'google-analytics': GoogleAnalyticsSVG,
}
-const PROVIDER_DISPLAY_NAMES = {
+const PROVIDER_DISPLAY_NAMES: Record<string, string> = {
umami: 'Umami',
'simple-analytics': 'Simple Analytics',
fathom: 'Fathom Analytics',
-} as const
+ 'google-analytics': 'Google Analytics 4',
+}
+
+const FILE_BASED_PROVIDERS = new Set(['umami', 'simple-analytics', 'fathom'])
-const PROVIDER_FILE_TYPES = {
+const PROVIDER_FILE_TYPES: Record<string, string> = {
umami: '.zip',
'simple-analytics': '.csv',
fathom: '.csv',
-} as const
+}
const STATUS_ICONS = {
pending: ClockIcon,
@@ -97,12 +104,18 @@ function StatusBadge({
)
}
+interface Ga4Property {
+ propertyId: string
+ displayName: string
+}
+
interface DataImportTabProps {
projectId: string
}
export default function DataImportTab({ projectId }: DataImportTabProps) {
const { t } = useTranslation('common')
+ const [searchParams, setSearchParams] = useSearchParams()
const [imports, setImports] = useState<DataImport[]>([])
const [loading, setLoading] = useState(true)
const [selectedProvider, setSelectedProvider] = useState<Provider | null>(
@@ -111,9 +124,18 @@ export default function DataImportTab({ projectId }: DataImportTabProps) {
const [deleteTarget, setDeleteTarget] = useState<DataImport | null>(null)
const pollRef = useRef<ReturnType<typeof setInterval> | null>(null)
+ // GA4-specific state
+ const [ga4Connected, setGa4Connected] = useState(false)
+ const [ga4Properties, setGa4Properties] = useState<Ga4Property[]>([])
+ const [ga4SelectedProperty, setGa4SelectedProperty] = useState('')
+ const [ga4LoadingProperties, setGa4LoadingProperties] = useState(false)
+
const listFetcher = useFetcher<ProjectSettingsActionData>()
const uploadFetcher = useFetcher<ProjectSettingsActionData>()
const deleteFetcher = useFetcher<ProjectSettingsActionData>()
+ const ga4ConnectFetcher = useFetcher<ProjectSettingsActionData>()
+ const ga4PropertiesFetcher = useFetcher<ProjectSettingsActionData>()
+ const ga4StartFetcher = useFetcher<ProjectSettingsActionData>()
const settingsAction = `/projects/settings/${projectId}`
@@ -131,6 +153,23 @@ export default function DataImportTab({ projectId }: DataImportTabProps) {
)
}, [listFetcher, settingsAction])
+ // Check for GA4 OAuth redirect
+ useEffect(() => {
+ if (searchParams.get('ga4') === 'connected') {
+ setGa4Connected(true)
+ setSelectedProvider('google-analytics')
+ setSearchParams(
+ (prev) => {
+ const next = new URLSearchParams(prev)
+ next.delete('ga4')
+ return next
+ },
+ { replace: true },
+ )
+ }
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [])
+
useEffect(() => {
fetchImports()
// eslint-disable-next-line react-hooks/exhaustive-deps
@@ -204,6 +243,69 @@ export default function DataImportTab({ projectId }: DataImportTabProps) {
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [deleteFetcher.state, deleteFetcher.data])
+ // GA4 connect response: redirect to Google OAuth
+ useEffect(() => {
+ if (ga4ConnectFetcher.state !== 'idle' || !ga4ConnectFetcher.data) return
+ if (ga4ConnectFetcher.data.intent !== 'ga4-connect') return
+
+ if (ga4ConnectFetcher.data.ga4AuthUrl) {
+ window.location.href = ga4ConnectFetcher.data.ga4AuthUrl
+ } else if (ga4ConnectFetcher.data.error) {
+ toast.error(ga4ConnectFetcher.data.error)
+ }
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [ga4ConnectFetcher.state, ga4ConnectFetcher.data])
+
+ // GA4 properties response
+ useEffect(() => {
+ if (ga4PropertiesFetcher.state !== 'idle' || !ga4PropertiesFetcher.data)
+ return
+ if (ga4PropertiesFetcher.data.intent !== 'ga4-properties') return
+
+ setGa4LoadingProperties(false)
+
+ if (ga4PropertiesFetcher.data.ga4Properties) {
+ setGa4Properties(ga4PropertiesFetcher.data.ga4Properties)
+ if (ga4PropertiesFetcher.data.ga4Properties.length > 0) {
+ setGa4SelectedProperty(
+ ga4PropertiesFetcher.data.ga4Properties[0].propertyId,
+ )
+ }
+ } else if (ga4PropertiesFetcher.data.error) {
+ toast.error(ga4PropertiesFetcher.data.error)
+ setGa4Connected(false)
+ }
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [ga4PropertiesFetcher.state, ga4PropertiesFetcher.data])
+
+ // GA4 start import response
+ useEffect(() => {
+ if (ga4StartFetcher.state !== 'idle' || !ga4StartFetcher.data) return
+ if (ga4StartFetcher.data.intent !== 'ga4-start-import') return
+
+ if (ga4StartFetcher.data.success) {
+ toast.success(t('project.settings.dataImport.importStarted'))
+ setSelectedProvider(null)
+ resetGa4State()
+ fetchImports()
+ } else if (ga4StartFetcher.data.error) {
+ toast.error(ga4StartFetcher.data.error)
+ }
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [ga4StartFetcher.state, ga4StartFetcher.data])
+
+ // Fetch GA4 properties when connected
+ useEffect(() => {
+ if (ga4Connected && selectedProvider === 'google-analytics') {
+ setGa4LoadingProperties(true)
+ ga4PropertiesFetcher.submit(
+ { intent: 'ga4-properties' },
+ { method: 'POST', action: settingsAction },
+ )
+ }
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [ga4Connected, selectedProvider])
+
const handleUpload = (file: File) => {
if (!selectedProvider) return
@@ -228,25 +330,74 @@ export default function DataImportTab({ projectId }: DataImportTabProps) {
)
}
+ const handleGa4Connect = () => {
+ ga4ConnectFetcher.submit(
+ { intent: 'ga4-connect' },
+ { method: 'POST', action: settingsAction },
+ )
+ }
+
+ const handleGa4StartImport = () => {
+ if (!ga4SelectedProperty) return
+
+ ga4StartFetcher.submit(
+ {
+ intent: 'ga4-start-import',
+ propertyId: ga4SelectedProperty,
+ },
+ { method: 'POST', action: settingsAction },
+ )
+ }
+
+ const resetGa4State = () => {
+ setGa4Connected(false)
+ setGa4Properties([])
+ setGa4SelectedProperty('')
+ }
+
+ const handleProviderClick = (provider: Provider) => {
+ if (provider === 'google-analytics') {
+ setSelectedProvider(provider)
+ } else {
+ setSelectedProvider(provider)
+ }
+ }
+
+ const handleCloseModal = () => {
+ if (selectedProvider === 'google-analytics') {
+ if (ga4StartFetcher.state === 'idle') {
+ setSelectedProvider(null)
+ resetGa4State()
+ }
+ } else {
+ if (!uploading) setSelectedProvider(null)
+ }
+ }
+
const uploading = uploadFetcher.state !== 'idle'
const deleting = deleteFetcher.state !== 'idle'
+ const ga4Connecting = ga4ConnectFetcher.state !== 'idle'
+ const ga4Starting = ga4StartFetcher.state !== 'idle'
+
+ const isFileBased =
+ selectedProvider && FILE_BASED_PROVIDERS.has(selectedProvider)
+ const isGA4 = selectedProvider === 'google-analytics'
const providerFileType = selectedProvider
- ? t(`project.settings.dataImport.${selectedProvider}.fileType`)
+ ? PROVIDER_FILE_TYPES[selectedProvider] || ''
: ''
+ const selectedGa4Property = ga4Properties.find(
+ (p) => p.propertyId === ga4SelectedProperty,
+ )
+
return (
<div className='space-y-8'>
<div>
<Text as='h3' size='base' weight='semibold' colour='primary'>
{t('project.settings.dataImport.importFrom')}
</Text>
- <Text
- as='p'
- size='sm'
- colour='inherit'
- className='mt-1 text-gray-500 dark:text-gray-400'
- >
+ <Text as='p' size='sm' colour='muted' className='mt-1'>
{t('project.settings.dataImport.importFromDesc')}
</Text>
@@ -257,14 +408,17 @@ export default function DataImportTab({ projectId }: DataImportTabProps) {
(i) => i.status === 'pending' || i.status === 'processing',
)
const name = PROVIDER_DISPLAY_NAMES[provider] || provider
- const fileType = PROVIDER_FILE_TYPES[provider] || ''
+ const subtitle =
+ provider === 'google-analytics'
+ ? t('project.settings.dataImport.google-analytics.fileType')
+ : PROVIDER_FILE_TYPES[provider] || ''
return (
<button
key={provider}
type='button'
disabled={hasActive}
- onClick={() => setSelectedProvider(provider)}
+ onClick={() => handleProviderClick(provider)}
className={cx(
'group relative flex flex-col items-start rounded-lg border p-4 text-left transition-all',
hasActive
@@ -280,22 +434,12 @@ export default function DataImportTab({ projectId }: DataImportTabProps) {
<Text as='p' size='sm' weight='semibold' colour='primary'>
{name}
</Text>
- <Text
- as='p'
- size='xs'
- colour='inherit'
- className='text-gray-500 dark:text-gray-400'
- >
- {fileType}
+ <Text as='p' size='xs' colour='muted'>
+ {subtitle}
</Text>
</div>
</div>
- <Text
- as='p'
- size='xs'
- colour='inherit'
- className='mt-2 text-gray-500 dark:text-gray-400'
- >
+ <Text as='p' size='xs' colour='muted' className='mt-2'>
{t(`project.settings.dataImport.${provider}.description`)}
</Text>
</button>
@@ -316,12 +460,7 @@ export default function DataImportTab({ projectId }: DataImportTabProps) {
) : imports.length === 0 ? (
<div className='mt-4 rounded-lg border border-dashed border-gray-300 py-8 text-center dark:border-slate-700'>
<UploadIcon className='mx-auto size-8 text-gray-400 dark:text-gray-500' />
- <Text
- as='p'
- size='sm'
- colour='inherit'
- className='mt-2 text-gray-500 dark:text-gray-400'
- >
+ <Text as='p' size='sm' colour='muted' className='mt-2'>
{t('project.settings.dataImport.noImports')}
</Text>
</div>
@@ -369,7 +508,7 @@ export default function DataImportTab({ projectId }: DataImportTabProps) {
key={imp.id}
className='bg-white hover:bg-gray-50 dark:bg-slate-950 dark:hover:bg-slate-900/50'
>
- <td className='px-4 py-3 text-sm font-medium whitespace-nowrap text-gray-900 capitalize dark:text-gray-100'>
+ <td className='px-4 py-3 text-sm font-medium whitespace-nowrap text-gray-900 dark:text-gray-100'>
{PROVIDER_DISPLAY_NAMES[imp.provider] || imp.provider}
</td>
<td className='px-4 py-3'>
@@ -432,11 +571,10 @@ export default function DataImportTab({ projectId }: DataImportTabProps) {
)}
</div>
+ {/* File upload modal for file-based providers */}
<Modal
- isOpened={!!selectedProvider}
- onClose={() => {
- if (!uploading) setSelectedProvider(null)
- }}
+ isOpened={!!isFileBased}
+ onClose={handleCloseModal}
title={t('project.settings.dataImport.importFromProvider', {
provider: selectedProvider
? PROVIDER_DISPLAY_NAMES[selectedProvider] || selectedProvider
@@ -445,12 +583,7 @@ export default function DataImportTab({ projectId }: DataImportTabProps) {
size='medium'
message={
<div className='space-y-4'>
- <Text
- as='p'
- size='sm'
- colour='inherit'
- className='text-gray-600 dark:text-gray-400'
- >
+ <Text as='p' size='sm' colour='muted'>
<Trans
i18nKey='project.settings.dataImport.uploadInstructions'
t={t}
@@ -475,18 +608,8 @@ export default function DataImportTab({ projectId }: DataImportTabProps) {
uploading ? (
t('project.settings.dataImport.uploadingProcessing')
) : (
- <Text
- as='span'
- size='sm'
- colour='inherit'
- className='text-gray-600 dark:text-gray-300'
- >
- <Text
- as='span'
- weight='medium'
- colour='inherit'
- className='text-gray-900 dark:text-gray-100'
- >
+ <Text as='span' size='sm' colour='muted'>
+ <Text as='span' weight='medium' colour='primary'>
{t('project.settings.dataImport.clickToUpload')}
</Text>{' '}
{t('project.settings.dataImport.orDragDrop')}
@@ -507,6 +630,100 @@ export default function DataImportTab({ projectId }: DataImportTabProps) {
closeText={t('common.cancel')}
/>
+ {/* GA4 OAuth + property selection modal */}
+ <Modal
+ isOpened={!!isGA4}
+ onClose={handleCloseModal}
+ title={t('project.settings.dataImport.importFromProvider', {
+ provider: 'Google Analytics 4',
+ })}
+ size='medium'
+ submitText={
+ ga4Connected && ga4Properties.length > 0
+ ? t('project.settings.dataImport.google-analytics.startImport')
+ : undefined
+ }
+ onSubmit={
+ ga4Connected && ga4Properties.length > 0
+ ? handleGa4StartImport
+ : undefined
+ }
+ isLoading={ga4Starting}
+ closeText={t('common.cancel')}
+ message={
+ <div className='space-y-4'>
+ {!ga4Connected ? (
+ <>
+ <Text as='p' size='sm' colour='muted'>
+ {t(
+ 'project.settings.dataImport.google-analytics.connectDesc',
+ )}
+ </Text>
+ <Button
+ secondary
+ large
+ onClick={handleGa4Connect}
+ loading={ga4Connecting}
+ className='flex w-full items-center justify-center gap-2'
+ >
+ {!ga4Connecting && <GoogleAnalyticsSVG className='size-5' />}
+ {ga4Connecting
+ ? t(
+ 'project.settings.dataImport.google-analytics.connecting',
+ )
+ : t(
+ 'project.settings.dataImport.google-analytics.connectGoogle',
+ )}
+ </Button>
+ </>
+ ) : ga4LoadingProperties ? (
+ <div className='space-y-4'>
+ <div className='flex items-center justify-center py-6'>
+ <Loader className='pt-0' />
+ <Text as='p' size='sm'>
+ {t(
+ 'project.settings.dataImport.google-analytics.loadingProperties',
+ )}
+ </Text>
+ </div>
+ </div>
+ ) : ga4Properties.length === 0 ? (
+ <Text
+ as='p'
+ size='sm'
+ colour='muted'
+ className='py-4 text-center'
+ >
+ {t('project.settings.dataImport.google-analytics.noProperties')}
+ </Text>
+ ) : (
+ <>
+ <Select
+ label={t(
+ 'project.settings.dataImport.google-analytics.selectProperty',
+ )}
+ items={ga4Properties}
+ selectedItem={selectedGa4Property}
+ title={
+ selectedGa4Property
+ ? `${selectedGa4Property.displayName} (${selectedGa4Property.propertyId})`
+ : ''
+ }
+ keyExtractor={(prop) => prop.propertyId}
+ labelExtractor={(prop) =>
+ `${prop.displayName} (${prop.propertyId})`
+ }
+ onSelect={(prop) => setGa4SelectedProperty(prop.propertyId)}
+ />
+ <Text as='p' size='xs' colour='muted'>
+ {t('project.settings.dataImport.google-analytics.importNote')}
+ </Text>
+ </>
+ )}
+ </div>
+ }
+ />
+
<Modal
isOpened={!!deleteTarget}
onClose={() => {
diff --git a/web/app/routes/api.auth.ts b/web/app/routes/api.auth.ts
index 796a488a2..c5a1b1987 100644
--- a/web/app/routes/api.auth.ts
+++ b/web/app/routes/api.auth.ts
@@ -11,6 +11,7 @@ import {
linkBySSOHashServer,
processSSOTokenServer,
processGSCTokenServer,
+ processGA4ImportTokenServer,
authMeServer,
linkSSOWithPasswordServer,
type SSOProvider,
@@ -30,6 +31,7 @@ interface ProxyRequest {
| 'linkBySSOHash'
| 'processSSOToken'
| 'processGSCToken'
+ | 'processGA4ImportToken'
| 'authMe'
| 'linkSSOWithPassword'
provider?: SSOProvider
@@ -220,6 +222,28 @@ export async function action({ request }: ActionFunctionArgs) {
})
}
+ case 'processGA4ImportToken': {
+ if (!body.code || !body.state) {
+ return data<ProxyResponse<null>>(
+ { data: null, error: 'code and state are required' },
+ { status: 400 },
+ )
+ }
+ const result = await processGA4ImportTokenServer(
+ request,
+ body.code,
+ body.state,
+ )
+ return data<ProxyResponse<{ pid: string }>>({
+ data: result.data,
+ error: result.error
+ ? Array.isArray(result.error)
+ ? result.error.join(', ')
+ : result.error
+ : null,
+ })
+ }
+
case 'authMe': {
const result = await authMeServer(request)
return data<ProxyResponse<AuthMeResponse>>({
diff --git a/web/app/routes/ga4-import-connected.tsx b/web/app/routes/ga4-import-connected.tsx
new file mode 100644
index 000000000..cfb0a3b0b
--- /dev/null
+++ b/web/app/routes/ga4-import-connected.tsx
@@ -0,0 +1,146 @@
+import _replace from 'lodash/replace'
+import { useEffect, useState } from 'react'
+import type { LoaderFunctionArgs, MetaFunction } from 'react-router'
+import { redirect, useLoaderData, useNavigate } from 'react-router'
+import type { SitemapFunction } from 'remix-sitemap'
+
+import { processGA4ImportTokenServer } from '~/api/api.server'
+import { useAuthProxy } from '~/hooks/useAuthProxy'
+import { isSelfhosted } from '~/lib/constants'
+import StatusPage from '~/ui/StatusPage'
+import routes from '~/utils/routes'
+import { getTitle } from '~/utils/seo'
+
+export const sitemap: SitemapFunction = () => ({
+ exclude: true,
+})
+
+export const meta: MetaFunction = () => [
+ ...getTitle('Google Analytics Import Connected'),
+ { name: 'robots', content: 'noindex' },
+]
+
+export interface Ga4ImportConnectedLoaderData {
+ error?: string
+ useClientFallback?: boolean
+}
+
+export async function loader({
+ request,
+}: LoaderFunctionArgs): Promise<Ga4ImportConnectedLoaderData | Response> {
+ if (isSelfhosted) {
+ return redirect('/login', 302)
+ }
+
+ const url = new URL(request.url)
+
+ const state = url.searchParams.get('state')
+ const code = url.searchParams.get('code')
+
+ if (!state || !code) {
+ return { useClientFallback: true }
+ }
+
+ const result = await processGA4ImportTokenServer(request, code, state)
+
+ if (result.status === 401 || result.status === 403) {
+ return { useClientFallback: true }
+ }
+
+ if (result.error || !result.data) {
+ return { useClientFallback: true }
+ }
+
+ const { pid } = result.data
+ const redirectUrl = _replace(routes.project_settings, ':id', pid)
+
+ return redirect(`${redirectUrl}?tab=import&ga4=connected`)
+}
+
+export default function Ga4ImportConnectedRoute() {
+ const data = useLoaderData<Ga4ImportConnectedLoaderData>()
+
+ if (data.useClientFallback) {
+ return <Ga4HashHandler />
+ }
+
+ return (
+ <StatusPage
+ type='error'
+ title='Failed to connect Google Analytics'
+ description={data.error || 'Unknown error'}
+ actions={[{ label: 'Support', to: routes.contact }]}
+ />
+ )
+}
+
+function Ga4HashHandler() {
+ const navigate = useNavigate()
+ const [error, setError] = useState<string | null>(null)
+ const { processGA4ImportToken } = useAuthProxy()
+ const [{ state, code }] = useState(() => {
+ if (typeof window === 'undefined') return { state: null, code: null }
+ const _location = _replace(
+ window.location.href,
+ `${routes.ga4_import_connected}#`,
+ `${routes.ga4_import_connected}?`,
+ )
+ const { searchParams } = new URL(_location)
+ return {
+ state: searchParams.get('state'),
+ code: searchParams.get('code'),
+ }
+ })
+
+ useEffect(() => {
+ if (!state || !code) return
+
+ const processedKey = `ga4_import_processed:${state}`
+ if (sessionStorage.getItem(processedKey) === '1') {
+ return
+ }
+ sessionStorage.setItem(processedKey, '1')
+
+ processGA4ImportToken(code, state)
+ .then(({ pid }) => {
+ navigate({
+ pathname: _replace(routes.project_settings, ':id', pid),
+ search: new URLSearchParams({
+ tab: 'import',
+ ga4: 'connected',
+ }).toString(),
+ })
+ })
+ .catch((reason) => {
+ sessionStorage.removeItem(processedKey)
+ setError(String(reason))
+ console.error(
+ `[ERROR] Error while processing GA4 import connection: ${reason}`,
+ )
+ })
+ }, [navigate, state, code, processGA4ImportToken])
+
+ if (!state || !code) {
+ return (
+ <StatusPage
+ type='error'
+ title='Failed to connect Google Analytics'
+ description='Invalid callback parameters'
+ actions={[{ label: 'Support', to: routes.contact }]}
+ />
+ )
+ }
+
+ if (error) {
+ return (
+ <StatusPage
+ type='error'
+ title='Failed to connect Google Analytics'
+ description={error}
+ actions={[{ label: 'Support', to: routes.contact }]}
+ />
+ )
+ }
+
+ return <StatusPage loading />
+}
diff --git a/web/app/routes/projects.settings.$id.tsx b/web/app/routes/projects.settings.$id.tsx
index 703935440..109de885a 100644
--- a/web/app/routes/projects.settings.$id.tsx
+++ b/web/app/routes/projects.settings.$id.tsx
@@ -93,6 +93,8 @@ export interface ProjectSettingsActionData {
gscProperties?: GscProperty[]
dataImports?: DataImport[]
dataImport?: unknown
+ ga4AuthUrl?: string
+ ga4Properties?: { propertyId: string; displayName: string }[]
}
export async function action({ request, params }: ActionFunctionArgs) {
@@ -864,6 +866,78 @@ export async function action({ request, params }: ActionFunctionArgs) {
)
}
+ case 'ga4-connect': {
+ const result = await serverFetch<{ url: string }>(
+ request,
+ `data-import/${id}/ga4/connect`,
+ { method: 'POST' },
+ )
+
+ if (result.error || !result.data?.url) {
+ return data<ProjectSettingsActionData>(
+ { intent, error: (result.error as string) || 'Failed to connect' },
+ { status: result.status || 400 },
+ )
+ }
+
+ return data<ProjectSettingsActionData>(
+ { intent, ga4AuthUrl: result.data.url },
+ { headers: createHeadersWithCookies(result.cookies) },
+ )
+ }
+
+ case 'ga4-properties': {
+ const result = await serverFetch<
+ { propertyId: string; displayName: string }[]
+ >(request, `data-import/${id}/ga4/properties`)
+
+ if (result.error) {
+ return data<ProjectSettingsActionData>(
+ { intent, error: result.error as string },
+ { status: result.status || 400 },
+ )
+ }
+
+ return data<ProjectSettingsActionData>(
+ {
+ intent,
+ success: true,
+ ga4Properties:
+ (result.data as { propertyId: string; displayName: string }[]) ||
+ [],
+ },
+ { headers: createHeadersWithCookies(result.cookies) },
+ )
+ }
+
+ case 'ga4-start-import': {
+ const propertyId = formData.get('propertyId')?.toString()
+
+ if (!propertyId) {
+ return data<ProjectSettingsActionData>(
+ { intent, error: 'Property ID is required' },
+ { status: 400 },
+ )
+ }
+
+ const result = await serverFetch(request, `data-import/${id}/ga4/start`, {
+ method: 'POST',
+ body: { propertyId },
+ })
+
+ if (result.error) {
+ return data<ProjectSettingsActionData>(
+ { intent, error: result.error as string },
+ { status: result.status || 400 },
+ )
+ }
+
+ return data<ProjectSettingsActionData>(
+ { intent, success: true, dataImport: result.data },
+ { headers: createHeadersWithCookies(result.cookies) },
+ )
+ }
+
default:
return data<ProjectSettingsActionData>(
{ error: 'Unknown action' },
diff --git a/web/app/ui/Loader.tsx b/web/app/ui/Loader.tsx
index 28501bb27..e74a01cb1 100644
--- a/web/app/ui/Loader.tsx
+++ b/web/app/ui/Loader.tsx
@@ -1,7 +1,8 @@
import Spin from './icons/Spin'
+import { cn } from '~/utils/generic'
-const Loader = () => (
- <div className='flex justify-center pt-10'>
+const Loader = ({ className }: { className?: string }) => (
+ <div className={cn('flex justify-center pt-10', className)}>
<Spin />
<span className='sr-only'>Loading...</span>
</div>
diff --git a/web/app/ui/icons/GoogleAnalytics.tsx b/web/app/ui/icons/GoogleAnalytics.tsx
new file mode 100644
index 000000000..c1b2da734
--- /dev/null
+++ b/web/app/ui/icons/GoogleAnalytics.tsx
@@ -0,0 +1,29 @@
+const GoogleAnalyticsSVG = ({ className }: { className?: string }) => (
+ <svg
+ className={className}
+ viewBox='0 0 192 192'
+ enableBackground='new 0 0 192 192'
+ xmlSpace='preserve'
+ >
+ <rect x='0' y='0' fill='none' width='192' height='192' />
+ <g>
+ <g>
+ <path
+ fill='#F9AB00'
+ d='M130,29v132c0,14.77,10.19,23,21,23c10,0,21-7,21-23V30c0-13.54-10-22-21-22S130,17.33,130,29z'
+ />
+ </g>
+ <g>
+ <path
+ fill='#E37400'
+ d='M75,96v65c0,14.77,10.19,23,21,23c10,0,21-7,21-23V97c0-13.54-10-22-21-22S75,84.33,75,96z'
+ />
+ </g>
+ <g>
+ <circle fill='#E37400' cx='41' cy='163' r='21' />
+ </g>
+ </g>
+ </svg>
+)
+
+export default GoogleAnalyticsSVG
diff --git a/web/app/utils/routes.ts b/web/app/utils/routes.ts
index 5a61b4c49..31a5a1d0b 100644
--- a/web/app/utils/routes.ts
+++ b/web/app/utils/routes.ts
@@ -30,6 +30,7 @@ const routes = Object.freeze({
transfer_reject: '/project/transfer/cancel',
socialised: '/socialised',
gsc_connected: '/gsc-connected',
+ ga4_import_connected: '/ga4-import-connected',
open: '/open',
blog: '/blog',
imprint: '/imprint',
diff --git a/web/public/locales/en.json b/web/public/locales/en.json
index 1e63f9b82..7c663a8d1 100644
--- a/web/public/locales/en.json
+++ b/web/public/locales/en.json
@@ -1848,6 +1848,18 @@
},
"fathom": {
"description": "Import pageviews and events from Fathom Analytics export"
+ },
+ "google-analytics": {
+ "description": "Import pageviews and events from Google Analytics 4",
+ "fileType": "Google OAuth",
+ "connectGoogle": "Connect Google Account",
+ "connectDesc": "Connect your Google account to import historical data from Google Analytics 4. We only request read-only access to your analytics data.",
+ "selectProperty": "Select a GA4 property",
+ "startImport": "Start Import",
+ "connecting": "Connecting...",
+ "loadingProperties": "Loading properties...",
+ "noProperties": "No GA4 properties found for this Google account.",
+ "importNote": "Data will be imported in the background. Some details like locale or browser/OS versions are not available from GA4 aggregate exports."
}
},
"captcha": {