Skip to main content

Configuration

This section describes the configuration options that enable you to control how Uniform tracking operates.

tip

Some configuration can be set in multiple places. In these cases, the order of priority (from low to high) is:

  1. Sitecore config setting
  2. Sitecore module setting
  3. Tracker code

Sitecore config settings#

Some aspects of Uniform tracking can be configured using settings configured in Sitecore config files.

Campaign id conversion#

Sitecore tracks campaigns using the campaign item id. The Sitecore campaign manager generates a query string that can be added to a url in order to track a campaign. An example of this value is:

sc_camp=5704C80F7DD3491393C9B2AF1D485801

When a Sitecore instance handles this query string, Sitecore converts the value into a guid when a personalization condition that involves a campaign id runs. Since the Uniform personalization
engine does not run on the Sitecore instance, it is important that values be formatted consistently.

By default, the Uniform personalization engine attempts to format guids in a standard format. This setting enables you to disable this formatting.

This feature is controlled using the following setting:

Uniform.Optimize.Personalization.Esi.DoNotConvertCampaignParameterToId

The following values are supported:

  • false - Uniform will try to convert the campaign id into a standard guid format. This is the default value.
  • true - Uniform use the campaign id value as it was provided.
caution

In most cases this setting should not be enabled. Enabling it may result in personalization conditions failing to match and creating a situation that is difficult to troubleshoot.

Sitecore module settings#

Some aspects of Uniform tracking can be configured using fields on items in the Sitecore content database.

Campaign parameters#

It is a common practice for a url to include a query string parameter to indicate that the visitor has navigated to the site as a result of a marketing campaign. This setting allows you to specify the name of the query string parameter used in this way.

This setting is configured in the following field:

  • Item path: /sitecore/system/Uniform/Modules/Optimize/Settings
  • Field name: Campaign parameters

The field value is a string. Multiple query string parameter names can be specified by using a comma-separate value, such as sc_camp,camp,utm_campaign.

Goal parameters#

The Uniform tracker can pick up goals that are included in a query string parameter. This setting allows you to specify the name of the query string parameter used in this way.

This setting is configured in the following field:

  • Item path: /sitecore/system/Uniform/Modules/Optimize/Settings
  • Field name: Goal parameters

The field value is a string. Multiple query string parameter names can be specified by using a comma-separate value, such as sc_goals,goals,utm_goals.

Include Uniform Optimize script with tracker scripts#

In most cases, the Uniform component used to add the tracker to a site ensures the Uniform tracker script is loaded. With certain front-end technologies, this does not happen automatically. In those cases, this setting can be used to load the script.

note

This feature is not enabled by default because it can result in the Uniform tracker script being loaded when it is not needed.

This setting is configured in the following field:

  • Item path: /sitecore/system/Uniform/Modules/Optimize/Settings
  • Field name: Include Uniform Optimize script with tracker scripts

Script url#

The Uniform tracker script contains the logic to track visitor activity. In some cases (e.g. JSS application built using React), this script is incorporated into other components. In other cases (e.g. MVC site), the script must be loaded. This setting specifies the location of the script so the front-end technology can resolve it, if necessary.

If you need to change the path for the tracker script, the best way is to change the value of this field. If you need to override this field value but do not want to make the change to the Sitecore content database, you can use this setting.

This setting is configured in the following field:

  • Item path: /sitecore/system/Uniform/Modules/Optimize/Settings
  • Field name: Script url

The default value for this field is /scripts/uniform.optimize.min.js.

Session timeout#

The Uniform tracker captures website visitor activity on the visitor's browser. Since there is no server-based session, the tracker must determine when when one session ends and the next begins. A session ends when a certain number of minutes passes without the tracker collecting additional data. This is the session timeout value.

This setting is configured in the following field:

  • Item path: /sitecore/system/Uniform/Modules/Optimize/Settings
  • Field name: Session timeout

The value used for this setting must be a positive, non-zero integer.

Visit cookies#

Visit cookies are deleted when a new visit is created.

Version 5.1+

Each cookie is represented by its own field in the following section:

  • Item path: /sitecore/system/Uniform/Modules/Optimize/Settings
  • Section name: Cookies
Version 5.0 (and earlier)

