Skip to main content

Dispatch

Customers who are already using Sitecore XP to collect visitor activity data may want to continue to do so even when Uniform Optimize is used to decouple tracking. Uniform's dispatch process can be used to ensure Sitecore can collect visitor activity data.

Uniform also provides the ability to load historical data from Sitecore Experience Database into the Uniform tracker. This makes it possible to personalize your site using visitor activity that was collected before Uniform was added to your site.

How does it work?#

The Uniform tracker collects visit activity and stores it locally on the browser. After the tracker stores the data, it runs the dispatch process if any destinations are configured. Normally the dispatch process takes the data that was stored, converts it into a format that is compatible with the specified destinations and then makes an API call to the destination in order to transmit the data.

When the destination is Sitecore Xdb, the dispatch process works differently. There are two kinds of tracking data to consider:

Page views#

Tracking data can be assigned directly to Sitecore items. This includes things like profile scores, pattern cards, goals and campaigns. When a Sitecore CD instance handles a request for an item with tracking data assigned, the Sitecore tracker captures that data.

The Uniform Optimize dispatch process takes advantage of this. The Uniform tracker sends a request to the Sitecore CD instance. The Sitecore instance handles this request just as if the visitor had accessed the Sitecore CD instance directly. This allows all of the standard Sitecore tracking processes to run.

Triggered events#

Tracking data can also be captured programmatically. For example, when a visitor plays a video on a page, that may trigger an event. In this case, the front-end developer would use the Uniform tracker API to capture the event.

Just like with a page view, after the Uniform tracker saves the activity, the dispatch process makes a request to the Sitecore CD instance so that the activity can be tracked in Sitecore Xdb.

note

Only goals and page events are handled in this way.

Configuration#

Dispatching visit activity data to Sitecore Xdb is configured in Sitecore Content Editor. No changes to the front-end application is required.

Add tracking configuration#

When the Uniform tracker sends a dispatch request to Sitecore Xdb, it sends an asynchronous call to an endpoint on the Sitecore content delivery (CD) instance. The tracking configuration item tells the tracker how to construct the call to the endpoint.

  1. In Sitecore Content Editor, navigate to:

    sitecore > System > Uniform > Optimize > Tracking > Destinations > Sitecore xDB > Tracking Configurations

  2. Create the following item:

    • Template: Tracking Configuration
    • Name: Xdb tracking config

  3. Enter values for the following fields:

    • Enabled - A tracking configuration must be enabled in order for it to be active.
    • Sitecore sites - Select the Sitecore sites that the tracking configuration will apply to.
    • Only track dispatch requests - Ticked.

  4. Enter the following values for the field HTTP headers:

    • Key: Uniform-Tracking
    • Value: true

  5. Save and publish the item.

Configure CDN#

If you are using a CDN in front of the Sitecore content delivery instance, you must configure the CDN so dispatch requests sent from the Uniform tracker are not cached.

tip

If you are not using a CDN in front of the Sitecore CD instance, skip this section.

In the previous section you configured the tracker so that dispatch requests include the following HTTP request header. instructions must be added to the CDN configuration so that requests that include this header are not cached:

Uniform-Tracking: true

Troubleshooting#

Confirm tracking includes Sitecore Xdb destination#

When the Uniform tracker is rendered, details about any dispatchers that are assigned to the Sitecore site are rendered, as well. The precise way these details are rendered depends on the kind of site involved.

MVC sites#

  1. In Sitecore Content Editor, get the item id for the Sitecore Xdb tracking configuration item configured above.

  2. Using your browser, navigate to your site.

  3. Open Developer Tools.

  4. Navigate to the Console tab.

  5. Enter the following command (replace the guid with the item id from step 1):

    uniform.tracking.destinations    .find(d => "{BBBBBBBB-BBBB-BBBB-BBBB-BBBBBBBBBBBB}"        .toLowerCase()            .indexOf(d.configId) != -1)

  6. An object is returned that contains the configuration that powers the dispatch process.

JSS sites (React + Optimize)#

Follow the same steps as in the MVC sites section, but use the following command in the JavaScript console:

JSON.parse(window.__JSS_STATE__.textContent)        .sitecore.context.tracking.destinations            .find(d => "{BBBBBBBB-BBBB-BBBB-BBBB-BBBBBBBBBBBB}"                .toLowerCase()                    .indexOf(d.configId) != -1)

JSS sites (React + Deploy + Optimize)#

Follow the same steps as in the MVC sites section, but use the following command in the JavaScript console:

window.__NEXT_DATA__    .props.pageProps        .layoutData.sitecore.context.tracking.destinations            .find(d => "{BBBBBBBB-BBBB-BBBB-BBBB-BBBBBBBBBBBB}"                .toLowerCase()                    .indexOf(d.configId) != -1)

Confirm tracking request is sent#

When the dispatch process run, the Uniform tracker will send a request to the website. This request can be found using your browser's debugging tools.

  1. Using your browser, navigate to your site.

  2. Open Developer Tools.

  3. Navigate to the Network tab.

  4. Apply the filter so only XHR requests are shown.

  5. Find a request for the current URL. The request should have a request header and/or query string parameter that matches the settings in the tracking configuration item configured above.

Enable logging#

Uniform has a feature where you can enable a greater level of logging for when Uniform performs the logic to determine whether a request is a dispatch request. This means you can capture logging messages at the logging level you want without having to change the global Sitecore logging level.

This feature will result in logging that describes how each request was handled and whether or not the request was resolved as a dispatch request.

  1. In Sitecore, navigate to the tracking configuration item configured above.

  2. Scroll to the section Logging.

  3. For the field Logging level, select the Sitecore logging level for messages related to dispatch requests.

    note

    In order to see any messages in the log, you must select a logging level that is at least as severe as the one set on your Sitecore instance. For example, if your Sitecore instance is set to log at INFO, you must select INFO or greater.

    The logging levels, in order of least severe to most severe are:

    • DEBUG
    • INFO
    • WARN
    • ERROR
    • FATAL

  4. For the field Logging prefix, and a string that you want to be included in all logging messages that pertain to determining whether the request is a dispatch request. This setting makes it easier for you to find the relevant messages in the Sitecore log.

  5. Save the item.

  6. Publish the item.

The following is an example of the kind of details you will see in the log:

2956 12:08:12 INFO  ==  UNIFORM  ==   DISPATCH DEBUG - Determining if request should be tracked:2956 12:08:12 INFO  ==  UNIFORM  ==   DISPATCH DEBUG -   * Sitecore.Context.Site.Name = habitat2956 12:08:12 INFO  ==  UNIFORM  ==   DISPATCH DEBUG -   * Sitecore.Context.Request.ItemPath = /sitecore/content/habitat/Home/about-habitat/introduction2956 12:08:12 INFO  ==  UNIFORM  ==   DISPATCH DEBUG -   * HttpContext.Current.Request.Url.OriginalString = https://habitat.dev.local:443/en/About-Habitat/Introduction2956 12:08:12 INFO  ==  UNIFORM  ==   DISPATCH DEBUG -   * Sitecore.Analytics.Tracker.IsActive = False2956 12:08:12 INFO  ==  UNIFORM  ==   DISPATCH DEBUG -   * Sitecore.Analytics.Tracker.Current.Contact.ContextId = 930efb44-fb5d-4b5c-b52c-ce92a02c35132956 12:08:12 INFO  ==  UNIFORM  ==   DISPATCH DEBUG -   * Sitecore.Analytics.Tracker.Current.Interaction.InteractionId = c63f20b5-0a3d-4067-bb69-30b54b6241892956 12:08:12 INFO  ==  UNIFORM  ==   DISPATCH DEBUG - START: pipeline "filterTrackingRequest".2956 12:08:12 INFO  ==  UNIFORM  ==   DISPATCH DEBUG - Applying rules from xDB dispatch config item {9E5E8113-EAAB-4487-9F6D-64B2BA8427CF}2956 12:08:12 INFO  ==  UNIFORM  ==   DISPATCH DEBUG - Request header value does not match the required value.2956 12:08:12 INFO  ==  UNIFORM  ==   DISPATCH DEBUG -   * Key: Uniform-Tracker2956 12:08:12 INFO  ==  UNIFORM  ==   DISPATCH DEBUG -   * Required value: true2956 12:08:12 INFO  ==  UNIFORM  ==   DISPATCH DEBUG -   * Actual value: 2956 12:08:12 INFO  ==  UNIFORM  ==   DISPATCH DEBUG - At least one rule from config item {9E5E8113-EAAB-4487-9F6D-64B2BA8427CF} was not satisfied.2956 12:08:12 INFO  ==  UNIFORM  ==   DISPATCH DEBUG - Request is not a dispatch request.2956 12:08:12 INFO  ==  UNIFORM  ==   DISPATCH DEBUG - END: pipeline "filterTrackingRequest".2956 12:08:12 INFO  ==  UNIFORM  ==   DISPATCH DEBUG - Request should not be tracked.2956 12:08:12 INFO  ==  UNIFORM  ==   DISPATCH DEBUG - Aborting pipeline "startAnalytics".