π Open source, privacy-first web analytics β a cookie-less Google Analytics alternative with built-in error tracking and performance monitoring. Self-host it or use our cloud. Get started for free!
TypeScript chartsclickhousedockergdprgoogle-analyticsmetricsmonitoringmysqlnestjsprivacyredisself-hostedselfhostedstatisticstailwindcssweb-analyticswebanalyticswebsite
Add support for Google Search Console integration to Swetrix CE
Blue Mouse5001e1ee7c88
diff --git a/backend/.env.example b/backend/.env.exampleindex 688e028e7..4fae334ff 100644--- a/backend/.env.example+++ b/backend/.env.example@@ -44,6 +44,11 @@ DISABLE_REGISTRATION=trueDEBUG_MODE=IP_GEOLOCATION_DB_PATH=+# Public URL of the Swetrix CE instance (used by the API for the Google Search+# Console OAuth redirect URI: ${BASE_URL}/gsc-connected). Must exactly match the+# redirect URI configured in the Google Cloud Console OAuth client.+BASE_URL=+OIDC_ENABLED=falseOIDC_ONLY_AUTH=false@@ -56,7 +61,8 @@ OIDC_PROMPT=select_accountGOOGLE_OAUTH2_CLIENT_ID=GOOGLE_OAUTH2_CLIENT_SECRET=-# Google GSC Integration Client+# Google Search Console integration (Cloud and Community Edition).+# The OAuth client's Authorized redirect URI must be set to ${BASE_URL}/gsc-connected.GOOGLE_GSC_CLIENT_ID=GOOGLE_GSC_CLIENT_SECRET=diff --git a/backend/apps/community/src/analytics/analytics.controller.ts b/backend/apps/community/src/analytics/analytics.controller.tsindex 43d1e0ab4..e71f875d5 100644--- a/backend/apps/community/src/analytics/analytics.controller.ts+++ b/backend/apps/community/src/analytics/analytics.controller.ts@@ -85,6 +85,8 @@ import { GetOverallStatsDto } from './dto/get-overall-stats.dto'import { GetHeartbeatStatsDto } from './dto/get-heartbeat-stats'import { LiveVisitorsDto } from './dto/live-visitors.dto'import { NoscriptDto } from './dto/noscript.dto'+import { GetKeywordsDto } from './dto/get-keywords.dto'+import { GSCService } from '../project/gsc.service'dayjs.extend(utc)dayjs.extend(dayjsTimezone)@@ -191,6 +193,7 @@ export class AnalyticsController {constructor(private readonly analyticsService: AnalyticsService,private readonly logger: AppLoggerService,+ private readonly gscService: GSCService,) {}@Get()@@ -2551,4 +2554,186 @@ export class AnalyticsController {return { sessionId: null }}}++ @Get('keywords')+ @Auth(true, true)+ async getKeywords(+ @Query() data: GetKeywordsDto,+ @CurrentUserId() uid: string,+ @Headers() headers: { 'x-password'?: string },+ ) {+ const { pid, period, from, to, timezone = DEFAULT_TIMEZONE } = data++ await this.analyticsService.checkProjectAccess(+ pid,+ uid,+ headers['x-password'],+ )++ this.logger.log(`pid: ${pid}, period: ${period}`, 'GET /analytics/keywords')++ let diff++ if (period === 'all') {+ const res = await this.analyticsService.calculateTimeBucketForAllTime(+ pid,+ 'analytics',+ )++ diff = res.diff+ }++ const safeTimezone = this.analyticsService.getSafeTimezone(timezone)+ const { groupFrom, groupTo } = this.analyticsService.getGroupFromTo(+ from,+ to,+ null,+ period,+ safeTimezone,+ diff,+ )++ const keywords = await this.gscService.getKeywords(pid, groupFrom, groupTo)+ return { keywords }+ }++ @Get('gsc-dashboard')+ @Auth(true, true)+ async getGSCDashboard(+ @Query() data: GetKeywordsDto,+ @CurrentUserId() uid: string,+ @Headers() headers: { 'x-password'?: string },+ ) {+ const {+ pid,+ period,+ from,+ to,+ timezone = DEFAULT_TIMEZONE,+ timeBucket,+ filters,+ } = data++ await this.analyticsService.checkProjectAccess(+ pid,+ uid,+ headers['x-password'],+ )++ const finalTimeBucket =+ timeBucket ||+ (['1h', 'today', 'yesterday', '1d'].includes(period) ? 'hour' : 'day')++ this.logger.log(+ `pid: ${pid}, period: ${period}, timeBucket: ${finalTimeBucket}, filters: ${filters}`,+ 'GET /analytics/gsc-dashboard',+ )++ let diff++ if (period === 'all') {+ const res = await this.analyticsService.calculateTimeBucketForAllTime(+ pid,+ 'analytics',+ )++ diff = res.diff+ }++ const safeTimezone = this.analyticsService.getSafeTimezone(timezone)+ const { groupFrom, groupTo } = this.analyticsService.getGroupFromTo(+ from,+ to,+ null,+ period,+ safeTimezone,+ diff,+ )++ return this.gscService.getDashboard(+ pid,+ groupFrom,+ groupTo,+ finalTimeBucket,+ filters,+ )+ }++ @Get('gsc-details')+ @Auth(true, true)+ async getGSCDetails(+ @Query() data: GetKeywordsDto,+ @CurrentUserId() uid: string,+ @Headers() headers: { 'x-password'?: string },+ ) {+ const {+ pid,+ period,+ from,+ to,+ timezone = DEFAULT_TIMEZONE,+ page,+ query,+ } = data++ this.logger.log(+ `pid: ${pid}, period: ${period}, page: ${page}, query: ${query}`,+ 'GET /analytics/gsc-details',+ )++ await this.analyticsService.checkProjectAccess(+ pid,+ uid,+ headers['x-password'],+ )++ let diff++ if (period === 'all') {+ const res = await this.analyticsService.calculateTimeBucketForAllTime(+ pid,+ 'analytics',+ )++ diff = res.diff+ }++ const safeTimezone = this.analyticsService.getSafeTimezone(timezone)+ const { groupFrom, groupTo } = this.analyticsService.getGroupFromTo(+ from,+ to,+ null,+ period,+ safeTimezone,+ diff,+ )++ if (page) {+ const keywords = await this.gscService.getKeywords(+ pid,+ groupFrom,+ groupTo,+ 50,+ 0,+ undefined,+ page,+ )+ return { type: 'queries', data: keywords }+ }++ if (query) {+ const pages = await this.gscService.getTopPages(+ pid,+ groupFrom,+ groupTo,+ 50,+ 0,+ undefined,+ query,+ )+ return { type: 'pages', data: pages }+ }++ return { type: 'none', data: [] }+ }}diff --git a/backend/apps/community/src/analytics/dto/get-keywords.dto.ts b/backend/apps/community/src/analytics/dto/get-keywords.dto.tsnew file mode 100644index 000000000..a46fb74d2--- /dev/null+++ b/backend/apps/community/src/analytics/dto/get-keywords.dto.ts@@ -0,0 +1,37 @@+import { IsOptional, IsString } from 'class-validator'++export class GetKeywordsDto {+ @IsString()+ pid: string++ @IsString()+ period: string++ @IsOptional()+ @IsString()+ from?: string++ @IsOptional()+ @IsString()+ to?: string++ @IsOptional()+ @IsString()+ timezone?: string++ @IsOptional()+ @IsString()+ timeBucket?: string++ @IsOptional()+ @IsString()+ filters?: string++ @IsOptional()+ @IsString()+ page?: string++ @IsOptional()+ @IsString()+ query?: string+}diff --git a/backend/apps/community/src/common/utils.ts b/backend/apps/community/src/common/utils.tsindex 61a1d6c10..359987b7c 100644--- a/backend/apps/community/src/common/utils.ts+++ b/backend/apps/community/src/common/utils.ts@@ -85,7 +85,7 @@ 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',+ purpose: 'refresh-token' | 'access-token' | 'gsc-token',length = 32,) => {const base = Buffer.from(process.env.SECRET_KEY_BASE || '', 'utf8')@@ -132,9 +132,19 @@ const ALLOWED_KEYS = ['websiteUrl','captchaSecretKey','captchaDifficulty',+ 'brandKeywords',]-const CLICKHOUSE_PROJECT_UPDATABLE_KEYS = [...ALLOWED_KEYS, 'adminId']+const CLICKHOUSE_PROJECT_UPDATABLE_KEYS = [+ ...ALLOWED_KEYS,+ 'adminId',+ 'gscPropertyUri',+ 'gscAccessTokenEnc',+ 'gscRefreshTokenEnc',+ 'gscTokenExpiry',+ 'gscScope',+ 'gscAccountEmail',+]const ALLOWED_FUNNEL_KEYS = ['name', 'steps']const ALLOWED_SHARE_KEYS = ['role', 'confirmed']@@ -397,6 +407,15 @@ const updateProjectClickhouse = async (const INT8_COLUMNS = ['active', 'public', 'isPasswordProtected']const UINT8_COLUMNS = ['captchaDifficulty']+ const NULLABLE_INT64_COLUMNS = ['gscTokenExpiry']+ const NULLABLE_STRING_COLUMNS = [+ 'gscPropertyUri',+ 'gscAccessTokenEnc',+ 'gscRefreshTokenEnc',+ 'gscScope',+ 'gscAccountEmail',+ 'brandKeywords',+ ]const params: Record<string, any> = { id: project.id }const assignments = _map(columns, (col) => {@@ -406,6 +425,10 @@ const updateProjectClickhouse = async (type = 'Int8'} else if (UINT8_COLUMNS.includes(col)) {type = 'UInt8'+ } else if (NULLABLE_INT64_COLUMNS.includes(col)) {+ type = 'Nullable(Int64)'+ } else if (NULLABLE_STRING_COLUMNS.includes(col)) {+ type = 'Nullable(String)'}return `${col}={${col}:${type}}`}).join(', ')diff --git a/backend/apps/community/src/project/dto/project.dto.ts b/backend/apps/community/src/project/dto/project.dto.tsindex 056fc86fe..3f4dec05f 100644--- a/backend/apps/community/src/project/dto/project.dto.ts+++ b/backend/apps/community/src/project/dto/project.dto.ts@@ -5,8 +5,10 @@ import {IsOptional,Length,IsArray,+ IsString,IsUrl,MaxLength,+ ValidateIf,} from 'class-validator'import { BotsProtectionLevel } from '../entity'@@ -92,4 +94,16 @@ export class ProjectDTO {@IsUrl({}, { message: 'websiteUrl must be a valid URL' })@MaxLength(512)websiteUrl?: string | null++ @ApiProperty({+ example: ['swetrix', 'swetrix analytics'],+ required: false,+ description:+ 'Brand keywords used to classify search queries as branded vs non-branded traffic.',+ })+ @IsOptional()+ @ValidateIf((o) => o.brandKeywords !== null && o.brandKeywords !== undefined)+ @IsArray()+ @IsString({ each: true })+ brandKeywords?: string[] | null}diff --git a/backend/apps/community/src/project/entity/project.entity.ts b/backend/apps/community/src/project/entity/project.entity.tsindex 20de18742..cdd426f9a 100644--- a/backend/apps/community/src/project/entity/project.entity.ts+++ b/backend/apps/community/src/project/entity/project.entity.ts@@ -23,6 +23,15 @@ export class Project {isCaptchaProject: booleancaptchaSecretKey?: stringcaptchaDifficulty?: number+ // Google Search Console integration fields+ gscPropertyUri?: string | null+ gscAccessTokenEnc?: string | null+ gscRefreshTokenEnc?: string | null+ gscTokenExpiry?: string | number | null+ gscScope?: string | null+ gscAccountEmail?: string | null+ // SEO branded traffic classification keywords+ brandKeywords?: string | string[] | null}export enum Role {diff --git a/backend/apps/community/src/project/gsc.controller.ts b/backend/apps/community/src/project/gsc.controller.tsnew file mode 100644index 000000000..c368b9675--- /dev/null+++ b/backend/apps/community/src/project/gsc.controller.ts@@ -0,0 +1,96 @@+import {+ Controller,+ Post,+ Get,+ Delete,+ Param,+ Body,+ UseGuards,+ BadRequestException,+ HttpCode,+} from '@nestjs/common'+import { ApiBearerAuth, ApiTags } from '@nestjs/swagger'++import { AuthenticationGuard } from '../auth/guards/authentication.guard'+import { Auth } from '../auth/decorators'+import { CurrentUserId } from '../auth/decorators/current-user-id.decorator'+import { GSCService } from './gsc.service'+import { ProjectService } from './project.service'++@ApiTags('Project - Google Search Console')+@UseGuards(AuthenticationGuard)+@Controller({ path: 'project/gsc', version: '1' })+export class GSCController {+ constructor(+ private readonly gscService: GSCService,+ private readonly projectService: ProjectService,+ ) {}++ @Post('process-token')+ @Auth()+ async processGSCToken(+ @Body() body: { code: string; state: string },+ @CurrentUserId() uid: string,+ ) {+ const { code, state } = body++ if (!code || !state) {+ throw new BadRequestException('Invalid GSC token parameters')+ }++ const { pid } = await this.gscService.handleOAuthCallback(uid, code, state)++ return { pid }+ }++ @ApiBearerAuth()+ @Post(':pid/connect')+ @Auth()+ async connect(@Param('pid') pid: string, @CurrentUserId() uid: string) {+ const project = await this.projectService.getRedisProject(pid)+ this.projectService.allowedToManage(project, uid)+ return this.gscService.generateConnectURL(uid, pid)+ }++ @ApiBearerAuth()+ @Get(':pid/status')+ @Auth()+ async status(@Param('pid') pid: string, @CurrentUserId() uid: string) {+ const project = await this.projectService.getRedisProject(pid)+ this.projectService.allowedToManage(project, uid)+ return this.gscService.getStatus(pid)+ }++ @ApiBearerAuth()+ @Get(':pid/properties')+ @Auth()+ async properties(@Param('pid') pid: string, @CurrentUserId() uid: string) {+ const project = await this.projectService.getRedisProject(pid)+ this.projectService.allowedToManage(project, uid)+ return this.gscService.listSites(pid)+ }++ @ApiBearerAuth()+ @Post(':pid/property')+ @Auth()+ async setProperty(+ @Param('pid') pid: string,+ @CurrentUserId() uid: string,+ @Body() body: { propertyUri: string },+ ) {+ const project = await this.projectService.getRedisProject(pid)+ this.projectService.allowedToManage(project, uid)+ await this.gscService.setProperty(pid, body?.propertyUri)+ return {}+ }++ @ApiBearerAuth()+ @Delete(':pid/disconnect')+ @Auth()+ @HttpCode(204)+ async disconnect(@Param('pid') pid: string, @CurrentUserId() uid: string) {+ const project = await this.projectService.getRedisProject(pid)+ this.projectService.allowedToManage(project, uid)+ await this.gscService.disconnect(pid)+ }+}diff --git a/backend/apps/community/src/project/gsc.service.ts b/backend/apps/community/src/project/gsc.service.tsnew file mode 100644index 000000000..58ed9a76d--- /dev/null+++ b/backend/apps/community/src/project/gsc.service.ts@@ -0,0 +1,987 @@+import { parse as parseDomain } from 'tldts'+import countries from 'i18n-iso-countries'+import _isEmpty from 'lodash/isEmpty'+import dayjs from 'dayjs'+import utc from 'dayjs/plugin/utc'+import {+ Injectable,+ BadRequestException,+ InternalServerErrorException,+} from '@nestjs/common'+import { ConfigService } from '@nestjs/config'+import { OAuth2Client } from 'google-auth-library'+import { searchconsole } from '@googleapis/searchconsole'++import CryptoJS from 'crypto-js'++import { redis } from '../common/constants'+import { ProjectService, deleteProjectRedis } from './project.service'+import {+ deriveKey,+ getProjectClickhouse,+ updateProjectClickhouse,+} from '../common/utils'++dayjs.extend(utc)++type StoredTokens = {+ access_token?: string+ refresh_token?: string+ scope?: string+ expiry_date?: number+ property_uri?: string | null+}++const REDIS_STATE_PREFIX = 'gsc:state:'++const ENCRYPTION_KEY = deriveKey('gsc-token')++const MAX_ROW_LIMIT = 25000+const MAX_BRANDED_PAGES = 10+const MAX_FILTER_EXPRESSION_LENGTH = 500+const MAX_FILTERS = 20++type GSCRow = {+ keys: string[]+ clicks?: number+ impressions?: number+ ctr?: number+ position?: number+}++type GSCContext = {+ sc: ReturnType<typeof searchconsole>+ siteUrl: string+}++interface QueryGSCOptions {+ dimensions?: string[]+ rowLimit?: number+ startRow?: number+ dataState?: string+ dimensionFilterGroups?: any[]+}++function parseBrandKeywords(+ raw: string | string[] | null | undefined,+): string[] | null {+ if (!raw) return null+ if (Array.isArray(raw)) {+ return raw.every((item) => typeof item === 'string') ? raw : null+ }+ try {+ const parsed = JSON.parse(raw)+ if (+ Array.isArray(parsed) &&+ parsed.every((item) => typeof item === 'string')+ ) {+ return parsed+ }+ return null+ } catch {+ return null+ }+}++const getBaseUrl = (): string | null => {+ const raw = process.env.BASE_URL?.trim()+ if (!raw) return null+ return raw.replace(/\/+$/, '')+}++@Injectable()+export class GSCService {+ constructor(+ private readonly configService: ConfigService,+ private readonly projectService: ProjectService,+ ) {}++ isAvailable(): boolean {+ const clientId = this.configService.get<string>('GOOGLE_GSC_CLIENT_ID')+ const clientSecret = this.configService.get<string>(+ 'GOOGLE_GSC_CLIENT_SECRET',+ )+ return Boolean(clientId && clientSecret && getBaseUrl())+ }++ private getRedirectUrl(): string {+ const base = getBaseUrl()+ if (!base) {+ throw new InternalServerErrorException(+ 'BASE_URL is not configured. Set BASE_URL on the API container to enable Google Search Console integration.',+ )+ }+ return `${base}/gsc-connected`+ }++ private getOAuthClient() {+ const clientId = this.configService.get<string>('GOOGLE_GSC_CLIENT_ID')+ const clientSecret = this.configService.get<string>(+ 'GOOGLE_GSC_CLIENT_SECRET',+ )++ if (!clientId || !clientSecret) {+ throw new InternalServerErrorException(+ 'Google GSC client is not configured. Set GOOGLE_GSC_CLIENT_ID and GOOGLE_GSC_CLIENT_SECRET on the API container.',+ )+ }++ return new OAuth2Client(clientId, clientSecret, this.getRedirectUrl())+ }++ async generateConnectURL(uid: string, pid: string): Promise<{ url: string }> {+ const project = await this.projectService.getRedisProject(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',+ 600,+ )++ const url = oauth2Client.generateAuthUrl({+ access_type: 'offline',+ scope: [+ 'https://www.googleapis.com/auth/webmasters.readonly',+ 'https://www.googleapis.com/auth/userinfo.email',+ ],+ prompt: 'consent',+ state,+ })++ return { url }+ }++ async handleOAuthCallback(uid: string, code: string, state: string) {+ const cached = await redis.get(REDIS_STATE_PREFIX + state)+ if (!cached) {+ throw new BadRequestException('Invalid or expired OAuth state')+ }++ const { pid } = JSON.parse(cached)++ const project = await this.projectService.getRedisProject(pid)++ this.projectService.allowedToManage(project, uid)++ const oauth2Client = this.getOAuthClient()+ const { tokens } = await oauth2Client.getToken(code)+ oauth2Client.setCredentials(tokens)++ let accountEmail: string | null = null+ try {+ const res = await fetch('https://www.googleapis.com/oauth2/v2/userinfo', {+ headers: {+ Authorization: `Bearer ${tokens.access_token}`,+ },+ })+ const data = await res.json()+ accountEmail = data?.email || null+ } catch {+ //+ }++ const previous = await this.getStoredTokens(pid)++ const toStore: StoredTokens = {+ access_token: tokens.access_token,+ refresh_token: tokens.refresh_token,+ expiry_date: tokens.expiry_date,+ scope: tokens.scope,+ property_uri: previous.property_uri ?? null,+ }++ await this.setStoredTokens(pid, toStore)++ await updateProjectClickhouse(+ { id: pid, gscAccountEmail: accountEmail },+ { ignoreAllowedKeys: true },+ )++ await deleteProjectRedis(pid)++ await redis.del(REDIS_STATE_PREFIX + state)++ return { pid }+ }++ private async getStoredTokens(pid: string): Promise<StoredTokens> {+ let project: any+ try {+ project = await getProjectClickhouse(pid)+ } catch {+ return {}+ }++ if (!project) return {}++ const decrypt = (val?: string | null) => {+ if (!val) return undefined+ try {+ const bytes = CryptoJS.Rabbit.decrypt(val, ENCRYPTION_KEY)+ return bytes.toString(CryptoJS.enc.Utf8) || undefined+ } catch {+ return undefined+ }+ }++ const expiry =+ project.gscTokenExpiry !== undefined && project.gscTokenExpiry !== null+ ? Number(project.gscTokenExpiry)+ : undefined++ return {+ access_token: decrypt(project.gscAccessTokenEnc),+ refresh_token: decrypt(project.gscRefreshTokenEnc),+ expiry_date: expiry,+ scope: project.gscScope || undefined,+ property_uri: project.gscPropertyUri || null,+ }+ }++ private async setStoredTokens(pid: string, tokens: StoredTokens) {+ const encrypt = (val?: string) =>+ val ? CryptoJS.Rabbit.encrypt(val, ENCRYPTION_KEY).toString() : null++ await updateProjectClickhouse(+ {+ id: pid,+ gscAccessTokenEnc: encrypt(tokens.access_token),+ gscRefreshTokenEnc: encrypt(tokens.refresh_token),+ gscTokenExpiry:+ tokens.expiry_date !== undefined && tokens.expiry_date !== null+ ? Number(tokens.expiry_date)+ : null,+ gscScope: tokens.scope || null,+ gscPropertyUri: tokens.property_uri ?? null,+ },+ { ignoreAllowedKeys: true },+ )++ await deleteProjectRedis(pid)+ }++ async disconnect(pid: string) {+ await updateProjectClickhouse(+ {+ id: pid,+ gscAccessTokenEnc: null,+ gscRefreshTokenEnc: null,+ gscTokenExpiry: null,+ gscScope: null,+ gscPropertyUri: null,+ gscAccountEmail: null,+ },+ { ignoreAllowedKeys: true },+ )++ await deleteProjectRedis(pid)+ }++ async isConnected(pid: string) {+ const tokens = await this.getStoredTokens(pid)+ return !_isEmpty(tokens?.refresh_token || tokens?.access_token)+ }++ async getStatus(pid: string): Promise<{+ connected: boolean+ email: string | null+ available: boolean+ }> {+ const available = this.isAvailable()+ const connected = available ? await this.isConnected(pid) : false++ if (!connected) {+ return { connected, email: null, available }+ }++ let project: any+ try {+ project = await getProjectClickhouse(pid)+ } catch {+ return { connected, email: null, available }+ }++ return {+ connected,+ email: project?.gscAccountEmail || null,+ available,+ }+ }++ private async getAuthedClientForPid(pid: string) {+ const tokens = await this.getStoredTokens(pid)+ if (_isEmpty(tokens)) {+ throw new BadRequestException(+ 'Search Console is not connected for this project',+ )+ }+ const oauth2Client = this.getOAuthClient()+ oauth2Client.setCredentials(tokens)++ if (tokens.expiry_date && tokens.expiry_date <= Date.now()) {+ const refreshed = await oauth2Client.getAccessToken()+ const newAccess =+ typeof refreshed === 'string' ? refreshed : refreshed?.token+ if (newAccess) {+ const updated: StoredTokens = {+ ...tokens,+ access_token: newAccess,+ expiry_date: Date.now() + 55 * 60 * 1000,+ }+ await this.setStoredTokens(pid, updated)+ oauth2Client.setCredentials({ ...updated })+ }+ }++ return oauth2Client+ }++ private async getGSCContext(pid: string): Promise<GSCContext> {+ const tokens = await this.getStoredTokens(pid)+ if (_isEmpty(tokens) || _isEmpty(tokens.property_uri)) {+ throw new BadRequestException(+ 'Search Console property is not linked for this project',+ )+ }++ const oauth2Client = this.getOAuthClient()+ oauth2Client.setCredentials(tokens)++ if (tokens.expiry_date && tokens.expiry_date <= Date.now()) {+ const refreshed = await oauth2Client.getAccessToken()+ const newAccess =+ typeof refreshed === 'string' ? refreshed : refreshed?.token+ if (newAccess) {+ const updated: StoredTokens = {+ ...tokens,+ access_token: newAccess,+ expiry_date: Date.now() + 55 * 60 * 1000,+ }+ await this.setStoredTokens(pid, updated)+ oauth2Client.setCredentials({ ...updated })+ }+ }++ return {+ sc: searchconsole({ version: 'v1', auth: oauth2Client }),+ siteUrl: tokens.property_uri as string,+ }+ }++ async listSites(+ pid: string,+ ): Promise<{ siteUrl: string; permissionLevel?: string }[]> {+ const auth = await this.getAuthedClientForPid(pid)+ const sc = searchconsole({ version: 'v1', auth })+ try {+ const { data } = await sc.sites.list({})+ // @ts-ignore+ const sites = (data?.siteEntry || data?.siteEntries || []) as any[]+ return sites.map((s: any) => ({+ siteUrl: s.siteUrl,+ permissionLevel: s.permissionLevel,+ }))+ } catch {+ throw new InternalServerErrorException(+ 'Failed to fetch Search Console sites',+ )+ }+ }++ async setProperty(pid: string, propertyUri: string) {+ const tokens = await this.getStoredTokens(pid)+ if (_isEmpty(tokens)) {+ throw new BadRequestException(+ 'Search Console is not connected for this project',+ )+ }+ await updateProjectClickhouse(+ { id: pid, gscPropertyUri: propertyUri ?? null },+ { ignoreAllowedKeys: true },+ )+ await deleteProjectRedis(pid)+ }++ private parseFilters(filtersStr?: string) {+ if (!filtersStr) return undefined++ let filters: unknown+ try {+ filters = JSON.parse(filtersStr)+ } catch {+ throw new BadRequestException('Invalid filters parameter')+ }++ if (!Array.isArray(filters) || filters.length > MAX_FILTERS) {+ throw new BadRequestException('Invalid filters parameter')+ }++ const mappedFilters: Array<{+ dimension: string+ expression: string+ operator?: string+ }> = []++ for (const filter of filters) {+ if (typeof filter !== 'object' || filter === null) {+ throw new BadRequestException('Invalid filters parameter')+ }++ const {+ column,+ filter: value,+ isExclusive,+ isContains,+ } = filter as {+ column?: unknown+ filter?: unknown+ isExclusive?: unknown+ isContains?: unknown+ }++ if (typeof column !== 'string' || typeof value !== 'string') {+ throw new BadRequestException('Invalid filters parameter')+ }+ if (value.length > MAX_FILTER_EXPRESSION_LENGTH) continue++ let dimension: string | undefined+ let expression = value++ if (column === 'pg') {+ dimension = 'page'+ } else if (column === 'keywords') {+ dimension = 'query'+ } else if (column === 'country' || column === 'cc') {+ dimension = 'country'+ if (expression.length === 2) {+ const alpha3 = countries.alpha2ToAlpha3(expression.toUpperCase())+ if (!alpha3) continue+ expression = alpha3.toLowerCase()+ } else {+ expression = expression.toLowerCase()+ }+ } else if (column === 'device' || column === 'dv') {+ dimension = 'device'+ expression = expression.toLowerCase()+ } else {+ continue+ }++ let operator = 'equals'+ if (isExclusive) {+ operator = isContains ? 'notContains' : 'notEquals'+ } else if (isContains) {+ operator = 'contains'+ }++ const filterObj: {+ dimension: string+ expression: string+ operator?: string+ } = {+ dimension,+ expression,+ }+ if (operator !== 'equals') {+ filterObj.operator = operator+ }++ mappedFilters.push(filterObj)+ }++ if (mappedFilters.length > 0) {+ return [{ groupType: 'and', filters: mappedFilters }]+ }++ return undefined+ }++ private getDimensionFilterGroups(+ filtersStr?: string,+ extraFilters: Array<{ dimension: string; expression: string }> = [],+ ) {+ const baseGroups = this.parseFilters(filtersStr) || []++ if (_isEmpty(extraFilters)) {+ return baseGroups+ }++ if (_isEmpty(baseGroups)) {+ return [{ groupType: 'and', filters: extraFilters }]+ }++ return baseGroups.map((group, index) =>+ index === 0+ ? {+ ...group,+ filters: [...(group.filters || []), ...extraFilters],+ }+ : group,+ )+ }++ private async getProjectBrandKeywords(pid: string): Promise<string[]> {+ let project: any+ try {+ project = await getProjectClickhouse(pid)+ } catch {+ return []+ }++ if (!project) return []++ const parsed = parseBrandKeywords(project.brandKeywords)+ if (parsed && parsed.length > 0) {+ return Array.from(+ new Set(parsed.map((k) => k.toLowerCase().trim()).filter(Boolean)),+ )+ }++ const keywords = new Set<string>()++ if (project.websiteUrl) {+ try {+ const { domainWithoutSuffix } = parseDomain(project.websiteUrl)+ if (domainWithoutSuffix) {+ keywords.add(domainWithoutSuffix.toLowerCase())+ }+ } catch {+ //+ }+ }++ if (project.name) {+ const name = String(project.name).toLowerCase().trim()+ if (name.length >= 3) {+ keywords.add(name)+ }+ }++ return Array.from(keywords)+ }++ private async queryGSC(+ ctx: GSCContext,+ from: string,+ to: string,+ options: QueryGSCOptions = {},+ ): Promise<GSCRow[]> {+ const startDate = dayjs(from).format('YYYY-MM-DD')+ const endDate = dayjs(to).format('YYYY-MM-DD')++ const { data } = await ctx.sc.searchanalytics.query({+ siteUrl: ctx.siteUrl,+ requestBody: {+ startDate,+ endDate,+ ...(options.dimensions ? { dimensions: options.dimensions } : {}),+ ...(options.rowLimit != null ? { rowLimit: options.rowLimit } : {}),+ ...(options.startRow != null ? { startRow: options.startRow } : {}),+ dataState: options.dataState || 'all',+ ...(options.dimensionFilterGroups &&+ options.dimensionFilterGroups.length > 0+ ? { dimensionFilterGroups: options.dimensionFilterGroups }+ : {}),+ },+ })++ return (data.rows || []) as GSCRow[]+ }++ private static clampLimit(limit: number, fallback = 50): number {+ return Math.max(1, Math.min(limit || fallback, MAX_ROW_LIMIT))+ }++ private static clampOffset(offset: number): number {+ return Math.max(0, offset || 0)+ }++ async getKeywords(+ pid: string,+ from: string,+ to: string,+ limit = 250,+ offset = 0,+ filtersStr?: string,+ page?: string,+ ctx?: GSCContext,+ ): Promise<+ {+ name: string+ count: number+ impressions: number+ position: number+ ctr: number+ }[]+ > {+ const gsc = ctx || (await this.getGSCContext(pid))+ const dimensionFilterGroups = this.getDimensionFilterGroups(+ filtersStr,+ page ? [{ dimension: 'page', expression: page }] : [],+ )++ try {+ const rows = await this.queryGSC(gsc, from, to, {+ dimensions: ['query'],+ rowLimit: GSCService.clampLimit(limit, 250),+ startRow: GSCService.clampOffset(offset),+ dimensionFilterGroups,+ })++ return rows+ .map((row) => ({+ name: row.keys?.[0] || '(not set)',+ count: Math.round(row.clicks || 0),+ impressions: Math.round(row.impressions || 0),+ position: Number(Number(row.position || 0).toFixed(2)),+ ctr: Number(Number((row.ctr || 0) * 100).toFixed(2)),+ }))+ .filter(Boolean)+ } catch {+ throw new InternalServerErrorException(+ 'Failed to fetch keywords from Search Console',+ )+ }+ }++ async getSummary(+ pid: string,+ from: string,+ to: string,+ filtersStr?: string,+ ctx?: GSCContext,+ ): Promise<{+ clicks: number+ impressions: number+ ctr: number+ position: number+ }> {+ const gsc = ctx || (await this.getGSCContext(pid))+ const dimensionFilterGroups = this.getDimensionFilterGroups(filtersStr)++ try {+ const rows = await this.queryGSC(gsc, from, to, {+ dimensionFilterGroups,+ })++ const row = rows[0]+ return {+ clicks: Math.round(row?.clicks || 0),+ impressions: Math.round(row?.impressions || 0),+ ctr: Number(Number((row?.ctr || 0) * 100).toFixed(2)),+ position: Number(Number(row?.position || 0).toFixed(1)),+ }+ } catch {+ throw new InternalServerErrorException(+ 'Failed to fetch summary from Search Console',+ )+ }+ }++ async getDateSeries(+ pid: string,+ from: string,+ to: string,+ timeBucket?: string,+ filtersStr?: string,+ ctx?: GSCContext,+ ): Promise<+ {+ date: string+ clicks: number+ impressions: number+ ctr: number+ position: number+ }[]+ > {+ const gsc = ctx || (await this.getGSCContext(pid))+ const dimensionFilterGroups = this.getDimensionFilterGroups(filtersStr)+ const isHourly = timeBucket === 'hour'++ try {+ const rows = await this.queryGSC(gsc, from, to, {+ dimensions: isHourly ? ['HOUR'] : ['date'],+ rowLimit: 5000,+ dataState: isHourly ? 'HOURLY_ALL' : 'all',+ dimensionFilterGroups,+ })++ return rows.map((row) => ({+ date: row.keys?.[0]+ ? isHourly+ ? dayjs.utc(row.keys[0]).format('YYYY-MM-DD HH:mm:ss')+ : row.keys[0]+ : '',+ clicks: Math.round(row.clicks || 0),+ impressions: Math.round(row.impressions || 0),+ ctr: Number(Number((row.ctr || 0) * 100).toFixed(2)),+ position: Number(Number(row.position || 0).toFixed(1)),+ }))+ } catch {+ throw new InternalServerErrorException(+ 'Failed to fetch date series from Search Console',+ )+ }+ }++ async getTopPages(+ pid: string,+ from: string,+ to: string,+ limit = 50,+ offset = 0,+ filtersStr?: string,+ query?: string,+ ctx?: GSCContext,+ ): Promise<+ {+ page: string+ clicks: number+ impressions: number+ ctr: number+ position: number+ }[]+ > {+ const gsc = ctx || (await this.getGSCContext(pid))+ const dimensionFilterGroups = this.getDimensionFilterGroups(+ filtersStr,+ query ? [{ dimension: 'query', expression: query }] : [],+ )++ try {+ const rows = await this.queryGSC(gsc, from, to, {+ dimensions: ['page'],+ rowLimit: GSCService.clampLimit(limit),+ startRow: GSCService.clampOffset(offset),+ dimensionFilterGroups,+ })++ return rows.map((row) => ({+ page: row.keys?.[0] || '(not set)',+ clicks: Math.round(row.clicks || 0),+ impressions: Math.round(row.impressions || 0),+ ctr: Number(Number((row.ctr || 0) * 100).toFixed(2)),+ position: Number(Number(row.position || 0).toFixed(1)),+ }))+ } catch {+ throw new InternalServerErrorException(+ 'Failed to fetch top pages from Search Console',+ )+ }+ }++ async getTopCountries(+ pid: string,+ from: string,+ to: string,+ limit = 50,+ offset = 0,+ filtersStr?: string,+ ctx?: GSCContext,+ ): Promise<+ {+ country: string+ clicks: number+ impressions: number+ ctr: number+ position: number+ }[]+ > {+ const gsc = ctx || (await this.getGSCContext(pid))+ const dimensionFilterGroups = this.getDimensionFilterGroups(filtersStr)++ try {+ const rows = await this.queryGSC(gsc, from, to, {+ dimensions: ['country'],+ rowLimit: GSCService.clampLimit(limit),+ startRow: GSCService.clampOffset(offset),+ dimensionFilterGroups,+ })++ return rows.map((row) => ({+ country: (row.keys?.[0] || '').toLowerCase(),+ clicks: Math.round(row.clicks || 0),+ impressions: Math.round(row.impressions || 0),+ ctr: Number(Number((row.ctr || 0) * 100).toFixed(2)),+ position: Number(Number(row.position || 0).toFixed(1)),+ }))+ } catch {+ throw new InternalServerErrorException(+ 'Failed to fetch top countries from Search Console',+ )+ }+ }++ async getTopDevices(+ pid: string,+ from: string,+ to: string,+ limit = 50,+ offset = 0,+ filtersStr?: string,+ ctx?: GSCContext,+ ): Promise<+ {+ device: string+ clicks: number+ impressions: number+ ctr: number+ position: number+ }[]+ > {+ const gsc = ctx || (await this.getGSCContext(pid))+ const dimensionFilterGroups = this.getDimensionFilterGroups(filtersStr)++ try {+ const rows = await this.queryGSC(gsc, from, to, {+ dimensions: ['device'],+ rowLimit: GSCService.clampLimit(limit),+ startRow: GSCService.clampOffset(offset),+ dimensionFilterGroups,+ })++ return rows.map((row) => ({+ device: (row.keys?.[0] || '').toLowerCase(),+ clicks: Math.round(row.clicks || 0),+ impressions: Math.round(row.impressions || 0),+ ctr: Number(Number((row.ctr || 0) * 100).toFixed(2)),+ position: Number(Number(row.position || 0).toFixed(1)),+ }))+ } catch {+ throw new InternalServerErrorException(+ 'Failed to fetch top devices from Search Console',+ )+ }+ }++ async getBrandedTraffic(+ pid: string,+ from: string,+ to: string,+ filtersStr?: string,+ ctx?: GSCContext,+ ): Promise<{ branded: number; nonBranded: number }> {+ const brandKeywords = await this.getProjectBrandKeywords(pid)+ if (_isEmpty(brandKeywords)) {+ return { branded: 0, nonBranded: 0 }+ }++ const gsc = ctx || (await this.getGSCContext(pid))+ const dimensionFilterGroups = this.getDimensionFilterGroups(filtersStr)+ const rowLimit = MAX_ROW_LIMIT+ let startRow = 0+ let branded = 0+ let nonBranded = 0+ let pages = 0++ try {+ while (pages < MAX_BRANDED_PAGES) {+ const rows = await this.queryGSC(gsc, from, to, {+ dimensions: ['query'],+ rowLimit,+ startRow,+ dimensionFilterGroups,+ })++ for (const row of rows) {+ const query = (row.keys?.[0] || '').toLowerCase()+ const clicks = row.clicks || 0++ if (brandKeywords.some((keyword) => query.includes(keyword))) {+ branded += clicks+ } else {+ nonBranded += clicks+ }+ }++ if (rows.length < rowLimit) break++ startRow += rowLimit+ pages+++ }++ return {+ branded: Math.round(branded),+ nonBranded: Math.round(nonBranded),+ }+ } catch {+ throw new InternalServerErrorException(+ 'Failed to fetch branded traffic from Search Console',+ )+ }+ }++ async getDashboard(+ pid: string,+ from: string,+ to: string,+ timeBucket?: string,+ filtersStr?: string,+ ) {+ if (!this.isAvailable()) {+ return { notConnected: true }+ }++ const connected = await this.isConnected(pid)+ if (!connected) {+ return { notConnected: true }+ }++ const tokens = await this.getStoredTokens(pid)+ if (_isEmpty(tokens.property_uri)) {+ return { notConnected: true, noProperty: true }+ }++ let ctx: GSCContext+ try {+ ctx = await this.getGSCContext(pid)+ } catch {+ return { notConnected: true }+ }++ const fromDate = dayjs(from)+ const toDate = dayjs(to)+ const days = toDate.diff(fromDate, 'day') + 1+ const prevTo = fromDate.subtract(1, 'day').format('YYYY-MM-DD HH:mm:ss')+ const prevFrom = fromDate+ .subtract(days, 'day')+ .format('YYYY-MM-DD HH:mm:ss')++ const [+ summary,+ previousSummary,+ dateSeries,+ topPages,+ topQueries,+ topCountries,+ topDevices,+ brandedTraffic,+ ] = await Promise.all([+ this.getSummary(pid, from, to, filtersStr, ctx),+ this.getSummary(pid, prevFrom, prevTo, filtersStr, ctx).catch(() => null),+ this.getDateSeries(pid, from, to, timeBucket, filtersStr, ctx),+ this.getTopPages(pid, from, to, 50, 0, filtersStr, undefined, ctx),+ this.getKeywords(pid, from, to, 50, 0, filtersStr, undefined, ctx),+ this.getTopCountries(pid, from, to, 50, 0, filtersStr, ctx),+ this.getTopDevices(pid, from, to, 50, 0, filtersStr, ctx),+ this.getBrandedTraffic(pid, from, to, filtersStr, ctx),+ ])++ return {+ notConnected: false,+ summary,+ previousSummary,+ dateSeries,+ topPages,+ topQueries,+ topCountries,+ topDevices,+ brandedTraffic,+ }+ }+}diff --git a/backend/apps/community/src/project/project.controller.ts b/backend/apps/community/src/project/project.controller.tsindex 447fc2b09..757444527 100644--- a/backend/apps/community/src/project/project.controller.ts+++ b/backend/apps/community/src/project/project.controller.ts@@ -1115,6 +1115,10 @@ export class ProjectController {project.captchaDifficulty = projectDTO.captchaDifficulty}+ if (projectDTO.brandKeywords !== undefined) {+ project.brandKeywords = projectDTO.brandKeywords+ }+await updateProjectClickhouse(this.projectService.formatToClickhouse(project),)diff --git a/backend/apps/community/src/project/project.module.ts b/backend/apps/community/src/project/project.module.tsindex 0990bab76..46d3d9dc8 100644--- a/backend/apps/community/src/project/project.module.ts+++ b/backend/apps/community/src/project/project.module.ts@@ -2,14 +2,16 @@ import { Module, forwardRef } from '@nestjs/common'import { ProjectService } from './project.service'import { ProjectController } from './project.controller'+import { GSCService } from './gsc.service'+import { GSCController } from './gsc.controller'import { AppLoggerModule } from '../logger/logger.module'import { UserModule } from '../user/user.module'import { MailerModule } from '../mailer/mailer.module'@Module({imports: [AppLoggerModule, forwardRef(() => UserModule), MailerModule],- providers: [ProjectService],- exports: [ProjectService],- controllers: [ProjectController],+ providers: [ProjectService, GSCService],+ exports: [ProjectService, GSCService],+ controllers: [ProjectController, GSCController],})export class ProjectModule {}diff --git a/backend/apps/community/src/project/project.service.ts b/backend/apps/community/src/project/project.service.tsindex 1d04b3274..637b025d6 100644--- a/backend/apps/community/src/project/project.service.ts+++ b/backend/apps/community/src/project/project.service.ts@@ -445,6 +445,18 @@ export class ProjectService {: _join(updProject.countryBlacklist, ',')}+ if (updProject.brandKeywords !== undefined) {+ if (+ updProject.brandKeywords === null ||+ (Array.isArray(updProject.brandKeywords) &&+ updProject.brandKeywords.length === 0)+ ) {+ updProject.brandKeywords = null+ } else if (Array.isArray(updProject.brandKeywords)) {+ updProject.brandKeywords = JSON.stringify(updProject.brandKeywords)+ }+ }+return updProject}@@ -467,6 +479,17 @@ export class ProjectService {? []: _split(updProject.countryBlacklist, ',')+ if (updProject.brandKeywords && _isString(updProject.brandKeywords)) {+ try {+ const parsed = JSON.parse(updProject.brandKeywords)+ updProject.brandKeywords = Array.isArray(parsed) ? parsed : null+ } catch {+ updProject.brandKeywords = null+ }+ } else if (updProject.brandKeywords === undefined) {+ updProject.brandKeywords = null+ }+return updProject}diff --git a/backend/migrations/clickhouse/initialise_selfhosted.js b/backend/migrations/clickhouse/initialise_selfhosted.jsindex c2d840a46..f463fe67f 100644--- a/backend/migrations/clickhouse/initialise_selfhosted.js+++ b/backend/migrations/clickhouse/initialise_selfhosted.js@@ -38,6 +38,13 @@ const CLICKHOUSE_INIT_QUERIES = [isCaptchaProject Int8 DEFAULT 0,captchaSecretKey Nullable(String) CODEC(ZSTD(3)),captchaDifficulty UInt8 DEFAULT 4,+ gscPropertyUri Nullable(String) DEFAULT NULL CODEC(ZSTD(3)),+ gscAccessTokenEnc Nullable(String) DEFAULT NULL CODEC(ZSTD(3)),+ gscRefreshTokenEnc Nullable(String) DEFAULT NULL CODEC(ZSTD(3)),+ gscTokenExpiry Nullable(Int64) DEFAULT NULL,+ gscScope Nullable(String) DEFAULT NULL CODEC(ZSTD(3)),+ gscAccountEmail Nullable(String) DEFAULT NULL CODEC(ZSTD(3)),+ brandKeywords Nullable(String) DEFAULT NULL CODEC(ZSTD(3)),created DateTime CODEC(Delta(4), LZ4))ENGINE = MergeTree()diff --git a/backend/migrations/clickhouse/selfhosted_2026_04_28_gsc.js b/backend/migrations/clickhouse/selfhosted_2026_04_28_gsc.jsnew file mode 100644index 000000000..030ebdaf7--- /dev/null+++ b/backend/migrations/clickhouse/selfhosted_2026_04_28_gsc.js@@ -0,0 +1,14 @@+// This migration adds Google Search Console integration columns and brandKeywords to the project table+const { queriesRunner, dbName } = require('./setup')++const queries = [+ `ALTER TABLE ${dbName}.project ADD COLUMN IF NOT EXISTS gscPropertyUri Nullable(String) DEFAULT NULL CODEC(ZSTD(3));`,+ `ALTER TABLE ${dbName}.project ADD COLUMN IF NOT EXISTS gscAccessTokenEnc Nullable(String) DEFAULT NULL CODEC(ZSTD(3));`,+ `ALTER TABLE ${dbName}.project ADD COLUMN IF NOT EXISTS gscRefreshTokenEnc Nullable(String) DEFAULT NULL CODEC(ZSTD(3));`,+ `ALTER TABLE ${dbName}.project ADD COLUMN IF NOT EXISTS gscTokenExpiry Nullable(Int64) DEFAULT NULL;`,+ `ALTER TABLE ${dbName}.project ADD COLUMN IF NOT EXISTS gscScope Nullable(String) DEFAULT NULL CODEC(ZSTD(3));`,+ `ALTER TABLE ${dbName}.project ADD COLUMN IF NOT EXISTS gscAccountEmail Nullable(String) DEFAULT NULL CODEC(ZSTD(3));`,+ `ALTER TABLE ${dbName}.project ADD COLUMN IF NOT EXISTS brandKeywords Nullable(String) DEFAULT NULL CODEC(ZSTD(3));`,+]++queriesRunner(queries)diff --git a/docs/content/docs/integrations/google-search-console.mdx b/docs/content/docs/integrations/google-search-console.mdxindex 5ccf33ec6..8d2c4dc27 100644--- a/docs/content/docs/integrations/google-search-console.mdx+++ b/docs/content/docs/integrations/google-search-console.mdx@@ -26,6 +26,12 @@ You must have a Google Search Console account with your website property already</Callout>+<Callout type="info" title="Self-hosting">++Running Swetrix Community Edition? Before users can connect Search Console, an administrator needs to register a Google Cloud OAuth client and set a few environment variables on the API container. Follow the [self-hosted setup guide](/selfhosting/google-search-console) once and the integration will work for every project on your instance.++</Callout>+1. **Navigate to Project Settings:**Open your project dashboard and click on the **Settings** tab in the navigation menu.diff --git a/docs/content/docs/selfhosting/configuring.mdx b/docs/content/docs/selfhosting/configuring.mdxindex e2dbbf1ab..dbe185768 100644--- a/docs/content/docs/selfhosting/configuring.mdx+++ b/docs/content/docs/selfhosting/configuring.mdx@@ -28,6 +28,7 @@ The `BASE_URL` must be publicly reachable from your users' browsers. Do not set| Variable | Default | Description || ------------------------------------ | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- || `SECRET_KEY_BASE` | _auto-generated by `configure.sh`_ | Secret used for auth keys and login sessions. Must be set. |+| `BASE_URL` | | Public URL of your Swetrix CE instance, e.g. `https://analytics.example.com`. Used by the API to build the OAuth redirect URI for the [Google Search Console integration](/selfhosting/google-search-console). Required to enable that integration. || `CLIENT_IP_HEADER` | `null` | Defines what header should be used to get IP address (e.g. cf-connecting-ip, x-real-ip, etc.). If not set, Swetrix will use `x-forwarded-for` header. || `DISABLE_REGISTRATION` | `true` | When set to `true` - Swetrix will disable user registration, except for the initial user. || `IP_GEOLOCATION_DB_PATH` | `` | Path to the `.mmdb` file for IP geolocation database. By default Swetrix uses the IP to City Lite database by DB-IP, which provides country / region / city only. To populate the **Network intelligence** panel (ISP, organisation, usage type, connection type), point this at a paid MaxMind GeoIP2 ISP / Insights database or a paid DB-IP database that includes those fields. |@@ -49,6 +50,18 @@ Swetrix will send transactional emails for some actions, like password reset orIf you don't have an SMTP provider, some regular email providers offer this functionality. For example, you can [configure Gmail for app specific passwords](https://support.google.com/mail/answer/185833) and use them as SMTP credentials (in this case, the `SMTP_HOST` should be `smtp.gmail.com` with port `587`).+### Google Search Console integration++To let users connect their Google Search Console account from project settings (and populate the SEO dashboard), the API needs an OAuth client created in your own Google Cloud project. The full step-by-step guide lives in [Google Search Console](/selfhosting/google-search-console); the relevant variables are:++| Variable | Default | Description |+| -------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `GOOGLE_GSC_CLIENT_ID` | | OAuth 2.0 Client ID issued by the Google Cloud console for your Swetrix instance. |+| `GOOGLE_GSC_CLIENT_SECRET` | | OAuth 2.0 Client secret matching `GOOGLE_GSC_CLIENT_ID`. |+| `BASE_URL` | | Public URL of your Swetrix CE instance. The API uses `${BASE_URL}/gsc-connected` as the OAuth redirect URI; it must match the URI registered in the Google Cloud console. |++If any of these are unset the SEO tab still shows up but the integrations card displays a "not configured" notice instead of the **Connect** button.+### OIDC configurationSwetrix Community Edition also supports OIDC authentication. To enable it, you need to set the following variables:diff --git a/docs/content/docs/selfhosting/google-search-console.mdx b/docs/content/docs/selfhosting/google-search-console.mdxnew file mode 100644index 000000000..0f7cc9f7f--- /dev/null+++ b/docs/content/docs/selfhosting/google-search-console.mdx@@ -0,0 +1,115 @@+---+title: Google Search Console+slug: /selfhosting/google-search-console+---++Swetrix Community Edition can integrate with Google Search Console (GSC) to power the [SEO dashboard](/analytics-dashboard/seo). Unlike the cloud version, self-hosted instances need their own Google Cloud OAuth client because Google requires every OAuth app to be registered against a specific domain.++This guide walks you through everything you need to do once.++<Callout type="info">+Already have a Google Cloud project with an OAuth consent screen and a verified Search Console property? Skip to [Issue an OAuth client](#issue-an-oauth-client-and-secret).+</Callout>++## What you'll set up++1. A Google Cloud project that owns the OAuth client.+2. An OAuth consent screen for your Swetrix domain.+3. A web-application OAuth client with the correct redirect URI.+4. Verification of your domain in Google Search Console.+5. The Google Search Console API enabled in the same Google Cloud project.+6. Three environment variables on the Swetrix API container.++## 1. Create a Google Cloud project++Open the [Google Cloud console](https://console.cloud.google.com/) and either select an existing project or create a new one (we recommend a dedicated one for Swetrix).++Make sure the project stays selected for every step below β Google sometimes silently switches you to a "default" project.++## 2. Configure the OAuth consent screen++In the left sidebar go to **APIs & Services** β **OAuth consent screen**.++- **User type:** **External** (the **Internal** option requires a Google Workspace organization).+- **App name:** anything recognisable, e.g. `Swetrix`.+- **User support email** and **Developer contact information:** your email.+- **Authorized domains:** add the bare domain Swetrix is hosted on (no scheme, no path), e.g. `analytics.example.com`.+- **Scopes:** you can leave the optional scopes empty.+- **Test users:** add the Google account(s) that will connect Search Console from Swetrix. Google will warn you that the app is unverified; this is fine for self-hosted use.++Save and continue through the wizard until the consent screen is registered.++## 3. Issue an OAuth client and secret++Still in **APIs & Services**, open **Credentials** and click **+ Create credentials** β **OAuth client ID**.++- **Application type:** **Web application**.+- **Name:** `Swetrix CE` (or whatever you like).+- **Authorized redirect URIs:** add **exactly one** entry:++ ```+ https://analytics.example.com/gsc-connected+ ```++ Replace `https://analytics.example.com` with the public URL you'll set as `BASE_URL` on the Swetrix API container. The path must be `/gsc-connected`.++After you click **Create**, Google shows a **Client ID** and **Client secret**. Copy both β you'll need them in the next step.++## 4. Verify your domain in Search Console++Open the [Google Search Console](https://search.google.com/search-console/) and add your site as a property if you haven't already. Either the **Domain** or the **URL prefix** verification methods work β follow the in-product instructions.++The Google account that owns the verified property is the same account you'll connect from Swetrix later, so make sure it appears in the OAuth test-users list from step 2.++## 5. Enable the Search Console API++Back in the Google Cloud console, go to **APIs & Services** β **Library** and search for **Google Search Console API**. Open it and click **Enable**.++Without this step, every authorisation attempt from Swetrix will fail with `accessNotConfigured`.++## 6. Configure the Swetrix API container++Add the following variables to the `.env` file used by the `swetrix-api` container (or to your `docker-compose.yml`):++```env+# Public URL of your Swetrix CE instance. Must match the redirect URI you+# registered in step 3 (without the /gsc-connected suffix).+BASE_URL=https://analytics.example.com++# OAuth client created in step 3+GOOGLE_GSC_CLIENT_ID=1234567890-xxxxxxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com+GOOGLE_GSC_CLIENT_SECRET=GOCSPX-xxxxxxxxxxxxxxxxxxxxxxxx+```++Restart the API container so it picks up the new environment:++```bash+docker compose up -d swetrix-api+```++You can confirm the variables are visible to the container with:++```bash+docker compose exec swetrix-api sh -c 'echo $GOOGLE_GSC_CLIENT_ID'+```++## 7. Connect Search Console from Swetrix++1. Open any project in Swetrix.+2. Go to **Settings** β **Integrations**.+3. Click **Connect** in the **Google Search Console** card. You'll be sent to Google's consent screen.+4. Pick the Google account you added as a test user, click **Continue** through the unverified-app warnings, and approve the read-only Search Console scope.+5. You'll be redirected back to the Swetrix integrations page. Pick the Search Console **Website Property** that matches this project from the dropdown and click **Save**.++The **SEO** tab on the project dashboard will start showing data within a minute or two.++## Troubleshooting++- **"Google Search Console is not configured on this server"** in the integrations card β one of `GOOGLE_GSC_CLIENT_ID`, `GOOGLE_GSC_CLIENT_SECRET`, or `BASE_URL` is missing. Check the API container env and restart it.+- **`redirect_uri_mismatch`** during the Google consent flow β the redirect URI you registered in step 3 doesn't exactly match `${BASE_URL}/gsc-connected`. They must match character-for-character (scheme, hostname, port, trailing slash).+- **`accessNotConfigured`** or "API not enabled" errors β go back to step 5 and enable the Google Search Console API for the same Google Cloud project that owns the OAuth client.+- **`Access blocked: This app's request is invalid`** β your test user is not on the OAuth consent screen test-users list. Add them in step 2.++## Rotating credentials++If you ever rotate `GOOGLE_GSC_CLIENT_SECRET` or `SECRET_KEY_BASE`, existing GSC connections become invalid. Users will need to disconnect and reconnect Search Console for each project.diff --git a/docs/content/docs/selfhosting/meta.json b/docs/content/docs/selfhosting/meta.jsonindex 1fae29ec7..a99a2f5aa 100644--- a/docs/content/docs/selfhosting/meta.json+++ b/docs/content/docs/selfhosting/meta.json@@ -1,4 +1,4 @@{"title": "Self-hosting",- "pages": ["how-to", "configuring"]+ "pages": ["how-to", "configuring", "google-search-console"]}diff --git a/web/app/lib/constants/index.ts b/web/app/lib/constants/index.tsindex 5460f46d7..7a77c2ac0 100644--- a/web/app/lib/constants/index.ts+++ b/web/app/lib/constants/index.ts@@ -555,6 +555,7 @@ export const FUNNELS_PERIOD_PAIRS = [const SELFHOSTED_PROJECT_TABS = {traffic: 'traffic',performance: 'performance',+ seo: 'seo',funnels: 'funnels',profiles: 'profiles',sessions: 'sessions',diff --git a/web/app/pages/Project/Settings/ProjectSettings.tsx b/web/app/pages/Project/Settings/ProjectSettings.tsxindex 06c9c30c4..fb10fc93b 100644--- a/web/app/pages/Project/Settings/ProjectSettings.tsx+++ b/web/app/pages/Project/Settings/ProjectSettings.tsx@@ -331,9 +331,7 @@ const ProjectSettings = () => {'basic',gscPropertyUri: initialProject.gscPropertyUri || null,websiteUrl: initialProject.websiteUrl || null,- ...(!isSelfhosted && {- brandKeywords: initialProject.brandKeywords?.join(', ') || '',- }),+ brandKeywords: initialProject.brandKeywords?.join(', ') || '',}))const [validated, setValidated] = useState(false)const [errors, setErrors] = useState<{@@ -417,7 +415,7 @@ const ProjectSettings = () => {description: t('project.settings.tabs.integrationsDesc'),icon: PuzzlePieceIcon,iconColor: 'text-purple-500',- visible: !isSelfhosted,+ visible: true,},{id: 'alerts',@@ -519,6 +517,7 @@ const ProjectSettings = () => {{ siteUrl: string; permissionLevel?: string }[]>([])const [gscEmail, setGscEmail] = useState<string | null>(null)+ const [gscAvailable, setGscAvailable] = useState<boolean>(true)// CAPTCHA stateconst [captchaSecretKey, setCaptchaSecretKey] = useState<string | null>(@@ -612,6 +611,7 @@ const ProjectSettings = () => {if (intent === 'gsc-status' && gscStatus) {setGscConnected(gscStatus.connected)setGscEmail(gscStatus.email || null)+ setGscAvailable(gscStatus.available !== false)if (gscStatus.connected) {setGscPropertiesPending(true)} else {@@ -672,7 +672,7 @@ const ProjectSettings = () => {// Initial GSC status fetchuseEffect(() => {- if (isSelfhosted || gscInitialized.current) return+ if (gscInitialized.current) returngscInitialized.current = truegscFetcher.submit({ intent: 'gsc-status' }, { method: 'post' })// eslint-disable-next-line react-hooks/exhaustive-deps@@ -756,7 +756,7 @@ const ProjectSettings = () => {formData.set('countryBlacklist', JSON.stringify(data.countryBlacklist))if (data.websiteUrl !== undefined)formData.set('websiteUrl', data.websiteUrl || '')- if (!isSelfhosted && data.brandKeywords !== undefined)+ if (data.brandKeywords !== undefined)formData.set('brandKeywords', data.brandKeywords || '')fetcher.submit(formData, { method: 'post' })@@ -1137,6 +1137,27 @@ const ProjectSettings = () => {</h3>{gscConnected === null ? (<Loader />+ ) : !gscAvailable ? (+ <div className='rounded-md border border-amber-200 bg-amber-50 p-3 text-sm text-amber-900 dark:border-amber-900/60 dark:bg-amber-950/40 dark:text-amber-100'>+ <Trans+ t={t}+ i18nKey='project.settings.gsc.notConfigured'+ defaults='Google Search Console is not configured on this server. To enable it, set <code>GOOGLE_GSC_CLIENT_ID</code>, <code>GOOGLE_GSC_CLIENT_SECRET</code> and <code>BASE_URL</code> in your API container environment, then restart it. <url>See the self-hosting guide</url>.'+ components={{+ code: (+ <code className='rounded bg-amber-100 px-1 py-0.5 font-mono text-xs dark:bg-amber-900/60' />+ ),+ url: (+ <a+ href='https://docs.swetrix.com/selfhosting/google-search-console'+ target='_blank'+ rel='noopener noreferrer'+ className='font-medium underline decoration-dashed hover:decoration-solid'+ />+ ),+ }}+ />+ </div>) : !gscConnected ? (<div className='flex flex-col items-center justify-between gap-4 md:flex-row'><p className='text-sm text-gray-800 dark:text-gray-200'>@@ -1253,7 +1274,7 @@ const ProjectSettings = () => {</div>)}- {gscConnected ? null : (+ {gscConnected || !gscAvailable ? null : (<><hr className='-mx-4 mt-4 mb-4 border-gray-200 dark:border-slate-800' />diff --git a/web/app/pages/Project/Settings/tabs/General.tsx b/web/app/pages/Project/Settings/tabs/General.tsxindex b4ca39707..eb3c3b22f 100644--- a/web/app/pages/Project/Settings/tabs/General.tsx+++ b/web/app/pages/Project/Settings/tabs/General.tsx@@ -2,7 +2,6 @@ import React from 'react'import { useTranslation } from 'react-i18next'import Input from '~/ui/Input'-import { isSelfhosted } from '~/lib/constants'interface GeneralProps {form: {@@ -62,18 +61,16 @@ const General = ({onChange={handleInput}error={beenSubmitted ? errors.websiteUrl : null}/>- {!isSelfhosted && (- <Input- name='brandKeywords'- label={t('project.settings.brandKeywords')}- hint={t('project.settings.brandKeywordsHint')}- value={form.brandKeywords || ''}- placeholder={t('project.settings.brandKeywordsPlaceholder')}- className='mt-4'- onChange={handleInput}- error={null}- />- )}+ <Input+ name='brandKeywords'+ label={t('project.settings.brandKeywords')}+ hint={t('project.settings.brandKeywordsHint')}+ value={form.brandKeywords || ''}+ placeholder={t('project.settings.brandKeywordsPlaceholder')}+ className='mt-4'+ onChange={handleInput}+ error={null}+ /><Inputname='sharableLink'label={t('project.settings.sharableLink')}diff --git a/web/app/pages/Project/View/ViewProject.tsx b/web/app/pages/Project/View/ViewProject.tsxindex 692af96eb..d49eb7b45 100644--- a/web/app/pages/Project/View/ViewProject.tsx+++ b/web/app/pages/Project/View/ViewProject.tsx@@ -362,7 +362,6 @@ const ViewProjectContent = () => {const tnMapping = typeNameMapping(t)const refCalendar = useRef(null)const refCalendarCompare = useRef(null)- const seoTabId = !isSelfhosted ? PROJECT_TABS.seo : nullconst activeTab = useMemo(() => {const tab = searchParams.get('tab') as keyof typeof PROJECT_TABS@@ -718,15 +717,11 @@ const ViewProjectContent = () => {label: t('dashboard.traffic'),icon: ChartBarIcon,},- ...(seoTabId- ? [- {- id: seoTabId,- label: t('project.seo.title'),- icon: MagnifyingGlassIcon,- },- ]- : []),+ {+ id: PROJECT_TABS.seo,+ label: t('project.seo.title'),+ icon: MagnifyingGlassIcon,+ },{id: PROJECT_TABS.performance,label: t('dashboard.performance'),@@ -803,7 +798,7 @@ const ViewProjectContent = () => {}return newTabs- }, [t, projectQueryTabs, allowedToManage, seoTabId])+ }, [t, projectQueryTabs, allowedToManage])const activeTabLabel = useMemo(() => _find(tabs, (tab) => tab.id === activeTab)?.label,@@ -929,13 +924,13 @@ const ViewProjectContent = () => {return}- if (seoTabId && activeTab === seoTabId) {+ if (activeTab === PROJECT_TABS.seo) {setSeoRefreshTrigger((prev) => prev + 1)return}}},- [authLoading, dataLoading, activeTab, seoTabId],+ [authLoading, dataLoading, activeTab],)useEffect(() => {@@ -1550,7 +1545,7 @@ const ViewProjectContent = () => {{activeTab === PROJECT_TABS.performance ? (<PerformanceView tnMapping={tnMapping} />) : null}- {seoTabId && activeTab === seoTabId ? (+ {activeTab === PROJECT_TABS.seo ? (<SEOView projectId={id} tnMapping={tnMapping} />) : null}{activeTab === PROJECT_TABS.funnels ? (diff --git a/web/app/routes/gsc-connected.tsx b/web/app/routes/gsc-connected.tsxindex ccb5d41f9..414ed159e 100644--- a/web/app/routes/gsc-connected.tsx+++ b/web/app/routes/gsc-connected.tsx@@ -6,7 +6,6 @@ import type { SitemapFunction } from 'remix-sitemap'import { serverFetch } 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'@@ -28,10 +27,6 @@ export interface GscConnectedLoaderData {export async function loader({request,}: LoaderFunctionArgs): Promise<GscConnectedLoaderData | Response> {- if (isSelfhosted) {- return redirect('/login', 302)- }-const url = new URL(request.url)// Google sometimes redirects with hash instead of query paramsdiff --git a/web/app/routes/projects.settings.$id.tsx b/web/app/routes/projects.settings.$id.tsxindex 63ccaec6a..b650eac67 100644--- a/web/app/routes/projects.settings.$id.tsx+++ b/web/app/routes/projects.settings.$id.tsx@@ -64,6 +64,7 @@ export interface RevenueStatus {export interface GscStatus {connected: booleanemail?: string | null+ available?: boolean}export interface GscProperty {