Consolidated analytics, events, and tracking in Content SDK v2.0

What's happened to Cloud SDK?

If you've worked with Sitecore XM Cloud's analytics and tracking before Content SDK v2.0, you've dealt with the Cloud SDK. It had a separate initialization path, its own lifecycle, and a pattern that always felt slightly disconnected from the rest of your front-end. With Content SDK v2.0, Sitecore has consolidated that functionality into three focused packages and a single initialization function. The result is a cleaner, more modular approach that fits naturally into how we already build Next.js applications.

With that in mind, let's have a look at what changed, why it matters, and how to migrate.

The old way using Cloud SDK

Previously, analytics and event tracking in XM Cloud relied on the Cloud SDK which was nothing more than a standalone package with its own initialization:

//TODO: Confirm exact old CloudSDK init pattern from your project
import { CloudSDK } from '@sitecore-cloudsdk/core';
import '@sitecore-cloudsdk/events';
import '@sitecore-cloudsdk/personalize';
// Initialization typically happened in _app.tsx or a layout component
await CloudSDK({
  siteName: process.env.SITECORE_SITE_NAME,
  sitecoreEdgeContextId: process.env.SITECORE_EDGE_CONTEXT_ID,
  // ... additional config
}).initialize();

This worked, but had some challenges:

• Separate lifecycle: Cloud SDK initialized independently from your Content SDK / JSS setup, meaning two initialization paths to manage and debug.
• Monolithic imports: Even if you only needed page view events, you pulled in the full stack.
• Tree-shaking challenges: The package structure made it harder for bundlers to eliminate unused code.
• Disconnect from component data flow: Analytics lived next to your components rather than being part of the same SDK pipeline.

The new way to initialize via initContentSdk and plugins

Content SDK v2.0 replaces Cloud SDK with a plugin-based architecture. Everything runs through a single initContentSdk function, and you opt into capabilities by registering plugins:

//TODO: Confirm exact import paths and plugin registration API
import { initContentSdk } from '@sitecore-content-sdk/core';
import { analyticsPlugin } from '@sitecore-content-sdk/analytics-core';
import { eventsPlugin } from '@sitecore-content-sdk/events';
await initContentSdk({
  siteName: process.env.SITECORE_SITE_NAME,
  sitecoreEdgeContextId: process.env.SITECORE_EDGE_CONTEXT_ID,
  plugins: [
    analyticsPlugin(),
    eventsPlugin(),
    // personalize plugin covered in Part 7
  ],
});

What's the purpose of each

• @sitecore-content-sdk/analytics-core — The foundational analytics layer. Handles core tracking infrastructure including page views, session management, and the data pipeline to Sitecore's analytics backend. This is the package you'll always include if you need any analytics at all.
• @sitecore-content-sdk/events — Custom event tracking. If you're firing events beyond basic page views including button clicks, form submissions, video plays, custom engagement goals. It's this package that provides that API. Registers via eventsPlugin.
• @sitecore-content-sdk/personalize — Handles personalization variant resolution and audience evaluation on the front-end. We'll cover this in depth in Part 7 of this series, but know that it follows the same plugin pattern.

Why this is better

Migrating from Cloud SDK to Content SDK 2.0+ for managing the Sitecore CDP and Personalize improves things on a number of levels including:

• Having a single initialization call
• Only importing the necessary plugins that you require
• Being able to better utilize environment variables
• And perhaps most significantly, having it part of the upgrade strategy of Content SDK

Migration: Cloud SDK to Content SDK v2.0

Step 1: install the new packages

npm install @sitecore-content-sdk/analytics-core @sitecore-content-sdk/events
# If using personalization:
npm install @sitecore-content-sdk/personalize

Step 2: remove old Cloud SDK packages

npm uninstall @sitecore-cloudsdk/core @sitecore-cloudsdk/events @sitecore-cloudsdk/personalize

Step 3: update initialization

Find where you previously called CloudSDK().initialize() which typically resides in _app.tsx, a layout component, or a dedicated initialization file. Replace it with initContentSdk and the appropriate plugins.

