Cosmicjs Analytics Integrations: Setup Guide

Cosmic (formerly Cosmic JS) is a headless CMS that delivers content through a REST and GraphQL API. Like all headless CMS platforms, Cosmic has no frontend rendering layer -- analytics integration happens entirely in your frontend application (React, Next.js, Gatsby, Vue, Nuxt, etc.).

Integration Architecture

Cosmic is API-only with no server-rendered output:

1. Frontend Framework -- Your application handles all script loading, GTM initialization, and event firing. Cosmic has no involvement in page rendering.
2. Cosmic API -- The Bucket API (/v3/buckets/:slug/objects) returns structured content (Object Type, metadata, locale) that can populate your data layer.
3. Cosmic Webhooks -- Fire on content CRUD operations. Useful for cache invalidation and CI/CD triggers, not for user analytics.

There is no Cosmic admin-level analytics setting, no plugin marketplace, and no built-in tracking.

Available Integrations

Analytics Platforms

Google Analytics 4

• Frontend gtag.js integration
• GTM-based GA4 with Cosmic content data layer

Tag Management

Google Tag Manager

• App shell script injection
• SPA route-change tracking required

Marketing Pixels

Meta Pixel

• Via GTM container (recommended)
• Direct fbq integration

Next.js + Cosmic Example

Build a data layer from Cosmic API responses on each page render:

// app/posts/[slug]/page.tsx (Next.js App Router + Cosmic)
import { cosmic } from '@/lib/cosmic';

export default async function Post({ params }) {
  const { object } = await cosmic.objects
    .findOne({ type: 'posts', slug: params.slug })
    .props('title,slug,metadata,type,created_at')
    .depth(1);

  return (
    <>
      <script
        dangerouslySetInnerHTML={{
          __html: `
            window.dataLayer = window.dataLayer || [];
            window.dataLayer.push({
              event: 'virtual_pageview',
              content_type: '${object.type}',
              page_title: ${JSON.stringify(object.title)},
              author: ${JSON.stringify(object.metadata?.author?.title || '')},
              category: ${JSON.stringify(object.metadata?.category?.title || '')},
              publish_date: '${object.created_at}'
            });
          `,
        }}
      />
      <article>{/* render content */}</article>
    </>
  );
}

Cosmic Object Types for Data Layer

Cosmic organizes content into Object Types (similar to content types in other CMS platforms). Map these to analytics dimensions:

Platform Limitations

No platform-level tracking. Cosmic has no built-in analytics. There is no dashboard, no script injection field, and no tracking configuration in the Cosmic admin. All tracking is implemented in your frontend code.

SPA route tracking. Single-page application frontends require manual virtual pageview events on route changes. Cosmic's API calls happen in the background; GTM does not detect them as page navigations.

Object Type changes. If you rename or restructure Object Types in Cosmic, your data layer mapping breaks. Keep content type slugs stable or implement a mapping layer in your frontend that normalizes Object Type names for analytics.

Media delivery. Cosmic serves media through its own CDN (imgix.cosmicjs.com). This is separate from your frontend's domain. Image-heavy pages trigger cross-origin requests that compete with tracking script downloads.

Preview mode. Cosmic supports draft content preview via API parameters (?status=any). If preview URLs are publicly accessible, they may generate analytics events for unpublished content. Gate preview mode behind authentication or exclude it from tracking.

Performance Considerations

• GraphQL vs REST. Cosmic's GraphQL API allows you to request only the fields needed for the data layer, reducing payload size. REST responses include all Object fields by default.
• SSG/ISR benefits. Use static site generation or incremental static regeneration to pre-render pages with data layer values baked into the HTML. This eliminates runtime API calls and ensures the data layer is available before GTM fires.
• SDK bundle. The @cosmicjs/sdk package adds ~8KB gzipped. Use direct fetch() calls instead if you want to minimize bundle size.

Recommended Integration Priority

1. Add GTM to frontend app shell -- Single container for all tracking
2. Implement SPA route tracking -- Virtual pageview events on every navigation
3. Map Cosmic Object Types to data layer -- Use Object Type slug as content_type dimension
4. Configure GA4 in GTM -- Content groups from Cosmic categories, custom dimensions from metadata
5. Add Meta Pixel via GTM -- Map content engagement to Meta standard events

Next Steps

• Install Google Analytics 4
• Install Google Tag Manager
• Install Meta Pixel

For general integration concepts, see the integrations overview.