Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(web-analytics): score page health for page reports (#123507)

Jordan Mryyana62c5ec54a4e
diff --git a/products/web_analytics/frontend/pageReports/PageHealthCard.tsx b/products/web_analytics/frontend/pageReports/PageHealthCard.tsx
new file mode 100644
index 000000000000..3a09d2e52b77
--- /dev/null
+++ b/products/web_analytics/frontend/pageReports/PageHealthCard.tsx
@@ -0,0 +1,52 @@
+import clsx from 'clsx'
+
+import { PAGE_HEALTH_STATUS_LABEL, PageHealthStatus, PageHealthSummary } from './pageHealth'
+import { PageStatCard } from './PageStatCard'
+
+const STATUS_DOT: Record<PageHealthStatus, string | null> = {
+ loading: null,
+ strong: 'bg-success',
+ fair: 'bg-[var(--color-text-tertiary)]',
+ needs_attention: 'bg-warning',
+ not_found: 'bg-danger',
+ no_data: null,
+ not_set_up: null,
+}
+
+export interface PageHealthCardProps {
+ card: PageHealthSummary
+ onClick: () => void
+ onHover: () => void
+}
+
+export function PageHealthCard({ card, onClick, onHover }: PageHealthCardProps): JSX.Element {
+ const tooltip =
+ card.reasons.length > 0 ? (
+ <ul className="m-0 pl-4 flex flex-col gap-1">
+ {card.reasons.map((reason) => (
+ <li key={reason}>{reason}</li>
+ ))}
+ </ul>
+ ) : null
+
+ return (
+ <PageStatCard
+ label={card.title}
+ aside={
+ <span className="inline-flex items-center gap-1.5 text-xs text-secondary whitespace-nowrap">
+ {STATUS_DOT[card.status] ? (
+ <span className={clsx('size-1.5 rounded-full', STATUS_DOT[card.status])} aria-hidden />
+ ) : null}
+ <span>{PAGE_HEALTH_STATUS_LABEL[card.status]}</span>
+ </span>
+ }
+ value={card.value ?? <span className="text-secondary">-</span>}
+ detail={card.value ? card.detail : card.headline}
+ loading={card.status === 'loading'}
+ tooltip={tooltip}
+ onClick={onClick}
+ onHover={onHover}
+ data-attr={`page-report-health-card-${card.key}`}
+ />
+ )
+}
diff --git a/products/web_analytics/frontend/pageReports/PageStatCard.tsx b/products/web_analytics/frontend/pageReports/PageStatCard.tsx
new file mode 100644
index 000000000000..29fe7c1f204f
--- /dev/null
+++ b/products/web_analytics/frontend/pageReports/PageStatCard.tsx
@@ -0,0 +1,61 @@
+import { LemonSkeleton, Tooltip } from '@posthog/lemon-ui'
+
+export interface PageStatCardProps {
+ label: string
+ aside?: React.ReactNode
+ value: React.ReactNode
+ detail: React.ReactNode
+ loading: boolean
+ tooltip?: React.ReactNode
+ onClick: () => void
+ onHover?: () => void
+ 'data-attr': string
+}
+
+export function PageStatCard({
+ label,
+ aside,
+ value,
+ detail,
+ loading,
+ tooltip,
+ onClick,
+ onHover,
+ 'data-attr': dataAttr,
+}: PageStatCardProps): JSX.Element {
+ const card = (
+ <button
+ type="button"
+ className="text-left px-4 py-3 flex flex-col gap-0.5 min-w-0 cursor-pointer hover:bg-fill-highlight-50 focus-visible:outline-2 focus-visible:-outline-offset-2 transition-colors motion-reduce:transition-none"
+ onClick={onClick}
+ onMouseEnter={onHover}
+ aria-busy={loading}
+ data-attr={dataAttr}
+ >
+ <span className="flex items-center justify-between gap-2 min-w-0 text-sm">
+ <span className="text-secondary truncate">{label}</span>
+ {loading ? null : aside}
+ </span>
+ {loading ? (
+ <>
+ <LemonSkeleton className="h-7 w-20 my-0.5" />
+ <LemonSkeleton className="h-3 w-32" />
+ </>
+ ) : (
+ <>
+ <span className="text-xl leading-8 font-semibold tabular-nums truncate" translate="no">
+ {value}
+ </span>
+ <span className="text-xs text-secondary truncate">{detail}</span>
+ </>
+ )}
+ </button>
+ )
+ return tooltip ? (
+ <Tooltip title={tooltip} placement="bottom">
+ {card}
+ </Tooltip>
+ ) : (
+ card
+ )
+}
diff --git a/products/web_analytics/frontend/pageReports/PageVisitorsCard.tsx b/products/web_analytics/frontend/pageReports/PageVisitorsCard.tsx
new file mode 100644
index 000000000000..e38943abc8d1
--- /dev/null
+++ b/products/web_analytics/frontend/pageReports/PageVisitorsCard.tsx
@@ -0,0 +1,37 @@
+import { WebPageDirectoryValue } from '~/queries/schema/schema-general'
+
+import { formatShare } from 'products/web_analytics/frontend/searchAndAi/searchAndAiQueries'
+
+import { valueChange } from './pageReportsUtils'
+import { PageStatCard } from './PageStatCard'
+import { TrendChange } from './TrendChange'
+
+export interface PageVisitorsCardProps {
+ visitors: WebPageDirectoryValue | null
+ siteVisitors: number | null
+ onClick: () => void
+}
+
+export function PageVisitorsCard({ visitors, siteVisitors, onClick }: PageVisitorsCardProps): JSX.Element {
+ const change = valueChange(visitors)
+ const share = visitors && siteVisitors ? formatShare(visitors.current, siteVisitors) : null
+
+ return (
+ <PageStatCard
+ label="Visitors"
+ aside={
+ change !== null && change !== 0 ? (
+ <TrendChange change={change} className="gap-0.5 text-xs tabular-nums" />
+ ) : null
+ }
+ value={visitors ? visitors.current.toLocaleString() : '-'}
+ detail={share ? `${share} of all site visitors` : 'People who viewed this page'}
+ loading={!visitors}
+ tooltip={
+ visitors?.previous != null ? `${visitors.previous.toLocaleString()} in the previous period` : undefined
+ }
+ onClick={onClick}
+ data-attr="page-report-health-card-visitors"
+ />
+ )
+}
diff --git a/products/web_analytics/frontend/pageReports/cancellableRequest.ts b/products/web_analytics/frontend/pageReports/cancellableRequest.ts
new file mode 100644
index 000000000000..d589f0c18db4
--- /dev/null
+++ b/products/web_analytics/frontend/pageReports/cancellableRequest.ts
@@ -0,0 +1,75 @@
+import { BreakPointFunction, isBreakpoint } from 'kea'
+
+import { uuid } from 'lib/utils/dom'
+import { isAbortedRequest, isTimedOutRequest } from 'lib/utils/requests'
+
+import { cancelQueryOnServer } from '~/queries/nodes/DataNode/dataNodeLogic'
+
+interface RequestDisposables {
+ add: (setup: () => () => void, key: string, options: { pauseOnPageHidden: boolean }) => void
+}
+
+export interface CancellableRequest {
+ signal: AbortSignal
+ queryId: string
+ track: <T>(request: Promise<T>) => Promise<T>
+}
+
+export const startCancellableRequest = (
+ disposables: RequestDisposables,
+ key: string,
+ getTeamId: () => number | null
+): CancellableRequest => {
+ const abortController = new AbortController()
+ const queryId = uuid()
+ let finished = false
+ disposables.add(
+ () => () => {
+ abortController.abort()
+ if (!finished) {
+ void cancelQueryOnServer(getTeamId(), queryId)
+ }
+ },
+ key,
+ { pauseOnPageHidden: false }
+ )
+ return {
+ signal: abortController.signal,
+ queryId,
+ track: (request) =>
+ request.then(
+ (result) => {
+ finished = true
+ return result
+ },
+ (error) => {
+ if (isTimedOutRequest(error)) {
+ void cancelQueryOnServer(getTeamId(), queryId)
+ }
+ finished = true
+ throw error
+ }
+ ),
+ }
+}
+
+export const runCancellableRequest = async <T>(
+ disposables: RequestDisposables,
+ key: string,
+ getTeamId: () => number | null,
+ breakpoint: BreakPointFunction,
+ load: (request: CancellableRequest) => Promise<T>
+): Promise<T> => {
+ const request = startCancellableRequest(disposables, key, getTeamId)
+ try {
+ const result = await request.track(load(request))
+ breakpoint()
+ return result
+ } catch (error) {
+ breakpoint()
+ throw error
+ }
+}
+
+export const isCancelledRequest = (error: unknown): boolean =>
+ (error instanceof Error && isBreakpoint(error)) || isAbortedRequest(error)
diff --git a/products/web_analytics/frontend/pageReports/pageDirectoryLogic.ts b/products/web_analytics/frontend/pageReports/pageDirectoryLogic.ts
index d8705b1357ba..fb481a898871 100644
--- a/products/web_analytics/frontend/pageReports/pageDirectoryLogic.ts
+++ b/products/web_analytics/frontend/pageReports/pageDirectoryLogic.ts
@@ -4,7 +4,6 @@ import {
actions,
afterMount,
connect,
- isBreakpoint,
kea,
key,
listeners,
@@ -16,15 +15,12 @@ import {
import { subscriptions } from 'kea-subscriptions'
import posthog from 'posthog-js'
-import { uuid } from 'lib/utils/dom'
-import { isAbortedRequest, isTimedOutRequest } from 'lib/utils/requests'
import { teamLogic } from 'scenes/teamLogic'
import { WEB_ANALYTICS_DATA_COLLECTION_NODE_ID } from 'scenes/web-analytics/common'
import { DateFilterState, webAnalyticsLogic } from 'scenes/web-analytics/webAnalyticsLogic'
import { WebAnalyticsLogicProps } from 'scenes/web-analytics/webAnalyticsLogicProps'
import { dataNodeCollectionLogic } from '~/queries/nodes/DataNode/dataNodeCollectionLogic'
-import { cancelQueryOnServer } from '~/queries/nodes/DataNode/dataNodeLogic'
import { performQuery } from '~/queries/query'
import {
CompareFilter,
@@ -39,7 +35,8 @@ import {
} from '~/queries/schema/schema-general'
import { TeamPublicType, TeamType } from '~/types'
-import { buildPageDirectoryBaseQuery, looksLikePageUrl, splitPageKey } from './pageReportsUtils'
+import { CancellableRequest, isCancelledRequest, startCancellableRequest } from './cancellableRequest'
+import { buildPageDirectoryBaseQuery, buildSiteTotalsQuery, looksLikePageUrl, splitPageKey } from './pageReportsUtils'
export const PAGE_DIRECTORY_PAGE_SIZE = 25
@@ -74,13 +71,6 @@ const SORT_METRIC: Record<WebPageDirectorySortBy, WebPageDirectoryMetric> = {
[WebPageDirectorySortBy.BounceRate]: WebPageDirectoryMetric.BounceRate,
}
-const SITE_SUMMARY_METRICS: WebPageDirectoryMetric[] = [
- WebPageDirectoryMetric.Visitors,
- WebPageDirectoryMetric.GoogleSearch,
- WebPageDirectoryMetric.AiReferrals,
- WebPageDirectoryMetric.AiCrawls,
-]
-
const mergePageDirectoryRows = (
driverRows: WebPageDirectoryRow[],
metricRows: Partial<Record<WebPageDirectoryMetric, Record<string, WebPageDirectoryRow>>>
@@ -436,13 +426,7 @@ export const pageDirectoryLogic: LogicWrapper<pageDirectoryLogicType> = kea<page
],
siteTotalsQuery: [
(s) => [s.baseQuery],
- (baseQuery: WebPageDirectoryQuery): WebPageDirectoryQuery => ({
- ...baseQuery,
- conversionGoal: null,
- pageKeys: [],
- metrics: SITE_SUMMARY_METRICS,
- includeSiteTotals: true,
- }),
+ (baseQuery: WebPageDirectoryQuery): WebPageDirectoryQuery => buildSiteTotalsQuery(baseQuery),
],
siteTotalsInput: [
(s) => [s.siteTotalsQuery],
@@ -507,43 +491,8 @@ export const pageDirectoryLogic: LogicWrapper<pageDirectoryLogicType> = kea<page
],
}),
listeners(({ values, actions, cache }) => {
- const startRequest = (
- key: string
- ): { signal: AbortSignal; queryId: string; track: <T>(request: Promise<T>) => Promise<T> } => {
- const abortController = new AbortController()
- const queryId = uuid()
- let finished = false
- cache.disposables.add(
- () => () => {
- abortController.abort()
- if (!finished) {
- void cancelQueryOnServer(values.currentTeam?.id ?? null, queryId)
- }
- },
- key,
- { pauseOnPageHidden: false }
- )
- return {
- signal: abortController.signal,
- queryId,
- track: (request) =>
- request.then(
- (result) => {
- finished = true
- return result
- },
- (error) => {
- if (isTimedOutRequest(error)) {
- void cancelQueryOnServer(values.currentTeam?.id ?? null, queryId)
- }
- finished = true
- throw error
- }
- ),
- }
- }
- const isCancellation = (error: unknown): boolean =>
- (error instanceof Error && isBreakpoint(error)) || isAbortedRequest(error)
+ const startRequest = (key: string): CancellableRequest =>
+ startCancellableRequest(cache.disposables, key, () => values.currentTeam?.id ?? null)
const failureMessage = (error: unknown): string =>
error instanceof Error ? error.message : 'Could not load pages'
@@ -569,7 +518,7 @@ export const pageDirectoryLogic: LogicWrapper<pageDirectoryLogicType> = kea<page
})
}
} catch (error) {
- if (isCancellation(error) || cache.disposables.isDisposed) {
+ if (isCancelledRequest(error) || cache.disposables.isDisposed) {
return
}
breakpoint()
@@ -607,7 +556,7 @@ export const pageDirectoryLogic: LogicWrapper<pageDirectoryLogicType> = kea<page
actions.loadMetricSuccess(metric, response.results ?? [])
}
} catch (error) {
- if (isCancellation(error) || isStale()) {
+ if (isCancelledRequest(error) || isStale()) {
return
}
actions.loadMetricFailure(metric)
@@ -628,7 +577,7 @@ export const pageDirectoryLogic: LogicWrapper<pageDirectoryLogicType> = kea<page
breakpoint()
actions.loadSiteTotalsSuccess(response.siteTotals ?? null)
} catch (error) {
- if (isCancellation(error) || cache.disposables.isDisposed) {
+ if (isCancelledRequest(error) || cache.disposables.isDisposed) {
return
}
actions.loadSiteTotalsFailure()
diff --git a/products/web_analytics/frontend/pageReports/pageHealth.test.ts b/products/web_analytics/frontend/pageReports/pageHealth.test.ts
new file mode 100644
index 000000000000..da58b9926f90
--- /dev/null
+++ b/products/web_analytics/frontend/pageReports/pageHealth.test.ts
@@ -0,0 +1,137 @@
+import { WebPageDirectoryRow, WebPageDirectorySiteTotals } from '~/queries/schema/schema-general'
+
+import {
+ GoogleSearchConsoleState,
+ PageHealthStatus,
+ computeAiHealth,
+ computeEngagementHealth,
+ computeSearchHealth,
+} from './pageHealth'
+
+const site = (overrides: Partial<WebPageDirectorySiteTotals> = {}): WebPageDirectorySiteTotals => ({
+ serverLogs: 100,
+ visitors: { current: 10000 },
+ googleSearch: { current: 3000 },
+ aiReferrals: { current: 200 },
+ aiCrawls: { current: 5000 },
+ timeOnPageP90: 60,
+ bounceRate: 0.4,
+ ...overrides,
+})
+
+const page = (overrides: Partial<WebPageDirectoryRow> = {}): WebPageDirectoryRow => ({
+ page: 'example.com/pricing',
+ visitors: { current: 1000 },
+ googleSearch: { current: 300, previous: 300 },
+ aiReferrals: { current: 20, previous: 20 },
+ aiCrawls: { current: 400 },
+ aiCrawlers: 5,
+ timeOnPageP90: 90,
+ bounceRate: 0.4,
+ ...overrides,
+})
+
+const connected: GoogleSearchConsoleState = { clicks: 300, impressions: 9000, position: 4.2 }
+
+describe('pageHealth', () => {
+ test.each<[string, WebPageDirectoryRow | null, GoogleSearchConsoleState, PageHealthStatus]>([
+ ['loading until data arrives', null, connected, 'loading'],
+ ['too few visitors to judge', page({ visitors: { current: 12 } }), connected, 'no_data'],
+ [
+ 'no Google visitors and no impressions',
+ page({ googleSearch: { current: 0 } }),
+ { clicks: 0, impressions: 0, position: null },
+ 'not_found',
+ ],
+ ['Google share at the site level and a good position', page(), connected, 'strong'],
+ ['a strong page without Search Console stays strong', page(), 'not_connected', 'strong'],
+ ['a strong page stays strong when Search Console fails to load', page(), 'error', 'strong'],
+ ['Google share well below the site', page({ googleSearch: { current: 50 } }), connected, 'needs_attention'],
+ [
+ 'Google visitors falling',
+ page({ googleSearch: { current: 300, previous: 500 } }),
+ connected,
+ 'needs_attention',
+ ],
+ [
+ 'Google visitors falling exactly 20%',
+ page({ googleSearch: { current: 240, previous: 300 } }),
+ connected,
+ 'needs_attention',
+ ],
+ ['ranking past page two', page(), { clicks: 300, impressions: 9000, position: 31 }, 'needs_attention'],
+ ['share between weak and strong', page({ googleSearch: { current: 200 } }), connected, 'fair'],
+ ])('search visibility: %s', (_name, pageRow, searchConsole, status) => {
+ expect(computeSearchHealth({ page: pageRow, site: site(), searchConsole }).status).toEqual(status)
+ })
+
+ test.each<[string, WebPageDirectoryRow, WebPageDirectorySiteTotals, PageHealthStatus]>([
+ [
+ 'no server logs and no AI visitors',
+ page({ aiReferrals: { current: 0 }, aiCrawls: { current: 0 }, aiCrawlers: 0 }),
+ site({ serverLogs: 0, aiCrawls: { current: 0 } }),
+ 'not_set_up',
+ ],
+ [
+ 'crawler events without server logs',
+ page({ aiReferrals: { current: 0 } }),
+ site({ serverLogs: 0 }),
+ 'needs_attention',
+ ],
+ [
+ 'logs forwarded but nothing read or referred',
+ page({ aiReferrals: { current: 0 }, aiCrawls: { current: 0 }, aiCrawlers: 0 }),
+ site(),
+ 'not_found',
+ ],
+ ['read by several crawlers and recommended', page(), site(), 'strong'],
+ [
+ 'crawled but never recommended',
+ page({ aiReferrals: { current: 0 }, aiCrawlers: 4 }),
+ site(),
+ 'needs_attention',
+ ],
+ ['only one crawler', page({ aiCrawlers: 1 }), site(), 'needs_attention'],
+ [
+ 'AI visitors without measured crawlers',
+ page({ aiCrawls: { current: 0 }, aiCrawlers: 0 }),
+ site({ serverLogs: 0, aiCrawls: { current: 0 } }),
+ 'strong',
+ ],
+ ['fewer crawlers than strong needs', page({ aiCrawlers: 2 }), site(), 'fair'],
+ [
+ 'crawled with too few visitors to judge referrals',
+ page({ visitors: { current: 1 }, aiReferrals: { current: 1, previous: 1 }, aiCrawlers: 3 }),
+ site(),
+ 'no_data',
+ ],
+ [
+ 'crawled but never recommended with few visitors',
+ page({ visitors: { current: 5 }, aiReferrals: { current: 0 } }),
+ site(),
+ 'needs_attention',
+ ],
+ ])('AI visibility: %s', (_name, pageRow, siteTotals, status) => {
+ expect(computeAiHealth({ page: pageRow, site: siteTotals, searchConsole: 'not_connected' }).status).toEqual(
+ status
+ )
+ })
+
+ test.each<[string, WebPageDirectoryRow, PageHealthStatus, string, Partial<WebPageDirectorySiteTotals>?]>([
+ ['no timing or bounce data', page({ timeOnPageP90: null, bounceRate: null }), 'no_data', ''],
+ ['sub-second visits read as a redirect', page({ timeOnPageP90: 0.096 }), 'needs_attention', 'redirect'],
+ ['quick exits', page({ timeOnPageP90: 6 }), 'needs_attention', ''],
+ ['bounce far above the site', page({ bounceRate: 0.7 }), 'needs_attention', ''],
+ ['bounce exactly at the poor margin', page({ bounceRate: 0.7 }), 'needs_attention', '', { bounceRate: 0.55 }],
+ ['long visits and a normal bounce rate', page(), 'strong', ''],
+ ['visits shorter than strong needs', page({ timeOnPageP90: 20 }), 'fair', ''],
+ ])('engagement: %s', (_name, pageRow, status, headlineIncludes, siteOverrides = {}) => {
+ const card = computeEngagementHealth({
+ page: pageRow,
+ site: site(siteOverrides),
+ searchConsole: 'not_connected',
+ })
+ expect(card.status).toEqual(status)
+ expect(card.headline).toContain(headlineIncludes)
+ })
+})
diff --git a/products/web_analytics/frontend/pageReports/pageHealth.ts b/products/web_analytics/frontend/pageReports/pageHealth.ts
new file mode 100644
index 000000000000..65fb2847a306
--- /dev/null
+++ b/products/web_analytics/frontend/pageReports/pageHealth.ts
@@ -0,0 +1,337 @@
+import { humanFriendlyDuration } from 'lib/utils/durations'
+import { percentage } from 'lib/utils/numbers'
+import { pluralize } from 'lib/utils/strings'
+
+import { WebPageDirectoryRow, WebPageDirectorySiteTotals } from '~/queries/schema/schema-general'
+
+import { GoogleSearchConsoleSummary } from 'products/web_analytics/frontend/searchAndAi/searchAndAiQueries'
+
+import { valueChange } from './pageReportsUtils'
+
+const MIN_VISITORS_FOR_HEALTH = 30
+const STRONG_SHARE_OF_SITE = 0.8
+const WEAK_SHARE_OF_SITE = 0.5
+const DECLINE_THRESHOLD = -0.2
+const GOOD_SEARCH_POSITION = 10
+const POOR_SEARCH_POSITION = 20
+const MIN_AI_CRAWLERS = 3
+const STRONG_BOUNCE_MARGIN = 0.05
+const POOR_BOUNCE_MARGIN = 0.15
+const MIN_ENGAGED_SECONDS = 30
+const QUICK_EXIT_SECONDS = 10
+const REDIRECT_SECONDS = 1
+
+export type PageHealthKey = 'search' | 'ai' | 'engagement'
+
+export type PageHealthStatus =
+ | 'loading'
+ | 'strong'
+ | 'fair'
+ | 'needs_attention'
+ | 'not_found'
+ | 'no_data'
+ | 'not_set_up'
+
+export interface PageHealthCard {
+ key: PageHealthKey
+ title: string
+ status: PageHealthStatus
+ headline: string
+ reasons: string[]
+}
+
+export type GoogleSearchConsoleState = GoogleSearchConsoleSummary | 'not_connected' | 'loading' | 'error'
+
+export interface PageHealthInput {
+ page: WebPageDirectoryRow | null
+ site: WebPageDirectorySiteTotals | null
+ searchConsole: GoogleSearchConsoleState
+}
+
+export const PAGE_HEALTH_STATUS_LABEL: Record<PageHealthStatus, string> = {
+ loading: 'Checking',
+ strong: 'Strong',
+ fair: 'Fair',
+ needs_attention: 'Needs attention',
+ not_found: 'Not found',
+ no_data: 'Not enough data',
+ not_set_up: 'Not set up',
+}
+
+const share = (part: number, whole: number): number => (whole > 0 ? part / whole : 0)
+
+const formatPct = (value: number): string => percentage(value, value < 0.1 ? 1 : 0)
+
+const atLeast = (value: number, threshold: number): boolean => value >= threshold - 1e-9
+
+const atMost = (value: number, threshold: number): boolean => value <= threshold + 1e-9
+
+const isDecline = (change: number | null): change is number => change !== null && atMost(change, DECLINE_THRESHOLD)
+
+const loadingCard = (key: PageHealthKey, title: string): PageHealthCard => ({
+ key,
+ title,
+ status: 'loading',
+ headline: 'Checking this page',
+ reasons: [],
+})
+
+const notEnoughVisitors = (key: PageHealthKey, title: string, visitors: number): PageHealthCard => ({
+ key,
+ title,
+ status: 'no_data',
+ headline: 'Not enough visitors yet',
+ reasons: [
+ `This page had ${pluralize(visitors, 'visitor')} in this period. Health needs at least ${MIN_VISITORS_FOR_HEALTH}.`,
+ ],
+})
+
+export function computeSearchHealth({ page, site, searchConsole }: PageHealthInput): PageHealthCard {
+ const title = 'Search visibility'
+ if (!page || !site || searchConsole === 'loading') {
+ return loadingCard('search', title)
+ }
+ const visitors = page.visitors?.current ?? 0
+ if (visitors < MIN_VISITORS_FOR_HEALTH) {
+ return notEnoughVisitors('search', title, visitors)
+ }
+ const google = page.googleSearch?.current ?? 0
+ const pageShare = share(google, visitors)
+ const siteShare = share(site.googleSearch?.current ?? 0, site.visitors?.current ?? 0)
+ const googleChange = valueChange(page.googleSearch)
+ const gsc = typeof searchConsole === 'string' ? null : searchConsole
+ const connectHint =
+ searchConsole === 'error'
+ ? 'Google Search Console data did not load.'
+ : 'Connect Google Search Console to see rankings and impressions.'
+
+ if (google === 0 && (!gsc || gsc.impressions === 0)) {
+ return {
+ key: 'search',
+ title,
+ status: 'not_found',
+ headline: 'No visitors from Google search',
+ reasons: [
+ gsc
+ ? 'Google Search Console shows no impressions for this page.'
+ : `None of this page's ${visitors.toLocaleString()} visitors arrived from Google search.`,
+ ...(gsc ? [] : [connectHint]),
+ ],
+ }
+ }
+
+ const issues: string[] = []
+ if (siteShare > 0 && !atLeast(pageShare, siteShare * WEAK_SHARE_OF_SITE)) {
+ issues.push(`${formatPct(pageShare)} of visitors come from Google, against ${formatPct(siteShare)} site-wide.`)
+ }
+ if (isDecline(googleChange)) {
+ issues.push(`Visitors from Google dropped ${formatPct(Math.abs(googleChange))} from the previous period.`)
+ }
+ if (gsc?.position != null && gsc.position > POOR_SEARCH_POSITION) {
+ issues.push(`The average Google position is ${gsc.position.toFixed(1)}.`)
+ }
+ if (gsc && gsc.impressions > 0 && gsc.clicks === 0) {
+ issues.push(`The page appeared in ${pluralize(gsc.impressions, 'search', 'searches')} but got no clicks.`)
+ }
+
+ const summary = `${formatPct(pageShare)} of visitors come from Google search, against ${formatPct(siteShare)} site-wide.`
+ const positionLine = gsc?.position != null ? `The average Google position is ${gsc.position.toFixed(1)}.` : null
+ if (issues.length > 0) {
+ return { key: 'search', title, status: 'needs_attention', headline: issues[0], reasons: issues }
+ }
+ const isStrong =
+ atLeast(pageShare, siteShare * STRONG_SHARE_OF_SITE) &&
+ !isDecline(googleChange) &&
+ (gsc?.position == null || gsc.position <= GOOD_SEARCH_POSITION)
+ return {
+ key: 'search',
+ title,
+ status: isStrong ? 'strong' : 'fair',
+ headline: summary,
+ reasons: [summary, ...(positionLine ? [positionLine] : []), ...(gsc ? [] : [connectHint])],
+ }
+}
+
+export const areCrawlersMeasured = (site: WebPageDirectorySiteTotals): boolean =>
+ site.serverLogs > 0 || (site.aiCrawls?.current ?? 0) > 0
+
+export function computeAiHealth({ page, site }: PageHealthInput): PageHealthCard {
+ const title = 'AI visibility'
+ if (!page || !site) {
+ return loadingCard('ai', title)
+ }
+ const visitors = page.visitors?.current ?? 0
+ const referrals = page.aiReferrals?.current ?? 0
+ const crawls = page.aiCrawls?.current ?? 0
+ const crawlers = page.aiCrawlers ?? 0
+ const crawlersMeasured = areCrawlersMeasured(site)
+ const enoughVisitors = visitors >= MIN_VISITORS_FOR_HEALTH
+ const pageShare = share(referrals, visitors)
+ const siteShare = share(site.aiReferrals?.current ?? 0, site.visitors?.current ?? 0)
+ const referralChange = valueChange(page.aiReferrals)
+ const logsHint = 'Forward your server logs to see which AI crawlers read this page.'
+
+ if (!crawlersMeasured && referrals === 0) {
+ return {
+ key: 'ai',
+ title,
+ status: 'not_set_up',
+ headline: 'AI crawlers are not measured yet',
+ reasons: [logsHint, 'No visitors arrived from an AI assistant in this period.'],
+ }
+ }
+ if (crawls === 0 && !enoughVisitors) {
+ return notEnoughVisitors('ai', title, visitors)
+ }
+ if (crawls === 0 && referrals === 0) {
+ return {
+ key: 'ai',
+ title,
+ status: 'not_found',
+ headline: 'Not read or recommended by AI yet',
+ reasons: ['No AI crawler read this page and no AI assistant sent visitors to it.'],
+ }
+ }
+
+ const issues: string[] = []
+ if (crawlersMeasured && crawls > 0 && referrals === 0) {
+ issues.push(`Read by ${pluralize(crawlers, 'AI crawler')} but no AI assistant sent visitors.`)
+ }
+ if (crawlersMeasured && crawlers === 1) {
+ issues.push('Only one AI crawler read this page.')
+ }
+ if (enoughVisitors && referrals > 0 && siteShare > 0 && !atLeast(pageShare, siteShare * WEAK_SHARE_OF_SITE)) {
+ issues.push(
+ `${formatPct(pageShare)} of visitors come from AI assistants, against ${formatPct(siteShare)} site-wide.`
+ )
+ }
+ if (enoughVisitors && isDecline(referralChange)) {
+ issues.push(
+ `Visitors from AI assistants dropped ${formatPct(Math.abs(referralChange))} from the previous period.`
+ )
+ }
+
+ const crawlerLine = crawlersMeasured
+ ? `Read by ${pluralize(crawlers, 'AI crawler')} ${pluralize(crawls, 'time')}.`
+ : logsHint
+ const referralLine = `${pluralize(referrals, 'visitor')} arrived from an AI assistant.`
+ const shareLine = `${formatPct(pageShare)} of visitors come from AI assistants, against ${formatPct(siteShare)} site-wide.`
+ if (issues.length > 0) {
+ return { key: 'ai', title, status: 'needs_attention', headline: issues[0], reasons: [...issues, crawlerLine] }
+ }
+ if (!enoughVisitors) {
+ return notEnoughVisitors('ai', title, visitors)
+ }
+ const isStrong =
+ referrals > 0 &&
+ atLeast(pageShare, siteShare * STRONG_SHARE_OF_SITE) &&
+ (!crawlersMeasured || crawlers >= MIN_AI_CRAWLERS)
+ return {
+ key: 'ai',
+ title,
+ status: isStrong ? 'strong' : 'fair',
+ headline: referrals > 0 ? shareLine : referralLine,
+ reasons: [shareLine, referralLine, crawlerLine],
+ }
+}
+
+export function computeEngagementHealth({ page, site }: PageHealthInput): PageHealthCard {
+ const title = 'Engagement'
+ if (!page || !site) {
+ return loadingCard('engagement', title)
+ }
+ const visitors = page.visitors?.current ?? 0
+ if (visitors < MIN_VISITORS_FOR_HEALTH) {
+ return notEnoughVisitors('engagement', title, visitors)
+ }
+ const p90 = page.timeOnPageP90 ?? null
+ const bounce = page.bounceRate ?? null
+ const siteP90 = site.timeOnPageP90 ?? null
+ const siteBounce = site.bounceRate ?? null
+ if (p90 === null && bounce === null) {
+ return {
+ key: 'engagement',
+ title,
+ status: 'no_data',
+ headline: 'No timing data yet',
+ reasons: ['Time on page needs a following pageview, so the last page of each visit is not counted.'],
+ }
+ }
+
+ const issues: string[] = []
+ if (p90 !== null && p90 < REDIRECT_SECONDS) {
+ issues.push('Visits end in under a second, which usually means a redirect.')
+ } else if (p90 !== null && p90 < QUICK_EXIT_SECONDS) {
+ issues.push(`Most visitors leave within ${humanFriendlyDuration(p90)}.`)
+ }
+ if (bounce !== null && siteBounce !== null && atLeast(bounce, siteBounce + POOR_BOUNCE_MARGIN)) {
+ issues.push(
+ `${formatPct(bounce)} of visits that start here bounce, against ${formatPct(siteBounce)} site-wide.`
+ )
+ }
+
+ const timeLine = p90 !== null ? `90% of visitors spend up to ${humanFriendlyDuration(p90)} on this page.` : null
+ const bounceLine =
+ bounce !== null
+ ? `${formatPct(bounce)} of visits that start here bounce${siteBounce !== null ? `, against ${formatPct(siteBounce)} site-wide` : ''}.`
+ : null
+ const reasons = [timeLine, bounceLine].filter((line): line is string => !!line)
+ if (issues.length > 0) {
+ return { key: 'engagement', title, status: 'needs_attention', headline: issues[0], reasons: issues }
+ }
+ const isStrong =
+ (bounce === null || siteBounce === null || atMost(bounce, siteBounce + STRONG_BOUNCE_MARGIN)) &&
+ (p90 === null || atLeast(p90, Math.max(MIN_ENGAGED_SECONDS, (siteP90 ?? 0) * STRONG_SHARE_OF_SITE)))
+ return {
+ key: 'engagement',
+ title,
+ status: isStrong ? 'strong' : 'fair',
+ headline: reasons[0],
+ reasons,
+ }
+}
+
+export interface PageHealthSummary extends PageHealthCard {
+ value: string | null
+ detail: string | null
+}
+
+const formatDuration = (seconds: number): string => (seconds < 1 ? 'Under 1s' : humanFriendlyDuration(seconds))
+
+function summarizePageHealth(card: PageHealthCard, { page, site }: PageHealthInput): PageHealthSummary {
+ if (!page || !site || card.status === 'loading') {
+ return { ...card, value: null, detail: null }
+ }
+ const visitors = page.visitors?.current ?? 0
+ const siteVisitors = site.visitors?.current ?? 0
+ if (card.key === 'search') {
+ return {
+ ...card,
+ value: visitors > 0 ? formatPct(share(page.googleSearch?.current ?? 0, visitors)) : null,
+ detail: `from Google, site average ${formatPct(share(site.googleSearch?.current ?? 0, siteVisitors))}`,
+ }
+ }
+ if (card.key === 'ai') {
+ return {
+ ...card,
+ value: visitors > 0 ? formatPct(share(page.aiReferrals?.current ?? 0, visitors)) : null,
+ detail: `from AI assistants, site average ${formatPct(share(site.aiReferrals?.current ?? 0, siteVisitors))}`,
+ }
+ }
+ const p90 = page.timeOnPageP90 ?? null
+ const bounce = page.bounceRate ?? null
+ return {
+ ...card,
+ value: p90 !== null ? formatDuration(p90) : null,
+ detail:
+ [p90 !== null ? 'for 90% of visits' : null, bounce !== null ? `${formatPct(bounce)} bounce` : null]
+ .filter(Boolean)
+ .join(' · ') || null,
+ }
+}
+
+export function computePageHealth(input: PageHealthInput): PageHealthSummary[] {
+ return [computeSearchHealth(input), computeAiHealth(input), computeEngagementHealth(input)].map((card) =>
+ summarizePageHealth(card, input)
+ )
+}
diff --git a/products/web_analytics/frontend/pageReports/pageReportsUtils.ts b/products/web_analytics/frontend/pageReports/pageReportsUtils.ts
index 5929bd15bcd7..aef2e2e9ae27 100644
--- a/products/web_analytics/frontend/pageReports/pageReportsUtils.ts
+++ b/products/web_analytics/frontend/pageReports/pageReportsUtils.ts
@@ -10,6 +10,7 @@ import {
NodeKind,
WebAnalyticsConversionGoal,
WebAnalyticsPropertyFilters,
+ WebPageDirectoryMetric,
WebPageDirectoryQuery,
WebPageDirectoryValue,
} from '~/queries/schema/schema-general'
@@ -46,6 +47,21 @@ export const buildPageDirectoryBaseQuery = ({
tags: WEB_ANALYTICS_DEFAULT_QUERY_TAGS,
})
+export const SITE_SUMMARY_METRICS: WebPageDirectoryMetric[] = [
+ WebPageDirectoryMetric.Visitors,
+ WebPageDirectoryMetric.GoogleSearch,
+ WebPageDirectoryMetric.AiReferrals,
+ WebPageDirectoryMetric.AiCrawls,
+]
+
+export const buildSiteTotalsQuery = (baseQuery: WebPageDirectoryQuery): WebPageDirectoryQuery => ({
+ ...baseQuery,
+ conversionGoal: null,
+ pageKeys: [],
+ metrics: SITE_SUMMARY_METRICS,
+ includeSiteTotals: true,
+})
+
export const valueChange = (value: WebPageDirectoryValue | null | undefined): number | null =>
value?.previous != null ? changeVsPrevious(value.current, value.previous) : null
diff --git a/products/web_analytics/frontend/searchAndAi/searchAndAiQueries.ts b/products/web_analytics/frontend/searchAndAi/searchAndAiQueries.ts
index b50b04b4c8c1..9c92da3251a4 100644
--- a/products/web_analytics/frontend/searchAndAi/searchAndAiQueries.ts
+++ b/products/web_analytics/frontend/searchAndAi/searchAndAiQueries.ts
@@ -6,16 +6,22 @@ import type { DateFilterState } from 'scenes/web-analytics/webAnalyticsLogic'
import { performQuery } from '~/queries/query'
import {
+ BreakdownFilter,
CompareFilter,
+ DataTableNode,
EventsNode,
GroupNode,
HogQLQuery,
+ InsightVizNode,
NodeKind,
RefreshType,
+ TrendsQuery,
+ WebAnalyticsConversionGoal,
WebAnalyticsPropertyFilters,
+ WebStatsBreakdown,
} from '~/queries/schema/schema-general'
import { escapeDottedHogQLIdentifier, escapeHogQLString } from '~/queries/utils'
-import { BaseMathType, FilterLogicalOperator, PropertyFilterType, PropertyOperator } from '~/types'
+import { BaseMathType, ChartDisplayType, FilterLogicalOperator, PropertyFilterType, PropertyOperator } from '~/types'
import type { AiAssistantRow } from './AiAssistantList'
@@ -255,6 +261,119 @@ const aiAssistantBranch = ([terms, name]: [string[], string]): string => {
const AI_ASSISTANT_EXPR = `multiIf(${AI_ASSISTANT_NAMES.map(aiAssistantBranch).join(', ')}, coalesce(nullIf(nullIf(${AI_ASSISTANT_SOURCE}, ''), '$direct'), 'Unattributed'))`
+export const AI_ASSISTANT_BREAKDOWN: BreakdownFilter = { breakdown: AI_ASSISTANT_EXPR, breakdown_type: 'hogql' }
+
+export interface SearchAndAiTileFilters {
+ dateFilter: DateFilterState
+ filterTestAccounts: boolean
+ properties: WebAnalyticsPropertyFilters
+}
+
+export const buildTrendTile = (
+ { dateFilter, filterTestAccounts, properties }: SearchAndAiTileFilters,
+ trend: Pick<TrendsQuery, 'series' | 'trendsFilter' | 'breakdownFilter'>
+): InsightVizNode => ({
+ kind: NodeKind.InsightVizNode,
+ source: {
+ kind: NodeKind.TrendsQuery,
+ dateRange: { date_from: dateFilter.dateFrom, date_to: dateFilter.dateTo },
+ interval: dateFilter.interval,
+ ...trend,
+ properties,
+ filterTestAccounts,
+ tags: WEB_ANALYTICS_DEFAULT_QUERY_TAGS,
+ },
+ hidePersonsModal: true,
+ embedded: true,
+})
+
+export const buildAiReferralTrendQuery = (
+ filters: SearchAndAiTileFilters,
+ breakdownFilter: BreakdownFilter | undefined
+): InsightVizNode =>
+ buildTrendTile(
+ { ...filters, properties: [AI_CHANNEL_FILTER, ...filters.properties] },
+ {
+ series: [
+ { kind: NodeKind.EventsNode, event: '$pageview', name: '$pageview', math: BaseMathType.UniqueSessions },
+ ],
+ trendsFilter: { display: ChartDisplayType.ActionsLineGraph, showLegend: true },
+ breakdownFilter,
+ }
+ )
+
+export const buildAiCrawlerTrendQuery = (filters: SearchAndAiTileFilters, seriesName: string): InsightVizNode =>
+ buildTrendTile(
+ { ...filters, properties: [...AI_CRAWLER_FILTERS, ...filters.properties] },
+ { series: [aiCrawlerRequestSeries(seriesName)], trendsFilter: { display: ChartDisplayType.ActionsLineGraph } }
+ )
+
+const GOOGLE_SEARCH_FILTERS: WebAnalyticsPropertyFilters = [
+ {
+ key: '$channel_type',
+ value: ['Organic Search'],
+ operator: PropertyOperator.Exact,
+ type: PropertyFilterType.Session,
+ },
+ {
+ key: '$entry_referring_domain',
+ value: 'google',
+ operator: PropertyOperator.IContains,
+ type: PropertyFilterType.Session,
+ },
+]
+
+export const buildGoogleSearchTrendQuery = (filters: SearchAndAiTileFilters): InsightVizNode =>
+ buildTrendTile(
+ { ...filters, properties: [...GOOGLE_SEARCH_FILTERS, ...filters.properties] },
+ {
+ series: [
+ {
+ kind: NodeKind.EventsNode,
+ event: '$pageview',
+ name: '$pageview',
+ custom_name: 'Visitors from Google search',
+ math: BaseMathType.UniqueUsers,
+ },
+ ],
+ trendsFilter: { display: ChartDisplayType.ActionsLineGraph },
+ }
+ )
+
+export const buildAiReferralTableQuery = (
+ {
+ dateFilter,
+ filterTestAccounts,
+ properties,
+ compareFilter,
+ conversionGoal,
+ }: SearchAndAiTileFilters & { compareFilter: CompareFilter; conversionGoal: WebAnalyticsConversionGoal | null },
+ breakdownBy: WebStatsBreakdown
+): DataTableNode => ({
+ full: true,
+ kind: NodeKind.DataTableNode,
+ source: {
+ kind: NodeKind.WebStatsTableQuery,
+ properties: [AI_CHANNEL_FILTER, ...properties],
+ breakdownBy,
+ dateRange: { date_from: dateFilter.dateFrom, date_to: dateFilter.dateTo },
+ compareFilter,
+ conversionGoal,
+ limit: 10,
+ filterTestAccounts,
+ tags: WEB_ANALYTICS_DEFAULT_QUERY_TAGS,
+ },
+ embedded: false,
+ showActions: true,
+ columns: [
+ 'breakdown_value',
+ 'visitors',
+ 'views',
+ ...(conversionGoal ? ['total_conversions', 'conversion_rate'] : []),
+ 'cross_sell',
+ ],
+})
+
const aiSessionsPredicate = (window: PagePerformanceWindow): string => {
const lowerBound = window.currentFrom
? `$start_timestamp >= ${tsLiteral(window.currentFrom.subtract(1, 'day'), window.timezone)} AND `