Tracking page views and events on external sites

November 14, 2023

Overview

The wem.js library is jExperience tracker and is used to send events to jCustomer. Using wem.js with an external site requires the use of an additional javascript library (referred to as jtracker) which will take care of loading wem.js and generating an appropriate digitalData object.

The tracker snippet is fully configurable. By default, the tracker is preconfigured from the tracker snippet and uses information available for the current page to generate missing contextual configuration, such as using current page information to build the page view event. You can override any of this information and also provide additional data if needed.

More details can be found on enabling the tracker and getting its snipped in the End-User section of the academy.

Configuration

The jtracker library is pre-configured with a window.jtrackerConfig object pre-populated by jExperience when obtaining the snippet (also referred to as tracking code).

The section below details in Typescript notation the jtrackerConfig object:
 

declare namespace jtracker {
   /*
      Technical properties used by the tracker. These properties are likely to be
      the same across your website pages. The properties provide URLs to the 
      different servers, including Jahia and JCustomer, and some connection related
      configurations. We recommend that you do not change this configuration,
      unless you know what you are doing.   
   */
    interface Core {
        jahiaServerUrl: string;
        jahiaServerContextPath: string;
        jExperienceModuleVersion: string;
        jCustomerPublicUrl: string;
        jCustomerRequestsTimeout: string;
        jCustomerCookieName: string;
    }

   /*
      Contextual properties of the current web page. This information is used to
      build the different events that are sent to jCustomer. We recommend 
      overriding the default configuration with data that comes from your system.    
   */
    interface Context {
        scope: string;
        /*
          The lang property is used to both send language info in events and load the 
          contents from Jahia server, in case you would like to display a personalization. 
          For example, lang is used to ask Jahia for the best internationalized version of 
          the personalized content. It's important that the lang configuration is a known  
          locale for your Jahia website that contains your contents.
        */
        lang: string;
        siteID: string;
        pageID: string; // Defaults to value of document.location.pathname
        pageName: string; // Defaults to value of document.title
        pagePath: string; // Defaults to value of document.location.pathname
        pageAttributes: [key: string]: any; // Empty object by default
        pageAdditionalProperties: [key: string]: any; // Empty object by default
        siteAdditionalProperties: [key: string]: any; // Empty object by default 
        // Defaults to value of document.location.origin + document.location.pathname       
        destinationURL: string;
        destinationSearch: string; // Defaults to value of document.location.orogin.search
        referringURL: string; // Defaults to value of document.referrer
        requiredProfileProperties: string[]; // Defaults to ['j:nodename']
        templateName: string; // Defaults to ''
        nodeType: string; // Defaults to 'jnt:page'
        isContentTemplate: Boolean; // Defaults to false
        categories: string[]; // Defaults to Empty array
        tags: string[]; // Defaults to Empty array
        interests: [key: string]: any; // Empty object by default
    }

    interface JtrackerConfig {
       core: Core;
       context: Context;
    }
}

The jtracker library will then build a window.digitalData object from the values contained in jtrackerConfig.

Here’s an example of a jtrackerConfig object:
 

{
    "core": {
        "jahiaServerUrl": "http://localhost:8080",
        "jahiaServerContextPath": "",
        "jahiaGraphQLAuthToken": "",
        "jExperienceModuleVersion": "2_1_0-SNAPSHOT",
        "jCustomerPublicUrl": "http://localhost:8181",
        "jCustomerRequestsTimeout": 1500,
        "jCustomerCookieName": "context-profile-id"
    },
    "context": {
        "scope": "mySite",
        "lang": "en",
        "siteID": "mySite",
        "pageId": "http://my-external-site.com/home.html",
        "pageName": "My external site - Home page",
        "pagePath": "http://my-external-site.com/home.html",
        "pageAttributes": {},
        "pageAdditionalProperties": {},
        "siteAdditionalProperties": {},
        "destinationURL": "http://my-external-site.com/home.html",
        "referringURL": "",
        "requiredProfileProperties": [
            "j:nodename"
        ],
        "templateName": "",
        "nodeType": "jnt:page",
        "isContentTemplate": false,
        "categories": [],
        "tags": [],
        "interests": {}
    }
}

Providing a custom configuration

