Enhanced Page Event Tracking

Background

The Adobe Analytics AppMeasurement library (the code that compiles and sends the hits that record Visitor behaviour and experience on a website) treats Page Event hits (known as “link-tracking”) differently to Page View hits in some fundamental ways:

1. Page Event hits only include variables (dimensions and metrics) that are explicitly configured to be sent
   • By contrast, a Page View hit automatically includes every Adobe Analytics variable that is currently set
2. Page Event hits do not have Page Name or Page URL
   • We’ll explore shortly why this is an incomplete statement while still being essentially true for our current purposes
3. There is no single metric for Page Event hits
   • Page View hits have the “Page views” metric; Page Event hits are spread across three metrics (“Custom Link Instances”, “Download Link Instances”, and “Exit Link Instances”)

This article describes some (in my opinion) imperative implementation steps that will make Page Event hits more useful for Digital Analytics alongside a recommended new variable to house all Page Event hit data.

Capturing Page Name and Page URL on Page Event hits

I mentioned some implementation steps that I consider imperative for all Adobe Analytics deployments; they are:

1. Capture Page Name in a separate variable (e.g., a Conversion Variable, or “eVar”)
2. Capture Page URL in a separate variable

I mentioned that Page Event hits do not include the Page Name and Page URL parameters: it is more correct to say that, although the Page Name (pageName, or sometimes gn, in the hit URL) and Page URL (g in the hit URL) are included in the URL that is generated to record a Page Event hit, they are effectively discarded once processing of a hit begins on the Adobe Analytics servers.

This means that, for their values to be available in the captured Adobe Analytics data, they need to be copied into other locations; the easiest method for achieving this on all Page Event hits (i.e. including the automatic Download Link and Exit Link hits) is via the doPlugins function.

The following code snippet included inside the definition of doPlugins will:

1. Copy the Page Name value into eVar1
2. Copy the Page URL value into eVar2
3. Define a mechanism (see enhancedPageEventVars variable in the code snippet that follows) that can be extended to include, on Page Event hits, any variable that you normally only set on Page View hits

//  Enhanced Page Event tracking (from meriweb.co.uk)
// - requires 'appendList' plug-in

// define array of variables to be included on all Page Event hits
var enhancedPageEventVars = ["eVar1", "eVar2"]; 

//  use the Dynamic Variables feature to set the variables without increasing the Request URL size unnecessarily
s.evar1 = "D=pageName" //  change to "D=gn" if your implementation uses this version ('gn') of Page Name
s.eVar2 = "D=g"

// if 'linkType' is set, a Page Event hit is in progress
if (s.linkType) { 
	if (typeof enhancedPageEventVars != undefined && enhancedPageEventVars.length > 0) {
		for (var i = 0; i < enhancedPageEventVars.length; i++) {
			// set or extend 's.linkTrackVars' config variable as relevant
			s.linkTrackVars = (s.linkTrackVars == "None" ? enhancedPageEventVars[i] : s.apl(s.linkTrackVars, enhancedPageEventVars[i], ",", 2));
		}
	}
} else if (!s.linkType) {
	// if a Page Event isn't in progress, reset the configuration
	s.linkTrackVars = "None";
	s.eVar1 = s.eVar2 = "" //  comment out this line to set eVar1 and eVar2 on all Page View hits as well as Page Event hits
}

Capture Page Event Details in a Separate Variable

In addition to the differences between the handling of the two hit types, Page View and Page Event, in Adobe Analytics, the three variables that relate to Page Event hits in Adobe Analytics (Custom Link, Download Link, and Exit Link) have an additional limitation: they cannot be Classified.

My recommendation is to capture the details that describe each Page Event hit into another variable and apply Classifications to the collected values.

Introduction to Adobe Analytics Classifications

“Classifications” is a powerful Adobe Analytics feature for categorising the values of a given variable – essentially assigning metadata to captured data. Among other uses, employing Classifications allows multiple levels of detail to be extracted from a single value.

It is too large a topic to explore in this article, but imagine a simple example value that might be captured in the Download Link variable:

https://www.meriweb.co.uk/uploads/cheat-sheets/adobe-analytics-cheat-sheet.pdf?version=1.0

Using Classifications, there are all kinds of details that could be extracted from this value using a built-in feature (Classification Rule Builder):

• Filename (“adobe-analytics-cheat-sheet.pdf”)
• Filetype (“pdf”)
• Version (“1.0”)
• Domain (“www.meriweb.co.uk”)
• Protocol (“https”)

Classifications can also be used to break out the various natural groupings that are often lumped together inside the “Custom Link” variable; typical examples are:

