Triggering custom events

Current version: 9.1

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 event 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. Important This property is never saved to xConnect and should only be used to store data that will be copied to a custom xConnect event model in the event conversion pipeline.

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

RequestResponse

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:

RequestResponse

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.

Options for capturing event data in CustomValues

The following table shows how you an store event data in the CustomValues dictionary of events in session.

Important

The CustomValues property is never saved to xConnect. For each custom event model, you must create a conversion pipeline that copies data from CustomValues to that model.

Method	Description
Store simple values in `CustomValues`	Store the custom values that you need against a key in the `CustomValues` dictionary: RequestResponse `pageData.CustomValues["NewsletterID"] = "1234"; pageData.CustomValues["NewsletterBannerID"] = "1245";` This is the simplest way to store custom data in session and takes up the least amount of space.
Store a simple class in `CustomValues`	Store an instance of a custom class against a key in the `CustomValues` dictionary: RequestResponse `[Serializable] // Required public class NewsletterGoalSessionData { public string NewsletterID { get; set; } public string NewsletterBannerID { get; set; } } pageData.CustomValues["NewsletterImageCategory"] = new NewsletterGoalSessionData { NewsletterID = "1234", NewsletterBannerID = "1245" }`
Store an entire serialized xConnect event model in `CustomValues`	You can serialize the entire event model (such as `MyCustomGoal`) to JSON and store the serialized object as a custom value, then deserialize the object in the event conversion pipeline and return it. You must use the xConnect serialization helpers to do this. Important You cannot decorate your custom event class with the `[Serializable]` attribute and store it as a custom value - the tracker will throw a `System.Runtime.Serialization.SerializationException` exception. Pay attention to the size of the serialized event. Storing large amounts of data in session will negatively impact the performance of the session state provider and you may prefer to store simple values in the `CustomValues` dictionary instead.

Method

Description

Store simple values in CustomValues

Store the custom values that you need against a key in the CustomValues dictionary:

RequestResponse

pageData.CustomValues["NewsletterID"] = "1234";
pageData.CustomValues["NewsletterBannerID"] = "1245";

This is the simplest way to store custom data in session and takes up the least amount of space.

Store a simple class in CustomValues

Store an instance of a custom class against a key in the CustomValues dictionary:

RequestResponse

[Serializable] // Required
public class NewsletterGoalSessionData {
    public string NewsletterID { get; set; }
    public string NewsletterBannerID { get; set; }
}

pageData.CustomValues["NewsletterImageCategory"] = new NewsletterGoalSessionData {
    NewsletterID = "1234",
    NewsletterBannerID = "1245"
}

Store an entire serialized xConnect event model in CustomValues

You can serialize the entire event model (such as MyCustomGoal) to JSON and store the serialized object as a custom value, then deserialize the object in the event conversion pipeline and return it. You must use the xConnect serialization helpers to do this.

Important

You cannot decorate your custom event class with the [Serializable] attribute and store it as a custom value - the tracker will throw a System.Runtime.Serialization.SerializationException exception.

Pay attention to the size of the serialized event. Storing large amounts of data in session will negatively impact the performance of the session state provider and you may prefer to store simple values in the CustomValues dictionary instead.

The xConnect event CustomValues property

The Sitecore.XConnect.Event class has a CustomValues property of type Dictionary<string,string> for legacy reasons. If you are only storing string values in your PageEventData or OutcomeData custom values, you can technically 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 and do not rely on the xConnect event CustomValues.

Converting session events into xConnect events

You must create a conversion pipeline processor to convert a session event into a custom xConnect event. Each custom event will have its own processor. In each conversion pipeline processor, you will:

Create an instance of your xConnect event - such as NewsletterGoal.
Copy any custom data from the session event to the xConnect event - for example, you might copy the value of pageData.CustomValues["NewsletterImageCategory"] to a property on the NewsletterGoal class named NewsletterImageCategory.

Exact instructions depend on whether you are converting to an xConnect event model, a xConnect goal model, or an xConnect outcome model.

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.

Do you have some feedback for us?

If you have suggestions for improving this article,