API Reference

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

Exports

The plugin has two entry points:

sanity-plugin-ga-dashboard

Main entry — exports the plugin function for Sanity config.

sanity-plugin-ga-dashboard/api

API entry — exports the GET handler for your Next.js API route.

`googleAnalyticsPlugin`

The main plugin function that registers the Google Analytics tool in Sanity Studio.

typescript

import { googleAnalyticsPlugin } from 'sanity-plugin-ga-dashboard'

// Usage
googleAnalyticsPlugin(config?: GoogleAnalyticsPluginConfig): SanityPlugin

`GET`

The API route handler that fetches analytics data from GA4.

typescript

import { GET } from 'sanity-plugin-ga-dashboard/api'

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

// Signature
GET(request: NextRequest): Promise<NextResponse<AnalyticsData>>

Types

GoogleAnalyticsPluginConfig

typescript

interface GoogleAnalyticsPluginConfig {
  /**
   * URL of the API endpoint that serves analytics data.
   * @default '/api/analytics'
   */
  apiUrl?: string
}

AnalyticsData

The response shape returned by the GET handler:

typescript

interface AnalyticsData {
  dateRange: DateRange
  overview: OverviewMetrics
  timeSeries: TimeSeriesPoint[]
  hourlyData: HourlyPoint[]
  topPages: PageData[]
  topLandingPages: LandingPageData[]
  deviceCategory: DeviceCategoryData[]
  browsers: BrowserData[]
  operatingSystems: OSData[]
  countries: CountryData[]
  cities: CityData[]
  trafficSources: TrafficSourceData[]
  channelGrouping: ChannelData[]
  newVsReturning: NewVsReturningData[]
  topEvents: EventData[]
  topReferrers: ReferrerData[]
  realTimeUsers: number
}

OverviewMetrics

typescript

interface OverviewMetrics {
  totalUsers: string
  sessions: string
  screenPageViews: string
  bounceRate: string
  avgSessionDuration: string
  screenPageViewsPerSession: string
  newUsers: string
  eventCount: string
  conversions: string
  totalRevenue: string
}

DateRange

typescript

interface DateRange {
  startDate: string  // YYYY-MM-DD format
  endDate: string    // YYYY-MM-DD format
  days: number       // 7, 14, 30, or 90
}

Common Data Types

typescript

interface TimeSeriesPoint {
  date: string
  sessions: number
  screenPageViews: number
}

interface HourlyPoint {
  hour: string
  activeUsers: number
}

interface PageData {
  pagePath: string
  screenPageViews: number
}

interface LandingPageData {
  landingPage: string
  sessions: number
}

interface DeviceCategoryData {
  deviceCategory: string
  sessions: number
}

interface BrowserData {
  browser: string
  sessions: number
}

interface OSData {
  operatingSystem: string
  sessions: number
}

interface CountryData {
  country: string
  activeUsers: number
}

interface CityData {
  city: string
  activeUsers: number
}

interface TrafficSourceData {
  sessionSource: string
  sessions: number
}

interface ChannelData {
  sessionDefaultChannelGrouping: string
  sessions: number
}

interface NewVsReturningData {
  newVsReturning: string
  activeUsers: number
}

interface EventData {
  eventName: string
  eventCount: number
}

interface ReferrerData {
  pageReferrer: string
  sessions: number
}

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)