Understanding & enriching visitor profile data layer (cxs object)

March 23, 2022

Overview

jExperience stores a lot of data about the visitors of your website. This data might even be enriched by CRM or Marketing Automation using StackConnect. On the other end, many organizations are using web analytics and solutions such as Google Analytics, Google Data Studio, Matomo, AT Internet, Contentsquare, etc.. A classic requirement for these organizations is to make their analytics richer by adding information related to the jexperience profile in the data layer: segments, scores, interests or any profile properties.

Understanding the lifecycle and how the visitor profile data is loaded in the data layer

  1. The Jahia page is loaded. This page may contain a a javascript object called "wemInitConfig", in window.digitalData (window.digitalData.wemInitConfig).
  2. jExperience javascript tracker is loaded and reads wemInitConfig
  3. jExperience javascript tracker sends a http call to the endpoint "context.json"of Unomi/jCustomer, using information in the wemInitConfig. This http call has 2 main purposes: track the page view and get information related to the visitor profile.
  4. The visitor profile data layer (window.cxs javascript object) is updated with the information that was requested, thus making it available to any javascript code running on the page

Adding wemInitConfig to your page

window.digitalData.wemInitConfig is a javascript object that needs to be added to the pages where it is needed to enrich the data layer. As any other information that you want to add to a jahia page, there are several ways to inject wemInitConfig inside pages: 

  • Add the object in the jsp code of your template
  • Create a render filter (java code) 
  • Use the "addStuff" module. This method isn't the easiest the maintain and isn't ideal to go to production.

wemInitConfig.png

Example of test configuration using the addStuff module.

Enriching data layer with specific profile properties: requiredProfileProperties

is an array of profile property names, they will be loaded automatically by the tracker as soon as the jCustomer connection has been established. Exemple, to load the interests and the company of the visitor profile,

<script>
    window.digitalData.wemInitConfig = {
        "requiredProfileProperties": ["interests","company"]
    }
</script>

The resulting current user profile properties will be accessible as an object in the page using: 

window.cxs.profileProperties

Note, for test purposes, you can use "requiredProfileProperties": ['*']. This will add all visitor profiles roperties to the data layer. This setting is not advised in production for privacy reasons.

Enriching data layer with profile segments 

requireSegments: is an array containing the current user segments.

<script>
    window.digitalData.wemInitConfig = {
        "requireSegments": true
    }
</script>

The resulting current user segments will be accessible as an object in the page using: 

window.cxs.profileSegments

Enriching data layer with profile score (only supported since jCustomer 1.6.0)

requireScores: is an array containing the current user segments.

<script>
    window.digitalData.wemInitConfig = {
        "requireScores": true
    }
</script>

The resulting current user segments will be accessible as an object in the page using: 

window.cxs.profileScores

Example: adding properties, segments and scores

<script>
    window.digitalData.wemInitConfig = {
        "requiredProfileProperties": ["interests","company"],
        "requireSegments": true,
        "requireScores": true
    }
</script>

More information about visitor profile data layer

Any information added to the data layer by jExperience and related to the visitor profile will be added to the window.cxs object: 

cxs = {
    profileId: <identifier of the current user's profile>,
    sessionId: <identifier of the current user's session>,
    profileProperties: <optional, mapping profile property names to their values>,
    sessionProperties: <optional, mapping session property names to their values>,
    profileSegments: <optional array of segments the user matches>,
    profileScores: <optional array of scores the user matches>,
    filteringResults: <optional array of filtering results>,
    trackedConditions: <optional array of tracked conditions>
}

Technically, the cxs object is the result of a GET request to jCustomer context.json endpoint.

Context load callback

Since the window.cxs object is only created after the first call to jCustomer context, the wem.js library includes a function allowing callback functions to be registered to trigger actions on the collected data.

window.wem._registerCallback(() => {
    console.log('Context loaded')
})

Multiple callback functions can be added via wem.js and will all be called after every call to the jCustomer context.

More details about wem.js can be found on this page.