Using Sitecore FXM to update and track contacts

Sitecore Federated Experience Manager aka FXM is a great feature to utilize some of the Sitecore's CMS, marketing and analytics capabilities on non-Sitecore websites. If you are new to FXM you can read more about how to integrate FXM into your non-Sitecore website and utilize its capabilities on Sitecore's FXM documentation page.

While the well-known uses of FXM are to add placeholders to pages to show Sitecore content, track click action, assign marketing attributes and track goals, the area FXM lacks out of the box is contact tracking and updates. The FXM's scbeacon JavaScript API has following three methods you can use

• trackEvent
• trackGoal
• trackOutcome

You can read more about these methods in the documentation.

As you can see there is no out of the box API method to identify or update contact. In cases where you have a non-authenticated public website on Sitecore but an authenticated member portal on non-Sitecore website it would be really useful to pass the authenticated user information to Sitecore to identify and store the contact information which will be valuable for personalization.

As there is no out of the box API for this we can piggyback on one of the out of the box API methods, overwrite its processor and add our extra logic to identify and save contact. Out of the three methods, trackEvent is best suited for this purpose because, a page event can be excluded from activity in Experience Profile, given this event is not an actual page event we wouldn't want this event to show up in Experience Profile dashboard. If we set the points on the event to zero it won't affect the monitory value of the visit either.

Let's begin with creating a new page event folder called FXM under /sitecore/system/Settings/Analytics/Page Events in master database. Now create a new page event called Update Contact under the FXM folder.

Leave the points value to 0 and make sure to uncheck the Show in XFile and  Show In Events checkboxes under Experience Profile Options section.

The page events goes through Analytics workflow by default. The newly created event won't get published if you try to publish using Publish menu. Go to Review tab in the ribbon and click Deploy to publish the newly created page event.

Now let's overwrite the page event processor to add our custom code to identify and save the contact information. The page event is processed by tracking.triggerpageevent pipeline. We will implement a custom processor that will override the TriggerEventsProcessor class as this is where most of the actual processing is done. 

Please note that this processor and methods have changed from Sitecore 9. If you are using an earlier version of Sitecore the class and method may differ.

We will create a custom TriggerEventsProcessor class that inherits from the out of the box class and override the TriggerPageEvent method. Inside the method body will call the base class's TriggerPageEvent method to make sure the default functionality is not affected. We will then check if the current page event name matches the custom page event name and do our additional work of identifying and saving the contact. Assuming we get UserId, FirstName, LastName, JobTitle and Email from the FXM API call, the below example identifies the contact using UserId and saves the contact information into PersonalInfo facet.

From the above example you can see we are loading the contact and facet info from the database using XConnectClient. If the contact is new we are creating a new Contact and setting the facet info based on the values we received in the extras parameter.

This will save the contact information into xdb which can be used for Personalization or even just to track the identified contact's activity in Experience Profile dashboard. To use our custom TriggerEventsProcessor  class create a config patch to overwrite the pipeline processor

Now to call the page event and pass the contact info from your non-Sitecore website just add the following JavaScript call to your page assuming you already added the SCBeacon tracking script to your site. If not use the following documentation to setup the script on your non-Sitecore website.

In coming days I will write another blog post on how to use the facet info for personalization using a custom personalization rule. Keep an eye out for it.