Events

Abstract

Overview of events with an example of how to add a goal and a search event to an interaction using the xConnect Client API.

An event is anything significant that occurs within the context of an interaction, such viewing a web page or making a purchase in a physical store.

Events ultimately inherit the Sitecore.XConnect.Event class and are represented by the Events collection on the Interaction class. Interactions must have at least one event. All events are triggered with an event model, an event definition ID, and a timestamp. The following example demonstrates how to add a Goal and a SearchEvent to an interaction using the xConnect Client API:

using Sitecore.XConnect;
using Sitecore.XConnect.Collection.Model;
using System;

namespace Documentation
{
    public class AddMultipleEvents
    {
        public async void ExampleAsync()
        {
            using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                try
                {
                    var newContact = new Sitecore.XConnect.Contact();
                    client.AddContact(newContact);

                    Guid channelId = Guid.Parse("dee6a101-a5d7-4111-9dd0-c3ac18d78295");

                    var interaction = new Sitecore.XConnect.Interaction(newContact, InteractionInitiator.Brand, channelId, "Mozilla/5.0 (Nintendo Switch; ShareApplet) AppleWebKit/601.6 (KHTML, like Gecko) NF/4.0.0.5.9 NintendoBrowser/5.1.0.13341");

                    // Search event has built-in definition GUID as there is
                    // only one search event
                    SearchEvent searchEvent = new SearchEvent(DateTime.UtcNow)
                    {
                        Keywords = "sitecore" // Event-specific property
                    };

                    // Goal instantiated with goal definition GUID as there are
                    // multiple goals
                    Guid goalId = Guid.Parse("2ee6a101-45d7-a111-9dd0-c3ac18d78295");
                    Goal goal = new Goal(goalId, DateTime.UtcNow);

                    interaction.Events.Add(searchEvent);
                    interaction.Events.Add(goal);

                    client.AddInteraction(interaction);

                    await client.SubmitAsync();
                }
                catch (XdbExecutionException ex)
                {
                    // Handle exception
                }
            }
        }
    }
}

Refer to the following topics for information about how to use the xConnect Client API to work with events:

When an event is triggered, an event definition ID is passed into the constructor. Event definition ID come from items in Sitecore that give contextual meaning to an event in a reporting context. Event definitions are managed by marketers, who define properties such as the event name, description, and classification. The following table lists the types of events that are available and their location in the Sitecore tree:

Definition

Event models used

Path

Goals

Goal

/sitecore/system/Marketing Control Panel/Goals

Outcomes

Outcome

/sitecore/system/Marketing Control Panel/Outcomes

Generic events

EventPageViewEvent (system) MVTestTriggered (system) PersonalizationEvent (system)

/sitecore/system/Marketing Control Panel/Events

Page events

Event DownloadEvent SearchEvent CampaignEvent

/sitecore/system/Settings/Analytics/Page Events

Important

It is your responsibility to make sure that the correct event definition ID is used with the correct model. Although you can use the Goal model with an outcome definition ID, doing so will adversely affect you reporting data.

Events with fixed definitions

The following events have a fixed definition item, which means that there is a one-to-one relationship between the event model and a definition item in Sitecore.

  • PageViewEvent:Event

  • CampaignEvent:Event

  • DownloadEvent:Event

  • SearchEvent:Event

In the following example, the SearchEvent defines a fixed EventDefinitionId that is passed into the base Event model. There is no public constructor that allows you to pass in a different definition ID.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

namespace Sitecore.XConnect.Collection.Model
{
    public class SearchEvent : Event
    {
        public static readonly Guid EventDefinitionId = new Guid("0C179613-2073-41AB-992E-027D03D523BF");
        public string Keywords { get; set; }

        public SearchEvent(DateTime timestamp) : base(EventDefinitionId, timestamp)
        {
        }
    }
}

See the custom outcome for an example of how to create an event with a fixed definition item.

Event models determine what is be collected when an event is triggered. For example, the SearchEvent model represents the search terms that were used as the Keywords property. xConnect ships with the following default event models:

  • Event

  • Goal:Event

  • Outcome:Event

  • CampaignEvent:Event

  • DownloadEvent:Event

  • SearchEvent:Event

  • PageViewEvent:Event (System event)

  • PersonalizationEvent:Event (System event)

  • MVTestTriggered (System event)

Note

Not all goals, outcome, and page events have a model. Use the base Goal, Outcome, or Event classes to trigger the events that do not have a specialized model.

Keep the following recommended practices in mind when working with event models:

  • Goals and outcomes must be triggered using the Goal and Outcome models, or an inheriting type.

  • If an event definition ID is associated with a specialized model, such as SearchEvent, do not use that definition ID with another model.

  • If you want to capture any custom data or enforce a particular constructor parameter, you must create your own event model. Your event model can inherit Event, Goal, or Outcome.

Use custom event models with meaningful names wherever possible, particularly if you plan to export interaction data to a third party. For example, CarPurchaseOutcome has more contextual meaning than Outcome.

Important

Do not rely on the Data, DataKey, Text, and CustomValues properties on the Event class to store custom data. These properties are only available for legacy purposes.

Events or individual event properties can be decorated with the following attribute:

  • [DONOTINDEX]:  Events or event properties decorated with this attribute are not indexed and are therefore not searchable. Use this for data that you are not interested in searching - such as binary data.

In the context of the tracker, you must use the tracker API to trigger an event. On session end, event data is mapped to xConnect event models and submitted to xConnect as an interaction. In any other context, use the xConnect Client API directly. Refer to the following topics for more information about triggering events: