--- title: "Install and initialize the Cloud SDK" slug: "install-and-initialize-the-cloud-sdk" abstract: "Install the Cloud SDK and the SDK packages, and initialize their modules in your code so you can start setting up Cloud SDK functionality." --- # Install and initialize the Cloud SDK Before you can [start using the Cloud SDK](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/developer-guides.html "Developer guides"), you have to install and initialize all the SDK packages[^UUID-101b62f6-b640-ed11-1057-29646ebb9fb7_N665975d2b0614] you want to use, and then import their modules[^UUID-101b62f6-b640-ed11-1057-29646ebb9fb7_N665976bebafe9]. For more information, see [Initializing the Cloud SDK](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/cloud-sdk-concepts/initializing-the-cloud-sdk.html "Initializing the Cloud SDK"). ::::tabs :::tab{title="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](https://github.com/sitecorelabs/xmcloud-foundation-head/blob/main/headapps/nextjs-starter/package.json)). JSS Next.js apps already initialize the Cloud SDK `core` and `events` packages on the browser side, in [`Bootstrap.tsx`](https://github.com/Sitecore/jss/blob/dev/packages/create-sitecore-jss/src/templates/nextjs-xmcloud/src/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. > [!note] > **Before you begin** > - Make sure you're [ready to start development](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/getting-started/prerequisites.html "Prerequisites") 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](https://doc.sitecore.com/sdk/en/developers/004/cloud-sdk/en/cloud-sdk-cookies.html#UUID-a0454bd7-595b-1af9-43db-d9211d0960b4_section-idm234766426989109) to check if your site visitor accepts cookies. To install and initialize the Cloud SDK on the browser side: 1. 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](https://doc.sitecore.com/xmc/en/developers/xm-cloud/en/set-up-your-local-development-environment.html). 2. Open `package.json` and check that the following SDK packages are installed in your project: - `@sitecore-cloudsdk/core` - `@sitecore-cloudsdk/events` 3. Open the terminal and install any other SDK packages you want to use by running the following command: ```bash npm install @sitecore-cloudsdk/personalize npm install @sitecore-cloudsdk/search ``` 4. Open [`Bootstrap.tsx`](https://github.com/Sitecore/jss/blob/dev/packages/create-sitecore-jss/src/templates/nextjs-xmcloud/src/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`. 5. 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: ```typescript // ... import "@sitecore-cloudsdk/personalize/browser"; import "@sitecore-cloudsdk/search/browser"; ``` 6. In the Effect Hook, in the `CloudSDK` function, directly before the `initialize` method, paste the following code, then save your changes: ```typescript // ... .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](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/cloud-sdk-concepts/concepts-personalization/web-personalization.html "Web personalization"). 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. 7. In your terminal, enter `npm run start:production` to start your JSS Next.js app. 8. In your web browser, navigate to your JSS Next.js app, typically at `http://localhost:3000`. 9. 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. 10. 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. ::: :::tab{title="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. > [!note] > **Before you begin** > - Make sure you're [ready to start development](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/getting-started/prerequisites.html "Prerequisites") with the Cloud SDK. :::tab{title="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`](https://nextjs.org/docs/app/api-reference/file-conventions/layout). This ensures that the initialization runs only once, centrally. To install and initialize the Cloud SDK on the browser side: 1. 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: ```bash 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[^UUID-101b62f6-b640-ed11-1057-29646ebb9fb7_N6658898fbc9f0] capabilities. 2. Create a component, for example, `/components/CloudSDK.tsx`. 3. Depending on your router type, paste the following code into `CloudSDK.tsx`, then save your changes: - If using the *Pages Router*: ```typescript 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: "", siteName: "", 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*: ```typescript "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: "", siteName: "", 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](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/getting-started/prerequisites.html "Prerequisites") 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](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/cloud-sdk-concepts/concepts-personalization/web-personalization.html "Web personalization"). If you don't want to enable web personalizations, set `webPersonalization: false`. The component is now ready to be used elsewhere in your app. > [!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. 4. 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 ``: ```csharp // ... import CloudSDKComponent from "@/components/CloudSDK"; export default function App({ Component, pageProps }: AppProps) { return ( <> ); } ``` - If using the *App Router* - add the component you just created to `layout.tsx`, directly inside the `` tag, before `{children}`, then save your changes: ```typescript import CloudSDKComponent from "../components/CloudSDK"; // ... export default function RootLayout({ children }) { return ( {children} ); } ``` 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. 5. Start your app by entering the following command in your terminal: ```bash npm run dev ``` 6. In your web browser, navigate to your Next.js app, typically at `http://localhost:3000`. 7. 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. 8. 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](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/developer-guides/tracking/set-up-view-events.html "Set up VIEW events"). ::: :::tab{title="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: 1. 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: ```bash 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[^UUID-101b62f6-b640-ed11-1057-29646ebb9fb7_N6658898fbc9f0] capabilities. 2. Create `middleware.ts` in the `src` or the `src/app` folder, depending on your project structure. 3. Paste the following code into `middleware.ts`, then save your changes: ```typescript 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: "", siteName: "", 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](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/getting-started/prerequisites.html "Prerequisites") 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. 4. Start your app by entering the following command in your terminal: ```bash npm run dev ``` 5. In your web browser, navigate to your Next.js app, typically at `http://localhost:3000`. 6. 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](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/developer-guides/tracking/set-up-view-events.html "Set up 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](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/developer-guides.html "Developer guides") to ensure that your web app uses the full potential of Sitecore DXP products: - [Tracking](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/cloud-sdk-concepts/concepts-tracking.html "Tracking") - [Personalization](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/cloud-sdk-concepts/concepts-personalization.html "Personalization") - [Search experiences](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/cloud-sdk-concepts/concepts-search-experiences.html "Search experiences") We also recommend that you: - Explore the [reference documentation](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/cloud-sdk-reference.html "Sitecore Cloud SDK reference") for all Cloud SDK packages and modules. - Learn about [Cloud SDK cookies](https://doc.sitecore.com/sdk/en/developers/004/cloud-sdk/en/cloud-sdk-cookies.html). - Learn more about the [SDK initialization process](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/cloud-sdk-concepts/initializing-the-cloud-sdk.html "Initializing the Cloud SDK"). [^UUID-101b62f6-b640-ed11-1057-29646ebb9fb7_N665975d2b0614]: The Cloud SDK consists of *packages*. Each package represents a set of Sitecore DXP capabilities. Cloud SDK packages consist of `browser` and `server` modules. [^UUID-101b62f6-b640-ed11-1057-29646ebb9fb7_N665976bebafe9]: Cloud SDK packages consist of `browser` and `server` *modules*. Each module contains all the functions required to set up specific Sitecore DXP capabilities. The `browser` module is for setting them up on the browser side, and the `server` module is for setting them up on the server side. [^UUID-101b62f6-b640-ed11-1057-29646ebb9fb7_N6658898fbc9f0]: A suite of [SaaS-enabled Sitecore products](https://www.sitecore.com/products), each offering rich digital experience capabilities such as tracking, personalization, and search. The Cloud SDK supports the following Sitecore products: - Sitecore CDP - Sitecore Personalize - Sitecore Search