Saturday, 28 February 2015

Sitecore Pipelines - StartTracking

This post documents Sitecore's StartTracking pipeline, and is part of a series providing information on all the pipelines and processors in involved in a Sitecore 8 request. It's not a line by line account, but all the key logic is described.

I'd like the post to develop over time, so if you find any inaccuracies, would like to contribute more information, or have useful links, then please leave a comment. Better still, contact me on Twitter.

All information has been written with reference to Sitecore 8 (rev 141212)


The StartTracking pipeline is initiated from the StartTracking processor of the StartAnalytics pipeline. In general, it's responsible for intitiating any tracking related activity that occurs in response to an HTTP request.



JourneyPipeline

Namespace: Sitecore.ExperienceExplorer.Business.Pipelines.StartTracking
Assembly: Sitecore.ExperienceExplorer.Business
Despite it's name, the JourneyPipeline processor does not invoke a pipeline. It is responsible for ensuring that an appropriate analytics visitor cookie is set when in Experience mode.

The JourneyPipeline processor specifies the following requirements:

  • We must be in "Experience mode",
  • The current Experience Explorer model must not be null.
  • The sc_visitorid query string parameter must be present and its value must be a valid GUID,

If all these criteria are met, then the analytics cookie is reset using the  sc_visitorid GUID.

If the sc_visitorid query string was not present or was invalid, and the Experience Explorer model's JourneyMode property is set to Fixed, then the analytics cookie is reset using a generated GUID.



RaiseStartTracking

Namespace: Sitecore.Analytics.Pipelines.StartTracking
Assembly: Sitecore.Analytics
This processor simply raises the StartTracking event.



InitializeTracker

Namespace: Sitecore.Analytics.Pipelines.StartTracking
Assembly: Sitecore.Analytics
The IntializeTracker processor sets the IntializeTracker pipeline running. An InitializeTrackerArgs object is instantiated and passed to the pipeline. The properties of the args object are set as follows:

  • CanBeRobot is set to true.
  • Session is set to the value of Tracker.Current.Session,
  • IsNewContact is set to the value of Tracker.Current.Session.Contact.IsNew.
  • HttpContext is set to same object passed in from the StartTracking pipeline args object,



TrackerInitialized

Namespace: Sitecore.Analytics.Pipelines.StartTracking
Assembly: Sitecore.Analytics
This processor simply raises the TrackerInitialized event.



UpdateGeoIpData

Namespace: Sitecore.Analytics.Pipelines.StartTracking
Assembly: Sitecore.Analytics

The UpdatGeoIpData processor is responsible for initiating the lookup of Geo IP data, and then applying it to the current Interaction. The processor itself simply calls the UpdateGeoIpData() method on the Tracker.Current.Interaction property (an instance of CurrentVisitContext). If that property is null then the processor performs no actions at all.

The UpdateGeoIpData method first identifies if Geo IP data already exists for the current Interaction by null checking it's VisitData.GeoData property. If that data already exists, then the method simply returns true (it's a boolean method even though the return value isn't being used for anything).

If the current Interaction doesn't yet have any Geo IP data, then the GeoIpManager.GetGeoIpData method is called upon to work its magic. After this, if the Geo IP data has not been resolved (GeoIpResolveState.Resolved) then the method returns false. Otherwise the resolved data is assigned to the current Interaction's GeoData property.

The next step is to update the location data of the current Interaction. First, the method attempts to see if the location data is already cached (the lookup is based on business name and country). If it doesn't already exist, then it's added to the cache,

Finally, the ID of the cached location data is is assigned to the current Interaction.



GeoIpPipeline

Namespace: Sitecore.ExperienceExplorer.Business.Pipelines.StartTracking
Assembly: Sitecore.ExperienceExplorer.Business
Despite its name, the GeoIpPipline processor does not invoke a pipeline. It's responsible for setting Geo IP data while in Experience mode. For the processor to run, the following criteria must be met:

  • We must be in Experience Mode, or the filepath must contain the string
    "/sitecore modules/web/experienceexplorer/".
  • The current Interaction object, and it's IP property must not be null.
  • The context ExperienceExplorerModel object's GeoIp property must not be null

If any of these criteria are not met, then the processor returns with out performing any actions.

The processor first obtains a suitable IP address. It checks GeoIp.Ip. in the Experience Explorer model, and if it's not null then it uses it. 

If GeoIp.Ip was null, then the processor attempts to use the IP address of the current request instead. If that's unavailable, then a dummy IP address is obtained from the ExperienceExplorer.GeoTestingIp configuration setting.

