Work with interactions

Add interactions

Version:

Use the client.AddInteraction() extension method to add a new interaction to a new or existing contact. Interactions must have at least one event, which can be a core collection model event or a custom event. Interactions have the following mandatory properties that must be passed in as constructor parameters:

The contact that the interaction belongs to
The initiator of the interaction, such as the user or the brand
The user agent of the application or service that is creating the interaction - such as ‘Chrome’
The ID of the channel that resulted in the interaction, such as a YouTube ad or affiliate referral

Note

New interactions are not available in the contact’s Interactions collection after the interaction has been submitted to xConnect. To see new interactions, you must request the contact again and use expand options to retrieve the contact’s interactions.

Add an interaction to a new contact

The following example demonstrates how to add a new interaction to a new contact. The interaction has a single PageViewEvent.

Note

If xConnect fails to create a new contact, the operation to add a new interaction will also fail.

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

namespace Documentation
{
    public class AddInteraction
    {
        // Async example
        public async void ExampleAsync()
        {
            using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                try
                {
                    // New anonymous contact
                    var newContact = new Sitecore.XConnect.Contact();
                    client.AddContact(newContact);

                    Guid channelId = Guid.Parse("86c7467a-d019-460d-9fa9-85d6d5d77fc4"); // Replace with real channel ID GUID
                    string userAgent = "Sample User Agent";

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

                    var fakeItemID = Guid.Parse("5746c4f3-7e16-40d9-ba1d-14c70875724c"); // Replace with real item ID

                    Sitecore.XConnect.Collection.Model.PageViewEvent pageView = new PageViewEvent(DateTime.UtcNow, fakeItemID, 3, "en")
                    {
                        Duration = new TimeSpan(0, 0, 30),
                        Url = "/test/url/test/url?query=testing"
                    };

                    interaction.Events.Add(pageView);

                    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
                {
                    // New anonymous contact
                    var newContact = new Sitecore.XConnect.Contact();
                    client.AddContact(newContact);

                    Guid channelId = Guid.Parse("86c7467a-d019-460d-9fa9-85d6d5d77fc4"); // Replace with real channel ID GUID
                    string userAgent = "Sample User Agent";

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

                    var fakeItemID = Guid.Parse("5746c4f3-7e16-40d9-ba1d-14c70875724c"); // Replace with real item ID

                    Sitecore.XConnect.Collection.Model.PageViewEvent pageView = new PageViewEvent(DateTime.UtcNow, fakeItemID, 3, "en")
                    {
                        Duration = new TimeSpan(0, 0, 30),
                        Url = "/test/url/test/url?query=testing"
                    };

                    interaction.Events.Add(pageView);

                    client.AddInteraction(interaction);

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

Add interaction to an existing contact

In the following example, the interaction is being added to an existing contact:

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

namespace Documentation
{
    public class AddInteractionExistingContact
    {
        public async void ExampleAsync()
        {
            using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                try
                {
                    var existingContactTask = client.GetAsync<Sitecore.XConnect.Contact>(new Sitecore.XConnect.IdentifiedContactReference("twitter", "myrtlesitecore"), new Sitecore.XConnect.ContactExpandOptions());

                    var existingContact = await existingContactTask;

                    if (existingContact != null)
                    {
                        Guid channelId = Guid.Parse("86c7467a-d019-460d-9fa9-85d6d5d77fc4"); // Replace with real channel ID GUID
                        string userAgent = "Sample User Agent";

                        // Interaction
                        var interaction = new Interaction(existingContact, InteractionInitiator.Brand, channelId, userAgent);

                        var fakeItemID = Guid.Parse("5746c4f3-7e16-40d9-ba1d-14c70875724c"); // Replace with real item ID

                        Sitecore.XConnect.Collection.Model.PageViewEvent pageView = new PageViewEvent(DateTime.UtcNow, fakeItemID, 3, "en")
                        {
                            Duration = new TimeSpan(0, 0, 30),
                            Url = "/test/url/test/url?query=testing"
                        };

                        interaction.Events.Add(pageView);

                        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 existingContact = client.Get<Sitecore.XConnect.Contact>(new Sitecore.XConnect.IdentifiedContactReference("twitter", "myrtlesitecore"), new Sitecore.XConnect.ContactExpandOptions());

                    if (existingContact != null)
                    {
                        Guid channelId = Guid.Parse("86c7467a-d019-460d-9fa9-85d6d5d77fc4"); // Replace with real channel ID GUID
                        string userAgent = "Sample User Agent";

                        // Interaction
                        var interaction = new Interaction(existingContact, InteractionInitiator.Brand, channelId, userAgent);

                        var fakeItemID = Guid.Parse("5746c4f3-7e16-40d9-ba1d-14c70875724c"); // Replace with real item ID

                        Sitecore.XConnect.Collection.Model.PageViewEvent pageView = new PageViewEvent(DateTime.UtcNow, fakeItemID, 3, "en")
                        {
                            Duration = new TimeSpan(0, 0, 30),
                            Url = "/test/url/test/url?query=testing"
                        };

                        interaction.Events.Add(pageView);

                        client.AddInteraction(interaction);

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

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