--- title: "Triggering custom events" slug: "triggering-custom-events" abstract: "" --- # Triggering custom events By default, events that are triggered from the tracker are saved to xConnect using generic, built-in event models such as `Goal`, `Outcome`, or `Event`. To use a custom event model, you must create an event conversion pipeline processor that converts the generic event into a custom event. For example, a generic `Event` with an ID of `{7D59A563-29A1-4C3D-8C15-35FA110B79E0}` might be converted into a specialized `SearchEvent`. You can also copy custom event data that was captured by the tracker to properties on the specialized model. For example, the `SearchEvent` class has a `Keywords` property. This property is populated by copying the value of the `Data` field on the generic `Event` model. > [!note] > The following code examples are written in C# (.NET) and use server-side Sitecore XP tracking APIs. These examples must run on the Sitecore server (for example, in a controller, pipeline, event handler, or custom service) These APIs cannot be called directly from browser-side JavaScript. To trigger events from browser JavaScript in one of two ways: > > - *JSS apps* - use the [JSS Tracking API](https://doc.sitecore.com/xp/en/developers/hd/22/sitecore-headless-development/en/jss-tracking-api.html) to submit goals, outcomes, campaigns, events, and page views from the client. > > - *Traditional Sitecore MVC sites* - implement a server endpoint (MVC, or Web API, or a handler) that calls the Tracker APIs, and invoke that endpoint from JavaScript (for example, using `fetch`). ## Capturing custom event data To capture custom data, you must trigger your event using one of the following methods: - `Sitecore.Analytics.Tracker.Current.CurrentPage.Register()` for page events and goals. - `Sitecore.Analytics.Tracker.Current.CurrentPage.RegisterOutcome()` for outcomes. - `Sitecore.Analytics.Tracker.Current.Interaction.RegisterOutcome()` for outcomes at an interaction level (9.0 Update-1 only). If you do not need to capture custom data, you can [trigger your event in the same way that you would trigger a generic event](https://doc.sitecore.com/xp/en/developers/91/sitecore-experience-platform/triggering-built-in-events.html "Triggering built-in events") and skip this section. ### Capturing custom goal and event data Use the `Sitecore.Analytics.Tracker.Current.CurrentPage.Register()` method to trigger goals or page events with custom data. The following table describes the properties of the `Sitecore.Analytics.Model.PageEventData` class that can be used to store custom data. During event conversion, this data can be copied to your custom event. You must decide how to store custom data before it is converted - for example, the `DownloadEvent` expects the `ItemId` property to store the ID of the media item that was downloaded. | Property | Description | | --- | --- | | `ItemId` | The ID of page item where the event occurred, or the media item the event was associated with. | | `Text` | Human readable description of the event - e.g. “Installation guide downloaded” | | `DataKey` | A key that identifies the contents of ‘Data’ - e.g. “campaignid” or “keywords” | | `Data` | Any data collected as part of triggering the event, such as the campaign ID for campaign events or page load time for the ‘Slow Page’ event. | | `CustomValues` | Store any string/object combination.