At the end of the GeoIpPipline processor AnalyticsUtil.ReplaceCurrentVisitGeoData method is called.



ProcessQueryStringCampaign

Namespace: Sitecore.Analytics.Pipelines.StartTracking
Assembly: Sitecore.Analytics
The ProcessQueryStringCampaign processor appears to identify a campaign from the query string, and triggers it. The code is more obfuscated than you would normally expect, so it's a little difficult to know for sure what exactly is going on.

The processor first makes Not Null assertions against the following objects:

  • Tracker.Current
  • Tracker.Current.Session
  • Tracker.Current.Session.Interaction
  • Tracker.Current.Session.Interaction.CurrentPage
  • args.HttpContext
  • args.HttpContext.Request

The  processor will not do anything unless the sc_camp query string parameter exists. It attempts to determine if sc_camp is an ID/Short ID, then retrieves and triggers a campaign with that ID from Tracker.DefinitionItems.Campaigns.

Event handers are added to TrackerEvents.OnCurrentPageCancelled to ensure that the following properties are reverted to their current values when the event is raised:

  • Tracker.Current.Session.Interaction.CampaignId 
  • Tracker.Current.Session.Interaction.TrafficType



ProcessQueryStringPageEvent

Namespace: Sitecore.Analytics.Pipelines.StartTracking
Assembly: Sitecore.Analytics
The ProcessQueryStringPageEvent processor identifies a page event from the query string and registers it. The processor first makes Not Null assertions against the following objects:

  • Tracker.Current
  • Tracker.Current.CurrentPage
  • args.HttpContext
  • args.HttpContext.Request

The  processor will not do anything unless the sc_trk query string parameter exists and its value is not null. The query string parameter is parsed and a PageEventData object is produced. It's then passed to the CurrentPage.Register method.



ProcessQueryStringTriggers

Namespace: Sitecore.Analytics.Pipelines.StartTracking
Assembly: Sitecore.Analytics
The ProcessQueryStringTriggers processor is responsible for registering page events based on the presence of particular query string parameters. When the class is instantiated, a dictionary of query string name and event name mappings are built up using the AddTrigger method. These mapping are specified in the processor's configuration. In a vanilla installation, only one such mapping is added - querystring="sc_rss" eventname="RSS".

The Process method first performs Not Null assertions against the following objects:

  • args
  • args.HttpContext
  • args.HttpContext.Request

Then the processor loops through each of the query string keys in the mapping dictionary and checks if the current request URL contains them. For each match, a PageEventData object is instantiated from the query string data and Context.Item GUID, and a page event is registered by passing it to Tracker.Current.CurrentPage.Register.



ProcessItem

Namespace: Sitecore.Analytics.Pipelines.StartTracking
Assembly: Sitecore.Analytics
The ProcessItem processor is responsible for running the ProcessItem pipeline. First, it checks that the following objects are not null:

  • Tracker.Current
  • Tracker.Current.Session
  • Tracker.Current.Session.Interaction
  • Context.Item

If none of these objects are null then the ProcessItem pipeline is run, with its ProcessItemArgs object assembled using Tracker.Current.Session.Interaction and  Context.Item



CampaignPipeline

Namespace: Sitecore.ExperienceExplorer.Business.Pipelines.StartTracking
Assembly: Sitecore.ExperienceExplorer.Business
Despite its name, the CampaignPipline processor does not invoke a pipeline. It is responsible for triggering campaigns set in the Experience Explorer.

For the processor to run the following criteria must be met:

  • We must be in Experience Mode.
  • The page context must not be null.
  • The context Experience Explorer model and its CampaignDtos property must not be null.

The processor loops through every CampaignDto object in the CampaignDtos collection. For each iteration, the following actions occur:

  • If the current Experience Explorer model's JourneyMode is not Fixed or the CampaignDto's IsAssigned property is false, then the method skips to the next iteration. 
  • If the context page item's TrackingField contains only campaign IDs matching that of the CampaignDto, then the campaign is triggered using the context page's TriggerCampaign method, and the method skips to the next iteration.
  • If the CampaignDto's IsSelected property is set to true, then the associated campaign is triggered using the context page's TriggerCampaign method.

After this, the processor calls it SetCurrentCampaign method. I'll be honest. I've given up on this method. I spent a good hour trying to work out what was going on and got nowhere. Please contact me if you can help out.



TagsPipeline

