feat(integration): Google Search Console search terms

podman/env.sample

@@ -14,3 +14,7 @@ APP_SECRET=replace-me-with-a-random-string
 POSTGRES_DB=umami
 POSTGRES_USER=umami
 POSTGRES_PASSWORD=replace-me-with-a-random-string
+
+# Google Search Console integration (OAuth Client credentials)
+GOOGLE_CLIENT_ID=
+GOOGLE_CLIENT_SECRET=

prisma/migrations/20_add_google_auth/migration.sql

@@ -0,0 +1,17 @@
+-- CreateTable
+CREATE TABLE "website_google_auth" (
+    "google_auth_id" UUID NOT NULL,
+    "website_id" UUID NOT NULL,
+    "access_token" TEXT NOT NULL,
+    "refresh_token" TEXT NOT NULL,
+    "expires_at" TIMESTAMPTZ(6) NOT NULL,
+    "email" VARCHAR(255) NOT NULL,
+    "property_url" VARCHAR(500),
+    "created_at" TIMESTAMPTZ(6) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMPTZ(6) NOT NULL,
+
+    CONSTRAINT "website_google_auth_pkey" PRIMARY KEY ("google_auth_id")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "website_google_auth_website_id_key" ON "website_google_auth"("website_id");

prisma/schema.prisma

@@ -88,6 +88,7 @@ model Website {
   sessionData         SessionData[]
   sessionReplays      SessionReplay[]
   sessionReplaysSaved SessionReplaySaved[]
+  googleAuth          WebsiteGoogleAuth?
 
   @@index([userId])
   @@index([teamId])
@@ -96,6 +97,22 @@ model Website {
   @@map("website")
 }
 
+model WebsiteGoogleAuth {
+  id           String    @id @default(uuid()) @map("google_auth_id") @db.Uuid
+  websiteId    String    @unique @map("website_id") @db.Uuid
+  accessToken  String    @map("access_token") @db.Text
+  refreshToken String    @map("refresh_token") @db.Text
+  expiresAt    DateTime  @map("expires_at") @db.Timestamptz(6)
+  email        String    @db.VarChar(255)
+  propertyUrl  String?   @map("property_url") @db.VarChar(500)
+  createdAt    DateTime  @default(now()) @map("created_at") @db.Timestamptz(6)
+  updatedAt    DateTime  @updatedAt @map("updated_at") @db.Timestamptz(6)
+
+  website      Website   @relation(fields: [websiteId], references: [id], onDelete: Cascade)
+
+  @@map("website_google_auth")
+}
+
 model WebsiteEvent {
   id             String    @id() @map("event_id") @db.Uuid
   websiteId      String    @map("website_id") @db.Uuid

public/intl/messages/en-US.json

@@ -82,6 +82,7 @@
     "day": "Day",
     "default-date-range": "Default date range",
     "delete": "Delete",
+    "disconnect": "Disconnect",
     "delete-report": "Delete report",
     "delete-team": "Delete team",
     "delete-user": "Delete user",
@@ -351,6 +352,15 @@
     "untitled": "Untitled",
     "upgrade": "Upgrade",
     "update": "Update",
+    "google-search-console": "Google Search Console",
+    "google-account": "Google account",
+    "search-terms": "Search terms",
+    "connect-with-google": "Continue with Google",
+    "disconnect-google-account": "Disconnect Google account",
+    "select-gsc-property": "Select a property",
+    "impressions": "Impressions",
+    "ctr": "CTR",
+    "position": "Position",
     "url": "URL",
     "user": "User",
     "username": "Username",
@@ -429,6 +439,14 @@
     "user-deleted": "User deleted.",
     "viewed-page": "Viewed page",
     "upgrade-required": "This feature requires a {plan} plan subscription.",
-    "visitor-log": "Visitor from <b>{country}</b> using <b>{browser}</b> on <b>{os}</b> <b>{device}</b>"
+    "visitor-log": "Visitor from <b>{country}</b> using <b>{browser}</b> on <b>{os}</b> <b>{device}</b>",
+    "gsc-not-configured-prompt": "Connect your Google Search Console account to view search terms.",
+    "gsc-property-instruction": "Select the Google Search Console property you would like to pull keyword data from.",
+    "gsc-verification-note": "Note: You also need to set up your site on Google Search Console for this integration to work.",
+    "gsc-connect-error": "Failed to connect Google account. Please try again.",
+    "gsc-save-property-error": "Failed to save the selected property. Please try again.",
+    "gsc-description": "You can integrate Google Search Console to retrieve all search results statistics, including the search terms used by users who visit your site.",
+    "gsc-account-description": "Link the Google account that manages your website's Google Search Console.",
+    "visitors-gsc-tooltip": "Visitors represents the number of clicks from Google Search results."
   }
 }

src/app/(main)/websites/[websiteId]/ExpandedViewModal.tsx

@@ -1,20 +1,23 @@
 import { Dialog, Modal } from '@umami/react-zen';
+import { useEffect } from 'react';
 import { WebsiteExpandedView } from '@/app/(main)/websites/[websiteId]/WebsiteExpandedView';
-import { useMobile, useNavigation } from '@/components/hooks';
+import { WebsiteSearchTermsExpandedView } from '@/app/(main)/websites/[websiteId]/WebsiteSearchTermsExpandedView';
+import { useGoogleDomain, useMobile, useNavigation } from '@/components/hooks';
 
 export function ExpandedViewModal({
   websiteId,
   excludedIds,
 }: {
   websiteId: string;
-  excludedIds?: string[];
+  excludedIds?: Array<string>;
 }) {
   const {
     router,
     query: { view },
     updateParams,
   } = useNavigation();
   const { isMobile } = useMobile();
+  const googleDomain = useGoogleDomain();
 
   const handleClose = (close: () => void) => {
     router.push(updateParams({ view: undefined }));
@@ -27,6 +30,16 @@ export function ExpandedViewModal({
     }
   };
 
+  useEffect(() => {
+    if (view === 'searchTerms' && !googleDomain) {
+      router.replace(updateParams({ view: undefined }));
+    }
+  }, [view, googleDomain, router, updateParams]);
+
+  if (view === 'searchTerms' && !googleDomain) {
+    return null;
+  }
+
   return (
     <Modal isOpen={!!view} onOpenChange={handleOpenChange} isDismissable>
       <Dialog
@@ -38,6 +51,15 @@ export function ExpandedViewModal({
         }}
       >
         {({ close }) => {
+          if (view === 'searchTerms' && googleDomain) {
+            return (
+              <WebsiteSearchTermsExpandedView
+                websiteId={websiteId}
+                googleDomain={googleDomain}
+                onClose={() => handleClose(close)}
+              />
+            );
+          }
           return (
             <WebsiteExpandedView
               websiteId={websiteId}

src/app/(main)/websites/[websiteId]/WebsitePanels.tsx

@@ -1,10 +1,12 @@
 import { Grid, Heading, Row, Tab, TabList, TabPanel, Tabs } from '@umami/react-zen';
+import { useEffect, useState } from 'react';
 import { GridRow } from '@/components/common/GridRow';
 import { Panel } from '@/components/common/Panel';
-import { useMessages, useMobile } from '@/components/hooks';
+import { useGoogleDomain, useMessages, useMobile } from '@/components/hooks';
 import { MetricsTable } from '@/components/metrics/MetricsTable';
 import { WeeklyTraffic } from '@/components/metrics/WeeklyTraffic';
 import { WorldMap } from '@/components/metrics/WorldMap';
+import { WebsiteSearchTerms } from './WebsiteSearchTerms';
 
 export function WebsitePanels({ websiteId }: { websiteId: string }) {
   const { t, labels } = useMessages();
@@ -18,6 +20,20 @@ export function WebsitePanels({ websiteId }: { websiteId: string }) {
   const rowProps = { minHeight: '570px' };
   const { isMobile } = useMobile();
 
+  const googleDomain = useGoogleDomain();
+
+  const [sourcesTab, setSourcesTab] = useState<string | number>(
+    googleDomain ? 'searchTerms' : 'referrer',
+  );
+
+  useEffect(() => {
+    if (googleDomain) {
+      setSourcesTab('searchTerms');
+    } else {
+      setSourcesTab(prev => (prev === 'searchTerms' ? 'referrer' : prev));
+    }
+  }, [googleDomain]);
+
   return (
     <Grid gap="3">
       <GridRow layout="two" {...rowProps}>
@@ -42,11 +58,17 @@ export function WebsitePanels({ websiteId }: { websiteId: string }) {
         </Panel>
         <Panel>
           <Heading size="2xl">{t(labels.sources)}</Heading>
-          <Tabs>
+          <Tabs selectedKey={sourcesTab} onSelectionChange={key => setSourcesTab(key)}>
             <TabList>
+              {googleDomain && <Tab id="searchTerms">{t(labels.searchTerms)}</Tab>}
               <Tab id="referrer">{t(labels.referrers)}</Tab>
               <Tab id="channel">{t(labels.channels)}</Tab>
             </TabList>
+            {googleDomain && (
+              <TabPanel id="searchTerms">
+                <WebsiteSearchTerms websiteId={websiteId} googleDomain={googleDomain} />
+              </TabPanel>
+            )}
             <TabPanel id="referrer">
               <MetricsTable type="referrer" title={t(labels.referrer)} {...tableProps} />
             </TabPanel>

src/app/(main)/websites/[websiteId]/WebsiteSearchTerms.tsx

@@ -0,0 +1,106 @@
+'use client';
+
+import { Grid, Row, Text } from '@umami/react-zen';
+import { useMemo } from 'react';
+import { LoadingPanel } from '@/components/common/LoadingPanel';
+import { LinkButton } from '@/components/common/LinkButton';
+import {
+  useMessages,
+  useNavigation,
+  useWebsiteGoogleAuthQuery,
+  useWebsiteSearchTermsFilters,
+  useWebsiteSearchTermsQuery,
+} from '@/components/hooks';
+import { IconLabel } from '@/components/common/IconLabel';
+import { Maximize } from '@/components/icons';
+import { ListTable } from '@/components/metrics/ListTable';
+import type { GoogleDomain } from '@/lib/constants';
+
+interface Props {
+  websiteId: string;
+  googleDomain: GoogleDomain;
+}
+
+export function WebsiteSearchTerms({ websiteId, googleDomain }: Props) {
+  const { t, labels, messages } = useMessages();
+  const { updateParams } = useNavigation();
+  const { path, country } = useWebsiteSearchTermsFilters();
+
+  const { data: authData, isLoading: authLoading } = useWebsiteGoogleAuthQuery(websiteId);
+
+  const { data, isLoading, isFetching, error } = useWebsiteSearchTermsQuery(websiteId, {
+    path,
+    googleDomain,
+    country,
+    limit: 10,
+    offset: 0,
+    enabled: !!authData?.connected && !!authData?.propertyUrl,
+  });
+
+  const basePath = process.env.basePath || '';
+
+  const tableData = useMemo(() => {
+    if (!data?.rows?.length) return [];
+
+    const totalClicks = data.rows.reduce((sum, r) => sum + r.clicks, 0);
+
+    return data.rows.map(row => ({
+      label: row.query,
+      count: row.clicks,
+      percent: totalClicks > 0 ? (row.clicks / totalClicks) * 100 : 0,
+    }));
+  }, [data]);
+
+  // If GSC not connected, show prompt
+  if (!authLoading && !authData?.connected) {
+    return (
+      <Row alignItems="center" justifyContent="center" padding="8">
+        <Text color="muted" size="sm" align="center">
+          {t(messages.gscNotConfiguredPrompt)}{' '}
+          <LinkButton href={`${basePath}/websites/${websiteId}/settings`}>
+            {t(messages.goToSettings)}
+          </LinkButton>
+        </Text>
+      </Row>
+    );
+  }
+
+  if (!authLoading && authData?.connected && !authData?.propertyUrl) {
+    return (
+      <Row alignItems="center" justifyContent="center" padding="8">
+        <Text color="muted" size="sm" align="center">
+          {t(messages.gscPropertyInstruction)}{' '}
+          <LinkButton href={`${basePath}/websites/${websiteId}/settings`}>
+            {t(messages.goToSettings)}
+          </LinkButton>
+        </Text>
+      </Row>
+    );
+  }
+
+  return (
+    <LoadingPanel
+      data={data}
+      isFetching={isFetching}
+      isLoading={isLoading || authLoading}
+      error={error}
+      minHeight="400px"
+    >
+      <Grid padding="2">
+        {data && (
+          <ListTable
+            data={tableData}
+            title={t(labels.searchTerms)}
+            metric={t(labels.visitors)}
+            metricToolTip={t(messages.visitorsGscTooltip)}
+          />
+        )}
+        <Row justifyContent="center" alignItems="flex-end" paddingTop="4">
+          <LinkButton href={updateParams({ view: 'searchTerms' })} variant="quiet">
+            <IconLabel icon={<Maximize />}>{t(labels.more)}</IconLabel>
+          </LinkButton>
+        </Row>
+      </Grid>
+    </LoadingPanel>
+  );
+}