Interactions

Current version: 9.0

An interaction describes any point at which a contact interfaces with a brand, either online or offline. Examples of interactions include:

  • Purchasing a something from a physical store

  • Using an app

  • Browsing a website

  • A phone conversation

Interactions are represented by the Sitecore.XConnect.Interaction class and must have at least one event. In the following example, an interaction with a single goal is added to a new contact:

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

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

                    // Create new interaction for this contact
                    Guid channelId = Guid.NewGuid(); // Replace with channel ID from Sitecore
                    string userAgent = "Mozilla/5.0 (Nintendo Switch; ShareApplet) AppleWebKit/601.6 (KHTML, like Gecko) NF/4.0.0.5.9 NintendoBrowser/5.1.0.13341";
                    var interaction = new Sitecore.XConnect.Interaction(newContact, InteractionInitiator.Brand, channelId, userAgent);

                    // Get goal ID - this is the ID of the item in Sitecore
                    var fakeGoalId = Guid.Parse("2a413310-b086-12e6-9598-0800200c9a66");

                    // Create new instance of goal
                    Sitecore.XConnect.Model.Goal goal = new Goal(fakeGoalId, DateTime.UtcNow);
                    {
                    };

                    // Add goal to interaction
                    interaction.Events.Add(goal);

                    // Add interaction operation to client
                    client.AddInteraction(interaction);

                    // Submit interaction
                    await client.SubmitAsync();
                }
                catch (Exception ex)
                {
                    // Handle exception
                }
            }
        }
    }
}

The following table describes mandatory interaction properties that must be passed into the constructor:

Property

Description

ChannelId

Channels are the paths that contacts use to interact with your brand, such as webinars, e-mail campaigns, or a face-to-face conversation at a trade show. Channels are represented as definition items under /sitecore/system/Marketing Control Panel/Taxonomies/Channel.

Interactions that were created by the system use the system channel: /sitecore/system/Marketing Control Panel/Taxonomies/Channel/Online/System/System. Examples include interactions created as a byproduct of an automation activity.

Initiator

If a contact visits a brand’s website, the interaction was initiated by the contact. If a brand makes a delivery or a phone call, the interaction was initiated by the brand.

UserAgent

xConnect is a web service, which means that all interactions are created via an internet-enabled device. Every device has a user agent. User agents must follow the format set out in the RFC. For example, the Nintendo Switch user agent is Mozilla/5.0 (Nintendo Switch; ShareApplet) AppleWebKit/601.6 (KHTML, like Gecko) NF/4.0.0.5.9 NintendoBrowser/5.1.0.13341.

Note

Interactions created by an internal system, such as Marketing Automation, will have a user agent such as Sitecore/9.0 (Marketing Automation).

The following table describes optional interaction properties:

Property

Description

VenueId

The ID of the offline venue where the interaction occurred, if applicable. Venues are represented as definition items under /sitecore/system/Marketing Control Panel/Taxonomies/Venues.

CampaignId

The ID of the campaign that caused the interaction. The campaign represented by the CampaignId GUID is not duplicated in the Events collection.

In a tracking context, the CampaignId is set if the campaign is triggered on the first page of the session - for example, as a result of clicking a campaign URL on Facebook. Any additional campaigns that are triggered after the first page view are added as CampaignEvent objects.

Interactions do not have a type

Interactions do not have an explicit type. For example, there is no property the classifes an interaction as ‘offline’ or ‘online’. This is by design. You should infer an interaction’s type based on facets and properties. For example:

  • The presence of the WebVisit facet on an interaction indicates that an interaction happened in the context of a website

  • The presence of a VenueId indicates that an interaction happened in a physical location - such as a shop

Interaction engagement value

An interaction’s EngagementValue is the sum of the engagement value of that interaction’s events.

Interaction duration

An interaction’s StartDateTime, EndDateTime, and Duration are calculated using the interaction’s event time stamps and duration.

  • Interaction .StartDateTime corresponds to the smallest event Timestamp

  • Interaction .EndDateTime is calculated as the value of the largest event Timestamp plus event duration, if duration exists

  • Interaction .Duration is .EndDateTime - .StartDateTime

Not all interactions have a duration. For example, scanning a boarding card is an instantaneous interaction with a single event.

Extending the interaction model

Use facets to extend the interaction model. Refer to the following sections for more information:

Note

CustomValues has been removed from the Interaction object - facets should be used instead.

Do you have some feedback for us?

If you have suggestions for improving this article,