Contents
This is the second article I’ve written on deploying AEP Web SDK via Launch. Check out Part 1 which goes through the basics. I’ve created an XDM schema, created a Dataset in AEP to store data, set up a Datastream which configures the Edge Network to talk to my Dataset, and installed the Web SDK extension in Adobe Launch. Now it’s time to send event data.
Web SDK Send Event
The main task of Web SDK is to send data to the Datastream (Edge Server) we set up earlier. To do this we use rule action type called “Send Event” in the AEP Web SDK extension. This action requires an “event type” and a data element which holds your XDM format data, and that’s it. There is a bunch of event types for the ExperienceEvent class which our schema is based on. Check out the Adobe docs for a full list. I am sending a website page view event which is the “web.webpagedetails.pageViews” type.
Instance: If your site is running more than one instance of Web SDK at the same time you can use this field to determine which one to send events with. I’ve left the default value.
Type: This refers to the ExperienceEvent type of the event being sent.
XDM Data: This is where you specify your XDM data.
Data: Here you can attach non-XDM format data to your event. One use case for this field is with Data Prep where non-XDM data can be mapped into XDM fields as it’s ingested. Another use case for this field is sending data to Adobe Target Recommendations.
Merge ID: This is for AEP Datasets as two events with the same merge ID value get joined together.
Dataset ID: This field is where you can override the destination AEP Dataset, as compared to using the one set up in your Datastream.
But wait, what was that about an XDM data element? In the example above I have a data element “XDM | Global” set in the XDM Data field. This data element contains the information that we want to send based on the XDM schema created in Part 1. You can simply create a custom code data element to create a JSON object in the correct format OR you can use the handy data element type Adobe provides with the Web SDK extension. Let’s talk about these XDM objects for a bit.
XDM Data Elements
The basis of Web SDK is to send events with data, and that data must match your XDM schema. If you have set up Adobe Analytics before this process should be a little familiar. With Adobe Analytics you use data elements to retrieve data – for example from the data layer, from the page URL, from the DOM. Web SDK is similar – we use data elements to prepare our XDM object. In Adobe Analytics you map data elements into eVars, props and events on a Set Variables action. This is not the case with Web SDK. The mapping happens inside a data element not inside the Send Event action.
The best way to show this is to look at the XDM object data element type provided by the Web SDK extension.
When you create a new data element of XDM Object type you will need to specify your XDM schema. Once you do so, a nice interface is shown displaying the fields available in the schema. You can populate each field with hardcoded values or data elements. For example I’ve set web.webPageDetails.name to a data element “CC | Page Name” which is used to get the current page name. I can build out this XDM object – picking and choosing the fields to populate.
Note that some fields have an asterisk symbol next to them, such as the “web.webPageDetails.URL” field. This means that the Web SDK extension is going to automatically populate this field. That’s handy! You can, of course, override this by using your own value.
You will use this data element in your Send Event action. On a big website with many user interactions and many rules you will probably need several XDM data elements for specific events, as they might contain different data. Here is where a bit of forward planning might help down the line.
XDM Data Elements Planning
This section is more of a tip, you don’t need to do it this way. In fact it might often make sense not to do it this way especially for simple implementations. Think of a standard Adobe Launch tags container on a pretty standard commerce website, with rules for certain pages and more rules for interactions. There might be a standard ‘global page rule’ which fires on each page, a different rule for a checkout page, a rule for adding a product to the cart, and a rule for a button click. Each rule sends a beacon to Adobe Analytics with different data points. The global page load rule sends a page name, and the checkout page rule sends a list of products. The button click sends the name of the button.
This can work for Adobe Analytics because each beacon can have its own Set Variables action, allowing you to set different variables on each beacon. Web SDK works slightly differently since each Send Event action references an XDM object data element. You may be tempted to create a new XDM object for each rule – one for the page loads and one for the buttons, and this is not a bad way to go but it could become troublesome as time goes on. What if you need to update a value included in many XDM objects, now you must go and edit each data element making sure not to miss any! What if you now want to capture “authentication state” on every single XDM data element – that’s potentially a lot of data elements to open, edit and save.
Introducing the “merged objects” data element type from the Core Launch extension. This data element type takes two JSON objects and merges them together to form one object. I propose to use this data element type to make one single “global” XDM object and other “specific” XDM objects for each use case. Then I will create a new data element to merge them together as the final object to include in the Send Event action. Sound confusing and/or cumbersome? Now we need three data elements instead of one? Let me explain some more.
Global XDM Data Element
A global XDM object contains information required on every Send Event from Web SDK. Things like page name, URL, authentication status, a user identifier, order identifier, language settings, location, etc. Populate this with your data elements to get these values. (If you are used to Adobe Analytics implementation you can think of this as your “doPlugins” or global variables section, data meant to be sent with every hit.)
Specific XDM Data Element
A specific XDM object contains information required only on specific Send Events from Web SDK. For example the button name is only required on the button click rule. A search term might only be required on a search page rule. The web.webPageDetails.pageViews value is only required on page view events. I will create a bunch of very specific XDM object data elements to populate these values.
Merged XDM Object
The merged object is the final data element to bring together at least two XDM objects – the global and the specific. The “merged objects” data element type lets you specify two XDM object data elements as the input, and the output is the merged state of both. What you are left with is global + specific values. The merged object is what’s included in the Send Event action to send with Web SDK as it contains your global variables and your specific variables.
Why go to this trouble?
- You only need to populate global variables once, in one data element. You no longer need to populate “web.webPageDetails.name” in every single XDM object. The global variables can be edited and maintained over time.
- You can easily change global variables with one edit, rather than editing every single XDM object. Say you need to capture something new on every hit? Just edit the global XDM object.
- Once your rules and Send Event actions are set up, your future changes happen inside data elements only. Need to make a change to the data on the button click rule? Just edit the specific XDM data element for that rule, not the rule itself. You’ve abstracted the ‘data collection’ and the ‘data mapping’ away from rule actions and into data elements. Rules are for actions. Data Elements are for data.
Testing Your Web SDK Events
Now that we have actually populated an XDM object inside our data elements, and included that inside our Send Event action, it’s time to test.
We need to ensure that a) the XDM objects are being populated as expected and b) the Send Event action is actually sending an event and c) the Datastream is receiving and responding to the event. I am going to use Chrome development tools, specifically the console and network tabs. There is also the great AEP Debugger Chrome Extension built by Adobe.
Testing XDM
With my Launch environment saved and built to development I’m going to load up a page on my site running this Launch environment. The first thing I like to test is the XDM object data element. You might not always be able to test this way, since some values are populated during specific website events such as on a button click.
In the Chrome console get the value of your XDM object and take a look around.
_satellite.getVar('your-data-element-name-here');
I’ve cut out the values above, but you should be able to see something similar – a JSON object which has the values in your XDM schema format. Note that the XDM data element only contains your values – and not the automatically populated values. These get added right before the Send Event action, so we will see them later.
This step should give you an indication that a) your data is structured correctly and b) the values are as expected. Again, you might not be able to do this step with every event as values won’t always be available for you to view in the console. I like to do this step where I can.
Testing Web SDK Payload
This is really the main step for testing. You need to make sure that your event fired and included the relevant data. For this we can use the Chrome network tab and filter requests with “/ee” to find the requests to the AEP Edge Network. These requests have a parameter “configId” which is the ID of your Datastream.
Once you have your request, switch to the payload tab to view the contents.
Inside the payload is a few JSON objects. Open the “events” object, which is an array of events, and open the first item inside. You will see an “xdm” object which should contain your XDM data element plus any automatically populated fields. In the example above there is a bunch of data such as device screen size, timestamp and URL. I’ve cut out the “web.webPageDetails.name” value here, but this was populated with my “CC | Page Name” data element. Looks great!
This event has been sent to my Datastream. From there it gets forwarded on to any linked services configured to the Datastream.
I also wanted to show a real example of an XDM event object, so here is one taken directly from the Adobe marketing website. You can see the same Field Group in use!
[
{
"xdm": {
"eventType": "web.webpagedetails.pageViews",
"web": {
"webPageDetails": {
"URL": "https://business.adobe.com/au/products/experience-platform/adobe-experience-platform.html",
"pageViews": {
"value": 1
},
"name": "business.adobe.com:products:experience-platform:adobe-experience-platform",
"siteSection": "Adobe Experience Platform"
},
"webReferrer": {
"URL": "https://www.google.com/"
}
},
"device": {
"screenHeight": 1080,
"screenWidth": 1920,
"screenOrientation": "landscape"
},
"environment": {
"type": "browser",
"browserDetails": {
"viewportWidth": 1903,
"viewportHeight": 929
}
},
"placeContext": {
"localTime": "2022-04-26T18:29:12.253+10:00",
"localTimezoneOffset": -600
},
"timestamp": "2022-04-26T08:29:12.253Z",
"implementationDetails": {
"name": "https://ns.adobe.com/experience/alloy/reactor",
"version": "2.6.4+2.7.3",
"environment": "browser"
}
}
}
]JavaScript Send Events
I thought I would very briefly mention what the Adobe Launch extension is actually doing. Web SDK is a JavaScript library at it’s core, there is just a handy Launch extension to make life easier. When you configure a Send Event action you are actually instructing the browser to run something like the following code.
alloy("sendEvent", {
"xdm": myXDMData,
"type": "web.webpagedetails.pageViews"
});Where ‘myXDMData’ is a JSON object containing your XDM format data. I’m going to make a whole post about Web SDK using JavaScript rather than the Launch extension. You can see it’s a simple concept – a function defined by the JS library with options to configure and send your event. The Launch extension makes it a lot easier to set up and maintain though, and comes with extra benefits like automatically populated fields.
Next Steps
Through Part 1 and Part 2 the following tasks have been completed.
- Set up an XDM schema using the ExperienceEvent class with the Web SDK Field Group.
- Created a Dataset in AEP to hold event data. (Only required if you are sending data to AEP.)
- Set up a Datastream which is an Edge Configuration used to forward data from Web SDK to Adobe services.
- Configured the AEP Web SDK Launch extension.
- Created data elements to contain our XDM data.
- Created rules to send events with Web SDK.
- Did some quick tests to ensure those events are sent to the Datastream with populated XDM objects.
What’s next?
The steps above are a simple introduction to Web SDK. There is far more we can do. For example we could use Web SDK to replace the Adobe Analytics extension (appMeasurement.js) by forwarding our XDM data to Adobe Analytics with our Datastream. We could integrate with Adobe Target without the need for the at.js library. We could migrate away from the Experience Cloud Identity extension too, and let Web SDK handle our ECID fetching. If we did this, some of the page load benefits of Web SDK would be realised as users wouldn’t need to download so many separate libraries for these tasks.
As always there is much more to talk about! But I will leave it there for this post. Thanks for reading.