Sitemap Event Validation

A Sitemap sends events to Personalization based on the actions of the website visitors (users). There are several ways to validate whether the Sitemap configuration correctly recognizes the targeted user actions and sends the corresponding events.

Sitemap events are HTTP requests sent to Personalization's Event API endpoint that describes the page's context, or a specific action a user performed on the site. Examples of Sitemap events include:

  • Visiting a page
  • Viewing a catalog item
  • Submitting a form
  • Adding an item to a shopping cart
  • Purchasing an item
  • Clicking a designated page area

You can validate Sitemap events using the following tools and methods.

The remainder of this article provides guidance for using each of these tools to validate a Sitemap.

As you develop a Sitemap, you can use the Sitemap Editor as described in the following sections to confirm that the JavaScript describing your events is valid and configured correctly.

While the Sitemap Editor is vitally useful for the development process, it is essential to test your sitemap code using the other methods outlined in this document. The Sitemap Editor initializes the sitemap code after the website it is running on is fully loaded. Therefore, you cannot use the Sitemap Editor to test the real-world timing of initializing the sitemap while the page is still loading. Be sure to test the real-world timing on sitemap initialization outside the Sitemap Editor by monitoring the events sent by your sitemap as you browse the website naturally using the following event validation techniques outlined in this document.

Sitemap JS Tab Code Check

The Sitemap JS tab where you enter your Sitemap JavaScript has a built-in code validator that flags the presence of JavaScript syntax errors, as highlighted in the following figure.

Sitemap JS Code Errors

The Logs tab provides messages related to the JavaScript code errors flagged by the Sitemap JS code editor. However, it is advisable to use a more robust JavaScript validation tool to investigate JavaScript syntax issues and code execution errors flagged in the Sitemap JS code editor.

Current Page Object Validation

The following image shows the Current Page tab of the Sitemap Editor.

Sitemap JS Code Errors

The Current Page tab displays all Sitemap objects configured and executed on the current page shown in the browser, including:

  • Page Type: Name of the configured page type of the currently displayed page
  • User Data: The ID of the current user browsing the page and any user-triggered events that are configured on the page. The user ID can be the user ID that is randomly generated for anonymous site visitors, or a named user ID.
  • Catalog Data: Names of Catalog objects configured on the current page.
  • Content Zones: Names of Content Zone objects configured on the current page.
  • DOM Listeners: Names of JavaScript DOM listeners configured on the current page.

Current Page Object Examples

The following figure shows an example of how Sitemap objects display in the Current Page tab with key functional areas indicated by numbers.

Sitemap Current Page Objects

The following table lists the areas numbered on the figure and describes the purpose and function of each area.

NumberAreaDescription
1Current Page (Site Home Page)This area displays the current page of the target site that the Sitemap editor is targeting. The objects displayed in the Current Page tab are configured for the page type displayed here. In the preceding example, the browser used by the Sitemap editor is on the Home page of the target site and has a pageTypes object called home configured in the Sitemap (9).
2Execute (button)Clicking the Execute button runs and validates the JavaScript entered in the Sitemap JS editor. Sitemap objects that resolve with the current page type or global configuration are displayed in the Current Page tab. Objects with invalid JavaScript do not appear in the Current Page tab.
3Page TypeThis area displays the page type that matches the results of the isMatch function configured for the currently displayed page type. In the preceding example, the site Home page type (1) is matched by the isMatch function configured for the page type named home in the Sitemap (9).
4User DataThis area displays the user ID of the user visiting the current page and any user-triggered events configured in the Sitemap. The preceding example shows an anonymous user ID.
5Catalog DataThis area displays any catalog objects configured in the Sitemap JS for the currently displayed page. In the preceding Home page example, no catalog objects have been configured.
6Content Zones - GlobalThe preceding example shows that this Sitemap has two global Content Zones that are properly configured to display in the Current Page tab. Global content zones are active in all configured page types.
7DOM ListenersThe preceding example shows that this Sitemap has a listener in the global configuration that that is properly configured to display in the DOM Listeners section of the Current Page tab. This listener sends an event to Personalization when a user signs up for an email subscription.
8Content Zones - Page TypeThe preceding example shows that this Sitemap has three Content Zones that are properly configured to display in the Current Page tab when the Sitemap editor is on the home page type.
9pageTypes: homeThe preceding example shows that this Sitemap has a home page type configured to display in the Page Type section of the Current Page tab (3) when the Sitemap editor is on the home page type.

