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!

Security improvements & refactoring

Blue Mousefde3934a8c6c
diff --git a/backend/apps/cloud/src/analytics/analytics.controller.ts b/backend/apps/cloud/src/analytics/analytics.controller.ts
index 78e06f56d..88b7fa1e9 100644
--- a/backend/apps/cloud/src/analytics/analytics.controller.ts
+++ b/backend/apps/cloud/src/analytics/analytics.controller.ts
@@ -887,7 +887,6 @@ export class AnalyticsController {
@Auth(true, true)
async getGSCDashboard(
@Query() data: GetKeywordsDto,
- @Query('filters') filtersStr: string,
@CurrentUserId() uid: string,
@Headers() headers: { 'x-password'?: string },
) {
@@ -898,8 +897,8 @@ export class AnalyticsController {
to,
timezone = DEFAULT_TIMEZONE,
timeBucket,
+ filters,
} = data
- const filters = filtersStr || data.filters
await this.analyticsService.checkProjectAccess(
pid,
@@ -952,14 +951,18 @@ export class AnalyticsController {
@Auth(true, true)
async getGSCDetails(
@Query() data: GetKeywordsDto,
- @Query('page') pageStr: string,
- @Query('query') queryStr: string,
@CurrentUserId() uid: string,
@Headers() headers: { 'x-password'?: string },
) {
- const { pid, period, from, to, timezone = DEFAULT_TIMEZONE } = data
- const page = pageStr || data.page
- const query = queryStr || data.query
+ const {
+ pid,
+ period,
+ from,
+ to,
+ timezone = DEFAULT_TIMEZONE,
+ page,
+ query,
+ } = data
this.logger.log(
`pid: ${pid}, period: ${period}, page: ${page}, query: ${query}`,
diff --git a/backend/apps/cloud/src/project/gsc.service.ts b/backend/apps/cloud/src/project/gsc.service.ts
index 706fc0dfe..a2128406b 100644
--- a/backend/apps/cloud/src/project/gsc.service.ts
+++ b/backend/apps/cloud/src/project/gsc.service.ts
@@ -1,4 +1,5 @@
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'
@@ -35,6 +36,50 @@ const GSC_REDIRECT_URL = isDevelopment
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[]
+}
+
+export function parseBrandKeywords(
+ raw: string | null | undefined,
+): string[] | null {
+ if (!raw) return null
+ try {
+ const parsed = JSON.parse(raw)
+ if (
+ Array.isArray(parsed) &&
+ parsed.every((item) => typeof item === 'string')
+ ) {
+ return parsed
+ }
+ return null
+ } catch {
+ return null
+ }
+}
+
@Injectable()
export class GSCService {
constructor(
@@ -223,7 +268,6 @@ export class GSCService {
const oauth2Client = this.getOAuthClient()
oauth2Client.setCredentials(tokens)
- // Refresh if expired
if (tokens.expiry_date && tokens.expiry_date <= Date.now()) {
const refreshed = await oauth2Client.getAccessToken()
const newAccess =
@@ -242,6 +286,38 @@ export class GSCService {
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 }[]> {
@@ -274,43 +350,98 @@ export class GSCService {
} as any)
}
+ // ---------------------------------------------------------------------------
+ // Filter parsing with schema validation + country code normalization
+ // ---------------------------------------------------------------------------
+
private parseFilters(filtersStr?: string) {
if (!filtersStr) return undefined
+
+ let filters: unknown
try {
- const filters = JSON.parse(filtersStr)
- const mappedFilters = []
-
- for (const filter of filters) {
- const { column, filter: value, isExclusive, isContains } = filter
-
- let dimension
- if (column === 'pg') dimension = 'page'
- else if (column === 'keywords') dimension = 'query'
- else if (column === 'country' || column === 'cc') dimension = 'country'
- else if (column === 'device' || column === 'dv') dimension = 'device'
- else continue
-
- let operator = 'equals'
- if (isExclusive) {
- operator = isContains ? 'notContains' : 'notEquals'
- } else if (isContains) {
- operator = 'contains'
- }
+ filters = JSON.parse(filtersStr)
+ } catch {
+ return undefined
+ }
- const filterObj: any = { dimension, expression: value }
- if (operator !== 'equals') {
- filterObj.operator = operator
+ if (!Array.isArray(filters) || filters.length > MAX_FILTERS) {
+ return undefined
+ }
+
+ const mappedFilters: Array<{
+ dimension: string
+ expression: string
+ operator?: string
+ }> = []
+
+ for (const filter of filters) {
+ if (typeof filter !== 'object' || filter === null) continue
+
+ const {
+ column,
+ filter: value,
+ isExclusive,
+ isContains,
+ } = filter as {
+ column?: unknown
+ filter?: unknown
+ isExclusive?: unknown
+ isContains?: unknown
+ }
+
+ if (typeof column !== 'string' || typeof value !== 'string') continue
+ 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'
+ // Normalize alpha-2 → alpha-3 for GSC
+ 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
+ }
- mappedFilters.push(filterObj)
+ let operator = 'equals'
+ if (isExclusive) {
+ operator = isContains ? 'notContains' : 'notEquals'
+ } else if (isContains) {
+ operator = 'contains'
}
- if (mappedFilters.length > 0) {
- return [{ groupType: 'and', filters: mappedFilters }]
+ const filterObj: {
+ dimension: string
+ expression: string
+ operator?: string
+ } = {
+ dimension,
+ expression,
}
- } catch {
- // Ignore parse errors
+ if (operator !== 'equals') {
+ filterObj.operator = operator
+ }
+
+ mappedFilters.push(filterObj)
+ }
+
+ if (mappedFilters.length > 0) {
+ return [{ groupType: 'and', filters: mappedFilters }]
}
+
return undefined
}
@@ -338,6 +469,10 @@ export class GSCService {
)
}
+ // ---------------------------------------------------------------------------
+ // Brand keywords
+ // ---------------------------------------------------------------------------
+
private async getProjectBrandKeywords(pid: string): Promise<string[]> {
const project = await this.projectService.findOne({
where: { id: pid },
@@ -346,26 +481,11 @@ export class GSCService {
if (!project) return []
- if (project.brandKeywords) {
- try {
- const parsed = JSON.parse(project.brandKeywords)
-
- if (Array.isArray(parsed)) {
- return Array.from(
- new Set(
- parsed
- .map((keyword) =>
- typeof keyword === 'string'
- ? keyword.toLowerCase().trim()
- : '',
- )
- .filter(Boolean),
- ),
- )
- }
- } catch {
- //
- }
+ 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>()
@@ -391,6 +511,50 @@ export class GSCService {
return Array.from(keywords)
}
+ // ---------------------------------------------------------------------------
+ // Generic GSC query helper (eliminates duplication across query methods)
+ // ---------------------------------------------------------------------------
+
+ 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)
+ }
+
+ // ---------------------------------------------------------------------------
+ // Public query methods
+ // ---------------------------------------------------------------------------
+
async getKeywords(
pid: string,
from: string,
@@ -399,6 +563,7 @@ export class GSCService {
offset = 0,
filtersStr?: string,
page?: string,
+ ctx?: GSCContext,
): Promise<
{
name: string
@@ -408,47 +573,20 @@ export class GSCService {
ctr: number
}[]
> {
- 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 auth = await this.getAuthedClientForPid(pid)
- const sc = searchconsole({ version: 'v1', auth })
-
- const startDate = dayjs(from).format('YYYY-MM-DD')
- const endDate = dayjs(to).format('YYYY-MM-DD')
-
+ const gsc = ctx || (await this.getGSCContext(pid))
const dimensionFilterGroups = this.getDimensionFilterGroups(
filtersStr,
page ? [{ dimension: 'page', expression: page }] : [],
)
try {
- const { data } = await sc.searchanalytics.query({
- siteUrl: tokens.property_uri as string,
- requestBody: {
- startDate,
- endDate,
- dimensions: ['query'],
- rowLimit: limit,
- startRow: offset,
- dataState: 'all',
- ...(dimensionFilterGroups.length > 0
- ? { dimensionFilterGroups }
- : {}),
- },
+ const rows = await this.queryGSC(gsc, from, to, {
+ dimensions: ['query'],
+ rowLimit: GSCService.clampLimit(limit, 250),
+ startRow: GSCService.clampOffset(offset),
+ dimensionFilterGroups,
})
- const rows = (data.rows || []) as Array<{
- keys: string[]
- clicks?: number
- impressions?: number
- ctr?: number
- position?: number
- }>
return rows
.map((row) => ({
name: row.keys?.[0] || '(not set)',
@@ -465,58 +603,27 @@ export class GSCService {
}
}
- private async ensurePropertyLinked(pid: string) {
- 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',
- )
- }
- return tokens
- }
-
async getSummary(
pid: string,
from: string,
to: string,
filtersStr?: string,
+ ctx?: GSCContext,
): Promise<{
clicks: number
impressions: number
ctr: number
position: number
}> {
- const tokens = await this.ensurePropertyLinked(pid)
- const auth = await this.getAuthedClientForPid(pid)
- const sc = searchconsole({ version: 'v1', auth })
-
- const startDate = dayjs(from).format('YYYY-MM-DD')
- const endDate = dayjs(to).format('YYYY-MM-DD')
-
+ const gsc = ctx || (await this.getGSCContext(pid))
const dimensionFilterGroups = this.getDimensionFilterGroups(filtersStr)
try {
- const { data } = await sc.searchanalytics.query({
- siteUrl: tokens.property_uri as string,
- requestBody: {
- startDate,
- endDate,
- dataState: 'all',
- ...(dimensionFilterGroups.length > 0
- ? { dimensionFilterGroups }
- : {}),
- },
+ const rows = await this.queryGSC(gsc, from, to, {
+ dimensionFilterGroups,
})
- const row = data.rows?.[0] as
- | {
- clicks?: number
- impressions?: number
- ctr?: number
- position?: number
- }
- | undefined
-
+ const row = rows[0]
return {
clicks: Math.round(row?.clicks || 0),
impressions: Math.round(row?.impressions || 0),
@@ -536,6 +643,7 @@ export class GSCService {
to: string,
timeBucket?: string,
filtersStr?: string,
+ ctx?: GSCContext,
): Promise<
{
date: string
@@ -545,39 +653,18 @@ export class GSCService {
position: number
}[]
> {
- const tokens = await this.ensurePropertyLinked(pid)
- const auth = await this.getAuthedClientForPid(pid)
- const sc = searchconsole({ version: 'v1', auth })
-
- const startDate = dayjs(from).format('YYYY-MM-DD')
- const endDate = dayjs(to).format('YYYY-MM-DD')
-
+ const gsc = ctx || (await this.getGSCContext(pid))
const dimensionFilterGroups = this.getDimensionFilterGroups(filtersStr)
const isHourly = timeBucket === 'hour'
try {
- const { data } = await sc.searchanalytics.query({
- siteUrl: tokens.property_uri as string,
- requestBody: {
- startDate,
- endDate,
- dimensions: isHourly ? ['HOUR'] : ['date'],
- rowLimit: 5000,
- dataState: isHourly ? 'HOURLY_ALL' : 'all',
- ...(dimensionFilterGroups.length > 0
- ? { dimensionFilterGroups }
- : {}),
- },
+ const rows = await this.queryGSC(gsc, from, to, {
+ dimensions: isHourly ? ['HOUR'] : ['date'],
+ rowLimit: 5000,
+ dataState: isHourly ? 'HOURLY_ALL' : 'all',
+ dimensionFilterGroups,
})
- const rows = (data.rows || []) as Array<{
- keys: string[]
- clicks?: number
- impressions?: number
- ctr?: number
- position?: number
- }>
-
return rows.map((row) => ({
date: row.keys?.[0]
? isHourly
@@ -604,6 +691,7 @@ export class GSCService {
offset = 0,
filtersStr?: string,
query?: string,
+ ctx?: GSCContext,
): Promise<
{
page: string
@@ -613,42 +701,20 @@ export class GSCService {
position: number
}[]
> {
- const tokens = await this.ensurePropertyLinked(pid)
- const auth = await this.getAuthedClientForPid(pid)
- const sc = searchconsole({ version: 'v1', auth })
-
- const startDate = dayjs(from).format('YYYY-MM-DD')
- const endDate = dayjs(to).format('YYYY-MM-DD')
-
+ const gsc = ctx || (await this.getGSCContext(pid))
const dimensionFilterGroups = this.getDimensionFilterGroups(
filtersStr,
query ? [{ dimension: 'query', expression: query }] : [],
)
try {
- const { data } = await sc.searchanalytics.query({
- siteUrl: tokens.property_uri as string,
- requestBody: {
- startDate,
- endDate,
- dimensions: ['page'],
- rowLimit: limit,
- startRow: offset,
- dataState: 'all',
- ...(dimensionFilterGroups.length > 0
- ? { dimensionFilterGroups }
- : {}),
- },
+ const rows = await this.queryGSC(gsc, from, to, {
+ dimensions: ['page'],
+ rowLimit: GSCService.clampLimit(limit),
+ startRow: GSCService.clampOffset(offset),
+ dimensionFilterGroups,
})
- const rows = (data.rows || []) as Array<{
- keys: string[]
- clicks?: number
- impressions?: number
- ctr?: number
- position?: number
- }>
-
return rows.map((row) => ({
page: row.keys?.[0] || '(not set)',
clicks: Math.round(row.clicks || 0),
@@ -670,6 +736,7 @@ export class GSCService {
limit = 50,
offset = 0,
filtersStr?: string,
+ ctx?: GSCContext,
): Promise<
{
country: string
@@ -679,39 +746,17 @@ export class GSCService {
position: number
}[]
> {
- const tokens = await this.ensurePropertyLinked(pid)
- const auth = await this.getAuthedClientForPid(pid)
- const sc = searchconsole({ version: 'v1', auth })
-
- const startDate = dayjs(from).format('YYYY-MM-DD')
- const endDate = dayjs(to).format('YYYY-MM-DD')
-
+ const gsc = ctx || (await this.getGSCContext(pid))
const dimensionFilterGroups = this.getDimensionFilterGroups(filtersStr)
try {
- const { data } = await sc.searchanalytics.query({
- siteUrl: tokens.property_uri as string,
- requestBody: {
- startDate,
- endDate,
- dimensions: ['country'],
- rowLimit: limit,
- startRow: offset,
- dataState: 'all',
- ...(dimensionFilterGroups.length > 0
- ? { dimensionFilterGroups }
- : {}),
- },
+ const rows = await this.queryGSC(gsc, from, to, {
+ dimensions: ['country'],
+ rowLimit: GSCService.clampLimit(limit),
+ startRow: GSCService.clampOffset(offset),
+ dimensionFilterGroups,
})
- const rows = (data.rows || []) as Array<{
- keys: string[]
- clicks?: number
- impressions?: number
- ctr?: number
- position?: number
- }>
-
return rows.map((row) => ({
country: (row.keys?.[0] || '').toLowerCase(),
clicks: Math.round(row.clicks || 0),
@@ -733,6 +778,7 @@ export class GSCService {
limit = 50,
offset = 0,
filtersStr?: string,
+ ctx?: GSCContext,
): Promise<
{
device: string
@@ -742,39 +788,17 @@ export class GSCService {
position: number
}[]
> {
- const tokens = await this.ensurePropertyLinked(pid)
- const auth = await this.getAuthedClientForPid(pid)
- const sc = searchconsole({ version: 'v1', auth })
-
- const startDate = dayjs(from).format('YYYY-MM-DD')
- const endDate = dayjs(to).format('YYYY-MM-DD')
-
+ const gsc = ctx || (await this.getGSCContext(pid))
const dimensionFilterGroups = this.getDimensionFilterGroups(filtersStr)
try {
- const { data } = await sc.searchanalytics.query({
- siteUrl: tokens.property_uri as string,
- requestBody: {
- startDate,
- endDate,
- dimensions: ['device'],
- rowLimit: limit,
- startRow: offset,
- dataState: 'all',
- ...(dimensionFilterGroups.length > 0
- ? { dimensionFilterGroups }
- : {}),
- },
+ const rows = await this.queryGSC(gsc, from, to, {
+ dimensions: ['device'],
+ rowLimit: GSCService.clampLimit(limit),
+ startRow: GSCService.clampOffset(offset),
+ dimensionFilterGroups,
})
- const rows = (data.rows || []) as Array<{
- keys: string[]
- clicks?: number
- impressions?: number
- ctr?: number
- position?: number
- }>
-
return rows.map((row) => ({
device: (row.keys?.[0] || '').toLowerCase(),
clicks: Math.round(row.clicks || 0),
@@ -794,46 +818,30 @@ export class GSCService {
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 tokens = await this.ensurePropertyLinked(pid)
- const auth = await this.getAuthedClientForPid(pid)
- const sc = searchconsole({ version: 'v1', auth })
-
- const startDate = dayjs(from).format('YYYY-MM-DD')
- const endDate = dayjs(to).format('YYYY-MM-DD')
+ const gsc = ctx || (await this.getGSCContext(pid))
const dimensionFilterGroups = this.getDimensionFilterGroups(filtersStr)
- const rowLimit = 25000
+ const rowLimit = MAX_ROW_LIMIT
let startRow = 0
let branded = 0
let nonBranded = 0
+ let pages = 0
try {
- while (true) {
- const { data } = await sc.searchanalytics.query({
- siteUrl: tokens.property_uri as string,
- requestBody: {
- startDate,
- endDate,
- dimensions: ['query'],
- rowLimit,
- startRow,
- dataState: 'all',
- ...(dimensionFilterGroups.length > 0
- ? { dimensionFilterGroups }
- : {}),
- },
+ while (pages < MAX_BRANDED_PAGES) {
+ const rows = await this.queryGSC(gsc, from, to, {
+ dimensions: ['query'],
+ rowLimit,
+ startRow,
+ dimensionFilterGroups,
})
- const rows = (data.rows || []) as Array<{
- keys: string[]
- clicks?: number
- }>
-
for (const row of rows) {
const query = (row.keys?.[0] || '').toLowerCase()
const clicks = row.clicks || 0
@@ -845,11 +853,10 @@ export class GSCService {
}
}
- if (rows.length < rowLimit) {
- break
- }
+ if (rows.length < rowLimit) break
startRow += rowLimit
+ pages++
}
return {
@@ -863,6 +870,10 @@ export class GSCService {
}
}
+ // ---------------------------------------------------------------------------
+ // Dashboard orchestrator — fetches GSC context once, passes to all sub-queries
+ // ---------------------------------------------------------------------------
+
async getDashboard(
pid: string,
from: string,
@@ -880,6 +891,13 @@ export class GSCService {
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
@@ -898,14 +916,14 @@ export class GSCService {
topDevices,
brandedTraffic,
] = await Promise.all([
- this.getSummary(pid, from, to, filtersStr),
- this.getSummary(pid, prevFrom, prevTo, filtersStr).catch(() => null),
- this.getDateSeries(pid, from, to, timeBucket, filtersStr),
- this.getTopPages(pid, from, to, 50, 0, filtersStr),
- this.getKeywords(pid, from, to, 50, 0, filtersStr),
- this.getTopCountries(pid, from, to, 50, 0, filtersStr),
- this.getTopDevices(pid, from, to, 50, 0, filtersStr),
- this.getBrandedTraffic(pid, from, to, filtersStr),
+ 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 {
diff --git a/backend/apps/cloud/src/project/project.controller.ts b/backend/apps/cloud/src/project/project.controller.ts
index c859977b6..68f49c2b8 100644
--- a/backend/apps/cloud/src/project/project.controller.ts
+++ b/backend/apps/cloud/src/project/project.controller.ts
@@ -44,6 +44,7 @@ import _find from 'lodash/find'
import dayjs from 'dayjs'
import { hash } from 'bcrypt'
+import { parseBrandKeywords } from './gsc.service'
import { Auth, Public } from '../auth/decorators'
import { isValidDate } from '../analytics/analytics.service'
import {
@@ -1819,18 +1820,7 @@ export class ProjectController {
await deleteProjectRedis(id)
const result = _omit(project, ['admin', 'passwordHash', 'share']) as any
- if (result.brandKeywords) {
- try {
- const parsed = JSON.parse(result.brandKeywords)
- result.brandKeywords =
- Array.isArray(parsed) &&
- parsed.every((item) => typeof item === 'string')
- ? parsed
- : null
- } catch {
- result.brandKeywords = null
- }
- }
+ result.brandKeywords = parseBrandKeywords(result.brandKeywords)
return result
}
@@ -1954,20 +1944,6 @@ export class ProjectController {
const isManagerRole = role === 'owner' || role === 'admin'
const isViewerRole = role === 'viewer'
- let parsedBrandKeywords: string[] | null = null
- if (project.brandKeywords) {
- try {
- const parsed = JSON.parse(project.brandKeywords)
- parsedBrandKeywords =
- Array.isArray(parsed) &&
- parsed.every((item) => typeof item === 'string')
- ? parsed
- : null
- } catch {
- parsedBrandKeywords = null
- }
- }
-
return {
..._omit(project, [
'admin',
@@ -1981,7 +1957,7 @@ export class ProjectController {
!isManagerRole && !isViewerRole && 'share',
!isManagerRole && 'captchaSecretKey',
]),
- brandKeywords: parsedBrandKeywords,
+ brandKeywords: parseBrandKeywords(project.brandKeywords),
isAccessConfirmed,
isLocked: !!project.admin?.dashboardBlockReason,
isDataExists,
diff --git a/backend/package-lock.json b/backend/package-lock.json
index a1f23a0bd..1b72ce6d6 100644
--- a/backend/package-lock.json
+++ b/backend/package-lock.json
@@ -51,6 +51,7 @@
"front-matter": "^4.0.2",
"google-auth-library": "^10.6.1",
"handlebars": "^4.7.8",
+ "i18n-iso-countries": "^7.14.0",
"ioredis": "^5.10.0",
"ip-range-check": "^0.2.0",
"isbot": "^5.1.35",
@@ -6278,6 +6279,12 @@
"license": "MIT",
"optional": true
},
+ "node_modules/diacritics": {
+ "version": "1.3.0",
+ "resolved": "https://registry.npmjs.org/diacritics/-/diacritics-1.3.0.tgz",
+ "integrity": "sha512-wlwEkqcsaxvPJML+rDh/2iS824jbREk6DUMUKkEaSlxdYHeS43cClJtsWglvw2RfeXGm6ohKDqsXteJ5sP5enA==",
+ "license": "MIT"
+ },
"node_modules/display-notification": {
"version": "2.0.0",
"resolved": "https://registry.npmjs.org/display-notification/-/display-notification-2.0.0.tgz",
@@ -7881,6 +7888,18 @@
"url": "https://opencollective.com/express"
}
},
+ "node_modules/i18n-iso-countries": {
+ "version": "7.14.0",
+ "resolved": "https://registry.npmjs.org/i18n-iso-countries/-/i18n-iso-countries-7.14.0.tgz",
+ "integrity": "sha512-nXHJZYtNrfsi1UQbyRqm3Gou431elgLjKl//CYlnBGt5aTWdRPH1PiS2T/p/n8Q8LnqYqzQJik3Q7mkwvLokeg==",
+ "license": "MIT",
+ "dependencies": {
+ "diacritics": "1.3.0"
+ },
+ "engines": {
+ "node": ">= 12"
+ }
+ },
"node_modules/iconv-lite": {
"version": "0.7.2",
"resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.7.2.tgz",
diff --git a/backend/package.json b/backend/package.json
index 4930cba5a..6af7b70fa 100644
--- a/backend/package.json
+++ b/backend/package.json
@@ -72,6 +72,7 @@
"front-matter": "^4.0.2",
"google-auth-library": "^10.6.1",
"handlebars": "^4.7.8",
+ "i18n-iso-countries": "^7.14.0",
"ioredis": "^5.10.0",
"ip-range-check": "^0.2.0",
"isbot": "^5.1.35",
diff --git a/web/app/pages/Project/tabs/SEO/CompactReferralPanel.tsx b/web/app/pages/Project/tabs/SEO/CompactReferralPanel.tsx
new file mode 100644
index 000000000..b4b6668f9
--- /dev/null
+++ b/web/app/pages/Project/tabs/SEO/CompactReferralPanel.tsx
@@ -0,0 +1,140 @@
+import _isEmpty from 'lodash/isEmpty'
+import _round from 'lodash/round'
+import React, { useMemo } from 'react'
+import { useTranslation } from 'react-i18next'
+
+import type { Entry } from '~/lib/models/Entry'
+import { Text } from '~/ui/Text'
+import { nFormatter } from '~/utils/generic'
+
+const COMPACT_MAX_ENTRIES = 10
+const COMPACT_ENTRIES_PER_COL = 5
+
+interface CompactReferralPanelProps {
+ title: string
+ data: Entry[]
+ icon: React.ReactNode
+ rowMapper: (entry: any) => React.ReactNode
+}
+
+const CompactReferralPanel = ({
+ title,
+ data,
+ icon,
+ rowMapper,
+}: CompactReferralPanelProps) => {
+ const { t } = useTranslation('common')
+ const total = useMemo(() => data.reduce((sum, e) => sum + e.count, 0), [data])
+
+ const { displayEntries, othersCount } = useMemo(() => {
+ if (data.length <= COMPACT_MAX_ENTRIES) {
+ return { displayEntries: data, othersCount: 0 }
+ }
+ const top = data.slice(0, COMPACT_MAX_ENTRIES - 1)
+ const rest = data.slice(COMPACT_MAX_ENTRIES - 1)
+ return {
+ displayEntries: top,
+ othersCount: rest.reduce((sum, e) => sum + e.count, 0),
+ }
+ }, [data])
+
+ const allRows: Array<{ entry: Entry; isOther: boolean }> = useMemo(() => {
+ const rows = displayEntries.map((e) => ({ entry: e, isOther: false }))
+ if (othersCount > 0) {
+ rows.push({
+ entry: { name: t('project.seo.others'), count: othersCount },
+ isOther: true,
+ })
+ }
+ return rows
+ }, [displayEntries, othersCount, t])
+
+ const col1 = allRows.slice(0, COMPACT_ENTRIES_PER_COL)
+ const col2 = allRows.slice(COMPACT_ENTRIES_PER_COL)
+
+ if (_isEmpty(data)) {
+ return (
+ <div className='overflow-hidden rounded-lg border border-gray-200 bg-white px-4 py-3 dark:border-slate-800/60 dark:bg-slate-900/25'>
+ <div className='flex items-center gap-1 text-gray-900 dark:text-gray-50'>
+ {icon}
+ <Text size='sm' weight='semibold'>
+ {title}
+ </Text>
+ </div>
+ <div className='flex h-32 items-center justify-center'>
+ <Text size='xs' colour='inherit'>
+ {t('project.noParamData')}
+ </Text>
+ </div>
+ </div>
+ )
+ }
+
+ const renderRow = (
+ { entry, isOther }: { entry: Entry; isOther: boolean },
+ idx: number,
+ ) => {
+ const perc = total > 0 ? _round((entry.count / total) * 100, 0) : 0
+ return (
+ <div
+ key={isOther ? 'others' : `${entry.name}-${idx}`}
+ className='group relative flex h-7 items-center justify-between rounded-sm px-1.5 hover:bg-gray-50 dark:hover:bg-slate-900/60'
+ >
+ <div
+ className='absolute inset-0 rounded-sm bg-blue-50 dark:bg-blue-900/30'
+ style={{ width: `${perc}%` }}
+ />
+ <div className='relative z-10 flex min-w-0 flex-1 items-center gap-1.5'>
+ {isOther ? (
+ <div className='size-5 shrink-0' />
+ ) : (
+ <div className='min-w-0'>{rowMapper(entry)}</div>
+ )}
+ {isOther ? (
+ <Text size='xs' colour='inherit' truncate>
+ {entry.name}
+ </Text>
+ ) : null}
+ </div>
+ <div className='relative z-10 flex min-w-fit items-center justify-end pl-2'>
+ <Text
+ size='xs'
+ colour='inherit'
+ className='mr-1.5 hidden group-hover:inline'
+ >
+ ({perc}%)
+ </Text>
+ <Text size='xs' weight='medium'>
+ {nFormatter(entry.count, 1)}
+ </Text>
+ </div>
+ </div>
+ )
+ }
+
+ return (
+ <div className='overflow-hidden rounded-lg border border-gray-200 bg-white px-4 py-3 dark:border-slate-800/60 dark:bg-slate-900/25'>
+ <div className='mb-2 flex items-center justify-between'>
+ <div className='flex items-center gap-1 text-gray-900 dark:text-gray-50'>
+ {icon}
+ <Text size='sm' weight='semibold'>
+ {title}
+ </Text>
+ </div>
+ <Text size='sm' weight='medium' className='tabular-nums'>
+ {nFormatter(total, 1)}
+ </Text>
+ </div>
+ <div className='grid grid-cols-2 gap-x-3'>
+ <div className='space-y-0.5'>
+ {col1.map((row, i) => renderRow(row, i))}
+ </div>
+ <div className='space-y-0.5'>
+ {col2.map((row, i) => renderRow(row, i + COMPACT_ENTRIES_PER_COL))}
+ </div>
+ </div>
+ </div>
+ )
+}
+
+export default CompactReferralPanel
diff --git a/web/app/pages/Project/tabs/SEO/SEOView.tsx b/web/app/pages/Project/tabs/SEO/SEOView.tsx
index 4ba73e84a..766adf0aa 100644
--- a/web/app/pages/Project/tabs/SEO/SEOView.tsx
+++ b/web/app/pages/Project/tabs/SEO/SEOView.tsx
@@ -9,12 +9,6 @@ import {
MapPinIcon,
TargetIcon,
} from '@phosphor-icons/react'
-import type { ChartOptions } from 'billboard.js'
-import { area, donut, scatter } from 'billboard.js'
-import * as d3 from 'd3'
-import dayjs from 'dayjs'
-import isoWeek from 'dayjs/plugin/isoWeek'
-import quarterOfYear from 'dayjs/plugin/quarterOfYear'
import _isEmpty from 'lodash/isEmpty'
import _round from 'lodash/round'
import React, {
@@ -28,9 +22,6 @@ import React, {
import { Trans, useTranslation } from 'react-i18next'
import { Link, useLoaderData, useSearchParams } from 'react-router'
-dayjs.extend(isoWeek)
-dayjs.extend(quarterOfYear)
-
import { useGSCDashboardProxy } from '~/hooks/useAnalyticsProxy'
import type { TimeBucket } from '~/lib/constants'
import type { Entry } from '~/lib/models/Entry'
@@ -38,7 +29,6 @@ import BillboardChart from '~/ui/BillboardChart'
import DashboardHeader from '~/pages/Project/View/components/DashboardHeader'
import { MainChart } from '~/pages/Project/View/components/MainChart'
import Filters from '~/pages/Project/View/components/Filters'
-import type { Filter } from '~/pages/Project/View/interfaces/traffic'
import { Panel, PanelContainer } from '~/pages/Project/View/Panels'
import {
useViewProjectContext,
@@ -59,275 +49,30 @@ import Dropdown from '~/ui/Dropdown'
import Loader from '~/ui/Loader'
import { Text } from '~/ui/Text'
import Tooltip from '~/ui/Tooltip'
-import { escapeHtml, nFormatter } from '~/utils/generic'
+import { nFormatter } from '~/utils/generic'
import countries from '~/utils/isoCountries'
import { getSearchEngineReferrals, getAIReferrals } from '~/utils/referrers'
import routes from '~/utils/routes'
+import CompactReferralPanel from './CompactReferralPanel'
+import {
+ SEO_METRICS,
+ type SEOMetricKey,
+ aggregateDateSeries,
+ getGSCCompatibleFilters,
+} from './seo-utils'
+import type { QuadrantData } from './seo-chart-options'
+import {
+ buildMainChartOptions,
+ buildQuadrantChartOptions,
+ buildDonutChartOptions,
+} from './seo-chart-options'
+
interface SEOViewProps {
projectId: string
tnMapping: Record<string, string>
}
-const SEO_METRICS = {
- clicks: 'clicks',
- impressions: 'impressions',
- position: 'position',
- ctr: 'ctr',
-} as const
-
-type SEOMetricKey = keyof typeof SEO_METRICS
-
-interface DateSeriesEntry {
- date: string
- clicks: number
- impressions: number
- ctr: number
- position: number
-}
-
-const getBucketKey = (date: string, bucket: string): string => {
- const d = dayjs(date)
- switch (bucket) {
- case 'hour':
- case 'day':
- return date
- case 'week':
- return d.startOf('isoWeek').format('YYYY-MM-DD')
- case 'month':
- return d.startOf('month').format('YYYY-MM-DD')
- case 'quarter':
- return d.startOf('quarter').format('YYYY-MM-DD')
- case 'year':
- return d.startOf('year').format('YYYY-MM-DD')
- default:
- return date
- }
-}
-
-const aggregateDateSeries = (
- series: DateSeriesEntry[],
- bucket: string,
-): DateSeriesEntry[] => {
- if (!series.length || bucket === 'day' || bucket === 'hour') return series
-
- const buckets = new Map<
- string,
- {
- clicks: number
- impressions: number
- weightedPosition: number
- }
- >()
- const orderedKeys: string[] = []
-
- for (const entry of series) {
- const key = getBucketKey(entry.date, bucket)
- const existing = buckets.get(key)
- if (existing) {
- existing.clicks += entry.clicks
- existing.impressions += entry.impressions
- existing.weightedPosition += entry.position * entry.impressions
- } else {
- orderedKeys.push(key)
- buckets.set(key, {
- clicks: entry.clicks,
- impressions: entry.impressions,
- weightedPosition: entry.position * entry.impressions,
- })
- }
- }
-
- return orderedKeys.map((key) => {
- const b = buckets.get(key)!
- return {
- date: key,
- clicks: b.clicks,
- impressions: b.impressions,
- ctr:
- b.impressions > 0
- ? Number(((b.clicks / b.impressions) * 100).toFixed(2))
- : 0,
- position:
- b.impressions > 0
- ? Number((b.weightedPosition / b.impressions).toFixed(1))
- : 0,
- }
- })
-}
-
-const getGSCCompatibleFilters = (filters: Filter[]): Filter[] => {
- return filters.flatMap((filter) => {
- if (filter.column === 'cc') {
- const alpha3 = countries.alpha2ToAlpha3(filter.filter.toUpperCase())
- if (!alpha3) return []
-
- return [
- {
- ...filter,
- column: 'country',
- filter: alpha3.toLowerCase(),
- },
- ]
- }
-
- if (filter.column === 'dv') {
- return [
- {
- ...filter,
- column: 'device',
- filter: filter.filter.toLowerCase(),
- },
- ]
- }
-
- if (filter.column === 'country' || filter.column === 'device') {
- return [
- {
- ...filter,
- filter: filter.filter.toLowerCase(),
- },
- ]
- }
-
- if (filter.column === 'pg' || filter.column === 'keywords') {
- return [filter]
- }
-
- return []
- })
-}
-
-const COMPACT_MAX_ENTRIES = 10
-const COMPACT_ENTRIES_PER_COL = 5
-
-interface CompactReferralPanelProps {
- title: string
- data: Entry[]
- icon: React.ReactNode
- rowMapper: (entry: any) => React.ReactNode
-}
-
-const CompactReferralPanel = ({
- title,
- data,
- icon,
- rowMapper,
-}: CompactReferralPanelProps) => {
- const { t } = useTranslation('common')
- const total = useMemo(() => data.reduce((sum, e) => sum + e.count, 0), [data])
-
- const { displayEntries, othersCount } = useMemo(() => {
- if (data.length <= COMPACT_MAX_ENTRIES) {
- return { displayEntries: data, othersCount: 0 }
- }
- const top = data.slice(0, COMPACT_MAX_ENTRIES - 1)
- const rest = data.slice(COMPACT_MAX_ENTRIES - 1)
- return {
- displayEntries: top,
- othersCount: rest.reduce((sum, e) => sum + e.count, 0),
- }
- }, [data])
-
- const allRows: Array<{ entry: Entry; isOther: boolean }> = useMemo(() => {
- const rows = displayEntries.map((e) => ({ entry: e, isOther: false }))
- if (othersCount > 0) {
- rows.push({
- entry: { name: t('project.seo.others'), count: othersCount },
- isOther: true,
- })
- }
- return rows
- }, [displayEntries, othersCount, t])
-
- const col1 = allRows.slice(0, COMPACT_ENTRIES_PER_COL)
- const col2 = allRows.slice(COMPACT_ENTRIES_PER_COL)
-
- if (_isEmpty(data)) {
- return (
- <div className='overflow-hidden rounded-lg border border-gray-200 bg-white px-4 py-3 dark:border-slate-800/60 dark:bg-slate-900/25'>
- <div className='flex items-center gap-1 text-gray-900 dark:text-gray-50'>
- {icon}
- <Text size='sm' weight='semibold'>
- {title}
- </Text>
- </div>
- <div className='flex h-32 items-center justify-center'>
- <Text size='xs' colour='inherit'>
- {t('project.noParamData')}
- </Text>
- </div>
- </div>
- )
- }
-
- const renderRow = (
- { entry, isOther }: { entry: Entry; isOther: boolean },
- idx: number,
- ) => {
- const perc = total > 0 ? _round((entry.count / total) * 100, 0) : 0
- return (
- <div
- key={isOther ? 'others' : `${entry.name}-${idx}`}
- className='group relative flex h-7 items-center justify-between rounded-sm px-1.5 hover:bg-gray-50 dark:hover:bg-slate-900/60'
- >
- <div
- className='absolute inset-0 rounded-sm bg-blue-50 dark:bg-blue-900/30'
- style={{ width: `${perc}%` }}
- />
- <div className='relative z-10 flex min-w-0 flex-1 items-center gap-1.5'>
- {isOther ? (
- <div className='size-5 shrink-0' />
- ) : (
- <div className='min-w-0'>{rowMapper(entry)}</div>
- )}
- {isOther ? (
- <Text size='xs' colour='inherit' truncate>
- {entry.name}
- </Text>
- ) : null}
- </div>
- <div className='relative z-10 flex min-w-fit items-center justify-end pl-2'>
- <Text
- size='xs'
- colour='inherit'
- className='mr-1.5 hidden group-hover:inline'
- >
- ({perc}%)
- </Text>
- <Text size='xs' weight='medium'>
- {nFormatter(entry.count, 1)}
- </Text>
- </div>
- </div>
- )
- }
-
- return (
- <div className='overflow-hidden rounded-lg border border-gray-200 bg-white px-4 py-3 dark:border-slate-800/60 dark:bg-slate-900/25'>
- <div className='mb-2 flex items-center justify-between'>
- <div className='flex items-center gap-1 text-gray-900 dark:text-gray-50'>
- {icon}
- <Text size='sm' weight='semibold'>
- {title}
- </Text>
- </div>
- <Text size='sm' weight='medium' className='tabular-nums'>
- {nFormatter(total, 1)}
- </Text>
- </div>
- <div className='grid grid-cols-2 gap-x-3'>
- <div className='space-y-0.5'>
- {col1.map((row, i) => renderRow(row, i))}
- </div>
- <div className='space-y-0.5'>
- {col2.map((row, i) => renderRow(row, i + COMPACT_ENTRIES_PER_COL))}
- </div>
- </div>
- </div>
- )
-}
-
const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {
const {
t,
@@ -573,54 +318,16 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {
[data?.brandedTraffic],
)
- const donutChartOptions: ChartOptions = useMemo(() => {
- const total = brandedTraffic.branded + brandedTraffic.nonBranded
- if (total === 0) return {}
-
- const brandedLabel = t('project.seo.branded')
- const nonBrandedLabel = t('project.seo.nonBranded')
-
- return {
- data: {
- columns: [
- [brandedLabel, brandedTraffic.branded],
- [nonBrandedLabel, brandedTraffic.nonBranded],
- ],
- type: donut(),
- colors: {
- [brandedLabel]: theme === 'dark' ? '#818cf8' : '#6366f1',
- [nonBrandedLabel]: theme === 'dark' ? '#475569' : '#94a3b8',
- },
- },
- donut: {
- title: `${total > 0 ? _round((brandedTraffic.branded / total) * 100, 0) : 0}%`,
- label: {
- show: false,
- },
- width: 16,
- },
- transition: { duration: 200 },
- resize: { auto: true },
- legend: {
- show: true,
- position: 'bottom',
- item: {
- tile: { type: 'circle', width: 8, r: 4 },
- },
- },
- tooltip: {
- format: {
- value: (value: number, ratio: number) => {
- const pct = (ratio * 100).toFixed(1)
- return `${nFormatter(value, 1)} (${pct}%)`
- },
- },
- },
- size: {
- height: 180,
- },
- }
- }, [brandedTraffic, t, theme])
+ const donutChartOptions = useMemo(
+ () =>
+ buildDonutChartOptions(
+ brandedTraffic.branded,
+ brandedTraffic.nonBranded,
+ theme,
+ t,
+ ),
+ [brandedTraffic, t, theme],
+ )
const countryRowMapper = useCallback(
(entry: any) => <CCRow cc={entry.name} language={language} />,
@@ -634,12 +341,12 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {
const anyMetricActive = Object.values(activeMetrics).some(Boolean)
- const quadrantData = useMemo(() => {
+ const quadrantData: QuadrantData | null = useMemo(() => {
if (!topQueriesAsEntries.length) return null
const positions = topQueriesAsEntries.map((q) => q.position)
const ctrs = topQueriesAsEntries.map((q) => q.ctr)
const impressions = topQueriesAsEntries.map((q) => q.impressions)
- const names = topQueriesAsEntries.map((q) => q.name)
+ const names = topQueriesAsEntries.map((q) => q.name ?? '')
const maxImp = Math.max(...impressions) || 1
const minImp = Math.min(...impressions) || 0
@@ -647,271 +354,17 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {
return { positions, ctrs, impressions, names, maxImp, minImp }
}, [topQueriesAsEntries])
- const quadrantChartOptions: ChartOptions = useMemo(() => {
+ const quadrantChartOptions = useMemo(() => {
if (!quadrantData) return {}
-
- const { positions, ctrs, impressions, names, maxImp } = quadrantData
const avgCtr = data?.summary?.ctr ?? 5
const avgPos = data?.summary?.position ?? 10
-
- return {
- data: {
- x: 'x',
- columns: [
- ['x', ...positions],
- ['CTR', ...ctrs],
- ],
- type: scatter(),
- colors: {
- CTR: theme === 'dark' ? '#818cf8' : '#6366f1',
- },
- },
- axis: {
- x: {
- min: 0,
- label: {
- text: t('project.seo.avgPosition'),
- position: 'outer-center',
- },
- tick: {
- fit: false,
- format: (d: number) => Number(d).toFixed(0),
- },
- },
- y: {
- min: 0,
- max: 100,
- padding: { top: 0, bottom: 0 },
- label: { text: t('project.seo.avgCTR'), position: 'outer-middle' },
- tick: {
- format: (d: number) => `${d}%`,
- },
- },
- },
- point: {
- r: (d: any) => {
- if (!d || d.index === undefined) return 4
- const imp = impressions[d.index]
- if (!imp) return 4
- return 4 + 16 * Math.sqrt(imp / maxImp)
- },
- },
- grid: {
- x: {
- lines: [
- {
- value: avgPos,
- text: `${t('project.seo.avgPosition')}: ${avgPos.toFixed(1)}`,
- position: 'start',
- class: 'annotation-line',
- },
- ],
- },
- y: {
- lines: [
- {
- value: avgCtr,
- text: `${t('project.seo.avgCTR')}: ${avgCtr.toFixed(1)}%`,
- position: 'start',
- class: 'annotation-line',
- },
- ],
- },
- },
- tooltip: {
- contents: (items: any) => {
- const d = items[0]
- const name = names[d.index]
- const imp = impressions[d.index]
-
- return `<ul class='bg-gray-50 dark:text-gray-50 dark:bg-slate-900 rounded-md ring-1 ring-black/10 px-2 py-1 text-xs md:text-sm shadow-md z-50'>
- <li class='font-semibold pb-1 mb-1 border-b border-gray-200 dark:border-slate-800 break-all'>${escapeHtml(name ?? '')}</li>
- <li class='flex justify-between items-center py-px leading-snug'>
- <span class='mr-4'>${t('project.seo.position')}:</span>
- <span class='font-mono whitespace-nowrap'>${d.x.toFixed(1)}</span>
- </li>
- <li class='flex justify-between items-center py-px leading-snug'>
- <span class='mr-4'>${t('project.seo.ctr')}:</span>
- <span class='font-mono whitespace-nowrap'>${d.value.toFixed(1)}%</span>
- </li>
- <li class='flex justify-between items-center py-px leading-snug'>
- <span class='mr-4'>${t('project.seo.impressions')}:</span>
- <span class='font-mono whitespace-nowrap'>${nFormatter(imp, 1)}</span>
- </li>
- </ul>`
- },
- },
- legend: {
- show: false,
- },
- transition: {
- duration: 200,
- },
- }
+ return buildQuadrantChartOptions(quadrantData, avgCtr, avgPos, theme, t)
}, [quadrantData, data?.summary, theme, t])
- const chartOptions: ChartOptions = useMemo(() => {
- if (!aggregatedSeries.length) return {}
-
- const dates = aggregatedSeries.map((d) => d.date)
- const columns: any[] = [['x', ...dates]]
- const colors: Record<string, string> = {}
- const axes: Record<string, string> = {}
- let needsY2 = false
-
- if (activeMetrics.clicks) {
- const label = t('project.seo.clicks')
- columns.push([label, ...aggregatedSeries.map((d) => d.clicks)])
- colors[label] = '#3b82f6' // blue-500 - matching GSC
- }
-
- if (activeMetrics.impressions) {
- const label = t('project.seo.impressions')
- columns.push([label, ...aggregatedSeries.map((d) => d.impressions)])
- colors[label] = '#5b21b6' // violet-800 - matching GSC
- if (activeMetrics.clicks) {
- axes[label] = 'y2'
- needsY2 = true
- }
- }
-
- if (activeMetrics.position) {
- const label = t('project.seo.avgPosition')
- columns.push([label, ...aggregatedSeries.map((d) => d.position)])
- colors[label] = '#d97706' // amber-600 - matching GSC
- if (activeMetrics.clicks || activeMetrics.impressions) {
- axes[label] = 'y2'
- needsY2 = true
- }
- }
-
- if (activeMetrics.ctr) {
- const label = t('project.seo.avgCTR')
- columns.push([label, ...aggregatedSeries.map((d) => d.ctr)])
- colors[label] = '#0d9488' // teal-600 - matching GSC
- if (activeMetrics.clicks || activeMetrics.impressions) {
- axes[label] = 'y2'
- needsY2 = true
- }
- }
-
- const tickFormatMap: Record<string, string> = {
- hour: '%b %d %H:%M',
- day: '%b %d',
- week: '%b %d',
- month: '%b %Y',
- quarter: '%b %Y',
- year: '%Y',
- }
- const tickFormat = tickFormatMap[timeBucket] || '%b %d'
-
- return {
- data: {
- x: 'x',
- xFormat: timeBucket === 'hour' ? '%Y-%m-%d %H:%M:%S' : '%Y-%m-%d',
- columns,
- type: area(),
- axes,
- colors,
- },
- area: {
- linearGradient: true,
- },
- transition: {
- duration: 200,
- },
- resize: {
- auto: true,
- timer: false,
- },
- axis: {
- x: {
- clipPath: false,
- type: 'timeseries',
- tick: {
- fit: true,
- format: tickFormat,
- rotate: 0,
- },
- },
- y: {
- tick: {
- format: (d: number) => nFormatter(d, 1),
- },
- show: true,
- inner: true,
- min: 0,
- padding: { bottom: 0 },
- },
- y2: {
- show: needsY2,
- tick: {
- format: (d: number) => nFormatter(d, 1),
- },
- inner: true,
- min: 0,
- padding: { bottom: 0 },
- },
- },
- point: {
- focus: {
- only: dates.length > 1,
- },
- pattern: ['circle'],
- r: 2,
- },
- grid: {
- y: {
- show: true,
- },
- },
- legend: {
- item: {
- tile: {
- type: 'circle',
- width: 10,
- r: 3,
- },
- },
- },
- tooltip: {
- contents: (items, _defaultTitleFormat, _defaultValueFormat, color) => {
- const tooltipFormatMap: Record<string, string> = {
- hour: '%b %d, %Y %H:%M',
- day: '%b %d, %Y',
- week: 'Week of %b %d, %Y',
- month: '%B %Y',
- quarter: '%B %Y',
- year: '%Y',
- }
- const tooltipFmt = tooltipFormatMap[timeBucket] || '%b %d, %Y'
- const headerLabel = d3.timeFormat(tooltipFmt)(items[0].x)
- return `<ul class='bg-gray-50 dark:text-gray-50 dark:bg-slate-900 rounded-md ring-1 ring-black/10 px-2 py-1 text-xs md:text-sm max-h-[250px] md:max-h-[350px] overflow-y-auto shadow-md z-50'>
- <li class='font-semibold pb-1 mb-1 border-b border-gray-200 dark:border-slate-800 sticky top-0 bg-gray-50 dark:bg-slate-900'>${headerLabel}</li>
- ${items
- .map((el: any) => {
- const isCtr = el.name === t('project.seo.avgCTR')
- const isPos = el.name === t('project.seo.avgPosition')
- let formatted = nFormatter(el.value, 1)
- if (isCtr) formatted = `${Number(el.value).toFixed(1)}%`
- else if (isPos) formatted = Number(el.value).toFixed(1)
-
- return `
- <li class='flex justify-between items-center py-px leading-snug'>
- <div class='flex items-center min-w-0 mr-4'>
- <div class='w-2.5 h-2.5 rounded-xs mr-1.5 shrink-0' style=background-color:${color(el.id)}></div>
- <span class="truncate">${el.name}</span>
- </div>
- <span class='font-mono whitespace-nowrap'>${formatted}</span>
- </li>`
- })
- .join('')}
- </ul>`
- },
- },
- padding: { right: needsY2 ? 20 : undefined },
- }
- }, [aggregatedSeries, activeMetrics, timeBucket, t])
+ const chartOptions = useMemo(
+ () => buildMainChartOptions(aggregatedSeries, activeMetrics, timeBucket, t),
+ [aggregatedSeries, activeMetrics, timeBucket, t],
+ )
const detailsExtraColumns = useMemo(
() => [
diff --git a/web/app/pages/Project/tabs/SEO/seo-chart-options.ts b/web/app/pages/Project/tabs/SEO/seo-chart-options.ts
new file mode 100644
index 000000000..fe0dfc1f7
--- /dev/null
+++ b/web/app/pages/Project/tabs/SEO/seo-chart-options.ts
@@ -0,0 +1,356 @@
+import type { ChartOptions } from 'billboard.js'
+import { area, donut, scatter } from 'billboard.js'
+import * as d3 from 'd3'
+import _round from 'lodash/round'
+import type { TFunction } from 'i18next'
+
+import { escapeHtml, nFormatter } from '~/utils/generic'
+import type { DateSeriesEntry, SEOMetricKey } from './seo-utils'
+
+// ---------------------------------------------------------------------------
+// Main time-series chart
+// ---------------------------------------------------------------------------
+
+export function buildMainChartOptions(
+ series: DateSeriesEntry[],
+ activeMetrics: Record<SEOMetricKey, boolean>,
+ timeBucket: string,
+ t: TFunction,
+): ChartOptions {
+ if (!series.length) return {}
+
+ const dates = series.map((d) => d.date)
+ const columns: any[] = [['x', ...dates]]
+ const colors: Record<string, string> = {}
+ const axes: Record<string, string> = {}
+ let needsY2 = false
+
+ if (activeMetrics.clicks) {
+ const label = t('project.seo.clicks')
+ columns.push([label, ...series.map((d) => d.clicks)])
+ colors[label] = '#3b82f6'
+ }
+
+ if (activeMetrics.impressions) {
+ const label = t('project.seo.impressions')
+ columns.push([label, ...series.map((d) => d.impressions)])
+ colors[label] = '#5b21b6'
+ if (activeMetrics.clicks) {
+ axes[label] = 'y2'
+ needsY2 = true
+ }
+ }
+
+ if (activeMetrics.position) {
+ const label = t('project.seo.avgPosition')
+ columns.push([label, ...series.map((d) => d.position)])
+ colors[label] = '#d97706'
+ if (activeMetrics.clicks || activeMetrics.impressions) {
+ axes[label] = 'y2'
+ needsY2 = true
+ }
+ }
+
+ if (activeMetrics.ctr) {
+ const label = t('project.seo.avgCTR')
+ columns.push([label, ...series.map((d) => d.ctr)])
+ colors[label] = '#0d9488'
+ if (activeMetrics.clicks || activeMetrics.impressions) {
+ axes[label] = 'y2'
+ needsY2 = true
+ }
+ }
+
+ const tickFormatMap: Record<string, string> = {
+ hour: '%b %d %H:%M',
+ day: '%b %d',
+ week: '%b %d',
+ month: '%b %Y',
+ quarter: '%b %Y',
+ year: '%Y',
+ }
+ const tickFormat = tickFormatMap[timeBucket] || '%b %d'
+
+ return {
+ data: {
+ x: 'x',
+ xFormat: timeBucket === 'hour' ? '%Y-%m-%d %H:%M:%S' : '%Y-%m-%d',
+ columns,
+ type: area(),
+ axes,
+ colors,
+ },
+ area: {
+ linearGradient: true,
+ },
+ transition: {
+ duration: 200,
+ },
+ resize: {
+ auto: true,
+ timer: false,
+ },
+ axis: {
+ x: {
+ clipPath: false,
+ type: 'timeseries',
+ tick: {
+ fit: true,
+ format: tickFormat,
+ rotate: 0,
+ },
+ },
+ y: {
+ tick: {
+ format: (d: number) => nFormatter(d, 1),
+ },
+ show: true,
+ inner: true,
+ min: 0,
+ padding: { bottom: 0 },
+ },
+ y2: {
+ show: needsY2,
+ tick: {
+ format: (d: number) => nFormatter(d, 1),
+ },
+ inner: true,
+ min: 0,
+ padding: { bottom: 0 },
+ },
+ },
+ point: {
+ focus: {
+ only: dates.length > 1,
+ },
+ pattern: ['circle'],
+ r: 2,
+ },
+ grid: {
+ y: {
+ show: true,
+ },
+ },
+ legend: {
+ item: {
+ tile: {
+ type: 'circle',
+ width: 10,
+ r: 3,
+ },
+ },
+ },
+ tooltip: {
+ contents: (items, _defaultTitleFormat, _defaultValueFormat, color) => {
+ const tooltipFormatMap: Record<string, string> = {
+ hour: '%b %d, %Y %H:%M',
+ day: '%b %d, %Y',
+ week: 'Week of %b %d, %Y',
+ month: '%B %Y',
+ quarter: '%B %Y',
+ year: '%Y',
+ }
+ const tooltipFmt = tooltipFormatMap[timeBucket] || '%b %d, %Y'
+ const headerLabel = d3.timeFormat(tooltipFmt)(items[0].x)
+ return `<ul class='bg-gray-50 dark:text-gray-50 dark:bg-slate-900 rounded-md ring-1 ring-black/10 px-2 py-1 text-xs md:text-sm max-h-[250px] md:max-h-[350px] overflow-y-auto shadow-md z-50'>
+ <li class='font-semibold pb-1 mb-1 border-b border-gray-200 dark:border-slate-800 sticky top-0 bg-gray-50 dark:bg-slate-900'>${headerLabel}</li>
+ ${items
+ .map((el: any) => {
+ const isCtr = el.name === t('project.seo.avgCTR')
+ const isPos = el.name === t('project.seo.avgPosition')
+ let formatted = nFormatter(el.value, 1)
+ if (isCtr) formatted = `${Number(el.value).toFixed(1)}%`
+ else if (isPos) formatted = Number(el.value).toFixed(1)
+
+ return `
+ <li class='flex justify-between items-center py-px leading-snug'>
+ <div class='flex items-center min-w-0 mr-4'>
+ <div class='w-2.5 h-2.5 rounded-xs mr-1.5 shrink-0' style=background-color:${color(el.id)}></div>
+ <span class="truncate">${el.name}</span>
+ </div>
+ <span class='font-mono whitespace-nowrap'>${formatted}</span>
+ </li>`
+ })
+ .join('')}
+ </ul>`
+ },
+ },
+ padding: { right: needsY2 ? 20 : undefined },
+ }
+}
+
+// ---------------------------------------------------------------------------
+// Quadrant scatter chart
+// ---------------------------------------------------------------------------
+
+export interface QuadrantData {
+ positions: number[]
+ ctrs: number[]
+ impressions: number[]
+ names: string[]
+ maxImp: number
+ minImp: number
+}
+
+export function buildQuadrantChartOptions(
+ qd: QuadrantData,
+ avgCtr: number,
+ avgPos: number,
+ theme: string,
+ t: TFunction,
+): ChartOptions {
+ const { positions, ctrs, impressions, names, maxImp } = qd
+
+ return {
+ data: {
+ x: 'x',
+ columns: [
+ ['x', ...positions],
+ ['CTR', ...ctrs],
+ ],
+ type: scatter(),
+ colors: {
+ CTR: theme === 'dark' ? '#818cf8' : '#6366f1',
+ },
+ },
+ axis: {
+ x: {
+ min: 0,
+ label: {
+ text: t('project.seo.avgPosition'),
+ position: 'outer-center',
+ },
+ tick: {
+ fit: false,
+ format: (d: number) => Number(d).toFixed(0),
+ },
+ },
+ y: {
+ min: 0,
+ max: 100,
+ padding: { top: 0, bottom: 0 },
+ label: { text: t('project.seo.avgCTR'), position: 'outer-middle' },
+ tick: {
+ format: (d: number) => `${d}%`,
+ },
+ },
+ },
+ point: {
+ r: (d: any) => {
+ if (!d || d.index === undefined) return 4
+ const imp = impressions[d.index]
+ if (!imp) return 4
+ return 4 + 16 * Math.sqrt(imp / maxImp)
+ },
+ },
+ grid: {
+ x: {
+ lines: [
+ {
+ value: avgPos,
+ text: `${t('project.seo.avgPosition')}: ${avgPos.toFixed(1)}`,
+ position: 'start',
+ class: 'annotation-line',
+ },
+ ],
+ },
+ y: {
+ lines: [
+ {
+ value: avgCtr,
+ text: `${t('project.seo.avgCTR')}: ${avgCtr.toFixed(1)}%`,
+ position: 'start',
+ class: 'annotation-line',
+ },
+ ],
+ },
+ },
+ tooltip: {
+ contents: (items: any) => {
+ const d = items[0]
+ const name = names[d.index]
+ const imp = impressions[d.index]
+
+ return `<ul class='bg-gray-50 dark:text-gray-50 dark:bg-slate-900 rounded-md ring-1 ring-black/10 px-2 py-1 text-xs md:text-sm shadow-md z-50'>
+ <li class='font-semibold pb-1 mb-1 border-b border-gray-200 dark:border-slate-800 break-all'>${escapeHtml(name ?? '')}</li>
+ <li class='flex justify-between items-center py-px leading-snug'>
+ <span class='mr-4'>${t('project.seo.position')}:</span>
+ <span class='font-mono whitespace-nowrap'>${d.x.toFixed(1)}</span>
+ </li>
+ <li class='flex justify-between items-center py-px leading-snug'>
+ <span class='mr-4'>${t('project.seo.ctr')}:</span>
+ <span class='font-mono whitespace-nowrap'>${d.value.toFixed(1)}%</span>
+ </li>
+ <li class='flex justify-between items-center py-px leading-snug'>
+ <span class='mr-4'>${t('project.seo.impressions')}:</span>
+ <span class='font-mono whitespace-nowrap'>${nFormatter(imp, 1)}</span>
+ </li>
+ </ul>`
+ },
+ },
+ legend: {
+ show: false,
+ },
+ transition: {
+ duration: 200,
+ },
+ }
+}
+
+// ---------------------------------------------------------------------------
+// Branded traffic donut chart
+// ---------------------------------------------------------------------------
+
+export function buildDonutChartOptions(
+ branded: number,
+ nonBranded: number,
+ theme: string,
+ t: TFunction,
+): ChartOptions {
+ const total = branded + nonBranded
+ if (total === 0) return {}
+
+ const brandedLabel = t('project.seo.branded')
+ const nonBrandedLabel = t('project.seo.nonBranded')
+
+ return {
+ data: {
+ columns: [
+ [brandedLabel, branded],
+ [nonBrandedLabel, nonBranded],
+ ],
+ type: donut(),
+ colors: {
+ [brandedLabel]: theme === 'dark' ? '#818cf8' : '#6366f1',
+ [nonBrandedLabel]: theme === 'dark' ? '#475569' : '#94a3b8',
+ },
+ },
+ donut: {
+ title: `${total > 0 ? _round((branded / total) * 100, 0) : 0}%`,
+ label: {
+ show: false,
+ },
+ width: 16,
+ },
+ transition: { duration: 200 },
+ resize: { auto: true },
+ legend: {
+ show: true,
+ position: 'bottom',
+ item: {
+ tile: { type: 'circle', width: 8, r: 4 },
+ },
+ },
+ tooltip: {
+ format: {
+ value: (value: number, ratio: number) => {
+ const pct = (ratio * 100).toFixed(1)
+ return `${nFormatter(value, 1)} (${pct}%)`
+ },
+ },
+ },
+ size: {
+ height: 180,
+ },
+ }
+}
diff --git a/web/app/pages/Project/tabs/SEO/seo-utils.ts b/web/app/pages/Project/tabs/SEO/seo-utils.ts
new file mode 100644
index 000000000..27b613091
--- /dev/null
+++ b/web/app/pages/Project/tabs/SEO/seo-utils.ts
@@ -0,0 +1,115 @@
+import dayjs from 'dayjs'
+import isoWeek from 'dayjs/plugin/isoWeek'
+import quarterOfYear from 'dayjs/plugin/quarterOfYear'
+import type { Filter } from '~/pages/Project/View/interfaces/traffic'
+
+dayjs.extend(isoWeek)
+dayjs.extend(quarterOfYear)
+
+export const SEO_METRICS = {
+ clicks: 'clicks',
+ impressions: 'impressions',
+ position: 'position',
+ ctr: 'ctr',
+} as const
+
+export type SEOMetricKey = keyof typeof SEO_METRICS
+
+export interface DateSeriesEntry {
+ date: string
+ clicks: number
+ impressions: number
+ ctr: number
+ position: number
+}
+
+const getBucketKey = (date: string, bucket: string): string => {
+ const d = dayjs(date)
+ switch (bucket) {
+ case 'hour':
+ case 'day':
+ return date
+ case 'week':
+ return d.startOf('isoWeek').format('YYYY-MM-DD')
+ case 'month':
+ return d.startOf('month').format('YYYY-MM-DD')
+ case 'quarter':
+ return d.startOf('quarter').format('YYYY-MM-DD')
+ case 'year':
+ return d.startOf('year').format('YYYY-MM-DD')
+ default:
+ return date
+ }
+}
+
+export const aggregateDateSeries = (
+ series: DateSeriesEntry[],
+ bucket: string,
+): DateSeriesEntry[] => {
+ if (!series.length || bucket === 'day' || bucket === 'hour') return series
+
+ const buckets = new Map<
+ string,
+ {
+ clicks: number
+ impressions: number
+ weightedPosition: number
+ }
+ >()
+ const orderedKeys: string[] = []
+
+ for (const entry of series) {
+ const key = getBucketKey(entry.date, bucket)
+ const existing = buckets.get(key)
+ if (existing) {
+ existing.clicks += entry.clicks
+ existing.impressions += entry.impressions
+ existing.weightedPosition += entry.position * entry.impressions
+ } else {
+ orderedKeys.push(key)
+ buckets.set(key, {
+ clicks: entry.clicks,
+ impressions: entry.impressions,
+ weightedPosition: entry.position * entry.impressions,
+ })
+ }
+ }
+
+ return orderedKeys.map((key) => {
+ const b = buckets.get(key)!
+ return {
+ date: key,
+ clicks: b.clicks,
+ impressions: b.impressions,
+ ctr:
+ b.impressions > 0
+ ? Number(((b.clicks / b.impressions) * 100).toFixed(2))
+ : 0,
+ position:
+ b.impressions > 0
+ ? Number((b.weightedPosition / b.impressions).toFixed(1))
+ : 0,
+ }
+ })
+}
+
+/**
+ * Filters that the backend's GSC parseFilters can handle.
+ * Country code conversion (alpha-2 → alpha-3) is now done server-side.
+ */
+export const getGSCCompatibleFilters = (filters: Filter[]): Filter[] => {
+ return filters.flatMap((filter) => {
+ if (
+ filter.column === 'pg' ||
+ filter.column === 'keywords' ||
+ filter.column === 'cc' ||
+ filter.column === 'country' ||
+ filter.column === 'dv' ||
+ filter.column === 'device'
+ ) {
+ return [filter]
+ }
+
+ return []
+ })
+}