When my colleagues and I started working on a proof-of-concept for Sitecore CDP & Personalize, one of the important aspects of our plan was validation of how custom guest profile properties can be effectively stored and used in the CDP.
Many organisations need to save custom pieces of data associated with website visitors and their interactions on the website. These data properties may include marketing consent status, preferred language, or specific topics of interest just to name a few. During our research we found that Sitecore CDP offers a built-in feature for storing and reading these custom fields known as data extensions.
Types of data extensions
Sitecore CDP supports data extension attributes for the following data models:
- Guests
- Events
- Orders
In this article I will primarily focus on event and guest data extensions, but it is worth noting that similar principles apply to orders as well.
How to create data extensions
Depending on your application specifics and requirements, you can choose one or multiple available APIs: Stream API, REST API and Batch API. Regardless of the integration method you select, Sitecore CDP will provide an option for sending custom data and saving it in the system for future use.
Stream API
For seamless integration, Engage SDK provides an easy way of passing event data extensions to the CDP. The optional object extensionData can be included as the last function argument when sending events, page views or identifying guests.
Client-side tracking methods supporting the extensionData parameters are:
Engage.pageView(eventData[, extensionData])Engage.identity(eventData[, extensionData])Engage.event(type, eventData[, extensionData])Engage.addToEventQueue(type, eventData[, extensionData])
Server-side SDK tracking methods are similar, but they also require passing the HTTP request parameter req:
EngageServer.pageView(eventData, req[, extensionData])EngageServer.identity(eventData, req[, extensionData])EngageServer.event(type, eventData, req[, extensionData])
If you opt not to use Engage SDK and prefer to integrate through direct HTTP requests, you can still supply additional data with an event by utilising the ext data extension object. Please note that the name of the event data extension object must be ext, otherwise Sitecore CDP will not recognise it as a data extension.
Here's an example of a data extension object for HTTP requests:
{
"type": "VIEW",
"channel": "WEB",
"pos": "POS name",
"browser_id": "…",
"language": "EN",
"currency": "EUR",
"page": "home",
"ext": {
"pageCategory": "value",
"bonusPoints":10
}
}
Please note that after you send the event, the data in this object becomes available in the event, but not in the guest profile.
Some other limitations that are worth noting are:
- An event data extension object can have a maximum of 50 attributes
- The attribute name must be alphanumeric, i.e. it should only contain characters A-Z, a-z, or 0-9
- The attribute name must be unique within the entire event type
REST API
If you integration requires a synchronous communication method and you can’t use Stream API, the REST API is a good alternative. It provides a special API endpoint for sending extension data:
POST /v2/guests/<guestRef>/extext
It’s important to note that extext consists of two parts: the first ext is constant and means that we want to send extension data. The second ext represents the name of the extension property in Sitecore CDP. The system supports multiple extension group names allowing you to send data extensions from various source systems and store them separately. Failing to do so will result in overwriting guest extension data from other sources. You can create a maximum of six guest data extension groups and use only predefined names: ext, ext1, ext2, ext3, ext4, ext5.
For instance, if you want to send extension data from a second system, you can modify the request to use the extension group ext1 as follows:
POST /v2/guests/<guestRef>/extext1
Request body example:
{
"key": "default",
"loyaltyTier": "level2",
"loyaltyNumber": 12345,
"marketingConsent": true,
}
Please note that the key attribute must be set to default and guest data extension can have a maximum of 100 attributes. Naming conventions are the same as for the event extensions:
- Unique attribute name
- The attribute name must be alphanumeric and written in camel case (see examples above)
REST API also supports GET, POST and DELETE endpoints for retrieving, updating and deleting specific data extensions properties. To retrieve a data extension property from the guest profile, you can send a request like this:
GET /v2/guests/f7aabbca-1c1b-4fc2-be72-3e16294a4f03/extext1/09bfc8cc-3815-5b77-b75a-d3cc6a867c1a
where f7aabbca-1c1b-4fc2-be72-3e16294a4f03 is the guest reference, ext1 is the data extension group and 09bfc8cc-3815-5b77-b75a-d3cc6a867c1a is the data extension property reference.
Batch API
Additionally, you can send send additional data via Batch API https://doc.sitecore.com/cdp/en/developers/api/send-additional-guest-data.html. The principle is similar to the REST API, where you send data extensions using the ext property. You can specify one of the six extensions group names to differentiate data from multiple systems. Batch API is particularly suitable for asynchronous integration scenarios, such as daily imports from a CRM system to synchronise customer records updated within the last 24 hours.
How to use data extensions
Now, why would you need to send some guest information to CDP as data extensions?
One of the most common use cases is batch segmentation which enables creation of guest segments of guests based on their profile, event, and order extensions. This can be extremely helpful for implementing marketing automation campaigns such as sending newsletters or push notifications to specific groups of users. You can read more about batch segmentation in Sitecore CDP in my colleague’s blog post here.
Batch Segment configuration screen showing examples of customer profile fields and data extensions.
However, usage of data extensions is not limited to batch segmentation. Custom properties can be leveraged to build real-time audiences for live personalisation and A/B testing. They can be accessed within programmable nodes in decision models and returned as a part of API response in web and full stack experiences. Furthermore, this data can be extracted from Sitecore CDP and pushed to external systems, such as Tableau or Power BI for custom reporting.
In conclusion, Sitecore CDP's data extensions feature is essential for storing additional data that will help building marketing automation and personalisation, as well as getting insights into visitor segments and interactions.
By understanding how to create, manage, and read data extensions, you can harness the full potential of your customer data within Sitecore CDP & Personalize.
Top comments (0)