Sitecore Universal Tracker

In the recent releases, Sitecore has been moving from a Monolith software approach to a Micro-service based one. We have already seen this in other modules like Sitecore Javascript Services(JSS) and Sitecore Cortex. Universal Tracker is a headless API Micro-service to track data from mobile apps, IoT, AR, VR and other emerging channels into Sitecore xDB.

 

Universal Tracker is a collection of services to that allows capturing of data across multiple channels as the interactions are happening.

 

You might be asking yourself, isn’t that xConnect? No, Its not. xConnect only accepts immutable history and it designed for trusted service communication – Authentication only, no authorization. Universal Tracker is needed to not expose xConnect. Hence, the universal tracker would allow capturing of data from multiple channels like Sitecore Websites, Non – Sitecore Websites, Mobile Devices, IoT devices etc. The key difference between xConnect and Universal Tracker is that where xConnect collects the information regarding completed interactions, Universal Tracker collects information as soon as the interactions occur and submit those to xConnect when complete.

 

Architecture

There are 3 major parts of Sitecore Universal Tracker.

  1. Collection Service – A.Net Core Web API service and as the name suggests, it is responsible for collection of interactions/events from various channels and storing them temporarily in SQL.
  2. Processing Service – A .Net Core Web API service processes the interactions captured by Collection service and send the processed interactions to Sitecore xConnect. The interactions are processed by channels and custom filters can be defined for each channel.
  3. Interaction Cache – A component that consist for database schemas for MS SQL and Azure databases where the interactions are stored temporarily before being handed over to xConnect.

 

 

There are 3 Pipelines that can be used to manipulate the interactions data.

  • Pre-filter – To filter out interactions, aggregate multiple interactions etc.
  • Enrichment – To manipulate the interactions, add extra information if required.
  • Post-filter – To process the final data before it is sent to xConnect.

 

OOTB all these pipelines are empty.

Scaling

The Universal Tracker is built to scale. All the components along with the Universal Tracker itself can be scaling to suit the needs of an environment. There can be multiple collection services if there are numerous channels. The processing service can be scaled if the data being captures is large compared to the data being sent to xConnect.

Scaling Collection Service

A scenario that has numerous interactions but low processing.

Scaling Processing Service

A scenario where the number of interactions is less but the data is processed heavily before being sent to xConnect.

Scaling Universal Tracker

Total scaling to have multiple instances of Universal tracker.

Implementation

After setting up the Sitecore Universal Tracker by following the guide on https://dev.sitecore.net/Downloads/Sitecore_Universal_Tracker/1x/Sitecore_Universal_Tracker_100.aspx, there should be two new services; one for Processing and one for Collection along with a new database in SQL server.

Processing Service

The status page of processing service displays connections for both SQL Server and xConnect Client as the processing server interacts with both services.

Collection Service

The status page of collection displays only connection to SQL server as it does not directly communicate with the xConnect client.

 

Before starting, we need to check a few things.

  1. The channel to be used is registered with Universal Tracker

In Universal Tracker, only Web, Offline and Mobile channels are registered. If you are using any other channel, it needs to be registered with Universal Tracker in the following configuration. \Sitecore.Tracking.Processing.Service\sitecore\Sitecore.Tracking.Processing.ChannelManagement\PipelinesConfig\channelTypes.json

 

  1. Anonymous contacts are being indexed by xConnect.

If you want to index anonymous contacts visiting the website, we need to enable IndexAnonymousContactData setting in the following configs.

xconnectpath\root\App_data\jobs\continuous\IndexWorker\App_data\Config\Sitecore\SearchIndexer\sc.Xdb.Collection.IndexerSettings.xml

xconnectpath\root\App_data\Config\Sitecore\SearchIndexer\sc.Xdb.Collection.IndexerSettings.xml

  1. Disabling WebVisitFilter

Since the interactions captured by Universal Tracker are not Page Views or Web visits, these interactions are filtered out by the WebVisit Interaction Filter. In order to disable this filter, go to the following config.

sitecorewebpath\App_Config\Sitecore\ExperienceAnalytics\Sitecore.ExperienceAnalytics.Aggregation.config

and comment out the following line.

<InteractionFilter type="Sitecore.ExperienceAnalytics.Aggregation.Filters.WebVisitFilter, Sitecore.ExperienceAnalytics.Aggregation" />

Submitting Interactions

Interactions in Universal Tracker can be submitted either by using the Sitecore provided SDK or Postman.

Sitecore SDK

