Personalization and tracking

This article describes how you can leverage the Layout service for personalizing content in your custom headless app. For more infromation, see Layout service API.

PREREQUISITES: Before using personalization via the Layout service, you must have the following:

• A running headless app in a client-side framework, such as Angular, React, View, etc.
• A configured web service in Sitefinity CMS – for example, Default service under /api/default route

The Layout service is commonly used in scenarios for building headless applications, by leveraging the capabilities of Sitefinity .NET Core Renderer and its New page editor. The editor provides the hierarchical structure of the widgets inside the page and the templates that the page is based on. 
For more information, see .NET Core Renderer.

Likewise, you can use the Layout service to integrate personalization capabilities in an existing headless app. The app can consume the Layout service and use part of the output to enable personalization.

The Layout service provides:

• Page personalization
  For MVC and .NET Core pages
• Widget personalization
  For .NET Core pages only

This article uses the following example. You want to personalize a page according to an URL that your site visitors have visited. For this purpose, you create a personalization segment, defined by one characteristic – Query parameter of visited URL. You set the query parameter to utm_campaign and its value to social_media. You want to create two different page layouts, depending on which users visit that page. 

To demonstrate the page personalization, perform the following:

1. Create a segment and name it Potential clients.
2. Add the Query parameter of visited URL characteristic to the segment.
3. Set the query parameter to utm_campaign and its value to social_media
   For more information, see Segment your audience.
4. Create a page, name it Home, and add the Content block widget.
5. In the Content block widget, enter Default content
6. Personalize the page for the Potential clients segment.
   For more information, see Personalize pages.
7. Add the Content block widget in the personalized page. 
8. In the Content block widget, enter Content for potential clients
9. Request the page.

You request the page not through its exact URL, but by doing an AJAX service call to the Layout Service. 
Such a request must be client-based, because all the required information, such as IP address, referrer, and query parameter, is sent alongside this request. This way, the personalization feature kicks in and delivers the personalized page segment that matches the sent information. 

To request the page, use a plain AJAX GET request in the following way:

GET {sitefinity-url}/api/default/Default.Layout(url=@param)?@param=’home’

In this example, you call the Layout service under the Default web service - api/default, and pass to the service the URL of the home page - home. 

NOTE: The URL must be URL encoded, because it can contain query parameters – for example, an encoded URL can be ‘home%3Futm_campaign%3Dsocial_media’

Sample response 

The above request will receive the following response:

This is the non-personalized version of the page.
Under “ComponentContext”/”Components”/”Properties”, the value of the Content property is Default Content. 

To request the page with the personalized segment, execute the following GET request:

GET {sitefinity-url}/api/default/Default.Layout(url=@param)?@param='home%3Futm_campaign%3Dsocial_media' 

This request uses the encoded URL that contains the query parameters for the personalized version of the Home page – 'home%3Futm_campaign%3Dsocial_media'

Sample response 

The above request will receive the following response:

This is the personalized version of the page.

Under “ComponentContext”/”Components”/”Properties”, the value of the Content property is Potential clients content.

In addition to providing personalized page content, the Layout service returns the resources that you must include in a page to implement the following:

• Page visits tracking
• Tracking consent management
• Sitefinity Insight integration

These resources are returned alongside the main response for the requested page through the Layout service in a special property called “Scripts”. In the above sample responses, you can see the Scripts property that is returned together with the page.

The following is an example of the Scripts property:

Each of these scripts include either a script that references a URL or a script that can hold data. 

For example, when the tracking consent feature is enabled in Sitefinity CMS, it returns a script that points to a specific URL, which holds the logic for displaying a dialog and an HTML file for configuring the visual part of that dialog.

In HTML based headless apps, you can render this property with <script> tags on the page – each pointing to a specific resource with a specific purpose.

All of the scripts must manifest into a <script> tag with specific attributes. These attributes include Id, Type, and Async. The consuming client application must render these into valid <script> tags on the frontend. 

Following is an example of how to render the scripts before the closing <body> tag: