Events

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:

Event definitions

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 Event PageViewEvent (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

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.

Triggering events

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: