Category Archives: Experience Profile

Sitecore 8 – Extending Experience Profile – Part 4 – Displaying Specific Interactions Data

How to display specific interaction data

For this example, we would like to have a custom list in the Experience Profile where it listed the triggered page event when the site visitor downloaded a PDF file.

End result:

end-result-downloadedpdffiles-tab

 

How to set this up

Source code link is available at the end of this post.

How to setup a new page event

First we need to create a page event through the content editor, we can do so by going to the /sitecore/system/Settings/Analytics/Page Events

In the below screenshot I’ve created a page event called “Download PDF File”

create-page-event-downloadpdffile

 

How to assign page event to a media item

There’s a tutorial on how to this on Sitecore documentation site

I’m using a page event rather than goal for this POC because this event “download a pdf” doesn’t necessarily lead to a conversion but more about the actions that the site visitors took that we want to be aware of.

In the screenshot below I’ve assigned the pdf files in the media library with my custom page event.

assign-downloadedpdffile-pageevent-to-mediaitem

Now if there’s a site visitors that download the specified files on the website, Sitecore will trigger the page event and store the information in MongoDB which later on we will extract and display it in the Experience Profile.

How to setup the custom tab in Experience Profile

The content tree

downloadedpdffilespanel-contenttree

We define three column to be displayed on the ListControl rendering.

 

The full list of the renderings

downloadedpdffilespanel-layout

The SubPageCode rendering links to a javascript file downloadedpdffiles.js which will be executed when this item is loaded into the tab.

We can control the page size -the amount of records returned by the server-  in the GenericDataProvider properties.

How to register a new processors for the Experience Profile

Jonathan Robbin’s blog post explain it nicely on what this processors is doing.

Schema.cs

 

ConstructDownloadedPdfFilesDataTable.cs

 

PopulateDownloadedPdfFilesWithXdbData.cs

 

Register our custom processors

TC.Sitecore.ExperienceProfile.Reporting.config

notice that the sorting and paging is already built in the framework.

Register our custom result transformer

TC.Sitecore.ExperienceProfile.Client.config

 

Wire things together

As with the previous post, when the DownloadedPdfFilesPanel item is loaded we will trigger an API call to request the data to be displayed in the list control

The javascript file that’s responsible to do this is the downloadedpdffiles.js

The difference here compared to the previous post when triggering the API call is that we specify the /intel/downloadedpdffiles in the url which Sitecore recognize to be a special route. This route will try to run donwnloadedpdffiles pipelines that we define earlier in the config file.

An example of the API response

http://habitat.dev.local/sitecore/api/ao/v1/contacts/02b2e6c4-d38a-4e30-a18e-b4a31b63907d/intel/downloadedpdffiles?&pageSize=3&pageNumber=1

downloadedpdffiles-webapi-call-request

 

Source code

Source code is available in Github

Sitecore 8 – Extending Experience Profile – Part 3 – Displaying Contact Facet Collection Property

How to display contact facet collection property

End result:

end-result-newsletter-tab

How to set this up

Source code link is available at the end of this post.

How to setup the custom contact facet

Similar to what we’ve done in the first post, the only difference here is that we are using collection property instead of simple properties.

 

The  updated TC.Sitecore.Analytics.Model.config file

note that we need to register our INewsletterElement as well in order for Sitecore to know which type to resolve during runtime.

An example of how the data is being stored in MongoDB

newslettersubscriptions-mongodb

 

How to setup the web API controller

The updated InitializeRoutes.cs

 

The updated CustomContactController.cs

 

The main reason why we are returning as a ResultSet object here is that the list control rendering expects the returned data in a specific JSON structure.

While going through this I thought of the performance implications if we have a lot of data where we should ideally implement pagination when querying against MongoDB. For this POC, this works fine as for newsletters typically the users won’t have thousands of records to be displayed .

An example on how to implement pagination will be provided in the next post.

 

How to setup a custom tab in Experience Profile

The content tree

newslettersubscriptionpanel-contenttree

Under the NewsletterSubscriptionPanel item you can that there’s NewsletterSubscriptions which based on ListControl template, under that we have the NewsletterName which is using the ColumnField template.

When we use the list control rendering, we can specify what columns are there in the list control and bind the value with a specific property name returned from the API

newslettername-columnfield

 

The full list of the renderings used

newslettersubscriptionpanel-layout

note that there’s “more” button assigned to the layout, but this didn’t actually being used. That’s for future improvements when we implement pagination.

 

Wire things together

As with the previous post, when the NewsletterSubscriptionPanel item is loaded we will trigger an API call to request the data to be displayed in the list control

The javascript file that’s responsible to do this is the newslettersubscriptions.js

 

An example of the API response

http://habitat.dev.local/sitecore/api/ao/v1/contacts/02b2e6c4-d38a-4e30-a18e-b4a31b63907d/newslettersubscriptions/?&pageNumber=1

newslettersubscriptions-webapi-call-request

note that it has to return the response in a specific JSON structure that the list control can consume.

 

Source code

Source code is available in Github

Sitecore 8 – Extending Experience Profile – Part 2 – Displaying Contact Facet Simple Properties

How to display contact facet simple properties

End result:

end-result

There’s a good reference on how to create a custom tab in Sitecore Experience Profile on Jonathan Robbins blog post,  I recommend you go and read it through.

How to set this up

Source code link is available at the end of this post.

How to setup the custom contact facet

There’s a good reference on Sitecore documentation site on how to do so.

In my custom facet I only have two properties, which is the HospitalName and the ProfessionName.

ICustomFieldsFacet.cs

 

CustomFieldsFacet.cs

 

And the config patch file to register this custom facet

TC.Sitecore.Analytics.Model.config

 

To fillout the data in the custom facet I’ve setup a page to do this

updatecontact-page

 

How to setup the web API controller

First we need to register our custom route to our custom controller

InitializeRoutes.cs

 

In our custom controller, we just return the custom facet that contains all the properties that we want to display in Experience Profile

CustomContactController.cs

 

Finally we add the InitializeRoutes class to the pipeline

TC.Sitecore.ExperienceProfile.config

 

How to setup a custom tab in Experience Profile

I will not go in detail on how I setup the content tree as the reference I’ve provided should give you an idea on how to set it up and I’ll be providing the source code at the end of this post.

This is the content tree in the core database that I’ve setup in order to display those 3 tabs

professionpanel-contenttree

The first tab which is the Profession tab will be displaying the custom field from the custom contact facet that I’ve setup.

The rendering items

 

Wire things together

To display this information, after our Profession tab is loaded in the Experience Profile we would need to call our CustomContactController class to retrieve the data.

The code that’s responsible to do this is the profession.js that is set in the SubPageCode rendering control in the ProfessionPanel layout. This javascript file is executed when the ProfessionPanel item is loaded into the Profession tab

professionpanel-layout-subpagecode

profession.js

 

The script basically calls an API method in the server which then gives back the response in a JSON format which we then assign to the controls defined in the ProfessionPanel item layout.

customfields-webapi-call-request

This is the full url it’s trying to access http://habitat.dev.local/sitecore/api/ao/v1/contacts/02b2e6c4-d38a-4e30-a18e-b4a31b63907d/customfields/

It’s passing the current contact id and a specific url ‘customfields’ which we route to our custom web API controller. It will then use the cintelUtil helper to bind the data to the text controls defined in our ProfessionPanel layout.

 

Source code

Source code is available in Github

Sitecore 8 – Extending Experience Profile – Part 1 – Overview

I will be creating a series of blog posts on a recent POC that I’ve done on how to extend Sitecore 8 Experience Profile

This was done using Sitecore 8.1 update 1 at the time of writing.

There will be several things that this blog posts tries to cover

  1. How to display contact facet simple properties
  2. How to display contact facet collection property to a list control
  3. How to display specific interaction data to a list control

End results

Displaying contact facet simple properties

The below screenshot is an example on how to retrieve simple properties from the contact facet and then display them in our custom tab

end-result

 

Displaying contact facet collection property to a list control

The below screenshot is an example on how to retrieve collection property from the contact facet and then bind it to a list control

end-result-newsletter-tab

 

Displaying specific interaction data to a list control

The below screenshot is an example on how to retrieve specific interaction data, which in this case a Page Event that’s triggered whenever a site visitor downloaded a pdf file.

end-result-downloadedpdffiles-tab

 

Details on how to achieve this will be explained the next posts.

 

Sitecore 8 – how to update contact through FXM API

This post will talk through how to setup a custom actions to be executed to update Sitecore contact through FXM API. If you don’t know about FXM you can read a brief overview about it in the Sitecore site and the doc site

If you’ve played around with FXM and it’s javascript API then you would know that you can trigger client side call to send information back to Sitecore regarding the current visitor browsing behaviour. But what does one do if we want to update the Contact information instead? say the current visitor email address if they fill out a newsletter subscription form? or their unique user id if they have logged in through the external application?

Looking at the available javascript FXM API there’s these three methods available:

  1. SCBeacon.trackEvent
  2. SCBeacon.trackGoal
  3. SCBeacon.trackOutcome

and there’s no such things as SCBeacon.updateContact which we sought after. After some investigation there’s a couple of ways to do this.

1. A custom web service call to the Sitecore server

Setup a custom web service in Sitecore server and pass in the current visitor contact id for custom processing. Doable but I’m looking for something that can be done through the same javascript API if possible as it would mean greater coverage – can be reused by other external site. By doing it through FXM javascript API we don’t have to setup web service call in each external sites.

2. Modify the beacon script to include our custom function 

Modify the beacon script and include the custom SCBeacon.updateContact function. Figured that this won’t be ideal as we would muck around with the bundled javascript and won’t be compatible in Sitecore future upgrades.

3. Hook into one of the available methods to do some custom processing

This seems like the best place to start. Out of the available methods I choose to override the trackEvent tracking implementation because the action that I want to captured falls to “system” type action, doesn’t relate to conversion (Goal) or has monetary value (Outcome). Plus if I use page events then by default the events triggered will not show in the Experience Profile which might confused the marketers.

OK, let’s do this.

This is done with the latest Sitecore version at the time of writing which is 8.1 update 3.

First let’s open the Sitecore.FXM.config in /website/app_config/include/fxm folder

I opened up Sitecore.FXM.Pipelines.Tracking.TriggerPageEvent.RunRegisterPageEventProcessor using dotPeak to find out that it will run the tracking.registerpageevent pipeline

When I take a look at Sitecore.FXM.Pipelines.Tracking.RegisterPageEvent.RegisterPageEventProcessor and what it does it seems this would be the best place to put my custom logic

We can override the TriggerPageEvent method and implement our custom processing.

The next step is for us to create our custom Processor class which extends from Sitecore’s default RegisterPageEventProcessor

After that we need to register our custom processor class in the config file. For best practice use Sitecore config file patching to do.

In our custom config file we override the default processor class to process the triggered page events with our custom processor class. Put the file in /website/app_config/include/zzz.POC/ folder

Now that we have our custom processor class and have registered it through the custom config file, we need to create the actual page event items in Sitecore.

Here’s what the created page event items looks like in my setup.

registered-custom-page-events

And now to test it out, browse to the external site  and open the developer console to run these javascripts

We can check the end result in MongoDB after the session has timeout

updated-contact-through-FXM

And in the Experience Profile

updated-contact-through-FXM-xFile

That’s it folks.