API Reference

Complete reference for all exported functions, types, and interfaces from the plugin.

Entry Points

sanity-plugin-analytics

Main entry — plugin functions and TypeScript types for Sanity config.

sanity-plugin-analytics/api/analytics

GA4 API route handler.

sanity-plugin-analytics/api/search-console

Search Console API route handler.

sanity-plugin-analytics/api/pagespeed

PageSpeed Insights proxy route handler.

Plugin Functions

typescript

import {
  sanityAnalyticsPlugin,  // Combined: GA4 + Search Console + Lighthouse
  googleAnalyticsPlugin,  // GA4 only
  searchConsolePlugin,    // Search Console only
  lighthousePlugin,       // Lighthouse only
} from 'sanity-plugin-analytics'

Schema Exports

typescript

import {
  analyticsSchemas,   // Array of all Sanity schema types
  lighthouseReport,   // analytics.lighthouseReport document type
} from 'sanity-plugin-analytics'

Document View Factories

Add per-document analytics to the editor via the Structure tool. See Document Views for full usage.

typescript

import {
  createSeoView,          // SEO + performance panel for a document
  createLighthouseView,   // full PageSpeed/Lighthouse report for a document
} from 'sanity-plugin-analytics'

// Signatures
createSeoView(config: SeoDocumentViewConfig): DocumentViewComponent
createLighthouseView(config: LighthouseConfig): DocumentViewComponent

`GET`

The API route handler that fetches analytics data from GA4.

typescript

import { GET } from 'sanity-plugin-analytics/api/analytics'

// Re-export in your API route
export { GET } from 'sanity-plugin-analytics/api/analytics'

// Signature — Web Fetch handler; JSON body is AnalyticsData
GET(request: Request): Promise<Response>

Types

GoogleAnalyticsConfig

typescript

interface GoogleAnalyticsConfig {
  /** GA4 proxy route in your app. @default '/api/analytics' */
  apiUrl?: string
  /** Optional GA4 property ID. Falls back to GA_PROPERTY_ID. */
  propertyId?: string
  /** Label shown under the Analytics heading. */
  siteTitle?: string
  /** Tool title in 'separate' layout. @default 'Analytics' */
  title?: string
  /** Tool URL/route segment in 'separate' layout. @default 'analytics' */
  name?: string
  /** Hide the GA4 tab/tool. */
  disabled?: boolean
}

AnalyticsData

The response shape returned by the GET handler:

typescript

interface AnalyticsData {
  activeUsers: number
  overview: OverviewMetrics
  timeSeries: TimeSeriesDataPoint[]
  hourlyToday: HourlyDataPoint[]
  topPages: TopPage[]
  landingPages: LandingPage[]
  devices: DeviceCategory[]
  browsers: BrowserData[]
  operatingSystems: OsData[]
  countries: CountryData[]
  cities: CityData[]
  trafficSources: TrafficSource[]
  channels: ChannelData[]
  newVsReturning: UserTypeData[]
  topEvents: EventData[]
  referrers: ReferrerData[]
}

OverviewMetrics

typescript

interface OverviewMetrics {
  totalUsers: number
  newUsers: number
  sessions: number
  pageViews: number
  avgSessionDuration: number
  bounceRate: number
  engagedSessions: number
  engagementRate: number
  pagesPerSession: number
  eventsPerSession: number
}

DateRange

typescript

// Number of days the dashboard queries
type DateRange = '7' | '14' | '30' | '90'

Common Data Types

typescript

interface TimeSeriesDataPoint {
  date: string
  displayDate: string
  users: number
  sessions: number
  pageViews: number
}

interface HourlyDataPoint {
  hour: string
  label: string
  users: number
  sessions: number
}

interface TopPage {
  path: string
  pageViews: number
  users: number
}

interface LandingPage {
  path: string
  sessions: number
  users: number
  bounceRate: number
}

interface DeviceCategory {
  device: string
  sessions: number
  percentage: number
}

interface BrowserData {
  browser: string
  sessions: number
  percentage: number
}

interface OsData {
  os: string
  sessions: number
  percentage: number
}

interface CountryData {
  country: string
  users: number
  sessions: number
}

interface CityData {
  city: string
  country: string
  users: number
  sessions: number
}

interface TrafficSource {
  source: string
  sessions: number
  users: number
}

interface ChannelData {
  channel: string
  sessions: number
  users: number
  engagementRate: number
}

interface UserTypeData {
  type: string
  users: number
  percentage: number
}

interface EventData {
  name: string
  count: number
  usersCount: number
}

interface ReferrerData {
  referrer: string
  sessions: number
  users: number
}

Search Console Types

The response shape returned by the Search Console GET handler and consumed by the dashboard. Every row type extends ScRow.

typescript

type ScDateRange = '7' | '28' | '90' | '180'

interface ScRow {
  clicks: number
  impressions: number
  ctr: number
  position: number
}

interface ScQuery extends ScRow { query: string }
interface ScPage extends ScRow { page: string }
interface ScTimeSeriesPoint extends ScRow { date: string }
interface ScCountry extends ScRow { country: string; countryCode: string }
interface ScDevice extends ScRow { device: string }
interface ScSearchAppearance extends ScRow { appearance: string }

interface SitemapContent {
  type: string
  submitted: number
  indexed: number
}

interface Sitemap {
  path: string
  lastSubmitted: string
  lastDownloaded: string
  isPending: boolean
  warnings: number
  errors: number
  contents: SitemapContent[]
}

interface SearchConsoleData {
  overview: ScRow
  queries: ScQuery[]
  pages: ScPage[]
  timeSeries: ScTimeSeriesPoint[]
  countries: ScCountry[]
  devices: ScDevice[]
  searchAppearance: ScSearchAppearance[]
  sitemaps: Sitemap[]
}

Environment Variables

The API handler reads these environment variables at runtime:

Variable	Type	Description
`GA_PROPERTY_ID`	`string`	GA4 numeric Property ID
`GA_SERVICE_ACCOUNT_EMAIL`	`string`	Service account email from GCP
`GA_PRIVATE_KEY`	`string`	PEM private key (with \n escapes). Used by GA4 and Search Console.
`SEARCH_CONSOLE_SITE_URL`	`string`	Site URL as registered in Search Console (e.g. https://mysite.com). Read by the /api/search-console route.
`PAGESPEED_API_KEY`	`string (optional)`	PageSpeed Insights API key. Optional — lifts the rate limit for the /api/pagespeed route.