Understanding Sitecore xDB: Geolocation Basics

In Sitecore a user's location plays a key role in contextualizing content. Across the web I'd say geolocation is a well understood concept. But working with Sitecore adds a new dimension to it.

Why Geolocation in Sitecore is Unique and powerful

In Sitecore every visitor to your site - anonymous or identified - is a Contact. All information gathered about a visitor is stored as part of their Contact inside of Sitecore's xDB. This makes geolocation native to Sitecore and a native aspect of all visitors to your website.

Contact vs Interactions

When interacting with a Contact via the Sitecore API in a session you'll find a split between the users Session.Contact and Session.Interaction. The geolocation information is stored under Interaction.

When viewing your visitors through Sitecore's Experience Analytics tools, you see a user's * interactions through their contact. So when I say Contact I'm speaking broadly of both.

Geolocation Data Is Only Resolved Once

When Sitecore detects an untracked user, it creates a Contact for that visitor within xDB. It's only on this initial contact creation that Sitecore will resolves user location via GeoIP lookup. It uses the startTracking pipeline:

<startTracking patch:source="Sitecore.Analytics.Tracking.config">
<processor type="Sitecore.ExperienceExplorer.Business.Pipelines.StartTracking.JourneyPipeline, Sitecore.ExperienceExplorer.Business" patch:source="Sitecore.ExperienceExplorer.config"/>
<processor type="Sitecore.Analytics.Pipelines.StartTracking.RaiseStartTracking, Sitecore.Analytics"/>
<processor type="Sitecore.Analytics.Pipelines.StartTracking.InitializeTracker, Sitecore.Analytics"/>
<processor type="Sitecore.Analytics.Pipelines.StartTracking.TrackerInitialized, Sitecore.Analytics"/>
<processor type="Sitecore.Analytics.Pipelines.StartTracking.UpdateGeoIpData, Sitecore.Analytics"/>

And calls the UpdateGeoIpData class which looks something like this:

namespace Sitecore.Analytics.Pipelines.StartTracking
{
  public class UpdateGeoIpData : StartTrackingProcessor
  {
    public override void Process(StartTrackingArgs args)
    {
      if (Tracker.Current.Session.Interaction == null)
        return;
      Tracker.Current.Session.Interaction.UpdateGeoIpData();
    }
  }
}

This stores the geolocation data into the current session to ultimately reside as part of the users Contact.

The Sitecore Contact Is Always Referenced

Anytime a visitors location is referenced - usually from within the Sitecore Rules Editor - the information is pulled directly user's Contact. It does make subsequent calls to confirm GeoIP on every call. The visitor's Contact acts as a cache for the geolocation data.

Accessing Geolocation Data from xDB

Here is a snippet below where we get the current visit from the tracker and return it's geolocation data.

var tracker = Sitecore.Analytics.Tracker.Current;
var interactionData = tracker.Interaction;

if (interactionData.HasGeoIpData && interactionData.GeoData.Latitude != null)
{
    return interactionData.geoData;
}

Here is a more complete helper (though still quite basic) that validates the status of tracker, then returns the ContactLocation object:

public static ContactLocation GetLocation(){
    if (Tracker.IsActive == false) //In case this method gets called before tracking is initialized
    {
        Tracker.StartTracking();
    }


    var tracker = Tracker.Current;
    var interactionData = tracker.Interaction;


    if (interactionData.HasGeoIpData && interactionData.GeoData.Latitude != null && interactionData.GeoData.Longitude)
    {
        return interactionData.GeoData;
    }


        return null;
}

One Source For Visitor Locations

Because Sitecore already calculates your visitors location, I advocate using that geolocation data stored with the Contact (inside of Interaction instead of spinning up a secondary method to track their location. It's a nice simple centralized, cheap and cheerful approach.

However - if you want visitors to update their location and store it as a part of their Contact, that's a little more complex than I'll get into here. But it can be done. And I'll attempt to cover that next.

Thanks for for reading.