Here are the steps to send an Interaction to Universal Tracker using Sitecore SDK.

      1. Create a project in Visual Studio. This can be a desktop application, console application or any other.
      2. Install Sitecore Mobile SDK for Universal Tracker for the project using Nuget Package Manager.
      3. Add the following code to the Main function of the Application.

private static void Main(string[] args)

string instanceUrl = "http://sitecore.tracking.collection.service";

string channelId = "27b4e611-a73d-4a95-b20a-811d295bdf65";

string definitionId = "01f8ffbf-d662-4a87-beee-413307055c48";

var defaultInteraction = UTEntitiesBuilder.Interaction()

.ChannelId(channelId)

.Initiator(InteractionInitiator.Contact)

.Contact("jsdemo", "demo")

.Build();

using (var session = SitecoreUTSessionBuilder.SessionWithHost(instanceUrl)

.DefaultInteraction(defaultInteraction)

.BuildSession())

{

var eventRequest = UTRequestBuilder.EventWithDefinitionId(definitionId)

.Timestamp(DateTime.Now).Build();

var eventResponse = await session.TrackEventAsync(eventRequest);

Console.WriteLine("Track EVENT RESULT: " + eventResponse.StatusCode);

}

instanceUrl - Url of the UAT collection service.

channelId - Guid of the channel used. This needs to be registered with Universal Tracker.

definationId - Guid of the event to be triggered (Goal, Outcome etc.)

 

    1. The following references need to be added for the code to work properly.

using System;

using System.IO;

using System.Threading.Tasks;

using Sitecore.UniversalTrackerClient.Entities;

using Sitecore.UniversalTrackerClient.Request.RequestBuilder;

using Sitecore.UniversalTrackerClient.Session.SessionBuilder;

  1. If everything is setup correctly, you should be able to see the following output

 

More information regarding the Universal Tracker SDK can be found at https://doc.sitecore.com/developers/91/sitecore-experience-platform/en/universal-tracker.html

 

Postman

You can start submitting interactions to Universal Tracker directly from Postman without writing a line of code.

Here are the available endpoints that can be used to submit or edit Interactions to Universal Tracker.

    1. Initiating Interaction

Endpoint: CollectionServiceUrl/interaction

Request Type: PUT

Request Body:

{

                “Initiator”:””,                                         //brand or contact

                “ChannelId”:””,                                     //channel id to be used

                “UserAgent”:””,                                     //user agent info

                “Contact”: {

                                “Source”:””,                           //contact reference source

                                “Identifier”:””                        //contact reference identifier

//If the contact with specified source and identifier is not found, a new contact will be created for same.

},

                “Events”:{

                                “type”:””,                               //type of event; goal, outcome etc.

                                “definitionId”:””,   //guid of the event type

                                “Timestamp”:””                     //timestamp when the goal was triggered.

}

}

Response Code: 201

Response Content:

Tracking Interaction Id                                       //this interaction id is used for subsequent additions

and submitting the interaction

               

    1. Adding Events to existing Interaction

Endpoint: CollectionServiceUrl/event

Request Type: PUT

Request Body:

[

                      {

                                “type”:””,                                               //type of event; goal, outcome etc.

                                “definitionId”:””,                   //guid of the event type

                                “Timestamp”:””,                                    //timestamp when the goal was triggered.

                                “TrackingInteractionId”:””                 //tracking interaction id of the existing

interaction.

                      },

                      {

                                “type”:””,                                               //type of event; goal, outcome etc.

                                “definitionId”:””,                   //guid of the event type

                                “Timestamp”:””,                                    //timestamp when the goal was triggered.

                                “TrackingInteractionId”:””                 //interaction id of the existing interaction.

                      }

]

 

Response Code: 201

Response Content:

Empty                                                                                     //An error would appear if the tracking

interaction id is not valid or the interaction

with the tracking id is not found.

               

    1. Closing Interactions

Endpoint: CollectionServiceUrl/interaction/complete

Request Type: POST

Request Body:

{

                TrackingInteractionId

}

Response Code: 202

Response Content:

true                                                                                         //An error would appear if the tracking

interaction id is not valid or the interaction

with the tracking id is not found.

 

The interactions are not processed in real time by we can modify some settings in Sitecore.Tracking.Processing.Service\sitecore\Sitecore.Tracking.Processing.Engine\Config\config.xml to make it more efficient.

 

Experience Profile

You should be able to see the Interaction along with the events submitted from Postman on the experience profile of the recently created contact.

Leave a Reply

Your email address will not be published. Required fields are marked *