You can provide a custom configuration by simply adding an additional code snippet on top of the tracker snippet that contains the custom configuration. The name of this custom configuration object is jtrackerCustomConfig. It follows the same structure as the previous default configuration object and must be defined in the window object in the current page. Overwrite any properties contained in the default generated configuration by redefining the properties you would like to change.

Within the library, the override is applied using the following code:

if (window.jtrackerCustomConfig) {
    jtracker.config.core = {
        ...jtracker.config.core,
        ...window.jtrackerCustomConfig.core
    }
    jtracker.config.context = {
        ...jtracker.config.context,
        ...window.jtrackerCustomConfig.context
    }
}

For example, you can provide two tags named tag1 and tag2 using the following code snippet at the top of your page:

<script type="text/javascript">
   window.jtrackerCustomConfig = {
       context: {
           tags: ["tag1", "tag2"]
       }
   }
</script>
<!-- Tracker snippet -->

Checking the configuration

In your web page developer tools console, you can evaluate this expression:

jtracker.config

This prints the complete configuration currently used. This is the final configuration, which contains the default configuration merged with your custom configuration.

Configuring the tracker snippet

The tracker snippet is fully configurable. By default, the tracker is preconfigured from the tracker snippet and uses information available for the current page to generate missing contextual configuration, such as using current page information to build the page view event. You can override any of this information and also provide additional data if needed.

Note: This feature is available on JExperience 2.1 and above.

About the default generated configuration

Here is an example of default configuration generated by the tracker.

{
    "core": {
        "jahiaServerUrl": "http://localhost:8080",
        "jahiaServerContextPath": "",
        "jahiaGraphQLAuthToken": "",
        "jExperienceModuleVersion": "2_1_0-SNAPSHOT",
        "jCustomerPublicUrl": "http://localhost:8181",
        "jCustomerRequestsTimeout": 1500,
        "jCustomerCookieName": "context-profile-id"
    },
    "context": {
        "scope": "mySite",
        "lang": "en",
        "siteID": "mySite",
        "pageId": "http://my-external-site.com/home.html",
        "pageName": "My external site - Home page",
        "pagePath": "http://my-external-site.com/home.html",
        "pageAttributes": {},
        "pageAdditionalProperties": {},
        "siteAdditionalProperties": {},
        "destinationURL": "http://my-external-site.com/home.html",
        "referringURL": "",
        "requiredProfileProperties": [
            "j:nodename"
        ],
        "templateName": "",
        "nodeType": "jnt:page",
        "isContentTemplate": false,
        "categories": [],
        "tags": [],
        "interests": {}
    }
}

As you can see, there are two blocks of properties:

  • core
    Technical properties used by the tracker. These properties are likely to be the same across your website pages. The properties provide URLs to the different servers, including Jahia and jCustomer, and some connection related configurations. We recommend that you do not change this configuration, unless you know what you are doing.
  • context
    Contextual properties of the current web page. This information is used to build the different events that are sent to jCustomer. We recommend overriding the default configuration with data that comes from your system. For example, consider the following questions when you override the pageID and pageName properties:
    • pageID
      is generated using the current document.location.href. Is your system able to provide identifiers for your pages?
    • pageName
      is generated using current document.title. Is your system able to provide the page name?

Adding a custom configuration

You provide a custom configuration by simply adding an additional code snippet on top of the tracker snippet that contains the custom configuration. The name of this custom configuration object is jtrackerCustomConfig. It follows the same structure as the previous default configuration object and must be defined in the window object in the current page. Overwrite any properties contained in the default generated configuration by redefining the properties you would like to change.

Sample configurations

This section shows examples of custom configurations that you can provide including how to add tags to page view events, change the tracker language, change the Jahia server URL, provide multiple configurations, and request profile properties in context loading.

Adding tags to my page view events

This example shows how to provide two tags named tag1 and tag2 to my page view events.

<script type="text/javascript">
   window.jtrackerCustomConfig = {
       context: {
           tags: ["tag1", "tag2"]
       }
   }
</script>
<!-- Tracker snippet -->

Changing the language of the tracker

The lang property is used to both send language info in events and load the contents from Jahia server, in case you would like to display a personalization. For example, lang is used to ask Jahia for the best internationalized version of the personalized content. It’s important that the lang configuration is a known local for the Jahia website that contains your content.