> [!important]
> This property is never saved to xConnect and should only be used to store data that will be [copied to a custom xConnect event model in the event conversion pipeline](https://doc.sitecore.com/xp/en/developers/91/sitecore-experience-platform/triggering-custom-events.html#UUID-5ce016a2-d5e6-b590-d319-253834f02aa0_N1560769852457). | The following example demonstrates how to trigger a goal with custom data: ```csharp var ev = Sitecore.Analytics.Tracker.MarketingDefinitions.Goals[NewsletterSignupGoal.NewsletterGoalID]; var newsletterId = Guid.NewGuid(); // Fake newsletter ID var pageData = new Sitecore.Analytics.Data.PageEventData(ev.Alias, ev.Id); pageData.Data = newsletterId.ToString(); pageData.Text = "Signed up for newsletter"; pageData.DataKey = "newsletterid"; pageData.CustomValues["NewsletterImageCategory"] = "C"; // Never saved to xConnect, must be converted into a property on a custom model Sitecore.Analytics.Tracker.Current.CurrentPage.Register(pageData); ``` ### Capturing custom outcome data Use the `Sitecore.Analytics.Tracker.Current.CurrentPage.RegisterOutcome()` method to trigger outcomes with custom data. The `Sitecore.Analytics.Data.OutcomeData` object only allows you to save custom data in the `CustomValues` property, which is of type `Dictionary`. `CustomValues` is never saved to xConnect and can only be accessed during session or in the context of the event conversion pipeline. The following example demonstrates how to trigger an outcome with custom data for the current page: ```csharp var ev = Sitecore.Analytics.Tracker.MarketingDefinitions.Outcomes[CarPurchaseOutcome.CarPurchaseOutcomeID]; if (ev != null) { var outcomeData = new Sitecore.Analytics.Data.OutcomeData(ev, "DKK", 100000.00m); outcomeData.CustomValues.Add("Make", "Mazda"); // Never saved to xConnect, must be converted into a property on a custom model outcomeData.CustomValues.Add("Model", "MX-5"); // Never saved to xConnect, must be converted into a property on a custom model Sitecore.Analytics.Tracker.Current.CurrentPage.RegisterOutcome(outcomeData); } ``` > [!note] > From 9.0 Update-1 onwards, you can also trigger an outcome with custom data for the current interaction. ### Options for capturing event data in CustomValues The following table shows how you an store event data in the `CustomValues` dictionary of events in session. > [!important] > The `CustomValues` property is never saved to xConnect. For each custom event model, you must create a conversion pipeline that copies data from `CustomValues` to that model. - Method: Description - Store simple values in `CustomValues`: Store the custom values that you need against a key in the CustomValues dictionary:This is the simplest way to store custom data in session and takes up the least amount of space. ```csharp pageData.CustomValues["NewsletterID"] = "1234"; pageData.CustomValues["NewsletterBannerID"] = "1245"; ``` - Store a simple class in `CustomValues`: Store an instance of a custom class against a key in the CustomValues dictionary: ```csharp [Serializable] // Required public class NewsletterGoalSessionData { public string NewsletterID { get; set; } public string NewsletterBannerID { get; set; } } pageData.CustomValues["NewsletterImageCategory"] = new NewsletterGoalSessionData { NewsletterID = "1234", NewsletterBannerID = "1245" } ``` - Store an entire serialized xConnect event model in `CustomValues`: You can serialize the entire event model (such as `MyCustomGoal`) to JSON and store the serialized object as a custom value, then deserialize the object in the event conversion pipeline and return it. You must use the [xConnect serialization helpers](https://doc.sitecore.com/xp/en/developers/91/sitecore-experience-platform/serialize-xconnect-entities-using-json-net.html) to do this.ImportantYou cannot decorate your custom event class with the `[Serializable]` attribute and store it as a custom value - the tracker will throw a `System.Runtime.Serialization.SerializationException` exception.Pay attention to the size of the serialized event. Storing large amounts of data in session will negatively impact the performance of the session state provider and you may prefer to store simple values in the `CustomValues` dictionary instead. #### The xConnect event CustomValues property The `Sitecore.XConnect.Event` class has a `CustomValues` property of type `Dictionary` for legacy reasons. If you are only storing `string` values in your `PageEventData` or `OutcomeData` custom values, you can technically create a conversion processor that copies custom values from the tracker event to the xConnect event without changing the event type. The tracker does not automatically perform this conversion as it is not possible to guarantee that each dictionary object will be a string. > [!note] > The `CustomValues` property lacks contextual meaning and makes it difficult to analyze data in a third party tool. It is recommended that you create custom types for all events that include custom data and do not rely on the xConnect event `CustomValues`. ## Converting session events into xConnect events You must create a conversion pipeline processor to convert a session event into a custom xConnect event. Each custom event will have its own processor. In each conversion pipeline processor, you will: - Create an instance of your xConnect event - such as `NewsletterGoal`. - Copy any custom data from the session event to the xConnect event - for example, you might copy the value of `pageData.CustomValues["NewsletterImageCategory"]` to a property on the `NewsletterGoal` class named `NewsletterImageCategory`. Exact instructions depend on whether you are converting to an [xConnect event model](https://doc.sitecore.com/xp/en/developers/91/sitecore-experience-platform/convert-a-page-event.html "Convert a page event"), a xConnect [goal model](https://doc.sitecore.com/xp/en/developers/91/sitecore-experience-platform/convert-a-goal.html "Convert a goal"), or an xConnect [outcome model](https://doc.sitecore.com/xp/en/developers/91/sitecore-experience-platform/convert-an-outcome.html "Convert an outcome"). > [!note] > `ItemId`, `Text`, `DataKey`, and `Data` properties are saved to the base `Sitecore.XConnect.Event` class by default. You do not need to clear these properties, even if you are copying the data to another property.