1. Get interactions

Get interaction events

Version:

Events are available on the Events property of the Interaction object. Every interaction has at least one event.

Get events by type

The following example demonstrates how to retrieve a list of Goal events that occurred during an interaction, ordered by timestamp:

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

namespace Documentation
{
    public class GetInteractionEvents
    {
        // Async example
        public async void ExampleAsync()
        {
            using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                try
                {

                    // Contact reference from ID
                    var contactRef = new Sitecore.XConnect.ContactReference(Guid.Parse("B9814105-1F45-E611-82E6-34E6D7117DCB"));
                    Sitecore.XConnect.InteractionReference interactionRef = new Sitecore.XConnect.InteractionReference(contactRef, Guid.Parse("DA2DA5F0-4348-E611-82E7-34E6D7117DCB"));

                    var interactionTask = client.GetAsync<Interaction>(interactionRef, new InteractionExecutionOptions(new InteractionExpandOptions(IpInfo.DefaultFacetKey)));

                    Interaction interaction = await interactionTask;

                    if (interaction != null)
                    {
                        var events = interaction.Events;

                        // Get all goals
                        var goals = interaction.Events.OfType<Goal>().OrderBy(ev => ev.Timestamp).ToList();
                    }
                }
                catch (Exception ex)
                {
                    // Manage exceptions
                }
            }
        }

        // Sync example
        public void ExampleSync()
        {
            using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                try
                {

                    // Contact reference from ID
                    var contactRef = new Sitecore.XConnect.ContactReference(Guid.Parse("B9814105-1F45-E611-82E6-34E6D7117DCB"));
                    Sitecore.XConnect.InteractionReference interactionRef = new Sitecore.XConnect.InteractionReference(contactRef, Guid.Parse("DA2DA5F0-4348-E611-82E7-34E6D7117DCB"));

                    Interaction interaction = client.Get<Interaction>(interactionRef, new InteractionExecutionOptions(new InteractionExpandOptions(IpInfo.DefaultFacetKey)));

                    if (interaction != null)
                    {
                        var events = interaction.Events;

                        // Get all goals
                        var goals = interaction.Events.OfType<Goal>().OrderBy(ev => ev.Timestamp).ToList();
                    }
                }
                catch (Exception ex)
                {
                    // Manage exceptions
                }
            }
        }
    }
}

Get events by definition ID

To get a specific goal, outcome, or page event, you can filter by the event’s DefinitionId property. This property is the ID of the definition item in Sitecore that was used when triggering the event.

Some event models, such as DownloadEvent, have a fixed definition ID that is used every time the event is triggered - this means that there is a one to one relationship between the event model and the event definition. The Goal event model, however, can be used with any goal definition item.

In the following examle, every goal with the definition ID {A4364105-1F45-E611-82E6-34E6D7117DCB} is selected.

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

namespace Documentation
{
    public class GetEventByDefinition
    {
        // Async example
        public async void ExampleAsync()
        {
            using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                try
                {

                    // Contact reference from ID
                    var contactRef = new Sitecore.XConnect.ContactReference(Guid.Parse("B9814105-1F45-E611-82E6-34E6D7117DCB"));
                    Sitecore.XConnect.InteractionReference interactionRef = new Sitecore.XConnect.InteractionReference(contactRef, Guid.Parse("DA2DA5F0-4348-E611-82E7-34E6D7117DCB"));

                    var interactionTask = client.GetAsync<Interaction>(interactionRef, new InteractionExecutionOptions(new InteractionExpandOptions(IpInfo.DefaultFacetKey)));

                    Interaction interaction = await interactionTask;

                    if (interaction != null)
                    {
                        var events = interaction.Events;

                        // Get all goals with definition ID {A4364105-1F45-E611-82E6-34E6D7117DCB}
                        var goals = interaction.Events.OfType<Goal>().Where(x => x.DefinitionId == Guid.Parse("A4364105-1F45-E611-82E6-34E6D7117DCB"));
                    }
                }
                catch (XdbExecutionException ex)
                {
                    // Manage exceptions
                }
            }
        }

        // Sync example
        public void ExampleSync()
        {
            using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                try
                {

                    // Contact reference from ID
                    var contactRef = new Sitecore.XConnect.ContactReference(Guid.Parse("B9814105-1F45-E611-82E6-34E6D7117DCB"));
                    Sitecore.XConnect.InteractionReference interactionRef = new Sitecore.XConnect.InteractionReference(contactRef, Guid.Parse("DA2DA5F0-4348-E611-82E7-34E6D7117DCB"));

                    Interaction interaction = client.Get<Interaction>(interactionRef, new InteractionExecutionOptions(InteractionExpandOptions(IpInfo.DefaultFacetKey)));

                    if (interaction != null)
                    {
                        var events = interaction.Events;

                        // Get all goals with definition ID {A4364105-1F45-E611-82E6-34E6D7117DCB}
                        var goals = interaction.Events.OfType<Goal>().Where(x => x.DefinitionId == Guid.Parse("A4364105-1F45-E611-82E6-34E6D7117DCB"));
                    }
                }
                catch (XdbExecutionException ex)
                {
                    // Manage exceptions
                }
            }
        }
    }
}

