Welcome back, folks! Today, I'm continuing my mini-series on the Sitecore Personalize SDK I created, which wraps the Sitecore Personalize APIs detailed in the documentation here: [https://doc.sitecore.com/personalize/en/developers/api/rest-apis.html](https://doc.sitecore.com/personalize/en/developers/api/rest-apis.html). I'll be focusing on the REST APIs related to creating a Flow in Sitecore Personalize.

A flow in Sitecore Personalize is essentially a single object type representing two distinct types of functionality: an Experience or an Experiment. In my SDK, I've split the creation of Experiences and Experiments into separate functions. Why? To provide more control over the required fields of the Flow Definition.

Behind the scenes, I use Zod to manage which fields are absolutely required for creating an Experience or Experiment. It's worth noting that an Experiment needs more fields than an Experience. Also, creating a basic experience or experiment requires fewer fields than what's realistically needed. For instance, to create a true `experience` like a Web Experience, you'd want to include template assets as well. I'll dive deeper into this later in this post.

In this post, I'll focus specifically on Experiences, as the SDK is still being developed to fully support both experiences and experiments. As mentioned earlier, I aim to make this SDK user-friendly for creating either flow type. Consequently, significant effort is being invested in Zod schema definitions to achieve this goal. It's important to note that the required data will vary depending on the flow type, such as triggered flows or web/full stack flows. Additionally, incorporating a decision model or condition into the flow can significantly impact the required fields.

If you haven't already, make sure to pull the latest SDK from [https://www.npmjs.com/package/sitecore-personalize-tenant-sdk](https://www.npmjs.com/package/sitecore-personalize-tenant-sdk). To create experiences, you'll need version 0.4.5 or newer.

## Creating a Simple Experience with the SDK

Let's dive into creating a simple experience using the SDK. This basic example highlights the essential fields needed to create an experience. However, as mentioned earlier, there are many more fields involved in a flow, which can vary depending on the scenario. I'll document these in detail on the repo's README and supporting documents, as it would be too extensive to cover every scenario here. As with previous blog posts, ensure you have a Node-based repository and have installed the latest version of the SDK. Once that's set up, you'll need to initialize the SDK as discussed in the series. Here's the code to get started:

```typescript
const config: IClientInitOptions = {
	clientId: "<ClientId>",
	clientSecret: "<ClientSecret>",
	region: RegionOptions.EU
};

const personalizeClient = new Client(config);
```

Where can you obtain the Client ID and Secret? I won't delve into that in this post, but you can refer to my previous blog: [Sitecore Personalize: New Developer Focused API Keys (dylanyoung.dev)](https://dylanyoung.dev/insights/sitecore-personalize-new-developer-focused-api-keys/), where I covered this topic in detail. For our current use case, let's assume you're creating keys scoped to `Multiple resources`.

Once we've initialized the SDK, creating an experience is quite straightforward. However, it's crucial to keep in mind which fields are absolutely required. Let's examine the code we'll use to create our Experience:

```typescript
const testExperience: IFlowDefinition = {
	name: 'Test Blog Experience',
	friendlyId: 'test_blog_experience',
	type: FlowType.WebFlow,
	channels: [ FlowChannel.Web ],
	status: FlowStatus.Draft,
	schedule: {
		type: FlowScheduleType.Simple,
		startDate: new Date().toISOString(),
	}
}

let testExperienceResponse = await personalizeClient.Flows.CreateExperience(testExperience);

console.log(JSON.stringify(testExperienceResponse));
```

If all goes well with that code and you've initialized `personalizeClient` correctly above, you should now see the experience `Test Blog Experience` in your Sitecore Personalize tenant. But what about creating a more advanced experience that we can start using right away? Well, this is where adding the correct fields gets a bit trickier. Let's dive into this topic in the next section.

## Using a Web Experience with a Decision Model

Now that we've explored creating a simple experience in Sitecore Personalize, let's dive into a more advanced use case. We'll assume we have an existing `Decision Model` in our Sitecore Personalize tenant. As of this writing, the SDK offers limited support for Decision Models. However, a future scenario might involve creating a Decision Model via API, then using the APIs to create an Experience powered by that Decision Model. Why would anyone want to do this? Well, that's a teaser for some upcoming content in the pipeline—I've got some exciting ideas about potential applications, but we'll dive into those later.

Let's start by examining the code required to create our more complex use case. Then we'll work backwards to break down the new additions to this Web Experience.

```typescript
const testExperience: IFlowDefinition = {
        name: "Test API Experience5",
        friendlyId: "test_api_experience5",
        type: FlowType.WebFlow,
        channels: [ FlowChannel.Web ],
        status: FlowStatus.Draft,
        schedule: {
            type: FlowScheduleType.Simple,
            startDate: new Date().toISOString(),
        },
        variants: [
            {
                name: 'Variant API Test',
                isControl: false,
                assets: {
                    html: "\n\n<div id=\"pers-transition-card\">\n    <div class=\"img-container\">\n        <div class=\"img-container__image\"></div>\n    </div>\n    <div class=\"pers-transition-card__body\">\n        <h3>[[Title | string | Title | {required:true, group: Title, order: 1}]]</h3>\n        <p>[[Description | text | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt | {required:true, group: Description, order: 1}]]</p>\n        <div class=\"options-container\">\n            <a id=\"pers-transition-card--secondary\" class=\"options-container__secondary\">[[Dismiss Text | string | No Thanks | {required:true, group: Secondary Button, order: 1}]]</a>\n            <a id=\"pers-transition-card--primary\" class=\"options-container__primary\">[[CTA Text | string | Yes Please | {required:true, group: CTA Button, order: 1}]]</a>\n        </div>\n    </div>\n</div>",
                    css: "/*\n[[Background Colour | colour | #fff| {equired: true, group: General, groupOrder: 1, order: 3}]]\n[[Background Image Colour | colour | #F3F5F7| {equired: true, group: General, order: 4}]]\n[[Image URL | string || {required:true, group: General, order: 1}]]\n[[Font | enum(Arial,Arial Narrow,Brush Script MT,Calibri,Cambria,Candara,Copperplate,Courier,Courier New,Didot,Garamond,Geneva,Helvetica,Lucida Bright,Monaco,Optima,Perpetua,Times,Times New Roman,Verdana) |Arial|{group: General, order: 2}]];\n[[CTA Colour | colour | #000 | {equired: true, group: CTA Button, groupOrder: 4, order: 2}]]\n[[CTA Text Colour | colour | #fff | {equired: true, group: CTA Button, order: 3}]]\n[[CTA Hover Color | colour | #9e9e9e |{ required: true, group: CTA Button, order: 4} ]]\n[[CTA Text Hover Color | colour | #fff | { required: true, group: CTA Button, order: 5} ]]\n[[Secondary Colour | colour | #F3F5F7 | {equired: true, group: Secondary Button, groupOrder: 5, order: 2}]]\n[[Secondary Text Colour | colour | #000 | {equired: true, group: Secondary Button, order: 3}]]\n[[Secondary Hover Color | colour | #fff |{ required: true, group: Secondary Button, order: 4} ]]\n[[Secondary Text Hover Color | colour | #000 | { required: true, group: Secondary Button, order: 5} ]]\n[[Title Text Colour | colour | #4D4D4D | {group: Title, groupOrder: 2, order: 2}]]\n[[Title Text Font Size | number | 36 | { group: Title, order: 3 }]]\n[[Description Text Colour | colour | #4D4D4D | { group: Description, groupOrder: 3, order: 2 }]]\n[[Description Text Font Size | number | 16 | { group: Description, order: 3 }]]\n*/\n\n#pers-{{ref}} a,\n#pers-{{ref}} p,\n#pers-{{ref}} span {\n  font-family: [[ Font ]];\n  font-weight: 400;\n  line-height: 1.2;\n}\n\n#pers-{{ref}} #pers-transition-card {\n    position: fixed;\n    width: 435px;\n    right: 0;\n    bottom: -1000px;\n    z-index: 999999;\n    transition: bottom .6s ease-in-out;\n    margin-bottom: 0;\n    border-radius: 4px;\n    background-color: [[Background Colour]];\n    overflow: hidden;\n    box-shadow: 0 0.2rem 0.4rem 0.2rem rgba(0,0,0,.1);\n    font-size: initial;\n}\n\n#pers-{{ref}} #pers-transition-card.open {\n    bottom: 0;\n}\n\n#pers-{{ref}} #pers-transition-card .img-container {\n    width: 100%;\n    height: 250px;\n}\n\n#pers-{{ref}} #pers-transition-card .img-container__image {\n    margin: 0;\n    background: [[Background Image Colour]];\n    height: 100%;\n    display: flex;\n    justify-content: center;\n    align-items: center;\n    font-size: var(--font-size-h4);\n    background-image: url(\"[[Image URL]]\");\n    background-position: center;\n    background-repeat: no-repeat;\n    background-size: cover;\n}\n\n#pers-{{ref}} #pers-transition-card .pers-transition-card__body {\n    padding: 37px 34px;\n}\n\n#pers-{{ref}} #pers-transition-card .pers-transition-card__body h3 {\n    margin-top: 28px;\n    line-height: 1.5;\n    font-size: [[ Title Text Font Size ]]px;\n    font-weight: bold;\n    text-align: center;\n    margin: 0;\n    color: [[Title Text Colour]];\n    font-family: [[Font]];\n}\n\n#pers-{{ref}} #pers-transition-card .pers-transition-card__body p {\n    padding: 12px 0;\n    margin: 0;\n    font-size: [[ Description Text Font Size ]]px;\n    line-height: 28px;\n    text-align: center;\n    color: [[Description Text Colour]];\n    font-family: [[Font]];\n}\n\n#pers-{{ref}} #pers-transition-card .options-container {\n    display: flex;\n    justify-content: center;\n}\n\n#pers-{{ref}} #pers-transition-card .options-container__primary {\n    display: inline-block;\n    border-radius: 4px;\n    color: [[CTA Text Colour]];\n    background-color: [[CTA Colour]];\n    padding: 10px 30px;\n    cursor: pointer;\n    font-size: [[Font]];\n}\n\n#pers-{{ref}} #pers-transition-card .options-container__primary:hover {\n  color: [[CTA Text Hover Color]];\n  background-color: [[CTA Hover Color]];\n}\n\n#pers-{{ref}} #pers-transition-card .options-container__secondary {\n    display: inline-block;\n    border: 1px solid #C1C9D0;\n    border-radius: 4px;\n    color: [[Secondary Text Colour]];\n    background-color: [[Secondary Colour]];\n    padding: 10px 30px;\n    margin-right: 13px;\n    cursor: pointer;\n    font-size: [[Font]];\n}\n\n#pers-{{ref}} #pers-transition-card .options-container__secondary:hover {\n  color: [[Secondary Text Hover Color]];\n  background-color: [[Secondary Hover Color]];\n}",
                    js: "// Adds a unique variant identifier to CSS when deployed to ensure CSS does not impact styling of other elements.\nvar compiledCSS = Engage.templating.compile(variant.assets.css)(variant);\nvar styleTag = document.getElementById('style-' + variant.ref);\nif (styleTag) {\n    styleTag.innerHTML = compiledCSS;\n}\n// End Adds a unique variant identifier to CSS when deployed to ensure CSS does not impact styling of other elements.\n\n// make space in the body for the experience\ninsertHTMLAfter('body', 'pers-');\nvar persContent = document.querySelector(\"#pers-\"+variant.ref+ \" #pers-transition-card\");\n\nsetTimeout(function() {\n    persContent.classList.add(\"open\");\n    sendInteractionToPersonalize(\"VIEWED\");\n});\n\nvar persCardClose = document.body.querySelector(\"#pers-\"+variant.ref+ \" #pers-transition-card--secondary\");\npersCardClose.onclick = function() {\n    sendInteractionToPersonalize(\"DISMISSED\");\n    persContent.classList.remove(\"open\");\n}\n\nvar persCardCta = persContent.querySelector(\"#pers-\"+variant.ref+ \" #pers-transition-card--primary\");\npersCardCta.onclick = function() {\n    sendInteractionToPersonalize(\"CLICKED\");\n    window.location.href = \"[[CTA destination URL | string || {required:true, group: CTA Button}]]\";\n}\n\nfunction sendInteractionToPersonalize(interactionType) {\n    const type = \"[[ Experience ID | String | CORNER_POPUP | {required: true}]]_INTERACTION\";\n    const eventData = {\n        \"channel\": \"WEB\",\n        \"pointOfSale\": Engage.settings.pointOfSale,\n        \"interactionID\": \"PERS_CORNER_POPUP\",\n        \"interactionType\": interactionType\n    };\n\n    window.engage.event(type, eventData);\n}"
                },
                templateVariables: {
                    "Title": "Title",
                    "Description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt",
                    "Dismiss Text": "No Thanks",
                    "CTA Text": "Yes Please",
                    "Font": "Arial",
                    "CTA Colour": "#000",
                    "Secondary Colour": "#F3F5F7",
                    "Title Text Colour": "#4D4D4D",
                    "Description Text Colour": "#4D4D4D",
                    "Background Colour": "#fff",
                    "CTA Text Colour": "#fff",
                    "Secondary Text Colour": "#000",
                    "Title Text Font Size": "36",
                    "Description Text Font Size": "16",
                    "Background Image Colour": "#F3F5F7",
                    "CTA Hover Color": "#9e9e9e",
                    "Secondary Hover Color": "#fff",
                    "CTA Text Hover Color": "#fff",
                    "Secondary Text Hover Color": "#000",
                    "Experience ID": "CORNER_POPUP"
                },
                tasks: [
                    personalizeClient.Flows.CreateTemplateRenderTaskInput('<#-- Construct the API request body using Freemarker -->\n<#-- For your Experience to run your API tab must have, at a minimum, open and closing brackets -->\n{  <#-- Freemarker will go here -->   }'),
                    personalizeClient.Flows.CreateDecisionModelTaskInput([ "1885d8c9-d32d-4bf3-975d-f8dbd91882bc"])
                ]
            }
        ]
    }

    let testExperienceResponse = await personalizeClient.Flows.CreateExperience(testExperience);

    console.log(JSON.stringify(testExperienceResponse, null, 2));
```