Visit cookies are specified using the following field:

  • Item path: /sitecore/system/Uniform/Modules/Optimize/Settings
  • Field name: Visit cookies

Visitor cookies#

Visitor cookies persist across visits (i.e. they are not deleted when a new visit is created).

Version 5.1+

Each cookie is represented by its own field in the following section:

  • Item path: /sitecore/system/Uniform/Modules/Optimize/Settings
  • Section name: Cookies
Version 5.0 (and earlier)

Visitor cookies are specified using the following field:

  • Item path: /sitecore/system/Uniform/Modules/Optimize/Settings
  • Field name: Visitor cookies

Service settings#

EsiTrackingNodeService#

This service is used when edge-side personalization is activated. It is responsible for creating the tracking node, which is a component generated on the Sitecore server that is responsible for generating the tracking data used by the client-side tracker.

Examples of information included in the tracking node are:

  • campaigns assigned to the Sitecore item
  • goals assigned to the Sitecore item

Most of these values are "static" value, meaning they don't change based on who the visitor is or when the page is viewed.

However, as of v7.1, there are some values in the tracking node that are dynamic. For example, whether the visit is new. Prior to v7.1, the logic to determine if a visit timed out only existed in the client-side tracker. Starting in v7.1, that logic can run on the CDN. This makes it possible to properly evaluate conditions that involve the "current visit" (e.g. if the goal was triggered in the current visit).

A problem arises if you attempt to use the JSS Layout Service without going through the CDN. You end up with XML tags in the JSON output, which the JSS application cannot handle. If you must access Layout Service without a CDN, you can disable this functionality by patching the Sitecore instance:

<uniform>  ...  <services>    ...    <trackingNodeService patch:instead="*[@type='Uniform.Optimize.Services.TrackingNodeService, Uniform.Optimize.Core']"                         type="Uniform.Optimize.Services.EsiTrackingNodeService, Uniform.Optimize.Personalization.Esi.Core" singleInstance="true">      <requestChecker ref="uniform/personalization/esi/defaultRequestChecker" />        <enableEsi>false</enableEsi>      </trackingNodeService>    ...  </services></uniform>

MVC sites#

The Uniform tracker script is added to your site's main layout view using an HTML helper method. The following code adds the tracker using default settings:

@Html.Uniform().Tracker()

More fine-tuned control is possible using an alternate HTML helper method. It allows you to set properties on the object settings that control how the tracker works:

@Html.Uniform().TrackerWith(settings => {    // Set options on the settings object})

The following settings can be set on the tracker:

EnableConsoleDebugger#

The Uniform tracker runs in the website visitor's browser. The tracker performs a lot of activities, including capturing page views and calculating pattern matches. The tracker can be configured to log its activity in the JavaScript console of the visitor's browser. The activity that is logged is very granular. This is useful for troubleshooting tracking.

The following values are supported:

  • false - Tracker activity is not written to the JavaScript console. This is the default value.
  • true - Tracker activity is written to the JavaScript console.

The following code demonstrates how to use this setting:

@Html.Uniform().TrackerWith(settings => {    settings.EnableConsoleDebugger = true;})

EnableContextDebug#

When using edge-side personalization, most of the personalization rules use conditions that depend on values from the Edge Context. The Edge Context only exists on the edge, but it is possible to configure the tracker to expose this context on the rendered page. This is useful for troubleshooting personalization.

When Edge Context debug mode is enabled, the Edge Context is expressed in JSON format. The tracker injects a script tag into the rendered page. The script has the id __ESI_CONTEXT__. You can access the context using the JavaScript console in your browser.

For example, you can iterate the variables set in the Edge Context using the following code:

let variables = JSON.parse(window.__ESI_CONTEXT__.textContent).variables;Object.keys(variables).forEach(key => {  console.log(`${key} = ${variables[key]}`);});

Depending the state of the Edge Context, you will see a list context variables with values:

ESI_CONTEXT_campaigns = {'5704c80f7dd3491393c9b2af1d485801': ['1623175675']}ESI_CONTEXT_goals = ESI_CONTEXT_testing = ESI_CONTEXT_cookies_testing = ESI_CONTEXT_profiles_scores = {'03379af5-f1ae-4610-b15b-4c7f1032b464': 6}ESI_CONTEXT_personalization_rules =

The following values are supported:

  • false - The Edge Context is not exposed on the rendered page. This is the default value.
  • true - The Edge Context is exposed on the rendered page.

The following code demonstrates how to use this setting:

@Html.Uniform().TrackerWith(settings => {    settings.EnableContextDebug = true;})

Mode#

The Uniform tracker can work in a variety of types of sites, but the tracker needs to be told what kind of site it is being used in. The default value is mvc, which initializes the tracker to be compatible with sites built using ASP.NET MVC.

caution

In most cases this setting should not be used. It may result in tracking not working as expected, or not working at all.

OnBeforeDispatchData#

Name of a JavaScript function that is called right before a dispatcher dispatches visitor activity. This allows you to transform the activity data that's written.

tip

This feature can be used in cases when you don't want to create an entirely new dispatcher. For example, if you want to change one property on the data being dispatched, this gives you a place to add that logic.

info

Not all dispatchers support this functionality. Check the documentation for the dispatcher you are using.

caution

If this function returns undefined, the activity will not be dispatched. If the function does not apply to the activity - either because the dispatcher type doesn't match what you are expecting or because the data itself doesn't need to be changed - you should return the parameter data.

The function named must have the following signature:

Example#

<script>  function onBeforeDispatchData(type, data, logger) {    if (type === "my-dispatcher") {      //      //Do something here!      const newData = {...data};      return newData;    }    //    //You only want to affect a specific dispatcher.    //Since this activity is not being dispatched    //by that dispatcher, return the original data    //so the dispatch doesn't get cancelled.    return data;  }</script>@Html.Uniform().TrackerWith(settings => {  settings.OnBeforeDispatchData = "onBeforeDispatchData";})

OnDispatch#

Name of a JavaScript function that is called when the tracker dispatches activity.

The function named must have the following signature:

Example#

<script>  function onDispatch(results, settings, logger) {    //    //Do something here!  }</script>@Html.Uniform().TrackerWith(settings => {  settings.OnDispatch = "onDispatch";})

OnTrackingFinished#

Name of a JavaScript function that is called when the tracker fires the tracking-finished event.

The function named must have the following signature:

Example#

<script>  function onTrackingFinished(e) {    //    //Do something here!  }</script>@Html.Uniform().TrackerWith(settings => {  settings.OnTrackingFinished = "onTrackingFinished";})

OnVisitCreated#

Name of a JavaScript function that is called when the tracker fires the visit-created event.

The function named must have the following signature:

Example#

<script>  function onVisitCreated(e) {    //    //Do something here!  }</script>@Html.Uniform().TrackerWith(settings => {  settings.OnVisitCreated = "onVisitCreated";})

OnVisitorInitialized#

Name of a JavaScript function that is called when the tracker initializes a new visitor.

The function named must have the following signature:

Example#

<script>  function onVisitorInitialized(visitor, saveVisitor, logger) {    return new Promise(function(resolve, reject) {      //      //Do something here!      resolve();    });  }</script>@Html.Uniform().TrackerWith(settings => {  settings.OnVisitorInitialized = "onVisitorInitialized";})

OnVisitorUpdated#

Name of a JavaScript function that is called when the tracker fires the visitor-updated event.

The function named must have the following signature:

Example#

<script>  function onVisitorUpdated(e) {    //    //Do something here!  }</script>@Html.Uniform().TrackerWith(settings => {  settings.OnVisitorUpdated = "onVisitorUpdated";})

OnVisitUpdated#

Name of a JavaScript function that is called when the tracker fires the visit-updated event.

The function named must have the following signature:

Example#

<script>  function onVisitUpdated(e) {    //    //Do something here!  }</script>@Html.Uniform().TrackerWith(settings => {  settings.OnVisitUpdated = "onVisitUpdated";})

PredefinedRuleItemPath#

You can configure a predefined rule in Sitecore with conditions that must be met in order for the tracker to be activated. This setting allows you to identify the rule. When a rule is specified, the tracker is rendered inside a block of conditional logic that reflects the conditions configured in the rule.

The value used for this setting must be in one of the following formats:

  • Sitecore item id
  • Sitecore item path

The following code demonstrates how to use this setting:

@Html.Uniform().TrackerWith(settings => {    settings.PredefinedRuleItemPath = "fb177480-ec2f-484f-a0f9-dadfbc4f8352";})
note

The rule configured on the specified item is subject to the same limitations as personalization rules: all of the conditions used in the rule must be supported. The reference section provides information on which conditions are supported out-of-the-box, and how to support custom conditions you have added to your Sitecore instance.

PredefinedRuleMultiRuleAndOperator#

This setting is used in combination with PredefinedRuleItemPath when the specified item has more than one rule assigned. In this case, the default behavior is for the rules to be combined using the or operator (i.e. the tracker is injected into the page if at least one of the rules passed).

Setting this value to true will cause Uniform to use the and operator (i.e. the tracker is injected into the page if all of the rules pass).

Version note

This feature is available in version 5.1+.

The following code demonstrates how to use this setting:

@Html.Uniform().TrackerWith(settings => {    settings.PredefinedRuleItemPath = "fb177480-ec2f-484f-a0f9-dadfbc4f8352";    settings.PredefinedRuleMultiRuleAndOperator = true;})

RenderModes#

The tracker is rendered on a page only when the Sitecore page mode matches one of the modes specified by this setting. By default, only "normal" page mode is enabled.

The following page modes are supported:

  • Debugging
  • ExperienceEditor
  • ExperienceEditorEditing
  • Normal
  • Preview
  • SimulatedDevicePreview
  • Profiling
note

This setting overrides the Sitecore module setting Page Modes, but provides a bit more precision.

The following code demonstrates how to use this setting:

@Html.Uniform().TrackerWith(settings => {    settings.RenderModes.Normal = true;    settings.RenderModes.Preview = true;})
note

In most cases this value does not need to be changed.

ScriptUrl#

note

This setting overrides the Sitecore module setting Script url.

The following code demonstrates how to use this setting:

@Html.Uniform().TrackerWith(settings => {    settings.ScriptUrl = "/uniform.optimize.min.js";})

SessionTimeout#

note

This setting overrides the Sitecore module setting Session timeout.

The following code demonstrates how to use this setting:

@Html.Uniform().TrackerWith(settings => {    settings.SessionTimeout = 60;})

Source#

Uniform exposes details like item id, profile scores and other values that are collectively called "tracking data". Tracking data is used to determine the visitor activity that gets tracked. This setting tells the Uniform tracker that Sitecore is the source of the tracking data so the tracker knows how to parse the data.

caution

In most cases this setting should not be used. It may result in tracking not working as expected, or not working at all.

React sites#

The Uniform tracker is added to React sites using the Sitecore tracker hook. This hook is defined in the npm package @uniformdev/tracking-react.

The following code adds the tracker to a JSS site built using React:

  useSitecoreTracker(sitecoreContext, {    type: "jss"  });

This hook accepts the following parameters:

  1. sitecoreContext - Sitecore context object.
  2. props - Properties that provide additional configuration settings to the tracker.

The following props are supported.

note

While all of the props are optional (i.e. a missing prop will not result in an error), certain props are required in order for specific functionality to work.

campaignParameters#

  • Type: string[]
  • Default value: undefined
note

This setting overrides the Sitecore module setting Campaign parameters.

clientSideRouting#

  • Type: boolean
  • Default value: false

One of the main responsiblities of the Uniform tracker is to capture page views. A page view happens when the route changes. There are two kinds of routing:

  1. Server-side routing - The route changes because the browser requests an entirely new page from the web server. This is typically the result of a visitor clicking a link that causes the browser to request a new page.
  2. Client-side routing - This type of routing is used in SPAs (single-page apps). The React application handles navigation. New data may be retrieved from the web server, but the React application handles that by making requests.

By default, the Uniform tracker assumes server-side rendering is used. For sites that use client-side rendering, "client-side rendering mode" must be enabled. This prop is used to enable this.

The tracker behaves differently depending on the value of this prop:

  • true - The tracker will not track the page view automatically. You must add code to the application to capture the page view when the route changes.
  • false - The tracker will track the page view automatically after the tracker is finished initializing.

contextReaders#

This prop is an array of ContextReader objects that are added in addition to the default context readers set on the tracker.

cookies#

note

This prop overrides the Sitecore module setting Visit Cookies and Visitor Cookies

decay#

The Uniform tracker is responsible for calculating profile scores. This prop represents the settings that the tracker uses to determine how profile scores decay over time.

doNotUseDefaultContextReader#

  • Type: boolean
  • Default value: false

By default, the tracker automatically includes context readers that are appropriate for the tracker. If this prop is set to true, the only context readers that are added to the tracker are those assigned to the contextReaders prop.

note

The tracker type is used to resolve the appropriate context readers. For example, when the type is jss, the tracker uses context readers that can read from the Sitecore layout service.

getCookieName#

  • Type: (type: string): string|undefined
  • Default value: undefined

This prop allows you to override the default function that determines the cookie name for a specified cookie type.

caution

In most cases this prop should not be used. It may result in tracking and personalization not working as expected, or not working at all.

getCookieValueFromVisit#

This prop allows you to override the default function that determines the cookie value from the current visit.

getCookieValueFromVisitor#

This prop allows you to override the default function that determines the cookie value from the current visitor.

goalParameters#

  • Type: string[]
  • Default value: undefined
note

This setting overrides the Sitecore module setting Goal parameters.

logger#

  • Type: Logger
  • Default value: undefined

This prop allows you to set the component the tracker uses to write logging messages.

onBeforeDispatchData#

If specified, this function is called right before a dispatcher dispatches visitor activity. This allows you to transform the activity data that's written.

tip

This feature can be used in cases when you don't want to create an entirely new dispatcher. For example, if you want to change one property on the data being dispatched, this gives you a place to add that logic.

info

Not all dispatchers support this functionality. Check the documentation for the dispatcher you are using.

caution

If this function returns undefined, the activity will not be dispatched. If the function does not apply to the activity - either because the dispatcher type doesn't match what you are expecting or because the data itself doesn't need to be changed - you should return the parameter data.

Example#

function onBeforeDispatchData(type, data, logger) {  if (type === "my-dispatcher") {    //    //Do something here!    const newData = {...data};    return newData;  }  //  //You only want to affect a specific dispatcher.  //Since this activity is not being dispatched  //by that dispatcher, return the original data  //so the dispatch doesn't get cancelled.  return data;}

onDispatch#

This prop lets you specify a function that is called when the tracker has visitor activity to dispatch. It can be used to dispatch data to custom destinations.

onInitialized#

  • Type: (): void
  • Default value: undefined

Knowing when the tracker is initialized is important when client-side routing is used. The client app triggers the tracker when the route changes. But the route may change before the tracker is initialized. This callback enables the client app to trigger the tracker in this case.

onVisitorInitialized#

This callback is passed along to the tracker to enable the developer to specify code that runs after the visitor is initialized.

renderModes#

The tracker is rendered on a page only when the Sitecore page mode matches one of the modes specified by this setting. By default, only "normal" page mode is enabled.

The following page modes are supported:

  • edit
  • normal
  • preview
note

This setting overrides the Sitecore module setting Page Modes, but provides a bit more precision.

The following code demonstrates how to use this setting:

  useSitecoreTracker(sitecoreContext, {    pageModes: ["normal"]  });
note

In most cases this value does not need to be changed.

sessionTimeout#

  • Type: number
  • Default value: undefined
note

This setting overrides the Sitecore module setting Session timeout.

storage#

caution

In most cases this setting should not be used. It may result in tracking not working as expected, or not working at all.

subscriptions#

url#

  • Type: (): URL
  • Default value: undefined

This prop allows you to override the URL that the tracker uses for the page view activity.

type#

  • Type: string
  • Default value: default

Specifies the shape of the Sitecore context data. The tracker uses this prop to determine the default context readers.

caution

This prop must match the source of the Sitecore context data. If the prop is set incorrectly, tracking and personalization will not work properly.

The following values are supported:

  • cookie - Currently not implemented. This value is reserved for future use.
  • js - This value should not use used directly.
  • jss - Use when the Sitecore context is generated by the Sitecore Layout Service.
  • default - This is the same as the value uniform.
  • uniform - Use when the Sitecore context is generated by the Uniform Page Service.