Sitecore Experience Platform

Triggering custom events

By default, events that are triggered from the tracker are saved to xConnect using generic, built-in event models such as Goal, Outcome, or Event. To use a custom event model, you must create an event conversion pipeline processor that converts the generic event into a custom event. For example, a generic Event with an ID of {7D59A563-29A1-4C3D-8C15-35FA110B79E0} might be converted into a specialized SearchEvent.

You can also copy custom event data that was captured by the tracker to properties on the specialized model. For example, the SearchEvent class has a Keywords property. This property is populated by copying the value of the Data field on the generic Event model.

Capturing custom data

To capture custom data, you must trigger your event using one of the following methods:

  • Sitecore.Analytics.Tracker.Current.CurrentPage.Register() for page events and goals.

  • Sitecore.Analytics.Tracker.Current.CurrentPage.RegisterOutcome() for outcomes.

  • Sitecore.Analytics.Tracker.Current.Interaction.RegisterOutcome() for outcomes at an interaction level (9.0 Update-1 only).

If you do not need to capture custom data, you can trigger your event in the same way that you would trigger a generic event and skip this section.

Capturing custom goal and event data

Use the Sitecore.Analytics.Tracker.Current.CurrentPage.Register() method to trigger goals or page events with custom data.

The following table describes the properties of the Sitecore.Analytics.Model.PageEventData class that can be used to store custom data. During event conversion, this data can be copied to your custom event. You must decide how to store custom data before it is converted - for example, the DownloadEvent expects the ItemId property to store the ID of the media item that was downloaded.

Property

Description

ItemId

The ID of page item where the event occurred, or the media item the event was associated with.

Text

Human readable description of the event - e.g. “Installation guide downloaded”

DataKey

A key that identifies the contents of ‘Data’ - e.g. “campaignid” or “keywords”

Data

Any data collected as part of triggering the event, such as the campaign ID for campaign events or page load time for the ‘Slow Page’ event.

CustomValues

Store any string/object combination - this property is never saved to xConnect.

The following example demonstrates how to trigger a goal with custom data:

var ev = Sitecore.Analytics.Tracker.MarketingDefinitions.Goals[NewsletterSignupGoal.NewsletterGoalID];

var newsletterId = Guid.NewGuid(); // Fake newsletter ID
var pageData = new Sitecore.Analytics.Data.PageEventData(ev.Alias, ev.Id);

pageData.Data = newsletterId.ToString();
pageData.Text = "Signed up for newsletter";
pageData.DataKey = "newsletterid";
pageData.CustomValues["NewsletterImageCategory"] = "C"; // Never saved to xConnect, must be converted into a property on a custom model

Sitecore.Analytics.Tracker.Current.CurrentPage.Register(pageData);

Capturing custom outcome data

Use the Sitecore.Analytics.Tracker.Current.CurrentPage.RegisterOutcome() method to trigger outcomes with custom data. The Sitecore.Analytics.Data.OutcomeData object only allows you to save custom data in the CustomValues property, which is of type Dictionary<string,object>. CustomValues is never saved to xConnect and can only be accessed during session or in the context of the event conversion pipeline.

The following example demonstrates how to trigger an outcome with custom data for the current page:

var ev = Sitecore.Analytics.Tracker.MarketingDefinitions.Outcomes[CarPurchaseOutcome.CarPurchaseOutcomeID];

if (ev != null)
{
    var outcomeData = new Sitecore.Analytics.Data.OutcomeData(ev, "DKK", 100000.00m);

    outcomeData.CustomValues.Add("Make", "Mazda"); // Never saved to xConnect, must be converted into a property on a custom model
    outcomeData.CustomValues.Add("Model", "MX-5"); // Never saved to xConnect, must be converted into a property on a custom model

    Sitecore.Analytics.Tracker.Current.CurrentPage.RegisterOutcome(outcomeData);
}

Note

From 9.0 Update-1 onwards, you can also trigger an outcome with custom data for the current interaction.

Converting events

Create a conversion pipeline processor to convert generic events to custom events on session end. Each custom event will have its own processor. Refer to the following topics for information on how to convert different types of events into more specialized:

Note

ItemId, Text, DataKey, and Data properties are saved to the base Sitecore.XConnect.Event class by default. You do not need to clear these properties, even if you are copying the data to another property.

Copying custom values only

The Sitecore.XConnect.Event class has a CustomValues property of type Dictionary<string,string>. If you are only storing string values in your PageEventData or OutcomeData custom values, you can create a conversion processor that copies custom values from the tracker event to the xConnect event without changing the event type. The tracker does not automatically perform this conversion as it is not possible to guarantee that each dictionary object will be a string.

Note

The CustomValues property lacks contextual meaning and makes it difficult to analyze data in a third party tool. It is recommended that you create custom types for all events that include custom data.

Storing event models in custom values

It is possible to store the entire event model as a custom value in the tracker and copy properties to the converted event in a conversion processor. However, the event model must be decorated with [Serializable] attribute.