Get page view events

For web interactions, page views are represented by the PageViewEvent model. The following example demonstrates how to retrieve a list of PageViewEvent events:

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

namespace Documentation
{
    public class PageView
    {
        public async void Example()
        {
            using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                try
                {

                    // Contact reference from ID
                    var contactRef = new Sitecore.XConnect.ContactReference(Guid.Parse("B9814105-1F45-E611-82E6-34E6D7117DCB"));
                    Sitecore.XConnect.InteractionReference interactionRef = new Sitecore.XConnect.InteractionReference(contactRef, Guid.Parse("DA2DA5F0-4348-E611-82E7-34E6D7117DCB"));

                    var interactionTask = client.GetAsync<Interaction>(interactionRef, new InteractionExecutionOptions(new InteractionExpandOptions(IpInfo.DefaultFacetKey)));

                    var interaction = await interactionTask;

                    var events = interaction.Events;

                    var pageViews = interaction.Events.OfType<PageViewEvent>().OrderBy(ev => ev.Timestamp).ToList();
                }
                catch (XdbExecutionException ex)
                {
                    // Handle exception
                }
            }
        }

        // Sync example
        public void ExampleSync()
        {
            using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                try
                {

                    // Contact reference from ID
                    var contactRef = new Sitecore.XConnect.ContactReference(Guid.Parse("B9814105-1F45-E611-82E6-34E6D7117DCB"));
                    Sitecore.XConnect.InteractionReference interactionRef = new Sitecore.XConnect.InteractionReference(contactRef, Guid.Parse("DA2DA5F0-4348-E611-82E7-34E6D7117DCB"));

                    var interaction = client.Get<Interaction>(interactionRef, new InteractionExecutionOptions(new InteractionExpandOptions(IpInfo.DefaultFacetKey)));

                    var events = interaction.Events;

                    var pageViews = interaction.Events.OfType<PageViewEvent>().OrderBy(ev => ev.Timestamp).ToList();
                }
                catch (XdbExecutionException ex)
                {
                    // Handle exception
                }
            }
        }
    }
}

Get page view by sequence number

There is no direct replacement for VisitPageIndex. Order page views by Timestamp use the ElementAt() extension. For example:

var pageViews = interaction.Events.OfType<PageViewEvent>().OrderBy(ev => ev.Timestamp).ToList();
var event = pageViewEvents.ElementAt(3); // Gets fourth page view

Get an event that occurred on a specific page

When a contact visits a page, they will trigger a PageViewEvent. In the context of that page, they may also trigger an additional event, such as:

  • Goal
  • Outcome
  • DownloadEvent
  • SearchEvent
  • CampaignEvent
  • A page event represented by a generic Event

If an event is triggered in the context of a page, the ParentEventId of that event is the Id of the PageViewEvent. The example below demonstrates how to iterate through a list of pages and get all events that were triggered on that page.

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

namespace Documentation
{
    public class EventsOnPage
    {
        // Async example
        public async void ExampleAsync()
        {
            using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                try
                {

                    // Contact reference from ID
                    var contactRef = new Sitecore.XConnect.ContactReference(Guid.Parse("B9814105-1F45-E611-82E6-34E6D7117DCB"));
                    Sitecore.XConnect.InteractionReference interactionRef = new Sitecore.XConnect.InteractionReference(contactRef, Guid.Parse("DA2DA5F0-4348-E611-82E7-34E6D7117DCB"));

                    var interactionTask = client.GetAsync<Sitecore.XConnect.Interaction>(interactionRef, new InteractionExecutionOptions(new InteractionExpandOptions(IpInfo.DefaultFacetKey)));

                    var interaction = await interactionTask;

                    // This particular example is web-focused and is getting all events with a parent event of type PageViewEvent
                    var pageViews = interaction.Events.OfType<PageViewEvent>().OrderBy(ev => ev.Timestamp).ToList();

                    // Create a map of events - this is the most efficient way to work with an interaction that
                    // has many events. It is a general recommendation and not specific to Sitecore.
                    var eventMap = interaction.Events.Where(ev => ev.ParentEventId.HasValue).ToLookup(ev => ev.ParentEventId.Value);
                    var eventGuid = Guid.Parse("c91ce6eb-c346-447e-b65d-1f0f90b520e5"); // Replace with the ID of a real event definition item

                    // For each page view, get any events where ParentEventId equals ID of the page view event
                    // and the event has a specific definition ID
                    foreach (var pageView in pageViews)
                    {
                        var goalAssociatedWithPageView = eventMap[pageView.Id].OfType<Goal>();
                        var eventAssociatedWithPageView = eventMap[pageView.Id].OfType<Event>().Where(x => x.DefinitionId == eventGuid);
                    }
                }
                catch (XdbExecutionException ex)
                {
                    // Manage exceptions
                }
            }
        }

