Data Prep is an Adobe Experience Platform service that allows you to map, transform, and validate data to and from Experience Data Model (XDM). When configuring a Platform-enabled datastream, you can use Data Prep capabilities to map your source data to XDM when sending it to the Platform Edge Network.
All data sent from a web page must land in Experience Platform as XDM. There are 3 ways to translate data from an on-page data layer to the XDM accepted by Experience Platform:
This guide focuses on the 3rd option.
There are two uses cases where Data Prep for Data Collection is useful:
The existing data layer must be sent using the data
object within the sendEvent
command.
If you are using Tags, you must use the Data field of the Send Event action type, as described in the Web SDK tag extension documentation.
The rest of this guide will focus on how to map the data layer to XDM standards after it has been sent by the WebSDK.
For comprehensive guidance on all Data Prep capabilities, including transformation functions for calculated fields, refer to the following documentation:
This guide covers how to map your data within the UI. To follow along with the steps, start the process of creating a datastream up to (and including) the basic configuration step.
For a quick demonstration of the Data Prep for Data Collection process, refer to the following video:
Hi, I’m Travis Jordan on the Adobe product team. In this video, I’m going to show you how to use your existing data layer to send data to Adobe products and other third-party destinations. By the end of this video, you’ll be able to add your data layer to a new datastream in Data Collection. And you’ll also be able to perform basic mapping functions using the Data Prep for Data Collection feature. Let’s go ahead and hop over to Adobe Experience Platform Data Collection, and get started. Okay, first, we’ll go ahead and select Datastreams from the left menu, and now we’ll create a new datastream.
Let’s go ahead and give that a name.
You can also add a brief description if you’d like. Next, we’ll select a previously created event schema. For this use case, we’re going to select the schema titled “Alloy Magento Store.” Now, I’ll go ahead and click Save and Add Mapping. On the screen, you can upload a previously created JSON file representing your data layer or, if you’ve already implemented the Web SDK and are collecting your data layer via the data object, you can copy the data object from your website, and then simply paste it to your datastream. Let me walk you through how to do that. Okay, here we are on our sample website. Let’s go ahead and just copy the data layer here, and now just jump back over to data prep, and we’re going to paste this right here. Note, one thing to be aware of the JSON object must have a single root node data in order to pass validation. So let’s go ahead and just add that to our schema.
And we’ll add another curly bracket at the end. And now we’re good to go. Let’s go ahead and click Next.
Okay, now we’re going to map the data layer to Adobe’s XDM format so that it can be sent to other Adobe products, or third-party destinations. In this use case, we want to send page visibility data to Adobe so that we can know whether or not this page is visible in the browser. So let’s go ahead and click Add a new mapping, and from the source field we’re going to go ahead, and select Visibility, and then next we’ll jump over to the target field, and under Web we’ll go ahead and select PageVisibility. Now, you can see we have our source field and target field mapped. You can also clean up your data by selecting from a list of 75 plus data prep functions. This will be covered in more detail in another tutorial.
So, for now, we’ll go ahead and just click Save.
Lastly, you can add and configure a service, which tells your datastream where to send this data. For this use case, we’ll go ahead and send our data to Experience Platform. So I’m going to select Add Service, and Experience Platform.
I want to ensure that it is enabled. Now, I select my event data set. For this use case, I’m going to select Alloy Magento Store, and now I’ll go ahead and click Save, and there you go.
This wraps up our video tutorial on how to use your existing data layer to send data to Adobe products, and other third-party destinations, good luck. -
Select Save and Add Mapping after completing the basic configuration for a datastream, and the Select data step appears. From here, you must provide a sample JSON object that represents the structure of the data that you plan on sending to Platform.
To capture properties directly from your data layer, the JSON object must have a single root property data
. The subproperties of the data
object should then be constructed in a way that maps to the data layer properties that you want to capture. Select the section below to view an example of a properly formatted JSON object with a data
root.
data
root{
"data": {
"eventMergeId": "cce1b53c-571f-4f36-b3c1-153d85be6602",
"eventType": "view:load",
"timestamp": "2021-09-30T14:50:09.604Z",
"web": {
"webPageDetails": {
"siteSection": "Product section",
"server": "example.com",
"name": "product home",
"URL": "https://www.example.com"
},
"webReferrer": {
"URL": "https://www.adobe.com/index2.html",
"type": "external"
}
},
"commerce": {
"purchase": 1,
"order": {
"orderID": "1234"
}
},
"product": [
{
"productInfo": {
"productID": "123"
}
},
{
"productInfo": {
"productID": "1234"
}
}
],
"reservation": {
"id": "anc45123xlm",
"name": "Embassy Suits",
"SKU": "12345-L",
"skuVariant": "12345-LG-R",
"priceTotal": "112.99",
"currencyCode": "USD",
"adults": 2,
"children": 3,
"productAddMethod": "PDP",
"_namespace": {
"test": 1,
"priceTotal": "112.99",
"category": "Overnight Stay"
},
"freeCancellation": false,
"cancellationFee": 20,
"refundable": true
}
}
}
To capture properties from an XDM object data element, the same rules apply to the JSON object, but the root property must be keyed as xdm
instead. Select the section below to view an example of a properly formatted JSON object with an xdm
root.
xdm
root{
"xdm": {
"environment": {
"type": "browser",
"browserDetails": {
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_5) AppleWebkit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.112 Safari/537.36",
"javaScriptEnabled": true,
"javaScriptVersion": "1.8.5",
"cookiesEnabled": true,
"viewportHeight": 900,
"viewportWidth": 1680,
"javaEnabled": true
},
"domain": "adobe.com",
"colorDepth": 24,
"viewportHeight": 1050,
"viewportWidth": 1680
},
"device": {
"screenHeight": 1050,
"screenWidth": 1680
}
}
}
You can select the option to upload the object as a file, or paste the raw object into the provided textbox instead. If the JSON is valid, a preview schema is displayed in the right panel. Select Next to continue.
Use a sample JSON object that represents every data layer element that may be used on any page. For example, not all pages use shopping cart data layer elements. However, the shopping cart data layer elements should be included in this sample JSON object.
The Mapping step appears, allowing you to map the fields in your source data to that of the target event schema in Platform. From here, you can configure the mapping in two ways:
To create a mapping rule, select Add new mapping.
Select the source icon (), and in the dialog that appears select the source field that you want to map in the provided canvas. Once you have chosen a field, use the Select button to continue.
Next, select the schema icon () to open a similar dialog for the target event schema. Choose the field that you want to map the data to before confirming with Select.
The mapping page reappears with the completed field mapping shown. The Mapping progress section updates to reflect the total number of fields that have been successfully mapped.
If you want to map an array of objects (in the source field) to an array of different objects (in the target field), add [*]
after the array name in the source and destination field paths, as shown below.
If you have previously created a datastream, you can reuse its configured mapping rules for a new datastream.
Importing mapping rules from another datastream overwrites any field mappings that you might have added before the import.
To start, select Import Mapping.
In the dialog that appears, select the datastream whose mapping rules you want to import. Once the datastream is chosen, select Preview.
Datastreams can only be imported within the same sandbox. In other words, you cannot import a datastream from one sandbox to another.
The next screen shows a preview of the saved mapping rules for the selected datastream. Make sure that the displayed mappings are what you expect, and then select Import to confirm and add the mappings to the new datastream.
If any source fields in the imported mapping rules are not included in the sample JSON data that you provided earlier, those field mappings will not be included in the import.
Continue following the above steps to map the rest of the fields to the target schema. While you do not have to map all available source fields, any fields in the target schema that are set as required must be mapped to complete this step. The Required fields counter indicates how many required fields are not yet mapped in the current configuration.
Once the required field count reaches zero and you are satisfied with your mapping, select Save to finalize your changes.
This guide covered how to map your data to XDM when setting up a datastream in the UI. If you were following general datastreams tutorial, you can now return to the step on viewing datastream details.