---
title: "Upgrade from Cloud SDK version 0.3 to 0.4"
slug: "upgrade-from-cloud-sdk-version-0-3-to-0-4"
abstract: "Update the Cloud SDK initialization logic in your application to upgrade from Cloud SDK v0.3 to v0.4."
---
# Upgrade from Cloud SDK version 0.3 to 0.4

Cloud SDK version 0.4 introduces [new initialization logic](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/cloud-sdk-concepts/initializing-the-cloud-sdk.html "Initializing the Cloud SDK"). If you're upgrading from version 0.3 or earlier, follow this walkthrough to upgrade your initialization code. The old, version 0.3 initialization logic is deprecated in version 0.4 and removed in version 0.5.

The majority of your upgrade work involves installing the latest Cloud SDK packages and replacing old `init` function calls with new `CloudSDK` ones. You'll also set the `sc_{SitecoreEdgeContextId}_personalize` [cookie](https://doc.sitecore.com/sdk/en/developers/004/cloud-sdk/en/cloud-sdk-cookies.html) manually, which previous SDK versions set automatically if you opted in to setting cookies.

This walkthrough assumes that you have Cloud SDK version 0.3 or earlier installed in your JSS Next.js application.

This walkthrough describes how to:

:::walkthrough
1. [Install the latest @sitecore-cloudsdk packages](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/upgrading/upgrade-from-cloud-sdk-version-0-3-to-0-4.html#install-the-latest-sitecore-cloudsdk-packages)
2. [Import the CloudSDK function and other SDK modules](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/upgrading/upgrade-from-cloud-sdk-version-0-3-to-0-4.html#import-the-cloudsdk-function-and-other-sdk-modules)
3. [Rework the init function into CloudSDK code](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/upgrading/upgrade-from-cloud-sdk-version-0-3-to-0-4.html#rework-the-init-function-into-cloudsdk-code)
:::

> [!note]
> **Before you begin**
> -   In your code editor, open the root folder of your web app.

## Install the latest `@sitecore-cloudsdk` packages

The first step to upgrading is to install the latest `@sitecore-cloudsdk` packages, including a new package called `core`. 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 new initialization logic. You'll set up the new logic in a later procedure.

To install the latest packages:

1. In your code editor, in the root folder of your application where your app dependencies are installed, open the terminal.
2. To install version 0.4 of the `core` package and any other Cloud SDK packages you currently use in your app, run the following commands:

    ```bash
    npm install @sitecore-cloudsdk/core@0.4
    npm install @sitecore-cloudsdk/events@0.4
    npm install @sitecore-cloudsdk/personalize@0.4
    ```

3. In `package.json`, check that the Cloud SDK packages are now version `0.4`.

## Import the `CloudSDK` function and other SDK modules

The `core` package contains a `browser` and a `server` module. Each module contains a new `CloudSDK` function. This function initializes the SDK when you run its `initialize` method, and the function also allows you to initialize other SDK packages. 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).

Depending on your application requirements, use the `browser` module to initialize the SDK on the browser side, or use the `server` module to initialize it on the server.

::::tabs
:::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 make the necessary imports on the browser side:

- In a centralized place, on app initialization, for example, in `components/CloudSDKComponent.tsx`, import `useEffect` from `react`, `CloudSDK` from the `browser` module of the `core` package, and other SDK modules your app uses:

    ```typescript
    "use client";
    import { useEffect } from "react";
    import { CloudSDK } from "@sitecore-cloudsdk/core/browser";
    import "@sitecore-cloudsdk/events/browser";
    import "@sitecore-cloudsdk/personalize/browser";
    ```

:::
:::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 make the necessary imports on the server side:

- Depending on your server-side logic, in the files where you want to run Cloud SDK code, for example, in `middleware.ts`, import `NextRequest` and `NextResponse` from `next/server`, `CloudSDK` from the `server` module of the `core` package, and other SDK modules your app uses:

    ```typescript
    import type { NextRequest } from "next/server";
    import { NextResponse } from "next/server";
    import { CloudSDK } from "@sitecore-cloudsdk/core/server";
    import "@sitecore-cloudsdk/events/server";
    import "@sitecore-cloudsdk/personalize/server";
    ```

:::
::::

## Rework the `init` function into `CloudSDK` code

After making the necessary imports, your app still runs instances of the old `init` function, usually one for each Cloud SDK module your app uses. For example, if your app uses the `events/browser`, `events/server` , and `personalize/browser` modules, your application code contains three instances of `init`. In this procedure, you replace all `init` code with new code that uses the `CloudSDK` function.

::::tabs
:::tab{title="Browser side"}
On the browser side, you must replace all instances of `init` with a single instance of the `CloudSDK` function. You must run the `CloudSDK` function once, in a centralized place, on app initialization, so that the rest of your app can run Cloud SDK code.

To rework `init` into `CloudSDK` code on the browser side:

1. In your application code, find all instances of your `init` code.

    Example:

    ```typescript
    import { init, personalize } from "@sitecore-cloudsdk/personalize/browser";

    // ...

    export default function Home() {
      // Old way to initialize  ->
      useEffect(() => {
        initPersonalize();
      }, []);

      const initPersonalize = async () => {
        await init({
          sitecoreEdgeContextId: process.env.SITECORE_EDGE_CONTEXT_ID,
          siteName: process.env.SITECORE_SITE_NAME,
          enableBrowserCookie: true,
        });
      };
      // <- Old way to initialize

      return (<></>);
    };
    ```

    This code runs the old `init` function to initialize `personalize/browser`.

2. Comment out all instances of `init` code from your application code, and remove all `init` imports.

    For the code shown in step 1:

    ```typescript
    /*Remove the init import: */ import { personalize } from "@sitecore-cloudsdk/personalize/browser";

    // ...

    export default function Home() {
      // Old way to initialize  ->
      // useEffect(() => {
        //  initPersonalize();
      // }, []);

      // const initPersonalize = async () => {
        // await init({
          // sitecoreEdgeContextId: process.env.SITECORE_EDGE_CONTEXT_ID,
          // siteName: process.env.SITECORE_SITE_NAME,
          // enableBrowserCookie: true,
        // });
      // };
      // <- Old way to initialize

      return (<></>);
    };
    ```

3. In the file where you previously imported `CloudSDK` and other SDK modules, for example, in `CloudSDKComponent.tsx`, in an Effect hook, run the `CloudSDK` function to initialize the Cloud SDK:

    ```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 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: true }) // Initialize the personalize 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` and the `personalize` 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, remove `webPersonalization: true`.

    > [!tip]
    > This initialization logic uses the [Dynamic Prototype Pattern](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/upgrading/initializing-the-cloud-sdk.html "Initializing the Cloud SDK").

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

4. Add the component you just created to `layout.tsx`, directly inside the `<body>` tag, before `{children}`, then save your changes:

    ```typescript
    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.

5. Start your app by entering the following command in your terminal:

    ```bash
    npm run dev
    ```

6. In your web browser, navigate to your JSS 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, you must replace each instance of `init` with an instance of the `CloudSDK` function. You must run the `CloudSDK` function on every page request, API request, or middleware request, depending on your server-side logic. The `CloudSDK` function has to run on every request because every request will have its own cookies. In addition, to ensure correct execution order, the `CloudSDK` initialization code has to run before any other Cloud SDK functions.

To rework `init` into `CloudSDK` code on the server side:

1. In your application code, find all instances of your `init` code.

    Example:

    ```typescript
    import { NextResponse } from "next/server";
    import type { NextRequest } from "next/server";
    import { init } from "@sitecore-cloudsdk/personalize/server";

    export async function middleware(req: NextRequest) {
      const res = NextResponse.next();

      // Old way to initialize ->
      await init(req, res,
        {
          sitecoreEdgeContextId: process.env.SITECORE_EDGE_CONTEXT_ID,
          siteName: process.env.SITECORE_SITE_NAME,
          enableServerCookie: true,
        }
      );
      // <- Old way to initialize

      return res;
    };
    ```

    This code runs the old `init` function to initialize `personalize/server`.

2. Comment out all instances of `init` code from your application code, and remove all `init` imports.

    For the code shown in step 1:

    ```typescript
    import { NextResponse } from "next/server";
    import type { NextRequest } from "next/server";
    // import { init } from "@sitecore-cloudsdk/personalize/server";

    export async function middleware(req: NextRequest) {
      const res = NextResponse.next();

      // Old way to initialize ->
      // await init(req, res,
        // {
          // sitecoreEdgeContextId: process.env.SITECORE_EDGE_CONTEXT_ID,
          // siteName: process.env.SITECORE_SITE_NAME,
          // enableServerCookie: true,
        // }
      // );
      // <- Old way to initialize

      return res;
    };
    ```

3. In the file where you previously imported `CloudSDK` and other SDK modules, for example, in `middleware.ts`, run the `CloudSDK` function to initialize the Cloud SDK:

    ```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 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 }) // Initialize the personalize 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` and the `personalize` packages.

    > [!tip]
    > This initialization logic uses the [Dynamic Prototype Pattern](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/upgrading/initializing-the-cloud-sdk.html "Initializing the Cloud SDK").

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.

:::
::::

## Next steps

You've now successfully upgraded to the Cloud SDK version 0.4 initialization logic. You can now start your app to check that the Cloud SDK runs. You can also remove the code related to the old `init` function that you have previously commented out.

Next, you can:

- 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").
- Explore the reference documentation for the [`core`](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/cloud-sdk-reference/cloud-sdk-core.html "@sitecore-cloudsdk/core") package.
- Learn more about what changed in Cloud SDK version 0.4 in the [release notes](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/sitecore-cloud-sdk-for-javascript/cloud-sdk-release-notes.html "Cloud SDK release notes").