Page Match Validation

The Page Matches tab displays the currently matched page type as well as all other page types configured in the Sitemap. The currently matched page displays with a "checkmark" icon, while the other configured page types display with a "backslash" icon to indicate they were not matched as the current page.

The following figure shows an example of the Page Matches tab where the home page is the currently matched page as well as several other pages that are configured in the Sitemap JS editor but are not matched as the current page.

Page Matches in Sitemap

The Personalization Event Stream report displays all events received by Personalization, including events sent from the Sitemap as well as from other sources.

Accessing the Event Stream Report

To access the Event Stream report, do the following.

  1. Log in to Personalization.

Personalization Login

  1. In the Dashboard, use the dataset dropdown menu to select the dataset that contains the events you want to see.

Selecting the dataset

  1. Hover over Reports on the left menu to display the reports popup menu, and select Event Stream from the Activity section.

Accessing the Event Stream Report

Example: Event Processing and Display in the Event Stream

The Sitemap JavaScript is configured to send events to Personalization based on the actions by site visitors. This section presents an example based on an anonymous user who decides to sign up for emails from the company (thus becoming "known") and then browses the Men's section of the website.

JavaScript Listener for Email Sign-Up

The following is an example of a JavaScript listener configured to send an event when a user signs up for emails. Since the sign-up form appears on the bottom of every page on the site, ensure that you configure this listener as part of the global configuration.

  • SalesforceInteractions namespace

  • Evergage namespace

Site UI for Email Sign-Up

The following is an example of a site email sign-up form being completed by "Joe Customer". With the JavaScript listener configured as shown in the preceding section, an event is sent to Personalization and shows up in the Event Stream when a user provides their email address and clicks the submit button (->).

Email Sign Up Form

Events Displayed in the Event Stream Report

If the email signup listener is properly configured in the Sitemap, when "Joe Customer" provides his email and clicks Submit, the event shows up immediately in the Personalization Event Stream report. This report provides the following information and functionality.

  • Event stream search
  • Event stream table
  • Event details for individual events

The following figure shows an example of the events sent to Personalization before and after Joe Customer submitted his email in the email sign-up form. The following sections describe the information and functionality provided by the Event Stream report.

For more information on the available functionality in the Event Stream report, see Events.

Viewing Event Details

Event Stream Search

In the Event Stream search area, you can search for and filter the Event Stream table to display only events that were generated by a specific user ID/user name or email address. To search through the Event Stream, do the following.

  1. In the keyword field, enter text that matches characters in the username or email address for the user whose events you want to see.
  2. As soon as you enter characters that match an existing username or email address, the matching username is displayed.
  3. Click the desired user. The Event Stream table now displays only the events for that user.
  4. If you want to see only events of a specific type, click the Event Type dropdown menu and select the desired type.

Event Stream Table

The Event Stream table lists event data for all events triggered by the Sitemap and other event sources from other systems in the Personalization integration. The data in the Event Stream table is refreshed every 15 seconds and includes the following.

  • Timestamp: Time or date that the event occurred. Events triggered on the current day have a timestamp of how many minutes/hours ago the event was triggered. Events triggered the day before the current day have a timestamp of "yesterday". Earlier events have a timestamp of the date the event was triggered.
  • User Name or Email: User name or email address of the user who triggered the event.
  • Action or URL: Name of the action for which the event was triggered, or the URL of the page that the user visited that triggered the event.

Modifying the Event Stream Data View

The Event Stream table provides the following functionality to modify how the data in the table displays.

  • Click a column heading in the Event Stream table to sort the table by the data in that field.
  • Click the same column heading more than one time to toggle between an ascending/descending data sort.
  • Click an individual event entry in the table to display the details for that event as described in the following section.

From Anonymous to Known User