Namespace: Sitecore.ExperienceExplorer.Business.Pipelines.StartTracking
Assembly: Sitecore.ExperienceExplorer.Business
Despite its name, the TagsPipeline processor does not invoke a pipeline. It is part of the experience explorer, and is responsible for ensuring the Tracker.Current.Contact.Tags collection is populated.

The class is fairly simple. Like most Experience Explorer related processors, the first thing it does is check if we're in "Experience Mode" (PageModeHelper.IsExperienceMode). If we aren't, then the processor does not continue. However, if we are, then the AnalyticsUtil.InitializeVisitorTagsByModel method is called.

The InitializeVisitorTagsByModel method requires that:

  • Tracker.Current.Contact must not be null.
  • The context Experience Explorer model object's Dtos collection must not be null.

If these criteria are met, then the processor will take TagName property of each Dto object and add it to the Tags collection of the Tracker.Current.Contact



PageEventPipeline

Namespace: Sitecore.ExperienceExplorer.Business.Pipelines.StartTracking
Assembly: Sitecore.ExperienceExplorer.Business
Despite its name, the PageEventPipeline processor does not invoke a pipeline. It is part of the experience explorer, and is responsible for registering goals/page events within "Experience mode".

PageEventPipeline will not do anything without the following:

  • We must be in Experience mode.
  • Context page must not be null.
  • The context Experience Explorer model and its PageEvents property must not be null.

If these criteria are met, then the processor loops through each EventDto object in model.PageEvents. In each iteration, the processor checks that:

  • The model's JourneyMode property is set to Fixed.
  • The EventDto object's IsAssigned property is set to true

If these criteria are not met and the eventDto object's IsSelected property is set to false, then the processor skips to the next iteration. Otherwise, the page event represented by the eventDto object is registered against the current page (Tracker.Current.CurrentPage.Register),

Note that the code for the PageEventPipeline process is almost identical that of GoalPipeline.



GoalPipeline

Namespace: Sitecore.ExperienceExplorer.Business.Pipelines.StartTracking
Assembly: Sitecore.ExperienceExplorer.Business
Despite its name, the GoalPipeline processor does not invoke a pipeline. It is part of the experience explorer, and is responsible for registering goals/page events within "Experience mode".

GoalPipeline will not do anything without the following:

  • We must be in Experience mode.
  • Context page must not be null.
  • The context Experience Explorer model and its Goals property must not be null.

If these criteria are met, then the processor loops through each EventDto object in model.Goals. In each iteration, the processor checks that:

  • The model's JourneyMode property is set to Fixed.
  • The EventDto object's IsAssigned property is set to true

If these criteria are not met and the eventDto object's IsSelected property is set to false, then processor skips to the next iteration. Otherwise, the goal represented by the eventDto object is registered against the current page (Tracker.Current.CurrentPage.Register),

Note that the code for the GoalPipeline processor is almost identical that of PageEventPipeline.



ReferralPipeline

Namespace: Sitecore.ExperienceExplorer.Business.Pipelines.StartTracking
Assembly: Sitecore.ExperienceExplorer.Business
Despite its name, the ReferralPipeline processor does not invoke a pipeline. It is part of the experience explorer, and is responsible for ensuring that any relevant information about the referring URL is stored against the current Interaction.

For the processor to perform any actions, the following criteria must be met:

  • We must be in "Experience mode".
  • The current Tracker object and it Interaction property must not be null.
  • The context Experience Explorer model and its ReferralDto property must not be null.

If the ReferralDto.Referrer property is null or empty, then the current Interaction object's Referrer, ReferringSite and Keywords properties are all set to empty strings.

On the other hand, if the ReferralDto.Referrer property is not null or empty, then the following actions are performed:

  • The current Interaction's ReferringSite and Referrer properties are set based on the ReferralDto property of the context Experience Explorer model.
  • The ParseReferrer pipeline is run.
  • If the current Interaction object's Keywords property is null, then it is set to an empty string



SetPreventSessionCommitMarkerPipeline

Namespace: Sitecore.ExperienceExplorer.Business.Pipelines.StartTracking
Assembly: Sitecore.ExperienceExplorer.Business
Despite its name, the SetPreventSessionCommitPipeline processor does not invoke a pipeline. It is part of the experience explorer, and is responsible for indicating that the Experience explorer has been accessed during the session, so the analytics data collected should not be committed.

For the processor to perform any actions, the following criteria mus be met:

  • We must be in "Experience mode".
  • The current Tracker object and it Session property must not be null.
  • The ExplorerWasAccessed property of the SettingsHelper class must be false.

If this criteria are met, then the ExplorerWasAccessed property of the SettingsHelper class is set to true.