As you can see, considerably more code is needed to create this use case because we need to create a variant for our Experience. When I first learned Sitecore Personalize, you could have more than one variant per experience. However, that's no longer the case—now your main variant will receive 100% of the traffic.

The variant includes HTML, CSS, and JavaScript, typically derived from a template or custom-built. If we were creating this experience from local templates, we'd pull the template source to build out these three properties. The API output is stored in a different location, where I use `personalizeClient.Flows.CreateTemplateRenderTask('Pass in your Free marker here')` to easily create this object (as there's much more involved behind the scenes). I'm working on more helper functions like this, aiming to hide the boilerplate code and simplify experience creation.

The `templateVariables` is a key-value pair object where the keys are strings. This structure allows us to inject data into our template (although technically, we're not using a true template here). Our understanding of templates in Personalize evolves as we delve into the underlying code. In essence, the template functions more like a snippet—a reusable piece of code that drives the variants themselves.

I also created another task helper, `personalizeClient.Flows.CreateDecisionModelTaskInput([ "decision-model-ref"])`, which simplifies this object. As mentioned earlier, you need to create the Decision Model first. I hope to cover these multi-resource scenarios soon.

There you have it! Our experience is now successfully created in our tenant:

![](https://cdn.sanity.io/images/lanua4su/production/22fb52a7ed58cb0137ecc6f54f88b861c79cbbce-1385x764.jpg)

## Teaser

You might wonder why you'd want to create an experience using this SDK. Well, my next blog in this mini-series will showcase a compelling scenario—leveraging Generative AI. But that's just the tip of the iceberg. I'm excited to explore numerous other valuable use cases in the coming months. So, stay tuned for these upcoming articles—you won't want to miss them!

Creating an Experience with the Sitecore Personalize SDK

Hello friends! This post emerged from another topic I started writing last week. I realized it would be more sensible to take a step back and cover an introductory topic before diving into a mini-series on related subjects.

Today, I'm excited to introduce a project I've been working on: the Sitecore Personalize Tenant SDK, available on NPM here: [sitecore-personalize-tenant-sdk - npm (npmjs.com)](https://www.npmjs.com/package/sitecore-personalize-tenant-sdk). This SDK focuses on wrapping the freely available APIs for managing assets in Sitecore Personalize. While still a work in progress, it's already proving valuable for those handling testing scenarios or exploring other use cases with Sitecore CDP/P.

The SDK primarily targets Personalize, but it's worth noting that CDP and Personalize were originally a single product built by Boxever. As such, this tool is designed to streamline working with both products, making it easier to consume and interact with their features.

# Who is the SDK for?

This SDK is intended for anyone who wants to create, read, update, or delete Sitecore Personalize assets (such as flows, decision models, templates, and conditions). Some specific use cases include creating an Experience in Sitecore Personalize based on an action in another system, using a chat application with AI to generate experiences, or—as with the Serializer (which will soon use the SDK)—enabling new development approaches with Sitecore Personalize.

# Who is it not for?

To clarify, this SDK is not designed for data ingestion into Sitecore CDP/P. For those needs, use the Engage SDK if you're not on XM Cloud or JSS 21.6+. If you are, opt for the Cloud SDK. For non-Web/Node platforms, you'd still interact directly with the Stream APIs or use the Engage Script.

# Getting Started with the SDK

Getting started with the SDK for Sitecore Personalize is straightforward. You can pull the latest version from NPM using the following command:

```javascript
$ npm install sitecore-personalize-tenant-sdk@latest
```

This SDK is not a CLI, so you'll need to install it in your Node project. Once installed, you can interact with it by initializing the Client. The Client expects an object of `ClientInitOptions`, which requires a client ID, client secret, and the region for your Sitecore Personalize tenant. Keep in mind that this tool only supports tenants on Cloud Portal. If your tenant still requires access from a Boxever domain, you won't be able to use this SDK. Since most tenants will be migrated to the Cloud Portal soon, you'll need to wait until your tenant is converted before using this SDK.

Creating the Client ID and Secret is now straightforward. I've written a blog post about it here: [Sitecore Personalize: New Developer Focused API Keys (dylanyoung.dev)](https://dylanyoung.dev/insights/sitecore-personalize-new-developer-focused-api-keys/). You can also find more information in the Sitecore documentation: [Create an API key | Sitecore Documentation](https://doc.sitecore.com/personalize/en/developers/api/create-an-api-key.html). In my original article about creating New Developer Focused API Keys, I explored the potential of using the REST APIs—which I've incorporated into my SDK—to implement some of the use cases mentioned in the "Who is this for?" section. For now, let's focus on how to start using the client. You can use the code below as an example. While you might want to initialize the client using environment variables in practice, this example demonstrates the basic setup:

```typescript
import { Client, IClientInitOptions, RegionOptions } from "sitecore-personalize-tenant-sdk";

const clientOptions: IClientInitOptions = {
	clientId: "<Client Key Generated from Sitecore Personalize>",
	clientSecret: "<Client Secret Generated from Sitecore Personalize>",
	region: RegionOptions.US
}

const client = new Client(clientOptions);

// Now you can start using the Client
```

One nice feature of the client is that you don't have to worry about authentication—it's all handled for you. So if you want to get all the Web Templates from your tenant, you can simply run the following command. This will return a `Promise<IResponse<ITemplate[]> | undefined>`.

```typescript
import { IResponse, ITemplate, TemplateType } from "sitecore-personalize-tenant-sdk"

let templates: IResponse<ITemplate[]> | undefined = await client.Templates.GetAll(TemplateType.Web)
```

That covers the basics for now. I'll explore more use cases in the SDK documentation and upcoming blog posts.

# Testing Use Cases

Now that we've explored how to use this new SDK, let's discuss its potential applications in Sitecore Personalize for various testing scenarios.

## Unit Tests

This scenario is quite complex, as it's not directly about the SDK itself but rather how it enables a new workflow for building assets in Sitecore Personalize. Using the SDK, you could leverage a tool like the Serializer to implement a CI/CD process. This allows you to create code for Sitecore Personalize locally. You can then run unit tests on this local code to verify that your functionality works as intended. I'll delve deeper into this use case in future posts.

## Integration Tests

Integration testing verifies that the code you've written remains intact and functions as intended. The approach varies depending on the types of assets you're working with in Sitecore Personalize.

### Web Templates or Flows

What exactly can you test with a Web Template or Flow? The answer is somewhat complex. Ideally, you'd want to test the Experience or Experiment on your own website, but that's quite complicated and, to my knowledge, not currently possible. Instead, you may want to see how Sitecore Personalize renders the contents of your Web Template or the Experience/Experiment based on your inputs. I can confirm this is achievable and can be done with the SDK (which I'll cover in a future blog post). You can learn more about the available APIs here:

https://doc.sitecore.com/personalize/en/developers/api/preview-templates.html - This API allows you to test existing Templates. You can pass a friendly ID or ref for a web template along with template params, and it'll return a collection of HTML, CSS, and JavaScript output.

https://doc.sitecore.com/personalize/en/developers/api/preview-template-code.html - This API differs slightly from the one above. It lets you test the assets and template params before they actually exist, allowing for a final check in a local source control system before pushing changes to the environment.

Another crucial form of testing involves verifying that your local changes still align with what's been deployed to your tenant. This ensures proper governance and prevents customers or developers from making unauthorized changes directly in Personalize.

### Conditions

A Sitecore Personalize Condition is a newer concept, but it's essentially a type of template you can define in Sitecore Personalize. These conditions were designed to replace audience templates on Flows (Experiences and Experiments). They're probably the closest equivalent to XP personalization rules, though they don't fully replace that functionality. Conditions allow you to define small code segments that represent specific decisions you want to make. For instance, you could create a condition that determines whether the current session user is a Visitor or a Known Guest.

Integration tests for these conditions are available using the undocumented endpoint: `/v2/callFlows/testTemplate`. This endpoint accepts a specific set of parameters, enabling you to debug and verify if your condition's code works as expected in your environment. However, it's important to note that this endpoint doesn't function quite as you might expect. Rather than testing the template itself, it tests a flow and determines if it works based on the template it's using. One major challenge with this approach is that to test the integration of a Condition, you need a dummy experience to run this endpoint.

For Conditions, unit testing is likely your best approach. It allows you to test your code against mock data to ensure it performs as expected. However, the process isn't always straightforward. Sitecore Personalize uses ES5 syntax and requires a specific JavaScript format. Even if you write your code correctly locally, it might not work in Personalize. This is where integration tests prove valuable—they can help bridge the gap between local development and the Personalize environment.

### Decision Models or Decision Templates

When creating a Decision Model with Programmables or Decision Templates, testing individual components directly isn't possible. Instead, you must test the entire Decision Model. This approach, similar to Conditions, requires "dummy" decision models that incorporate your Programmables or Decision Templates. It's worth noting that JS Modules, which are only used alongside Programmables, can only be tested in this manner during integration testing. While this method is necessary for integration tests, I see value in running unit tests locally. These local tests can give you a general idea of how your components will perform before deploying them to an environment. The SDK includes a function called `TestDecisionModelVariant`, which accepts a guestContext object (I'll explain this further in my next blog post), a Decision Model Ref, and a Variant Ref. This function allows you to pass a custom Guest to your Decision Model Variant, enabling integration tests for specific outcomes.

### Conclusion

This concludes our overview of the SDK and introduction to integration versus unit testing for Sitecore Personalize. As mentioned throughout this post, I'll be releasing more content soon detailing how to use the SDK for specific integration testing scenarios. While it's still a work in progress, I plan to apply the SDK to the serializer and explore several unit testing scenarios. I'll also demonstrate how combining these with the Serializer can revolutionize your development workflow with Sitecore Personalize.

Unleashing Personalization: Deep Dive into Sitecore Personalize SDK

Related Content

Creating an Experience with the Sitecore Personalize SDK

Introduction to Sitecore Personalize SDK and Testing