The example shown in the following figure depicts what happens after "Joe Customer" submits his email address. Upon submission, the anonymous user 7ddc1195... changes to the known user joe.customer@email.com. This change happens anytime an anonymous user identifies themselves through an action like email submission or login. Personalization associates the anonymous ID with the known user and adds the browsing behavior of the anonymous ID to the Unified Customer Profile of the known user. A known user can have many associated anonymous IDs (and more than one known username) depending on their browsing habits on the site.

Event Stream Known User Example

The preceding figure is for example purposes only. In large environments with hundreds or thousands of simultaneous visitors, it is extremely difficult to visually associate the anonymous user ID with their known username.

Individual Event Details

When you click an individual event in the Event Stream table, the details for that event are displayed in the Event Detail area to the right of the Event Stream table.

Individual Event Details

As shown in the preceding figure, the details provided in the Event Detail area for the selected individual event include:

  • Timestamp: Date and time that the event was triggered.
  • User ID: User name, email address, or anonymous user ID of the user who triggered the event.
  • URL: Page on which the user generated the event.
  • Client IP: IP address of the user client that generated the event.
  • User Agent: User Agent (UA) string sent in the HTTP header with browser requests that typically identifies the browser type, browser version, and browser host operating system.
  • Beacon Version: Version of the JavaScript Beacon that sent the event.
  • contentZones: Content Zone in the Sitemap on which the event was generated. The preceding figure shows an event that was triggered when a user clicked in a Sitemap Content Zone called global_infobar_top_of_page.
  • pageType: The type of page that the user accessed. The preceding figure shows the event of a user accessing the "Men's" category page of a retailer. This page has no configured page type in the Sitemap, so the pageType value is default.
  • channel: The engagement channel that generated the event. For Sitemap-generated events, the channel is always Web.
  • .scv: The Sitemap Configuration Version (SCV) is incremented every time changes to the Sitemap are saved. This value is used internally by Personalization to prevent conflicts with events sent from earlier Sitemap versions.

Sitemap developers can also validate Sitemap events using Google Chrome's built-in developer tools, as described in the following sections.

Viewing Page Load Events

The simplest way to view events that are triggered by page load is to run the SalesforceInteractions.mcis.getSitemapResult().currentPage command (or Evergage.getCurrentPage in the Evergage namespace) from the Chrome Console developer panel. However, this command will not display events that are triggered after page load. To run this command, do the following:

  1. Exit the Personalization Sitemap Editor.
  2. Navigate to the site page containing the events you want to validate.
  3. Open Chrome Developer Tools and navigate to the Console panel.
  4. Depending on the namespace being used, run the following command.
  • SalesforceInteractions namespace

  • Evergage namespace

The following figure shows an example of the results of running the SalesforceInteractions.getSitemapResult().currentPage command.

Viewing events triggered by page load using getSitemapResult command

The following figure shows an example of the results of running the Evergage.getCurrentPage command.

Get Current Page Command

Validating Individual Event Configurations

In the Chrome Network developer panel, you can see all events generated on the current page, including those events generated after page load. To view all events generated on the current page, do the following.

  1. Exit the Personalization Sitemap Editor.

  2. Navigate to the site page containing the events you want to validate.

  3. Perform an action on the page that you expect to generate an event.

  4. Open the Chrome Developer Tools and navigate to the Network panel.

  5. Find and select the event. The event contains the name of your dataset followed by a question mark (?) and the word "event".

  6. Select the event and select the Headers panel to view the event. Events are sent from the Sitemap to Personalization as JSON GET requests. The events are converted to Base64 and appended to the request URL, as shown in the following figure.

    Event GET Request

  7. Copy the event GET request starting immediately after event= to the end, as highlighted in the following figure.

    Copying an Event

  8. Navigate to the Chrome Console developer tool. Run the atob command to convert the event back to JavaScript objects. You can run the JSON.parse command in combination with the atob command to return the event JavaScript formatted. The syntax for running this command is as follows:

    The following figure shows an example of running the atob command in the SalesforceInteractions namespace and the results returned.

    JSON.parse atob command

    The following figure shows an example of running the atob command in the Evergage namespace and the results returned.

    JSON.parse atob command

  9. Review the event and confirm it contains the expected objects.