Triggering built-in events

This topic describes how to trigger standard events Goal and Outcome from the tracker. You can also trigger events with custom types.

Trigger a goal

Use the Sitecore.Analytics.Tracker.Current.CurrentPage.RegisterGoal() method to register a goal against the current page. This method requires a goal definition item. The following example uses the goal ID to retrieve the definition item from Sitecore.Analytics.Tracker.MarketingDefinitions.Goals.

var goalId = Guid.NewGuid(); // ID of goal
var goalDefinition = Sitecore.Analytics.Tracker.MarketingDefinitions.Goals[goalId];

Sitecore.Analytics.Tracker.Current.CurrentPage.RegisterGoal(goalDefinition);

On session end, goals are converted into a Sitecore.XConnect.Goal objects.

Trigger an outcome

You can trigger an outcome against the entire interaction or against a specific page. Outcomes are converted into Sitecore.XConnect.Outcome objects on session end.

Trigger an outcome for the interaction

Use the Tracker.Current.Interaction.RegisterOutcome() method to register an outcome against the current interaction. This method requires an outcome definition item. The following example uses the outcome ID to retrieve the definition item from Sitecore.Analytics.Tracker.MarketingDefinitions.Outcomes.

var outcomeDefinitionId = Guid.NewGuid(); // Replace with outcome definition ID

var outcomeData = new OutcomeData(Tracker.MarketingDefinitions.Outcomes[outcomeDefinitionId], "DKK", 300.5m);
Tracker.Current.Interaction.RegisterOutcome(outcomeData);

Trigger an outcome for a particular page

Use the Sitecore.Analytics.Tracker.Current.CurrentPage.RegisterOutcome() method to register an outcome against the current page. This method requires an outcome definition item. The following example uses the outcome ID to retrieve the definition item from Sitecore.Analytics.Tracker.MarketingDefinitions.Outcomes.

var outcomeDefinitionId = Guid.NewGuid(); // Replace with outcome definition ID

Tracker.Current.CurrentPage.RegisterOutcome(Tracker.MarketingDefinitions.Outcomes[outcomeDefinitionId], "DKK", 300.5m);

Trigger an outcome without a monetary value

You can trigger an outcome with a monetary value of 0.0m as shown. However, the currencyCode parameter cannot be null or empty.

var outcomeDefinitionId = Guid.NewGuid(); // Replace with outcome definition ID

var outcomeData = new OutcomeData(Tracker.MarketingDefinitions.Outcomes[outcomeDefinitionId], "USD", 0.0m);
Tracker.Current.CurrentPage.RegisterOutcome(outcomeData);

Trigger a campaign event

Use the Sitecore.Analytics.Tracker.Current.CurrentPage.TriggerCampaign() method to register a campaign event against the current page. This method requires a campaign definition item. The following example uses the campaign ID to retrieve the definition item from Sitecore.Analytics.Tracker.MarketingDefinitions.Campaigns:

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

var definition = Sitecore.Analytics.Tracker.MarketingDefinitions.Campaigns[campaignDefinitionId];

Sitecore.Analytics.Tracker.Current.CurrentPage.TriggerCampaign(definition);

Campaigns are converted into Sitecore.XConnect.Collection.Model.CampaignEvent objects on session end. The campaign definition ID is represented by the CampaignDefinitionId property.

Trigger a page event

Use the RegisterPageEvent() method to register a page event against the current page. This method requires page event definition item. The following example uses the page event ID to retrieve the definition item from Sitecore.Analytics.Tracker.MarketingDefinitions.PageEvents:

var pageEventId = Guid.NewGuid(); // ID of goal
var pageEventDefinition = Sitecore.Analytics.Tracker.MarketingDefinitions.PageEvents[pageEventId];

Sitecore.Analytics.Tracker.Current.CurrentPage.RegisterPageEvent(pageEventDefinition);

Tip

You can find common page event IDs under Sitecore.Analytics.AnalyticsIds - for example, Sitecore.Analytics.AnalyticsIds.FollowHitEvent. Page events are defined under sitecore//system//Settings//Analytics//Page Events in the Sitecore tree.

Trigger search event

Search events are specialized page events and require custom data. Use the Sitecore.Analytics.Tracker.Current.CurrentPage.Register() method to register a search event against the current page. Set the Data property to the keywords that were used during the search:

var searchEvent = Tracker.MarketingDefinitions.PageEvents[AnalyticsIds.SearchEvent.Guid];

Sitecore.Analytics.Tracker.Current.CurrentPage.Register(new PageEventData(searchEvent.Alias, searchEvent.Id)
{
    Data = "sitecore experience platform"
});

This event is converted into a Sitecore.XConnect.Collection.Model.SearchEvent object. The Data property is mapped to the Keywords property.

Trigger download event

Download events are specialized page events and require custom data. Use the Sitecore.Analytics.Tracker.Current.CurrentPage.Register() method to register a download event against the current page. Set the ItemId property to the ID of the media item that was downloaded:

var mediaItemId = Guid.NewGuid(); // Replace with real media item ID
var downloadDefinition = Tracker.MarketingDefinitions.PageEvents[AnalyticsIds.DownloadEvent.Guid];

Sitecore.Analytics.Tracker.Current.CurrentPage.Register(new PageEventData(downloadDefinition.Alias, downloadDefinition.Id)
{
    Text = "Sitecore installation guide", // Not mandatory
    ItemId = mediaItemId
});

This event is converted into a Sitecore.XConnect.Collection.Model.DownloadEvent object. The ItemId property is mapped to a matching ItemId, and the optional Text property is mapped to a match Text property.

Event extensions

The following system events can be triggered using specialized extension methods:

  • Sitecore.Analytics.Extensions.CampaignExtensions.TriggerCampaignFailed() (AnalyticsIds.CampaignRegistrationFailedEvent.Guid)
  • Sitecore.Analytics.Extensions.ErrorExtensions.LongWait() (AnalyticsIds.LongRunningRequestEvent.Guid)
  • Sitecore.Analytics.Extensions.ErrorExtensions.RegisterError() (AnalyticsIds.ErrorEvent.Guid)
  • Sitecore.Analytics.Extensions.ErrorExtensions.RegisterPageError() (AnalyticsIds.PageErrorEvent.Guid)
  • Sitecore.Analytics.Extensions.ErrorExtensions.RegisterPageNotFound() (AnalyticsIds.PageNotFoundEvent.Guid)

Trigger an event by its alias

You can trigger an event by its alias. Use only if you do not have access to the event’s definition ID, as this method is less performant.

// Option 1 - pass event alias into PageEventData
Sitecore.Analytics.Tracker.Current.CurrentPage.Register(new PageEventData("Download") // Use only if ID of event is not available
{
    Text = "Sitecore installation guide",
});

// Option 2 - pass event alias into .Register() method; text parameter maps to 'Text' property on PageEventData
Sitecore.Analytics.Tracker.Current.CurrentPage.Register("Download", "Installation guide downloaded");