Work with interactions

Add interaction events

Version:

This topic demonstrates how to add various types of events to an interaction. Keep the following in mind when adding events to an interaction:

It is possible to associate an event with an incorrect definition (for example, associating an outcome definition with a Goal). The platform will not enforce any particular relationships between an event type collection model and a definition item. It is your responsibility to ensure the fidelity of your data.
The EngagementValue property is optional and must be set manually. In a tracking context, the tracker will set the engagement value to the event’s definition item’s default engagement value before saving. In a non-tracking context, must use the Marketing Operations API to retrieve the event definition item if you want to use the default engagement value.

Adding a Goal to an interaction

The following example demonstrates how to add a goal to an interaction.

using Sitecore.XConnect;
using Sitecore.XConnect.Client;
using System;

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

                    Guid channelId = Guid.NewGuid();
                    string userAgent = "Sample User Agent";
                    var interaction = new Sitecore.XConnect.Interaction(contact, InteractionInitiator.Brand, channelId, userAgent);

                    Guid goalID = Guid.Parse("21EC2020-3AEA-4069-A2DD-08002B30309D"); // ID of goal item

                    var goal = new Goal(goalID, DateTime.UtcNow);

                    goal.EngagementValue = 20; // Manually setting engagement value rather than going to definition item

                    interaction.Events.Add(goal);

                    client.AddContact(contact);
                    client.AddInteraction(interaction);

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

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

                    Guid channelId = Guid.NewGuid();
                    string userAgent = "Sample User Agent";
                    var interaction = new Sitecore.XConnect.Interaction(contact, InteractionInitiator.Brand, channelId, userAgent);

                    Guid goalID = Guid.Parse("21EC2020-3AEA-4069-A2DD-08002B30309D"); // ID of goal item

                    var goal = new Goal(goalID, DateTime.UtcNow);

                    goal.EngagementValue = 20; // Manually setting engagement value rather than going to definition item

                    interaction.Events.Add(goal);

                    client.AddContact(contact);
                    client.AddInteraction(interaction);

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

Adding an Outcome to an interaction

The following example demonstrates how to add an outcome to an interaction.

Note

Although Currency and MonetaryValue are mandatory properties, you can pass in String.Empty and 0.00m if your outcome is not associated with a monetary value.

using System;
using Sitecore.XConnect;
using Sitecore.XConnect.Client;

