Umbraco Engage
CMSCloudHeartcoreDXP
13.latest (LTS)
13.latest (LTS)
  • Umbraco Engage Documentation
  • Release Notes
  • Support
  • Installation
    • System Requirements
    • Installation
    • Licensing
    • Verify your Engage installation
  • Upgrading
    • Upgrade Umbraco Engage
    • Version specific Upgrade Notes
    • Migrate from uMarketingSuite
  • Getting Started
    • Getting Started
    • For Marketers and Editors
      • Cockpit
      • Marketing Resources
    • For Developers
      • Infrastructure sizing
      • Load Balancing and CM/CD Environments
      • Content Delivery Network recommendations
      • Cockpit
      • Content Security Policy nonce configuration
      • Troubleshooting installations
  • Marketers and Editors
    • Introduction
      • The Umbraco Engage Section
      • Content Apps
      • The Umbraco Engage Cookie
    • Analytics
      • What is measured by default
      • Client-side Events
      • Types Of Clients
      • Campaigns
      • Device Type
      • Location
      • Referral Traffic
      • Forms
      • Videos
      • Scroll Heatmap
      • Google Analytics vs Umbraco Engage
      • Search Terms
    • A/B Testing
      • What is A/B testing
      • Types of A/B Tests
        • Single-page A/B Test
        • Multiple Pages Test
        • Document Type Test
        • Split URL Test
      • Setting up the A/B Test
      • Previewing an A/B Test
      • Monitor the A/B Test
      • A/B Test Distribution Algorithm
      • Front end Rendering
      • Finish an A/B Test
    • Personalization
      • Creating a Segment
      • Setting up Personalization
      • Cockpit Insights
      • Implicit and Explicit Personalization
        • Setting up the customer journey
        • Personas
        • Implicit Personalization scoring explained
        • Content Scoring
        • Campaign Scoring
        • Referral Scoring
    • Profiling
      • Profile detail
      • External profile data
    • Reporting
    • Settings
      • Goals
      • IP Filtering
      • Configuration
      • Permissions
  • Developers
    • Introduction
      • Dataflow Pipeline
        • Data Collection
        • Data Storage
        • Data Parsing
        • Reporting
      • The Umbraco Engage Cookie
        • Module Permissions
      • Performance
    • Analytics
      • Request tracking
      • Bot detection
      • Capture location data
      • Extending forms
      • Video tracking
      • Scroll Heatmap
      • Client-side events
        • Additional measurements with analytics scripts
        • Bridging Library for Google Analytics
        • Bridging Library for Google Tag Manager
        • Google Analytics Blocker Detection
        • Create your own events
      • Extending Analytics
        • Getting the Correct IP Address
        • Sending data to the GTM Datalayer
    • A/B testing
      • Retrieving A/B test variants in C#
    • Personalization
      • Implement your own segment parameters
      • Retrieve segment information from code
      • Add custom scoring
    • Profiling
      • External Profile Data
    • Reporting
    • Settings
      • Custom goals scoring
      • Configuration
    • Headless
      • Using the Engage API
      • Headless Example
  • Security and Privacy
    • Security and privacy
    • Retention periods of data
    • Anonymization
    • GDPR & EU regulation
      • How to become GDPR compliant using cookiebot
    • How it works
  • Tutorials
    • Overview
    • How to Get Started with Personalization
    • How to Create a Persona
    • Create a Personalized Popup in 5 minutes
    • How to set up an A/B Test
    • Marketing Resources
      • Generic Topbar Template
      • Generic Popup Template
      • Generic Exit Intent Popup Template
Powered by GitBook
On this page

Was this helpful?

Edit on GitHub
Export as PDF
  1. Developers
  2. Personalization

Retrieve segment information from code

Sometimes you need more fine-grained personalization for your website. For this purpose the Umbraco Engage exposes a service called the IAnalyticsStateProvider.

PreviousImplement your own segment parametersNextAdd custom scoring

Last updated 6 months ago

Was this helpful?

This service provides access to all analytics-related information for the current request, and the segment information. When you need to execute custom code specifically tied to the personalization, you can use this service.

To get started you need an instance of anIAnalyticsStateProvider, which can be resolved through Dependency Injection. For example consider the following case, where we use to execute custom code for our content type called "Home":

using System.Web.Mvc;
using Umbraco.Engage.Business.Analytics.State;
using Umbraco.Web.Mvc;

public class HomeController : SurfaceController, IRenderController
{
    private readonly IAnalyticsStateProvider _analyticsStateProvider;
    public HomeController(IAnalyticsStateProvider analyticsStateProvider)
    {
        _analyticsStateProvider = analyticsStateProvider;
    }
    ...
}

Umbraco will automatically resolve the service, without having to write any code. We can now use the service in our request, by calling the .GetState() method to get the current state for the current request. Which in turn exposes the PageView containing the concrete information we are looking for.

The PageView lies at the heart of Umbraco Engage Analytics feature and exposes a lot of interesting information. For now, we will focus on reading all segments for the current pageview. Depending on your configuration, a visitor can fall into multiple segments, as we can see by enumerating overall PageViewSegments.

Consider the following example (continued from above) where the content of content type "Home" was requested. We will now tell Umbraco to execute this custom code whenever the template HomeTemplate is requested:

public ActionResult HomeTemplate()
{
    var analyticsState = _analyticsStateProvider.GetState();
    foreach (var pageviewSegment in analyticsState.Pageview.PageviewSegments)
    {
        if (pageviewSegment.Segment.Name == "MySegment")
        {
            // Execute custom code
        }
    }
    ...
}

We can for example check if the current visitor falls into a segment called "MySegment". Keep in mind that a visitor can fall into any number of segments (zero, one, or all). A segment alone don't anything and can be regarded as purely informational, or as a "Flag" or "Label".

The personalization used by the Umbraco Engage to modify the appearance of a page is called Applied Personalization.

A page request can have only one active Applied Personalization. Based on the current segments (and their sort order), Umbraco Engage picks the first applicable Applied Personalization. This could be a multi-doctype or multi-page personalization (Engage section) or single-page personalization (content).

To inspect the resolved Applied Personalization, we can use the property AppliedPersonalization on the state's PageView:

if (analyticsState.Pageview.AppliedPersonalization != null && analyticsState.Pageview.AppliedPersonalization.Name == "MyAppliedPersonalization")
{
    ...
}

Be aware that no personalization may have been resolved for the current request. Make sure to do a null check before reading the AppliedPersonalization property. The property SegmentId will tell you which active segment was responsible for triggering the Applied Personalization.

A Segment may be used by different Applied personalizations, but only one personalization will ever be resolved and displayed.

This implies some different important things:

  1. The Applied Personalization can only trigger on currently active segments (as found on Pageview.PageviewSegments)

  2. Not having any active segments automatically means there will never be any Applied Personalizations active. So configuring correct segments is essential.

  3. Having a maximum of one active Applied Personalization per request means that you might find an unexpected personalization was activated. Always make sure to check the segment sorting order.

When testing it is a good idea to inspect the Cockpit information in your front end requests so you can see which segments are active.

route hijacking