Sanity Integrations Overview | Blue Frog Docs

Sanity Integrations Overview

Available integrations for Sanity-powered sites including analytics platforms, tag managers, and marketing pixels.

Sanity Integrations Overview

Sanity is a headless CMS that delivers content via API to your frontend framework. Since Sanity doesn't render the frontend itself, all tracking and analytics are implemented in your chosen frontend framework (Next.js, Gatsby, Remix, SvelteKit, etc.).

Available Integrations

Analytics Platforms

Google Analytics 4

  • Frontend framework implementation (Next.js, Gatsby, Remix, etc.)
  • Real-time content tracking with GROQ queries
  • Custom event tracking for Sanity content types
  • Portable Text content analytics

Tag Management

Google Tag Manager

  • Framework-specific GTM installation
  • Data layer structure for Sanity documents
  • SSR/SSG compatibility with Next.js, Gatsby, Remix
  • Dynamic content tracking from GROQ queries

Marketing Pixels

Meta Pixel

Sanity-Specific Integration Considerations

Headless CMS Architecture

Sanity's architecture separates content management from presentation:

  • Sanity Studio: Visual content editing (React-based)
  • Content Lake: Hosted content storage
  • GROQ/GraphQL: Query languages for fetching content
  • Frontend Framework: Where all tracking is implemented

Content Delivery Methods

Real-time Preview (Sanity Live):

  • Content updates without rebuild
  • Special handling for analytics in preview mode
  • Exclude preview sessions from production analytics

CDN-Cached Content:

  • Static content delivery via Sanity CDN
  • Cache-aware analytics implementation
  • Consider cache timing in event tracking

On-Demand ISR:

  • Incremental Static Regeneration support
  • Track content freshness
  • Monitor revalidation patterns

Common Frontend Frameworks with Sanity

Next.js (Most Popular)

  • App Router and Pages Router support
  • Server Components and Client Components tracking
  • Sanity's official Next.js toolkit integration
  • API routes for server-side tracking

Remix

  • Loader/Action-based data fetching
  • Progressive enhancement considerations
  • SSR-first tracking approach
  • Streaming support

Gatsby

SvelteKit

  • Server-side rendering support
  • Load functions for data fetching
  • Stores for reactive analytics
  • Adapter flexibility

GROQ Query Integration

Leverage GROQ queries for rich analytics data:

// Fetch content with analytics-relevant fields
const query = groq`*[_type == "article" && slug.current == $slug][0]{
  _id,
  title,
  "slug": slug.current,
  publishedAt,
  "author": author->name,
  "categories": categories[]->title,
  body
}`

// Track with fetched metadata
gtag('event', 'view_content', {
  content_id: article._id,
  content_title: article.title,
  content_category: article.categories?.join(','),
  author: article.author
});

Portable Text Tracking

Track engagement with structured content:

// Track reading progress through Portable Text blocks
function trackBlockEngagement(blockKey, timeSpent) {
  gtag('event', 'content_block_engagement', {
    block_key: blockKey,
    time_spent_seconds: timeSpent,
    content_id: article._id
  });
}

Preview Mode Considerations

Handle Sanity preview modes appropriately:

// Next.js example with preview mode
import { draftMode } from 'next/headers';

export default async function Page() {
  const { isEnabled } = draftMode();

  // Skip analytics in preview mode
  if (!isEnabled) {
    trackPageView();
  }

  return <Content />;
}

Integration Best Practices

1. Use Sanity Document IDs

Track content using stable Sanity document IDs:

// Use _id for consistent tracking across URL changes
gtag('event', 'view_content', {
  content_id: document._id, // Stable ID
  content_slug: document.slug.current, // May change
  content_revision: document._rev // Track revisions
});

2. Track Content Types

Leverage Sanity's schema for content classification:

gtag('event', 'content_view', {
  content_type: document._type,
  content_id: document._id,
  schema_version: '2024-01' // Track schema versions
});

3. Monitor Real-time Content

Track live content updates:

// With Sanity's real-time listener
client.listen(query, params).subscribe(update => {
  gtag('event', 'content_updated', {
    document_id: update.documentId,
    update_type: update.transition
  });
});

4. Handle Localized Content

For multi-language Sanity projects:

gtag('event', 'page_view', {
  content_id: document._id,
  content_locale: document.__i18n_lang || 'en',
  localization_strategy: 'field-level' // or 'document-level'
});

Testing Integrations

Verify tracking across different scenarios:

Draft Content:

  • Exclude from production analytics
  • Test preview mode handling
  • Verify draft/published distinction

CDN-Cached Pages:

  • Test cache hit vs miss behavior
  • Verify analytics on cached content
  • Monitor stale-while-revalidate

Real-time Updates:

  • Test live preview tracking
  • Verify content refresh events
  • Monitor subscription events

Next Steps

Choose your integration to get started:

Additional Resources

Sanity Documentation:

↑ Back to top
// SYS.FOOTER