Insights

Understanding Sitecore xDB: Geolocation Basics

Let's Make Contact

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.

Meet Dan Cruickshank

President

Dan is the founder of Fishtank. He's a multi-time Sitecore MVP and Coveo MVP award winner. Outside of technology, he is widely considered to be a top 3 father (routinely receiving "Father of the Year" accolades from his family) and past his prime on the basketball court.

Connect with Dan