--- title: "Initializing the Cloud SDK" slug: "initializing-the-cloud-sdk" abstract: "Understand initializing the Cloud SDK: what happens during initialization, and which initialization option to choose." --- # Initializing the Cloud SDK How you initialize the Cloud SDK depends on what SDK functionalities you want to set up, the type of application you have, and whether you want to run SDK code on the browser side or on the server. ## SDK functionalities are available in packages Initializing the SDK involves installing all the SDK packages[^UUID-101b62f6-b640-ed11-1057-29646ebb9fb7_N665975d2b0614] you want to use, and then importing their modules[^UUID-101b62f6-b640-ed11-1057-29646ebb9fb7_N665976bebafe9] into your application. Because all Cloud SDK functionalities are [available in packages](https://www.npmjs.com/search?q=%40sitecore-cloudsdk), you'll install packages depending on which functionalities you want to set up. The [`core`](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/cloud-sdk-reference/cloud-sdk-core.html "@sitecore-cloudsdk/core") package contains the initialization logic, so you must install `core` to initialize the SDK. The other packages represent a set of Sitecore digital experience platform (DXP) capabilities you can set up on your site, such as tracking, personalization, and search. In each package, `browser` and `server` modules contain all the functions you need to set up these capabilities on the browser side and on the server side, respectively. For example, to set up browser-side personalization, you'll install the `core` and the `personalize` packages and import their `browser` modules. ## Application type The type of app you want to use the Cloud SDK in determines what you have to manually install and initialize. ::::tabs :::tab{title="JavaScript web app"} If you're using a JavaScript web app, you have to manually [install and initialize the Cloud SDK](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/getting-started/install-and-initialize-the-cloud-sdk.html "Install and initialize the Cloud SDK") using the `core` package, and then install and initialize other SDK packages. ::: :::tab{title="Content SDK or JSS app connected to SitecoreAI"} Content SDK and JSS apps already initialize the Cloud SDK `core` and `events` packages on the browser side, with no coding required. For example, Content SDK Next.js apps do this in [`Bootstrap.tsx`](https://github.com/Sitecore/content-sdk/blob/dev/packages/create-sitecore-jss/src/templates/nextjs/src/Bootstrap.tsx). JSS Next.js apps do this in [`Bootstrap.tsx`](https://github.com/Sitecore/jss/blob/dev/packages/create-sitecore-jss/src/templates/nextjs-xmcloud/src/Bootstrap.tsx). This means that if you only want to use `events/browser`, you can start using the Cloud SDK after installing all the app dependencies by running the following command: ```bash npm install ``` If you also want to use `events/server` or any other Cloud SDK packages, you have to manually [install and initialize those packages and import their modules](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/getting-started/install-and-initialize-the-cloud-sdk.html "Install and initialize the Cloud SDK"). ::: :::: You can install Cloud SDK packages 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 ``` ## Browser- and server-side code In each SDK package, you can use the `browser` modules to run Cloud SDK code on the browser side, or the `server` modules to run it on the server side. You can also run some functionality on the browser side, and some other on the server. > [!note] > 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. > > If you want to use the SDK on both the browser and server side, set cookies [either from the browser or from the server](https://doc.sitecore.com/sdk/en/developers/004/cloud-sdk/en/cloud-sdk-cookies.html), not both. ::::tabs :::tab{title="Initializing on the 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. Here's an example `components/CloudSDK.tsx` script, containing all the SDK initialization code: ```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; }; ``` The placeholder values represent [the Context ID and site name](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/getting-started/prerequisites.html "Prerequisites") you collected when you prepared for development. ::: :::tab{title="Initializing on the 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. Here's an example `middleware.ts` script, containing all the SDK initialization code: ```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; }; ``` The placeholder values represent [the Context ID and site name](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/getting-started/prerequisites.html "Prerequisites") you collected when you prepared for development. ::: :::: ## Understanding the initialization process Depending on your application requirements, you might need to modify the initialization code provided in this documentation. This section explains the initialization process so you can adjust the code to your needs. Successfully initializing the SDK involves the following steps: - [Find the right place for your initialization logic](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/cloud-sdk-concepts/initializing-the-cloud-sdk.html#UUID-ab4863d1-4962-fbb1-23ef-a316d0756407_section-idm234510792870225 "Browser- and server-side code"). - Import the modules of all the SDK packages you want to use. - Use the `CloudSDK` function to provide your initialization settings, such as [your Context ID and site name](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/getting-started/prerequisites.html "Prerequisites"). - Chain the package initialization methods, such as `addEvents`, on the `CloudSDK` function. - Chain `initialize` as the last method on the `CloudSDK` function to run the initialization logic. When you start the initialization, you must import the modules of all the SDK packages you want to use: ```typescript import { CloudSDK } from "@sitecore-cloudsdk/core/browser"; import "@sitecore-cloudsdk/events/browser"; import "@sitecore-cloudsdk/personalize/browser"; import "@sitecore-cloudsdk/search/browser"; ``` The `core` import lets you access the `CloudSDK` function. The other imports give the `CloudSDK` function access to the package initialization methods, such as to `addEvents`, `addPersonalize`, and `addSearch`. These are required to initialize the `events`, `personalize`, and `search` packages, respectively. The `CloudSDK` function initializes the SDK itself when you run the `initialize` method. The `initialize` method runs the initialization logic and sets [cookies](https://doc.sitecore.com/sdk/en/developers/004/cloud-sdk/en/cloud-sdk-cookies.html). The following code example does all this, but it doesn't initialize any other SDK packages on its own: ```typescript CloudSDK({ /* Your initialization settings */ }) .initialize(); ``` To initialize the other SDK packages, you have to chain the package initialization methods, such as `addEvents`, on the `CloudSDK` function, before the `initialize` method. The following code example initializes the SDK and all its packages. After this code runs, you can run other SDK functions available in the packages: ```typescript CloudSDK({ /* Your initialization settings */ })   .addEvents() .addPersonalize({ enablePersonalizeCookie: true, webPersonalization: { language: 'en' } }) .addSearch() .initialize(); ``` > [!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. > [!tip] > Behind the scenes, the initialization logic uses the JavaScript [Dynamic Prototype Pattern](https://www.calibraint.com/blog/dynamic-prototype-pattern-javascript). This is the pattern that gives the `CloudSDK` function access to the package initialization methods after you import their corresponding modules. You can initialize any number of SDK packages on the `CloudSDK` function after you import their corresponding modules. The order in which you run the package initialization methods does not matter, but they must precede the `initialize` method. Here's a list of all package initialization methods: - [`addEvents`](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/cloud-sdk-reference/cloud-sdk-events/cloud-sdk-events-browser/functions/cloud-sdk-events-browser-addevents.html "addEvents") initializes the `events` package. - [`addPersonalize`](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/cloud-sdk-reference/cloud-sdk-personalize/cloud-sdk-personalize-browser/functions/cloud-sdk-personalize-browser-addpersonalize.html "addPersonalize") initializes the `personalize` package. - [`addSearch`](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/cloud-sdk-reference/cloud-sdk-search/cloud-sdk-search-browser/functions/cloud-sdk-search-browser-addsearch.html "addSearch") initializes the `search` package. > [!note] > Certain functionality can be enabled directly in the package initialization methods. For example, you [enable web personalizations](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/cloud-sdk-concepts/set-up-web-personalization.html#UUID-9a978cf0-f941-4f45-f6dc-9cbb9f49db2b_section-idm234432972624269 "Enable web personalizations") on the browser side in the `addPersonalize` method, using the `webPersonalization` property. > > Although each Cloud SDK package contains a distinct set of functionalities, some functionalities depend on multiple packages. In this scenario, you have to install all the required packages, import their modules, and then run all the package initialization methods. > > For example, [web personalization](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/cloud-sdk-concepts/set-up-web-personalization.html#UUID-9a978cf0-f941-4f45-f6dc-9cbb9f49db2b_section-idm234432972624269 "Enable web personalizations") and [capturing events in search experiences](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/cloud-sdk-concepts/sitecore-search-events.html "Sitecore Search events") require that you also initialize the `events` package. ### The initialization logic The initialization logic makes it easy to set up the SDK and initialize packages dynamically, according to your application requirements. For example, the logic: - Centralizes the SDK setup, making your SDK code easier to scale and maintain. - Makes it easy to enable more SDK packages in your code in the future. - Separates package initialization into independent methods: initializing a package will not initialize another one. - Contains code autocompletion and IntelliSense to help with the initialization process. [^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.