• Media interactions (playing/pausing audio and video)
• Carousel interactions (e.g., advancing images in a gallery)
• Expanding/collapsing additional info elements (e.g., revealing answers on an FAQ page, showing extra info on a product card)
• Basket quantity modifications (often increasing or decreasing the quantity of a particular item in the shopping cart is captured as a Page Event, not a Page View)

Populating the Page Event Variable

As before, the most straightforward method involves doPlugins (although it should be noted that most – if not all – of what is described in this article can be accomplished using Adobe LAUNCH).

The steps involved are:

1. Configure a Conversion Variable with expiry set to “Hit”
   • A Conversion Variable (“eVar”) has 255 bytes to play with
   • Set to expire on hit, it effectively acts as a Traffic Variable (“prop”)
2. Include the code snippet below in the definition of doPlugins
3. Configure a Processing Rule that populates the Conversion Variable
4. Define Conversion Classification variables (against the Conversion Variable defined in step #1)
5. Set up a Classification Rule Builder entry to populate the Classification variables

Code Snippet

The code snippet that follows is an extended version of the earlier snippet in this article. Note the link_detail variable; this is an optional parameter that can be used to augment (typically) “Custom Link” Page Event hits with another level of detail – it will be set by the relevant Adobe LAUNCH Rule in each case. A sample use case would be to capture the value “webchat” in link_name and the detail of the interaction (e.g., “chat started (user-initiated)”, “chat started (proactive)”, “initial agent response”) in link_detail.

//  Enhanced Page Event tracking (from meriweb.co.uk)
// - requires 'appendList' plug-in

// define array of variables to be included on all Page Event hits
var enhancedPageEventVars = [
	"eVar1",
	"eVar2",
	"contextData.link_type",
	"contextData.link_name",
	"contextData.link_detail"
];

//  use the Dynamic Variables feature to set the variables without increasing the Request URL size unnecessarily
s.evar1 = "D=pageName" //  change to "D=gn" if your implementation uses this version ('gn') of Page Name
s.eVar2 = "D=g"

// if 'linkType' is set, a Page Event hit is in progress
if (s.linkType) {
	if (typeof enhancedPageEventVars != undefined && enhancedPageEventVars.length > 0) {
		for (var i = 0; i < enhancedPageEventVars.length; i++) {
			// set or extend 's.linkTrackVars' config variable as relevant
			s.linkTrackVars = (s.linkTrackVars == "None" ? enhancedPageEventVars[i] : s.apl(s.linkTrackVars, enhancedPageEventVars[i], ",", 2));
		}
		s.contextData['link_type'] = s.linkType;
		//  On Download and Exit Link hits, 'pev1' ("Page Event Variable 1") is set; otherwise, it's 'pev2'
		//  The next line's output will be "D=pev1" or "D=pev2" as appropriate
		s.contextData['link_name'] = "D=" + (s.linkType == "d" || s.linkType == "e" ? "pev1" : "pev2");
	}
} else if (!s.linkType) {
	// if a Page Event isn't in progress, reset the configuration
	s.linkTrackVars = "None";
	s.eVar1 = s.eVar2 = "" //  comment out this line to set eVar1 and eVar2 on all Page View hits as well as Page Event hits
	//  don't permit the Page Event-specific events to pollute subsequent hits
	s.contextData['link_type'] = s.contextData['link_name'] = s.contextData['link_detail'] = "" 
}

Processing Rule

This is quite straightforward and is easier shown than described:

The aim is end up with a value that looks like one of the following:

o~video~play
o~main menu reveal
e~https://www.bbc.co.uk/news
d~https://www.meriweb.co.uk/uploads/cheat-sheets/adobe-analytics-cheat-sheet.pdf?version=1.0

Values like these can be very usefully grouped in any number of ways. In the next section, I have included a simple example that uses three levels of detail.

Sample Rule Builder Classification Entry

Again, easier to demonstrate than explain. In the following images, you will see:

1. A sample Rule Builder Classification entry that extracts /infers various categorisation and other details from the Enhanced Page Event variable described in this section
   • This has been briefly annotated to give some guidance on what each Rule does
2. A set of “spoofed” values against which the Rule Builder Classification entry is evaluated
3. The results of running the Rule Builder Classification entry over the spoofed values

Summary

This article describes some relatively straightforward steps for adding more details (Page Name, etc.) to Page Event hits as well as capturing the data in a more useful manner.

An advantage of an approach like this is that it only needs to be set up correctly once for on-going benefits; all future Page Event hits will automatically fit into this framework, although the Rule Builder Classification entry will need refinement as you introduce new categories of Page Event hits on your site.