Upgrade from Cloud SDK version 0.3 to 0.4

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:

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

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:

  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";

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:

   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:

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

   "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.

4. 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.

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

   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.

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:

   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:

   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:

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

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

   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.

   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.