namespace Documentation
{
    public class AddOutcome
    {
        public async void Example()
        {
            using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                try
                {
                    var contact = new Sitecore.XConnect.Contact();

                    var channel = Guid.NewGuid(); // Use real channel ID from Sitecore

                    var interaction = new Interaction(contact, InteractionInitiator.Brand, channel, "iTunes/9.0.3 (Macintosh; U; Intel Mac OS X 10_6_2; en-ca)"); // Agent is iTunes

                    Guid outcomeId = Guid.Parse("21EC2020-3AEA-4069-A2DD-08002B30309D"); // ID of outcome item

                    var outcome = new Sitecore.XConnect.Outcome(outcomeId, DateTime.UtcNow, "USD", 100.00m);

                    interaction.Events.Add(outcome);

                    client.AddContact(contact);
                    client.AddInteraction(interaction);

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

        public void ExampleSync()
        {
            using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                try
                {
                    var contact = new Sitecore.XConnect.Contact();

                    var channel = Guid.NewGuid(); // Use real channel ID from Sitecore

                    var interaction = new Interaction(contact, InteractionInitiator.Brand, channel, "iTunes/9.0.3 (Macintosh; U; Intel Mac OS X 10_6_2; en-ca)"); // Agent is iTunes

                    Guid outcomeId = Guid.Parse("21EC2020-3AEA-4069-A2DD-08002B30309D"); // ID of outcome item

                    var outcome = new Sitecore.XConnect.Outcome(outcomeId, DateTime.UtcNow, "USD", 100.00m);

                    interaction.Events.Add(outcome);

                    client.AddContact(contact);
                    client.AddInteraction(interaction);

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

Adding a PageViewEvent to an interaction

Web interactions are likely to have multiple, nested events (goals and page events will have a page view event parent). The following example demonstrates how to simulate a web visit, which includes adding PageViewEvent events.

The PageViewEvent allows you to store both the page URL and the associated item ID, which means that you can store alias URLs or query strings in the Url property.

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

namespace Documentation
{
    public class SampleWebVisit
    {
        // Async example
        public async void Example()
        {
            using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                // Create a new contact and set some facets
                var contact = new Contact();

                var personalInfoFacet = new PersonalInformation()
                {
                    FirstName = "Myrtle",
                    LastName = "McSitecore"
                };

                client.SetPersonal(contact, personalInfoFacet);

                client.AddContact(contact);

                // Create a new interaction for the contact
                Guid channelId = Guid.NewGuid(); // Use real channel ID from Sitecore
                string userAgent = "Sample User Agent";
                Interaction webInteraction = new Interaction(contact, InteractionInitiator.Brand, channelId, userAgent);

                // Create a new web visit facet model

                var webVisitFacet = new WebVisit()
                {
                    // Populate data about the web visit
                    Browser = new BrowserData() { BrowserMajorName = "Chrome", BrowserMinorName = "Desktop", BrowserVersion = "22.0" },
                    Language = "en",
                    OperatingSystem = new OperatingSystemData() { Name = "Windows", MajorVersion = "10", MinorVersion = "4" },
                    Referrer = "www.google.com",
                    Screen = new ScreenData() { ScreenHeight = 1080, ScreenWidth = 685 },
                    SearchKeywords = "sitecore",
                    SiteName = "website"
                };


                var itemId = Guid.NewGuid();
                var itemVersion = 5;

                // First page view
                PageViewEvent
pageView = new PageViewEvent(new DateTime(2016, 10, 10, 13, 20,
22).ToUniversalTime(), itemId, itemVersion, "en")

                {

                    ItemLanguage = "en",

                    Duration = new
TimeSpan(3000)

                };
                webInteraction.Events.Add(pageView);

                var secondItemId = Guid.NewGuid();
                var secondItemVersion = 2;

                // Second page view
                PageViewEvent pageView2 = new
PageViewEvent(new DateTime(2016, 10, 10, 13, 21, 22).ToUniversalTime(),
secondItemId, secondItemVersion, "en")

                {

                    ItemLanguage = "en",

      
             Duration = new
TimeSpan(3200)

                };
                webInteraction.Events.Add(pageView2);

                // First goal, associated with second page view
                Goal goal1 = new Goal(Guid.NewGuid(), new DateTime(2016, 10, 10, 13, 22, 22).ToUniversalTime())
                {
                    ParentEventId = pageView2.Id
                };
                webInteraction.Events.Add(goal1);

                var thirdItemId = Guid.NewGuid();
                var thirdItemVersion = 2;

                // Third page view
                PageViewEvent pageView3 = new
PageViewEvent(new DateTime(2016, 10, 10, 13, 22, 22).ToUniversalTime(),
thirdItemId, thirdItemVersion, "en")

                {

                    ItemLanguage = "en",

      
             Duration = new
TimeSpan(1200)

                };

                webInteraction.Events.Add(pageView3);

                // Set web visit facet on interaction
                client.SetWebVisit(webInteraction, webVisitFacet);

                // Add interaction
                client.AddInteraction(webInteraction);

                // Submit contact and interaction
                await client.SubmitAsync();
            }
        }

        // Sync example
        public void ExampleSync()
        {
            using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                // Create a new contact and set some facets
                var contact = new Contact();

                var personalInfoFacet = new PersonalInformation()
                {
                    FirstName = "Myrtle",
                    LastName = "McSitecore"
                };

                client.SetPersonal(contact, personalInfoFacet);

                client.AddContact(contact);

                // Create a new interaction for the contact
                Guid channelId = Guid.NewGuid(); // Use real channel ID from Sitecore
                string userAgent = "Sample User Agent";
                Interaction webInteraction = new Interaction(contact, InteractionInitiator.Brand, channelId, userAgent);

                // Create a new web visit facet model
               

var webVisitFacet = new WebVisit()

                {

                    // Populate data about the
web visit

 
                  Browser = new
BrowserData() { BrowserMajorName = "Chrome", BrowserMinorName = "Desktop",
BrowserVersion = "22.0" },

                    Language = "en",

                    OperatingSystem = new
OperatingSystemData() { Name = "Windows", MajorVersion = "10",
MinorVersion = "4" },

                    Referrer = "www.google.com",

                    Screen = new ScreenData() {
ScreenHeight = 1080, ScreenWidth = 685 },

                    SearchKeywords = "sitecore",

                    SiteName = "website"

                }; 

                var itemId = Guid.NewGuid();
                var itemVersion = 5;

                // First page view
              PageViewEvent pageView = new PageViewEvent(new DateTime(2016, 10, 10, 13, 20, 22).ToUniversalTime(), itemId, itemVersion, "en");

                pageView.ItemLanguage = "en";
                pageView.Duration = new TimeSpan(3000);

                webInteraction.Events.Add(pageView);

                var secondItemId = Guid.NewGuid();
                var secondItemVersion = 2;

                // Second page view
                PageViewEvent pageView2 = new
PageViewEvent(new DateTime(2016, 10, 10, 13, 21, 22).ToUniversalTime(),
secondItemId, secondItemVersion, "en")

                {
                    ItemLanguage = "en",

                    Duration = new
TimeSpan(3200)
                };
              

                webInteraction.Events.Add(pageView2);

                // First goal, associated with second page view
                Goal goal1 = new Goal(Guid.NewGuid(), new DateTime(2016, 10, 10, 13, 22, 22).ToUniversalTime());

                goal1.ParentEventId = pageView2.Id;

                webInteraction.Events.Add(goal1);

                var thirdItemId = Guid.NewGuid();
                var thirdItemVersion = 2;

                // Third page view
                PageViewEvent pageView3 = new PageViewEvent(new DateTime(2016, 10, 10, 13, 22, 22).ToUniversalTime(), thirdItemId, thirdItemVersion, "en");

                pageView3.ItemLanguage = "en";
                pageView3.Duration = new TimeSpan(1200);

                webInteraction.Events.Add(pageView3);

                // Set web visit facet on interaction
                client.SetWebVisit(webInteraction, webVisitFacet);

                // Add interaction
                client.AddInteraction(webInteraction);

                // Submit contact and interaction
                client.Submit();
            }
        }
    }
}

Adding an event as a child of a page view event

To associate a goal with a page view, set the ParentEventId of the goal to the Id of the page view as demonstrated in the previous example.

// Second page view
PageViewEvent pageView2 = new PageViewEvent(new DateTime(2016, 10, 10, 13, 21, 22).ToUniversalTime(), secondItemId, secondItemVersion, "en")
                {
                    ItemLanguage = "en",
                    Duration = new TimeSpan(3200)
                };

webInteraction.Events.Add(pageView2);

// First goal, associated with second page view
Goal goal1 = new Goal(Guid.NewGuid(), new DateTime(2016, 10, 10, 13, 22, 22).ToUniversalTime())
                {
                    ParentEventId = pageView2.Id
                };

webInteraction.Events.Add(goal1);

var thirdItemId = Guid.NewGuid();
var thirdItemVersion = 2;

Adding a page event

Page events are stored under /sitecore/system/Settings/Analytics/Page Events and represent common, web-specific events such as ‘user performed a search’ or ‘the page is slow’. When triggering a page event, make sure you associate with a PageViewEvent by setting the ParentEventId property.

Not all page events are represented by a specialized class. For events without a specialized class, use the base Event class and pass in the ID of the event definition item.

Adding a DownloadEvent to an interaction

The following example demonstrates how to trigger a download event. The ItemId that is passed into the constructor is the ID of the media item that was downloaded.

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

namespace Documentation
{
    public class AddDownloadEvent
    {
        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.NewGuid();
                    string userAgent = "Sample User Agent";

                    var interaction = new Sitecore.XConnect.Interaction(newContact, InteractionInitiator.Brand, channelId, userAgent);

                    var fakeItemID = Guid.NewGuid();
                    var fakeItemVersion = 3;

                    Sitecore.XConnect.Collection.Model.PageViewEvent pageView = new PageViewEvent(DateTime.UtcNow, fakeItemID, fakeItemVersion, "en")
                    {
                        Duration = new TimeSpan(0, 0, 30),
                        Url = "/my/test/page?with=querystring"
                    };

                    interaction.Events.Add(pageView);

                    var guidOfDownload = Guid.NewGuid(); // Replace with GUID of media item that was downloaded

                    DownloadEvent download = new DownloadEvent(DateTime.UtcNow, guidOfDownload)
                    {
                        ParentEventId = pageView.Id
                    };

                    interaction.Events.Add(download);

                    client.AddInteraction(interaction);

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

        // Sync example
        public void ExampleSync()
        {
            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.NewGuid();
                    string userAgent = "Sample User Agent";

                    var interaction = new Sitecore.XConnect.Interaction(newContact, InteractionInitiator.Brand, channelId, userAgent);

                    var fakeItemID = Guid.NewGuid();
                    var fakeItemVersion = 3;

                    Sitecore.XConnect.Collection.Model.PageViewEvent pageView = new PageViewEvent(DateTime.UtcNow, fakeItemID, fakeItemVersion, "en")
                    {
                        Duration = new TimeSpan(0, 0, 30),
                        Url = "/my/test/page?with=querystring"
                    };

                    interaction.Events.Add(pageView);

                    var guidOfDownload = Guid.NewGuid(); // Replace with GUID of media item that was downloaded

                    DownloadEvent download = new DownloadEvent(DateTime.UtcNow, guidOfDownload)
                    {
                        ParentEventId = pageView.Id
                    };

                    interaction.Events.Add(download);

                    client.AddInteraction(interaction);

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

Adding a SearchEvent to an interaction

The following example demonstrates how to register a search event. The Keyword property is not mandatory.

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

namespace Documentation
{
    public class AddSearchEvent
    {
        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.NewGuid();
                    string userAgent = "Sample User Agent";

                    var interaction = new Sitecore.XConnect.Interaction(newContact, InteractionInitiator.Brand, channelId, userAgent);

                    var fakeItemID = Guid.NewGuid();
                    var fakeItemVersion = 3;

                    Sitecore.XConnect.Collection.Model.PageViewEvent pageView = new PageViewEvent(DateTime.UtcNow, fakeItemID, fakeItemVersion, "en")
                    {
                        Duration = new TimeSpan(0, 0, 30),
                        Url = "/my/test/page?with=querystring"
                    };

                    interaction.Events.Add(pageView);

                    var search = new SearchEvent(DateTime.UtcNow)
                    {
                        Keywords = "xConnect"
                    };

                    interaction.Events.Add(search);

                    client.AddInteraction(interaction);

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

        // Sync example
        public void ExampleSync()
        {
            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.NewGuid();
                    string userAgent = "Sample User Agent";

                    var interaction = new Sitecore.XConnect.Interaction(newContact, InteractionInitiator.Brand, channelId, userAgent);

                    var fakeItemID = Guid.NewGuid();
                    var fakeItemVersion = 3;

                    Sitecore.XConnect.Collection.Model.PageViewEvent pageView = new PageViewEvent(DateTime.UtcNow, fakeItemID, fakeItemVersion, "en")
                    {
                        Duration = new TimeSpan(0, 0, 30),
                        Url = "/my/test/page?with=querystring"
                    };

                    interaction.Events.Add(pageView);

                    var search = new SearchEvent(DateTime.UtcNow)
                    {
                        Keywords = "xConnect"
                    };

                    interaction.Events.Add(search);


                    client.AddInteraction(interaction);

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

Adding a CampaignEvent to an interaction

The following example demonstrates how to trigger a campaign.

The event ID of the CampaignEvent as the same event is happening - a campaign is being triggered. However, the campaign associated with the event will vary and is represented by the CampaignDefinitionId property.

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

namespace Documentation
{
    public class AddCampaignEvent
    {
        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.NewGuid();
                    string userAgent = "Sample User Agent";

                    var interaction = new Sitecore.XConnect.Interaction(newContact, InteractionInitiator.Brand, channelId, userAgent);

                    var fakeItemID = Guid.NewGuid();
                    var fakeItemVersion = 3;

                    Sitecore.XConnect.Collection.Model.PageViewEvent pageView = new PageViewEvent(DateTime.UtcNow, fakeItemID, fakeItemVersion, "en")
                    {
                        Duration = new TimeSpan(0, 0, 30),
                        Url = "/my/test/page?with=querystring"
                    };

                    interaction.Events.Add(pageView);

                    var campaignDefinition = Guid.NewGuid(); // Replace with real campaign ID

                    var campaign = new CampaignEvent(campaignDefinition, DateTime.UtcNow);

                    interaction.Events.Add(campaign);

                    client.AddInteraction(interaction);

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

        // Sync example
        public void ExampleSync()
        {
            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.NewGuid();
                    string userAgent = "Sample User Agent";

                    var interaction = new Sitecore.XConnect.Interaction(newContact, InteractionInitiator.Brand, channelId, userAgent);

                    var fakeItemID = Guid.NewGuid();
                    var fakeItemVersion = 3;

                    Sitecore.XConnect.Collection.Model.PageViewEvent pageView = new PageViewEvent(DateTime.UtcNow, fakeItemID, fakeItemVersion, "en")
                    {
                        Duration = new TimeSpan(0, 0, 30),
                        Url = "/my/test/page?with=querystring"
                    };

                    interaction.Events.Add(pageView);

                    var campaignDefinition = Guid.NewGuid(); // Replace with real campaign ID

                    var campaign = new CampaignEvent(campaignDefinition, DateTime.UtcNow);

                    interaction.Events.Add(campaign);

                    client.AddInteraction(interaction);

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

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