Install and initialize the Cloud SDK

Version:

Before you can start using the Cloud SDK, you have to install and initialize all the SDK packages packages you want to use, and then import their modules modules. For more information, see Initializing the Cloud SDK.

JSS Next.js

In this topic, you install and initialize all SDK packages on the browser side in a JSS Next.js app (JSS version 22.7).

JSS Next.js apps already initialize the Cloud SDK core and events packages on the browser side, in Bootstrap.tsx, with no coding required. If you don't want to use other SDK packages in your app, you don't need to complete this walkthrough.

Only complete this walkthrough if you want to use other SDK packages on the browser side, such as the personalize package.

Before you begin

Make sure you're ready to start development with the Cloud SDK.
In production, only initialize the Cloud SDK and set cookies if your site visitor grants consent. See also a code example to check if your site visitor accepts cookies.

To install and initialize the Cloud SDK on the browser side:

In your code editor, open your JSS Next.js app folder. This is the folder where you added environment variables when you set up your local development environment.
Open package.json and check that the following SDK packages are installed in your project:
- @sitecore-cloudsdk/core
- @sitecore-cloudsdk/events
Open the terminal and install any other SDK packages you want to use by running the following command:
npm install @sitecore-cloudsdk/personalize npm install @sitecore-cloudsdk/search
Open Bootstrap.tsx. This component already initializes the Cloud SDK and the events package. You'll update the component code in the next step to initialize other SDK packages, such as personalize.
At the top of the file, directly below the CloudSDK import statement, import the browser module of the packages you installed in a previous step:
// ... import "@sitecore-cloudsdk/personalize/browser"; import "@sitecore-cloudsdk/search/browser";
In the Effect Hook, in the CloudSDK function, directly before the initialize method, paste the following code, then save your changes:
// ... .addPersonalize({ enablePersonalizeCookie: true, webPersonalization: { language: 'en' } }) .addSearch() // ...
This code initializes the personalize and the search packages and enables the cookie required for personalization. It also enables Sitecore Personalize web personalizations. If you don't want to enable web personalizations, set webPersonalization: false.

Note

The language parameter was added to the addPersonalize method's webPersonalization property in Cloud SDK 0.5.6 to support languages for web personalization.
In your terminal, enter npm run start:production to start your JSS Next.js app.
In your web browser, navigate to your JSS Next.js app, typically at http://localhost:3000.
In your web browser console, enter window.scCloudSDK. If an object returns, you have successfully initialized the SDK.

Tip

This object lists all the packages you have initialized and their version. Use this in any future implementations to quickly verify that the SDK is correctly initialized.
Optionally, in your web browser's developer tools, in Cookies, find at least one cookie that starts with sc_. This is another way to verify that you've successfully initialized the Cloud SDK.

You can now run other browser-side SDK code in the rest of your app.

Next.js

In this topic, you install and initialize all SDK packages in a Next.js app. In production, only initialize the packages you need depending on your application requirements and your Sitecore subscriptions.

Before you begin

Make sure you're ready to start development with the Cloud SDK.

Browser side

On the browser side, initialize the SDK once, in a centralized place, on app initialization. For example, in a Next.js App Router app, initialize the SDK in an Effect Hook in a component, then add that component to layout.tsx. This ensures that the initialization runs only once, centrally.

To install and initialize the Cloud SDK on the browser side:

In your code editor, in the root folder of your web app, open the terminal and install the core package and any other SDK packages you want to use by running the following commands:
npm install @sitecore-cloudsdk/core npm install @sitecore-cloudsdk/events npm install @sitecore-cloudsdk/personalize npm install @sitecore-cloudsdk/search
The core package contains the SDK initialization logic. The other packages contain code for setting up Sitecore DXP Sitecore DXP capabilities.
Create a component, for example, /components/CloudSDK.tsx.

Depending on your router type, paste the following code into CloudSDK.tsx, then save your changes:

If using the Pages Router:

import { useEffect } from "react";
// Import SDK modules ->
import { CloudSDK } from "@sitecore-cloudsdk/core/browser";
import "@sitecore-cloudsdk/events/browser";
import "@sitecore-cloudsdk/personalize/browser";
import "@sitecore-cloudsdk/search/browser";
// <- Import SDK modules

export default function CloudSDKComponent() {
  useEffect(() => {
    CloudSDK({
      sitecoreEdgeContextId: "<YOUR_SITECORE_EDGE_CONTEXT_ID>",
      siteName: "<YOUR_SITE_NAME>",
      enableBrowserCookie: true
    })
     .addEvents() // Initialize the events package
     .addPersonalize({ enablePersonalizeCookie: true, webPersonalization: { language: 'en' } }) // Initialize the personalize package
     .addSearch() // Initialize the search package
     .initialize();  // Run the initialization logic and set cookies
  }, []);

  return null;
};

If using the App Router:

"use client";
import { useEffect } from "react";
// Import SDK modules ->
import { CloudSDK } from "@sitecore-cloudsdk/core/browser";
import "@sitecore-cloudsdk/events/browser";
import "@sitecore-cloudsdk/personalize/browser";
import "@sitecore-cloudsdk/search/browser";
// <- Import SDK modules