<script type="text/javascript">
   window.jtrackerCustomConfig = {
       context: {
           lang: "fr"
       }
   }
</script>
<!-- Tracker snippet -->

Changing the Jahia server URL

If your Jahia server is behind a proxy and the generated conf is not correct, you can manually configure the Jahia server URL through the jahiaServerUrl property.

<script type="text/javascript">
   window.jtrackerCustomConfig = {
       core: {
           jahiaServerUrl: "http://myJahiaServer.com"
       }
   }
</script>
<!-- Tracker snippet -->

Providing multiple configurations at the same time

You can redefine any number of properties at the same time, depending on what you need to configure. This example shows how to set multiple properties, including lang, pageName, pageId, tags, categories, and interests.

<script type="text/javascript">
   window.jtrackerCustomConfig = {
       core: {
           jahiaServerUrl: "http://myJahiaServer.com"
       },
       context: {
           lang: "fr",
           pageName: "myPage",
           pageId: "b4b6dcb3-4364-448a-8eaf-bfe50e813386",
           tags: ["tag1", "tag2"],
           categories: ["category1", "category2"],
           interests: {
               car: 15,
               moto: 5
           }
       }
   }
</script>
<!-- Tracker snippet -->

Request profile properties in context loading

<script type="text/javascript">
   window.jtrackerCustomConfig = {
       context: {
           requiredProfileProperties: ['j:nodename', 'firstName', 'lastName']
       }
   }
</script>
<!-- Tracker snippet -->

Debugging the current configuration used by the tracker

In your web page developer tools console, you can evaluate the following expression. This prints the complete configuration currently used. This is the final configuration, which contains the default configuration merged with your custom configuration.

jtracker.config

Cookies

There are 2 importants cookies used by the tracker.

About the wem-session-id cookie

The wem-session-id cookie is required by the wem.js when loading the context, which allows you to keep and reuse the generated session UUID. As this cookie is only read client side by Javascript (jtracker and wem.js), the cookie is not impacted by browser restrictions because it’s not used during HTTP requests directly. The session ID is reused by the wem.js context loading and the session ID is passed to the context request using JSON.

In jTracker implementation, Jahia checks if this cookie is already present in the browser. If the cookie:

  • is present, Jahia creates the cookie with a random UUID (new session)
  • is not present, Jahia reuses the cookie and remains on the same session ID (ongoing session)

About the context-profile-id cookie

The context-profile-id cookie is set by jCustomer to store the profile ID on the client browser. The cookie is currently configured like this:

  • domain
    jCustomer domain
  • path
    /
  • SameSite
    Lax

This cookie has a great chance to not work with recent browser limitations, because Lax configuration allows the cookie to be passed in top level navigation only (only for links and URL change in browser). However, in our case we are using AJAX requests to load the context.

There are two options:

  • Your external site and jCustomer share the same domain or subdomain
    It will work, the cookie will be passed during AJAX context loading, allowing jCustomer to retrieve the user profile from the cookie.
  • Your external site and jCustomer do not share the same domain or subdomain
    In this case, the cookie will not be sent to jCustomer during AJAX context loading. jCustomer cannot retrieve the current profile from the cookie and must retrieve the profile from the session ID (see wem-session-id cookie). JCustomer can retrieve the user profile based on the current session ID, but if the wem-session-id cookie is expired or lost, jCustomer will be forced to create a new profile.

In summary, if your external site and jCustomer share the same domain or subdomain, each new session is attached to the existing profile if the context-profile-id already exists on the client. Otherwise, each new session is attached to a new profile.

 

 

Sample configuration

This sample configuration shows jCustomer configured with:

 

  • cookie domain
    example.com
  • domain
    jcustomer.example.com
domain type of site cookie: wem-session-id cookie: context-profile-id sessions
example.com Jahia example.com example.com attached to an existing profile on example.com
portal.example.com Jahia portal.example.com example.com attached to an existing profile on example.com
examplesuccess.com Jahia examplesuccess.com example.com New session=new profile. Sessions are not attached to existing profiles.
app.example.com external app.example.com example.com attached to an existing profile on example.com
otherexamples.com external otherexamples.com example.com New session=new profile. Sessions are not attached to existing profiles.