Beginner’s Guide: Integrating Sitecore CDP with XM Cloud (Using the Cloud SDK)

September 04, 2025

If you're new to integrating Sitecore XM Cloud with Sitecore CDP, you're in the right place.

When I first worked with the XM Cloud Starter Kit and CDP, I found the documentation scattered—especially regarding the differences between the Engage SDK and Cloud SDK.

This post is a real-world, beginner-friendly guide to integrating CDP into an XM Cloud project.

🎯 Two SDKs for Sitecore CDP

There are two SDKs for Sitecore CDP integration, each serving a different use case:

1. Engage SDK

✅ Use when not using XM Cloud
Designed for standalone front-end apps (Next.js, React, etc.)
Requires manual installation and configuration
Not pre-integrated with XM Cloud

2. Cloud SDK

✅ Use with XM Cloud Starter Kit
Already included in the starter kit
Seamlessly integrates with CDP
No manual setup required

🔍 Note: This post focuses on the Cloud SDK. The Engage SDK will be covered in a future guide.

❓ First Confusion: “Where’s the CDP Client ID?”

If you’ve started exploring the XM Cloud Starter Kit, you might notice that it never asks for a CDP Client ID, unlike many tutorials.

Once you dive into the code, you’ll realize:
➡️ There’s no CDP Client ID being passed.

Why?

The Cloud SDK doesn’t need it directly. Instead, it uses an environment variable:


SITECORE_EDGE_CONTEXT_ID

This acts as the connection between your XM Cloud project and Sitecore CDP. It’s automatically picked up by the Cloud SDK — no need to expose or configure the Client ID manually.

🔍 Key Files for CDP Integration

Running the Starter Kit

You’ll typically use one of these two commands:


npm run start:production   # Runs in production mode(set process.env.NODE_ENV =production)
npm run start:connected    # Runs in development mode (set process.env.NODE_ENV =development)

⚠️ Behavior of CDP-related code varies by environment — especially for development vs production.

1. `bootstrap.tsx` — Initialization

Purpose: Initializes Sitecore Cloud SDK features
Location: Imported in _app.tsx
CDP Handling: Uses SITECORE_EDGE_CONTEXT_ID

Default behavior:


if (process.env.NODE_ENV === 'development') {
  console.debug('Browser Events SDK is not initialized in development environment');
}

CDP tracking is disabled locally by default for development environment.

🔧 Enabling CDP Tracking Locally

You have two options:

Option A: Run in Production Mode

Run using npm run start:production

Option B: Modify for Development Mode

Use npm run start:connected
Modify bootstrap.tsx to allow CDP tracking in development:


// Replace or remove the condition:
if (process.env.NODE_ENV === 'development') {
  // Instead of blocking, initialize the SDK here
}

2. `CdPPageView.tsx` — Page View Tracking

Purpose: Sends pageView events to CDP on route changes
Location: Imported into layout or _app.tsx

Default logic:


const disabled = () => {
  return process.env.NODE_ENV === 'development';
};

if (disabled()) return; // CDP tracking disabled in development

🔧 To enable in development:

Same options as above:

Run in production mode ()
Or remove/adjust the condition to enable in development

📌 Add `CdpPageView` to Your Layout

To ensure page view tracking works on all routes, include the component in your layout:


import CdpPageView from './components/CdpPageView';

const renderContent = () => (
  <>
    <header>
      <div id="header">{route && <Placeholder name="headless-header" rendering={route} />}</div>
      <CdpPageView />
    </header>
    {route && <Placeholder name="headless-main" rendering={route} />}
    <footer>
      <div id="footer">{route && <Placeholder name="headless-footer" rendering={route} />}</div>
    </footer>
  </>
);

⚙️ What Happens Behind the Scenes?

When a page is loaded, the following code is triggered:


pageView({
  channel: 'WEB',
  currency: 'USD',
  page: route.name,
  pageVariantId,
  language,
}).catch((e) => console.debug(e));

This:

Sends a pageView event to CDP
Creates a guest profile (if new)
Sets a CDP tracking cookie

Similar to how Sitecore XP tracks anonymous visitors.

🙋 Identifying Known Users

After a user logs in or signs up, use the identity() method to convert the guest to a known user:


identity({
  channel: 'WEB',
  currency: 'USD',
  firstName: 'Chandan',
  lastName: 'Kumar',
  email: 'chandan@example.com',
  identifiers: [
    {
      provider: 'Email',
      id: 'chandan@example.com',
    },
  ],
}).catch((e) => console.debug(e));

✅ Make sure Email is a valid identifier in your CDP settings.
Go to the Sitecore CDP instance, and you can see the Settings section. Inside Settings, you will find the option to create an Identifier.

✅ Verification Checklist

Check browser cookies for CDP tracking data-sc_key should get created on page load. The value of this key can be used to search the guest in Sitecore CDP

Use DevTools → Network tab → Look for pageView and identity events-these two vents must get triggered i.you can find this in network tab

Search for the guest in CDP using their email

🧠 Summary

✅ Use the Cloud SDK with XM Cloud — it’s pre-installed
❌ No need to manually configure the CDP Client ID
⚠️ CDP tracking is disabled by default in dev — update the logic to enable it
🔍 bootstrap.tsx and CdpPageView.tsx are the key files
🙋 Use identity() to enrich guest profiles after login

Search This Blog

Sitecore