// Before
import { CloudSDK } from '@sitecore-cloudsdk/core';
import '@sitecore-cloudsdk/events';
await CloudSDK({
  siteName: process.env.SITECORE_SITE_NAME,
  sitecoreEdgeContextId: process.env.SITECORE_EDGE_CONTEXT_ID,
}).initialize();
// After
import { initContentSdk } from '@sitecore-content-sdk/core';
import { analyticsPlugin } from '@sitecore-content-sdk/analytics-core';
import { eventsPlugin } from '@sitecore-content-sdk/events';
await initContentSdk({
  siteName: process.env.SITECORE_SITE_NAME,
  sitecoreEdgeContextId: process.env.SITECORE_EDGE_CONTEXT_ID,
  plugins: [
    analyticsPlugin(),
    eventsPlugin(),
  ],
});

Step 4: update event calls

If you had custom event tracking code you'll want to update each to utilize the new endpoints. This might be things like custom calls to personalize endpoints for dealing with certain events.

Step 5: update environment variables

Add the new custom Edge hostname variable if you're using custom domains:

SITECORE_EDGE_PLATFORM_HOSTNAME=media.abccompany.com

This is a direct improvement related to what I covered in my Custom Domains article. Previously, configuring custom Edge hostnames required manual URL transformation in your front-end code. The new SITECORE_EDGE_PLATFORM_HOSTNAME environment variable provides native SDK support for this. Migrating to this though in other environments may require additional work as you potentially have created custom rewrite urls for dealing with all that.

Custom Edge hostname support

This deserves its own callout. In my earlier article on custom domains, we built a getTransformedMediaUrl function to rewrite edge.sitecorecloud.io URLs to a custom domain for SEO and indexing purposes. We also discussed why first-party domains matter for analytics tracking.

Content SDK v2.0 now supports custom Edge hostnames natively:

SITECORE_EDGE_PLATFORM_HOSTNAME=media.abccompany.com

What this means in practice:

• Analytics requests can now route through your own domain without custom code
• First-party tracking becomes simpler. Which is great because it means no more CORS workarounds for analytics endpoints
• SEO benefits you get from custom domains now extend cleanly to the tracking layer

Custom query parameters in editing render handlers

A smaller but notable addition: Content SDK v2.0 supports custom query parameters in editing render handlers. This is useful when:

• You need to pass debug flags to the rendering host during editing
• Your components require additional context that isn't available through standard Sitecore fields
• You're building custom editing experiences that need to communicate state

What this means for your existing components

This might not impact you terribly much unless you're really utilizing everything within Sitecore CDP and Personalize.

Components using Cloud SDK directly

If any of your components imported from @sitecore-cloudsdk/*directly (rather than relying on the global initialization), those imports will break. Audit your codebase:

# Find all CloudSDK references
grep -r "@sitecore-cloudsdk" src/

Audit checklist

Creating yourself an audit checklist is a handy way to verify your own work. You might have an existing one already that you want to expand upon as you perhaps do this multiple times for multiple clients.

• Global Cloud SDK initialization replaced with initContentSdk
• All @sitecore-cloudsdk/* imports updated to new packages
• Custom event tracking code updated to new API
• Environment variables updated (SITECORE_EDGE_PLATFORM_HOSTNAME if using custom domains)
• Old Cloud SDK packages removed from package.json
• Analytics verified in non-production environment before deploying

Testing analytics and custom domains after migration

Don't skip this. Analytics bugs are silent. You don't really notice unless you go looking.

• Verify page view events fire in browser dev tools (Network tab, filter by your analytics endpoint)
• Confirm custom events still dispatch correctly
• Check that personalization variant resolution still works (if applicable)
• Test in both SSR and client-side navigation scenarios
• Validate that editing mode (Pages / Experience Editor) still functions without analytics interference
• Verify custom domains for media items work as they should in both normal mode and editing mode

Wrapping it all up

The consolidation of Cloud SDK into Content SDK is one of those changes that's easy to underestimate. On paper it largely just involves swapping imports. In practice, it means one initialization path, one versioning story, and a plugin model that lets you include only what you need.

If you've been maintaining a Sitecore XM Cloud project with analytics, this migration is straightforward but worth doing carefully, especially the analytics verification step. Honestly, this is what gets most people because they don't actually verify events are happening and triggering.