Upgrade from Cloud SDK version 0.3 to 0.4

Version: 0.5

Cloud SDK version 0.4 introduces new initialization logic. If you're upgrading from version 0.3 or earlier, follow this walkthrough to upgrade your initialization code. The version 0.3 initialization logic will be deprecated and removed in a future Cloud SDK release.

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 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:

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 package contains the new initialization logic. You'll set up the new logic in a later procedure.

To install the latest packages:

In your code editor, in the root folder of your application where your JSS Next.js app dependencies are installed, open the terminal.

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:

RequestResponse

npm install @sitecore-cloudsdk/[email protected]
npm install @sitecore-cloudsdk/[email protected]
npm install @sitecore-cloudsdk/[email protected]

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.

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.

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 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:
RequestResponse
```
"use client";
import { useEffect } from "react";
import { CloudSDK } from "@sitecore-cloudsdk/core/browser";
import "@sitecore-cloudsdk/events/browser";
import "@sitecore-cloudsdk/personalize/browser";
```

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.

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:

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

Example:

RequestResponse

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.

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

For the code shown in step 1:

RequestResponse

/*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 (<></>);
};

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:

RequestResponse

"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 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. If you don't want to enable web personalizations, remove webPersonalization: true.

Tip

This initialization logic uses the Dynamic Prototype Pattern.

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

Add the component you just created to layout.tsx, directly inside the <body> tag, before {children}, then save your changes:
RequestResponse
```
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:
RequestResponse
```
npm run dev
```
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. For example, you can start setting up tracking by capturing VIEW events.

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.
Explore the reference documentation for the core package.
Learn more about what changed in Cloud SDK version 0.4 in the release notes.

Do you have some feedback for us?

If you have suggestions for improving this article,