Triggering custom events

Convert a page event

Version:

This topic describes how to convert a generic event or a page event that was triggered from the tracker into a custom event before it is saved to xConnect.

Note

xConnect does not distinguish between generic events and page events. Page event definition items are located under /sitecore/system/Settings/Analytics/Page Events, where as generic event definition items are located under /sitecore/system/Marketing Control Panel/Events.

Create a custom event model

Create a custom event model as shown. This example uses the built-in ‘Print’ page event. Refer to the xConnect documentation for more information about creating custom events.

using Sitecore.XConnect;
using System;

namespace Documentation
{
    public class PrintEvent : Event
    {
        public static Guid PrintID = Guid.Parse("{CD52B756-21B4-4028-8BA5-E981B8A96F95}");

        public PrintEvent(DateTime timestamp) : base(PrintID, timestamp) { }

        public Orientation Orientation { get; set; }
    }

    public enum Orientation
    {
        Unknown = 0,
        Landscape = 1,
        Potrait = 2
    }
}

Create an event conversion processor

Create a pipeline processor that inherits ConvertPageEventDataToEventBase.
Implement CreateEvent and CanProcessPageEventData as shown. This handler assumes that the Orientation is stored in the CustomValues dictionary.

using Sitecore.Analytics.Model;
using Sitecore.Analytics.XConnect.DataAccess.Pipelines.ConvertToXConnectEventPipeline;
using Sitecore.Framework.Conditions;
using Sitecore.XConnect;

namespace Documentation
{
    public class ConvertPrintEvent : ConvertPageEventDataToEventBase
    {
        protected override bool CanProcessPageEventData(PageEventData pageEventData)
        {
            Condition.Requires(pageEventData, nameof(pageEventData)).IsNotNull();

            if (pageEventData.PageEventDefinitionId == PrintEvent.PrintID)
            {
                return true;
            }

            return false;
        }

        // Create new print event from pageEventData
        // All base Event properties are mapped automatically
        protected override Event CreateEvent(PageEventData pageEventData)
        {
            PrintEvent printEvent = new PrintEvent(pageEventData.DateTime);

            var orientation = (Orientation)pageEventData.CustomValues["Orientation"]; // Store 'Orientation' as a constant somewhere and use when triggering event

            printEvent.Orientation = orientation;

            return printEvent;
        }
    }
}

Register event conversion processor

Create a new new configuration file named MyBrand.CustomEvents.config and patch in your handler as shown:

Important

Your processor must be patched in before the final event handler as shown.

<?xml version="1.0" encoding="utf-8" ?>
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
    <sitecore>
        <pipelines>
        <convertToXConnectEvent>
            <processor patch:before="processor[@type='Sitecore.Analytics.XConnect.DataAccess.Pipelines.ConvertToXConnectEventPipeline.ConvertPageEventDataToEvent, Sitecore.Analytics.XConnect']" type="Documentation.ConvertPrintEvent, Documentation"/>
        </convertToXConnectEvent>
        </pipelines>
    </sitecore>
</configuration>

Trigger the event

Trigger the event with the custom data that the event conversion pipeline processor expects:

var ev = Sitecore.Analytics.Tracker.MarketingDefinitions.PageEvents[PrintEvent.PrintID];

if (ev != null)
{
    var pageData = new Sitecore.Analytics.Data.PageEventData(ev.Alias, ev.Id);

    pageData.CustomValues.Add("Orientation", Orientation.Potrait);

    Sitecore.Analytics.Tracker.Current.CurrentPage.Register(pageData);
}

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