Upgrade from Cloud SDK version 0.5 to 0.6

Version:

Cloud SDK version 0.6 introduces a breaking change to the names of the cookies the SDK sets in your app:

  • The sc_{SitecoreEdgeContextId} cookie, which persists the browser ID, is renamed to sc_cid.

  • The sc_{SitecoreEdgeContextId}_personalize cookie, which persists the guest ID, is renamed to sc_cid_personalize.

The cookie name changes mean that when you upgrade to version 0.6, new cookies will be created in your app. The old cookies remain in web browsers. In SDK version 0.6.1 and later, the new cookies inherit the values from the old ones, if the old ones are present in the web browser. This has the following consequences:

  • Privacy policy and cookie consent banners - you must update references to the old cookie names in your privacy policy and cookie consent banners. If required by applicable regulations, you must re-obtain consent.

  • Application code - if your application references the old cookie names, you must update your code. Common places where you might reference cookie names include:

    • Cookie consent logic.

    • Cookie whitelist.

    • Server-side middleware and client-side scripts that read cookie values.

    • Privacy policy documentation.

    • Cookie banner configurations.

    • Parts of your code where you pass cookie values to other systems.

  • Switching SitecoreAI environments during development - if you want to switch between different SitecoreAI environments during development, you need to delete your existing sc_cid and sc_cid_personalize cookies and create new ones with a different Context ID. For more information, see Switching environments for testing purposes.

Important

After the changes are deployed to production, the cookie name change occurs one time for every site visitor, when they next visit the deployed website.

This walkthrough focuses on updating your application code. It 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.

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.6 of the Cloud SDK packages you currently use in your app, run the following commands:

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

    To ensure the new cookies inherit values from the old cookies, install SDK packages 0.6.1 or later, not 0.6.0.

    Note

    Only install the packages your application uses. For example, if you don't use the search package, you don't need to install it.

  3. In package.json, check that the Cloud SDK packages are now version 0.6.1 or later.

Update application code that references cookies

If your application contains custom code that reads or references the old cookie names, you must update those references to use the new cookie names.

To update cookie references in your application code:

  1. Search your application code for any references to the old cookie name sc_{SitecoreEdgeContextId}, and then replace it with the new cookie name sc_cid. Your code might refer to the old cookie name using a variable, such as sc_${contextId}.

  2. Search your application code for any references to the old cookie name sc_{SitecoreEdgeContextId}_personalize, and then replace it with the new cookie name sc_cid_personalize. Your code might refer to the old cookie name using a variable, such as sc_${contextId}_personalize.

  3. Save your changes.

Test your implementation

After updating your application code, test that your app correctly sets the new cookies.

To test your implementation:

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

    npm run dev

  2. In your web browser, navigate to your Next.js app, typically at http://localhost:3000.

  3. In your web browser's developer tools, in Cookies, find the new cookies sc_cid and, if you use the personalize package, sc_cid_personalize. If these cookies are present, you've successfully initialized the Cloud SDK with the new cookies.

  4. Check that your cookie consent banner correctly identifies and manages the new cookie names.

  5. Check that your code continues to capture events and that they appear in Sitecore.

  6. If your app uses the personalize package, check that web personalization, interactive personalization, and A/B/n testing continue to work as expected.

    You've now successfully upgraded to Cloud SDK version 0.6.

A universally unique identifier (UUID) that Sitecore CDP assigns to every site visitor of your site. It is unique per browser, and it associates sessions and events with the respective site visitor. The Cloud SDK stores the browser ID as the value for the first-party sc_cid cookie in the web browser.

The guest ID, called guest reference in Sitecore CDP, is a universally unique identifier (UUID) that Sitecore CDP assigns to every site visitor of your site. It is unique per site visitor. The Cloud SDK personalize package stores the guest ID as a first-party cookie in the web browser.

If you have suggestions for improving this article, let us know!