        // Sync example
        public void ExampleSync()
        {
            using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                try
                {

                    // Contact reference from ID
                    var contactRef = new Sitecore.XConnect.ContactReference(Guid.Parse("B9814105-1F45-E611-82E6-34E6D7117DCB"));
                    Sitecore.XConnect.InteractionReference interactionRef = new Sitecore.XConnect.InteractionReference(contactRef, Guid.Parse("DA2DA5F0-4348-E611-82E7-34E6D7117DCB"));

                    var interaction = client.Get<Sitecore.XConnect.Interaction>(interactionRef, new InteractionExecutionOptions(new InteractionExpandOptions(IpInfo.DefaultFacetKey)));

                    // This particular example is web-focused and is getting all events with a parent event of type PageViewEvent
                    var pageViews = interaction.Events.OfType<PageViewEvent>().OrderBy(ev => ev.Timestamp).ToList();

                    // Create a map of events - this is the most efficient way to work with an interaction that
                    // has many events. It is a general recommendation and not specific to Sitecore.
                    var eventMap = interaction.Events.Where(ev => ev.ParentEventId.HasValue).ToLookup(ev => ev.ParentEventId.Value);
                    var eventGuid = Guid.Parse("c91ce6eb-c346-447e-b65d-1f0f90b520e5"); // Replace with the ID of a real event definition item

                    // For each page view, get any events where ParentEventId equals ID of the page view event
                    // and the event has a specific definition ID
                    foreach (var pageView in pageViews)
                    {
                        var goalAssociatedWithPageView = eventMap[pageView.Id].OfType<Goal>();
                        var eventAssociatedWithPageView = eventMap[pageView.Id].OfType<Event>().Where(x => x.DefinitionId == eventGuid);
                    }
                }
                catch (XdbExecutionException ex)
                {
                    // Manage exceptions
                }
            }
        }
    }
}

Get page events that are not represented by a custom type

Certain page events are represented by a custom type - such as DownloadEvent. If an event is not represented by a custom type, use the base Event type and filter by the definition ID of the event:

var eventGuid = Guid.Parse("c91ce6eb-c346-447e-b65d-1f0f90b520e5"); // Replace with the ID of a real event definition item

var event = interaction.Events.OfType<Event>().Where(x => x.DefinitionId == eventGuid);

Get campaign event by campaign ID

The CampaignEvent has two definition IDs:

  • DefinitionId is the ID of the event definition item itself - this ID is always the same
  • CampaignDefinitionId is the ID of the campaign definition item - this ID varies depending on the campaign that was triggered

In the following example, events referencing a campaign with the ID {29814105-2345-E611-AAE6-34E6D7117DCB} are selected:

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

namespace Documentation
{
    public class GetCampaignEvent
    {
        // Async example
        public async void ExampleAsync()
        {
            using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                try
                {

                    // Contact reference from ID
                    var contactRef = new Sitecore.XConnect.ContactReference(Guid.Parse("B9814105-1F45-E611-82E6-34E6D7117DCB"));
                    Sitecore.XConnect.InteractionReference interactionRef = new Sitecore.XConnect.InteractionReference(contactRef, Guid.Parse("DA2DA5F0-4348-E611-82E7-34E6D7117DCB"));

                    var interactionTask = client.GetAsync<Sitecore.XConnect.Interaction>(interactionRef, new InteractionExecutionOptions(new Sitecore.XConnect.InteractionExpandOptions(IpInfo.DefaultFacetKey)));

                    var interaction = await interactionTask;

                    var campaigns = interaction.Events.OfType<CampaignEvent>().Where(x => x.CampaignDefinitionId == Guid.Parse("29814105-2345-E611-AAE6-34E6D7117DCB")).ToList();
                }
                catch (XdbExecutionException ex)
                {
                    // Manage exceptions
                }
            }
        }

        // Sync example
        public void ExampleSync()
        {
            using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                try
                {

                    // Contact reference from ID
                    var contactRef = new Sitecore.XConnect.ContactReference(Guid.Parse("B9814105-1F45-E611-82E6-34E6D7117DCB"));
                    Sitecore.XConnect.InteractionReference interactionRef = new Sitecore.XConnect.InteractionReference(contactRef, Guid.Parse("DA2DA5F0-4348-E611-82E7-34E6D7117DCB"));

                    var interaction = client.Get<Sitecore.XConnect.Interaction>(interactionRef, new InteractionExecution Options(new Sitecore.XConnect.InteractionExpandOptions(IpInfo.DefaultFacetKey)));

                    var campaigns = interaction.Events.OfType<CampaignEvent>().Where(x => x.CampaignDefinitionId == Guid.Parse("29814105-2345-E611-AAE6-34E6D7117DCB")).ToList();
                }
                catch (XdbExecutionException ex)
                {
                    // Manage exceptions
                }
            }
        }
    }
}

Get definition item associated with an event or campaign

In a Sitecore context, you can use the Marketing Operations API to retrieve an event or campaign definition item. In a non-Sitecore context, use the Reference Data Service Client API.

Note

It is possible to trigger an event with a random GUID. However, this will adversely affect reporting.

If you have suggestions for improving this article, let us know!