export default function CloudSDKComponent() {
  useEffect(() => {
    CloudSDK({
      sitecoreEdgeContextId: "<YOUR_SITECORE_EDGE_CONTEXT_ID>",
      siteName: "<YOUR_SITE_NAME>",
      enableBrowserCookie: true
    })
     .addEvents() // Initialize the events package
     .addPersonalize({ enablePersonalizeCookie: true, webPersonalization: { language: 'en' } }) // Initialize the personalize package
     .addSearch() // Initialize the search package
     .initialize();  // Run the initialization logic and set cookies
  }, []);

  return null;
};

Replace the placeholder values with the required details you collected when you prepared for development.

This code runs the CloudSDK function, which initializes the Cloud SDK using your Context ID and site name, and it sets cookies from the browser side. It also initializes the events, personalize, and search packages, and it enables Sitecore Personalize web personalizations. If you don't want to enable web personalizations, set webPersonalization: false.

The component is now ready to be used elsewhere in your app.

Depending on your router type:

If using the Pages Router - add the component you just created to _app.tsx, in the return statement directly above <Component />:

// ...
import CloudSDKComponent from "@/components/CloudSDK";

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <CloudSDKComponent />
      <Component {...pageProps} />
    </>
  );
}

If using the App Router - add the component you just created to layout.tsx, directly inside the <body> tag, before {children}, then save your changes:

import CloudSDKComponent from "../components/CloudSDK";

// ...

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <CloudSDKComponent />
        {children}
      </body>
    </html>
  );
}

This code initializes the SDK once, on app initialization. Because this code runs in the app's root layout, the SDK code will be available globally, on all routes of your app.

Start your app by entering the following command in your terminal:
npm run dev
In your web browser, navigate to your Next.js app, typically at http://localhost:3000.
In your web browser console, enter window.scCloudSDK. If an object returns, you have successfully initialized the SDK.

Tip

This object lists all the packages you have initialized and their version. Use this in any future implementations to quickly verify that the SDK is correctly initialized.
Optionally, in your web browser's developer tools, in Cookies, find at least one cookie that starts with sc_. This is another way to verify that you've successfully initialized the Cloud SDK.

You can now run other browser-side SDK code in the rest of your app. For example, you can start setting up tracking by capturing VIEW events.

Server side

On the server side, initialize the SDK in every file that is intended to run Cloud SDK code. Depending on your application, these files might contain a page request, an API request, or a middleware request.

To install and initialize the Cloud SDK on the server side, in a middleware:

In your code editor, in the root folder of your web app, open the terminal and install the core package and any other SDK packages you want to use by running the following commands:
npm install @sitecore-cloudsdk/core npm install @sitecore-cloudsdk/events npm install @sitecore-cloudsdk/personalize npm install @sitecore-cloudsdk/search
The core package contains the SDK initialization logic. The other packages contain code for setting up Sitecore DXP Sitecore DXP capabilities.
Create middleware.ts in the src or the src/app folder, depending on your project structure.

Paste the following code into middleware.ts, then save your changes:

import type { NextRequest } from "next/server";
import { NextResponse } from "next/server";

// Import SDK modules ->
import { CloudSDK } from "@sitecore-cloudsdk/core/server";
import "@sitecore-cloudsdk/events/server";
import "@sitecore-cloudsdk/personalize/server";
import "@sitecore-cloudsdk/search/server";
// <- Import SDK modules

export default async function middleware(request: NextRequest) {
  const response = NextResponse.next();
  await CloudSDK(request, response, {
    sitecoreEdgeContextId: "<YOUR_SITECORE_EDGE_CONTEXT_ID>",
    siteName: "<YOUR_SITE_NAME>",
    enableServerCookie: true
  })
   .addEvents() // Initialize the events package
   .addPersonalize({ enablePersonalizeCookie: true, webPersonalization: { language: 'en' } }) // Initialize the personalize package
   .addSearch() // Initialize the search package
   .initialize(); // Run the initialization logic and set cookies
   
   return response;
};

Replace the placeholder values with the required details you collected when you prepared for development.

This code runs the CloudSDK function, which initializes the Cloud SDK using your Context ID and site name, and it sets cookies from the server side. It also initializes the events, personalize, and search packages.

Start your app by entering the following command in your terminal:
npm run dev
In your web browser, navigate to your Next.js app, typically at http://localhost:3000.
In your web browser's developer tools, in Cookies, find at least one cookie that starts with sc_. If such a cookie is present, you've successfully initialized the Cloud SDK.

You can now run other server-side SDK code in this file. For example, you can start setting up tracking by capturing VIEW events.

To run SDK code in other server-side files that handle page requests, API requests, or middleware requests, you'll have to import CloudSDK and the other SDK package modules into those files, and you'll have to run the CloudSDK function and initialize the SDK packages, depending on your application requirements.

You've now successfully installed and initialized the Cloud SDK. You are now ready to set up the following Cloud SDK capabilities to ensure that your web app uses the full potential of Sitecore DXP products:

We also recommend that you:

Explore the reference documentation for all Cloud SDK packages and modules.
Learn about Cloud SDK cookies.
Learn more about the SDK initialization process.

If you have suggestions for improving this article, let us know!