Topics

All topics

Development

Create segment characteristics

This article contains
NEW TO SITEFINITY?

Once you create a segment, you define one or more characteristics that contain the conditions, upon which Sitefinity CMS serves personalized content to the segment. Such conditions may be IP address, Location, Landing URL, and so on. Sitefinity API supports programmatic creation of the following characteristics by:

  • User role
  • IP address
  • Location
  • Landing URL
  • Query string
  • Referral URL
  • Visited page URL
  • Time of day
  • Visit duration

Segment characteristics are represented programmatically as objects of type Criterion (Telerik.Sitefinity.Personalization.Impl.Model.Criterion). To create a Criterion, you need to instantiate a new object of type Criterion and set its properties:

  • CriterionName – the predefined name of the Criterion (for example, IP Address, Location, Roles). This property represents the label of the characteristic type, as displayed in the UI.

    IMPORTANT: Make sure you use the property names provided in the code samples in this section.

  • CriterionTitle – has the same value as the CriterionName property. Sitefinity persists the value of the CriterionTitle property in the database.

    IMPORTANT: Make sure you use the property names provided in the code samples in this section.

  •  CriterionValue – represents the business logic of the characteristic condition. You need to serialize the property value, so make sure you follow the convention demonstrated in the samples from this section.
  • CriterionDisplayValue – represents the value of the characteristic, as displayed in the UI under CriterionName so you know what condition you set for this characteristic.
  • IsNegated – a Boolean property that controls the way the criterion value is interpreted by Sitefinity: [Characteristic] is / is not [Value]. In most scenarios, you set this value to false.
CriterionProps

The following samples give more details how to use the properties, listed above:

Create criterion by user role:

To create a criterion by user role you pass the role Id and Name and set the CriterionValue in the proper format:

using System;
using Telerik.Sitefinity.Personalization.Impl.Model;
using Telerik.Sitefinity.Security;
namespace SitefinityWebApp.Documentation.Samples.Personalization
{
public class PersonalizationApi_Roles
{
/// <summary>
/// Creates a criterion for roles
/// </summary>
/// <param name="roleName">The name of the role</param>
/// <param name="isNegated">Whether the criterion is negated.</param>
/// <returns>Criterion instance</returns>
public Criterion CreateRoleCriterion(string roleName, bool isNegated = false)
{
var roleId = GetRoleId(roleName);
string criterionValue = "{\"SelectedRoles\":[{\"Id\":\"" + roleId + "\",\"Title\":\"" + roleName + "\"}]}";
Criterion criterion = new Criterion()
{
CriterionName = "Roles",
CriterionValue = criterionValue,
CriterionDisplayValue = roleName,
CriterionTitle = "Roles",
IsNegated = isNegated
};
return criterion;
}
/// <summary>
/// Get the role Guid
/// </summary>
/// <param name="roleName">Name of the role</param>
/// <returns>The role Guid</returns>
public Guid GetRoleId(string roleName)
{
RoleManager manager = RoleManager.GetManager("AppRoles");
var role = manager.GetRole(roleName);
return role.Id;
}
}
}
view raw PersonalizationApi_Roles.cs hosted with ❤ by GitHub

Create criterion by IP Address

Creating a criterion by IP address is as simple as passing the IP address as string and setting the address to the CriterionValue property in the proper format:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using Telerik.Sitefinity.Personalization.Impl.Model;
namespace SitefinityWebApp.Documentation.Samples.Personalization
{
public class PersonalizationApi_IP_Address
{
/// <summary>
/// Creates a criterion for IP address.
/// </summary>
/// <param name="ipAddress">The IP address.</param>
/// <param name="isNegated">Whether the criterion is negated.</param>
/// <returns>Criterion instance</returns>
public Criterion CreateIpAddressCriterion(string ipAddress, bool isNegated = false)
{
string criterionValue = String.Format("\"{0}\"".Arrange(ipAddress));
Criterion criterion = new Criterion()
{
CriterionName = "IPAddress",
CriterionValue = criterionValue,
CriterionDisplayValue = ipAddress,
CriterionTitle = "IP address",
IsNegated = isNegated
};
return criterion;
}
}
}
view raw PersonalizationApi_IP_Address.cs hosted with ❤ by GitHub

Create criterion by Landing URL or Querystring:

Creating criteria by Landing URL or Querystring introduce an added functionality of using a criterion operator. Since these criteria allow you to specify a desired value and a second value to compare to, you also need to choose which operator to use for the comparison of the two. Thus, you can set conditions, such as “this characteristic is valid for visitors that land on an URL that contains/equals/starts with etc. the following value” The supported criterion operators are:

  • "=" - equal to
  • "!" - not equal to
  • "contains" - contains
  • "!contains" - does not contain
  • "startswith" - starts with
  • "!startswith" - doesn't start with
  • "endswith" - ends with
  • "!endswith" - does not end with

The following example demonstrates how to create a Landing URL and use the criterion operators, listed above:

using Telerik.Sitefinity.Personalization.Impl.Model;
namespace SitefinityWebApp.Documentation.Samples.Personalization
{
public class PersonalizationApi_LandingURL
{
/// <summary>
/// Creates a criterion for Landing URL.
/// </summary>
/// <param name="landingUrl">The landing URL. Examples: "http://www.wikipedia.com/" or "/about-us"</param>
/// <param name="criterionOperator">Criterion operator. It can be:
/// "=" - equal to
/// "!" - not equal to
/// "contains" - contains
/// "!contains" - does not contain
/// "startswith" - starts with
/// "!startswith" - doesn't start with
/// "endswith" - ends with
/// "!endswith" - does not end with
/// </param>
/// <returns>A new criterion instance.</returns>
///
public Criterion CreateLandingUrlCriterion(string landingUrl, string criterionOperator)
{
string value = string.Format("{{\"LandingUrl\":\"{0}\",\"ComparisonRule\":\"{1}\"}}", landingUrl, criterionOperator);
Criterion criterion = new Criterion()
{
CriterionName = "LandingURL",
CriterionValue = value,
CriterionDisplayValue = landingUrl,
CriterionTitle = "Landing URL",
IsNegated = false
};
return criterion;
}
}
}
view raw PersonalizationApi_LandingURL.cs hosted with ❤ by GitHub

The similar logic applies when creating a criterion by QueryString:

using Telerik.Sitefinity.Personalization.Impl.Model;
namespace SitefinityWebApp.Documentation.Samples.Personalization
{
public class PersonalizationApi_QueryString
{
/// <summary>
/// Creates a criterion for Query parameter of visited URL
/// </summary>
/// <param name="queryStringName">Query string name.</param>
/// <param name="queryStringValue">Query string value.</param>
/// <param name="criterionOperator">Criterion comparison operator.</param>
/// <returns>A new criterion instance.</returns>
public Criterion CreateQueryStringCriterion(string queryStringName, string queryStringValue, string criterionOperator)
{
string value = string.Format("{{\"QueryStringName\":\"{0}\",\"QueryStringValue\":\"{1}\",\"ComparisonRule\":\"{2}\"}}", queryStringName, queryStringValue, criterionOperator);
string displayValue = queryStringName + " " + criterionOperator + " " + queryStringValue;
Criterion criterion = new Criterion()
{
CriterionDisplayValue = displayValue,
CriterionName = "QueryString",
CriterionValue = value,
CriterionTitle = "Query parameter of visited URL",
IsNegated = false
};
return criterion;
}
}
}
view raw PersonalizationApi_QueryString.cs hosted with ❤ by GitHub

Create criterion by Location:
using System;
using Telerik.Sitefinity.Personalization.Impl.Model;
namespace SitefinityWebApp.Documentation.Samples.Personalization
{
public class PersonalizationApi_Location
{
/// <summary>
/// Creates a criterion for Location.
/// </summary>
/// <param name="location">The location. Examples: "Bulgaria", "Germany".</param>
/// <param name="isNegated">Whether the criterion is negated.</param>
/// <returns>A new criterion instance.</returns>
public Criterion CreateLocationCriterion(string location, bool isNegated = false)
{
string criterionValue = "[{{\"Location\":\"{0}\",\"Index\":0}}]".Arrange(location);
Criterion criterion = new Criterion()
{
CriterionName = "Location",
CriterionValue = criterionValue,
CriterionDisplayValue = location,
CriterionTitle = "Location",
IsNegated = isNegated
};
return criterion;
}
}
}
view raw PersonalizationApi_Location.cs hosted with ❤ by GitHub

Create criterion by Time of day:

To create a Time of day criterion, you need to pass two different DateTime values when building the CriterionValue – one for the start time and one for end time of the specified timeframe of the visit. For example, the criterion applies to visitors that browse the website between 9am and 5pm:

using System;
using Telerik.Sitefinity.Personalization.Impl.Model;
namespace SitefinityWebApp.Documentation.Samples.Personalization
{
public class PersonalizationApi_TimeOfDay
{
/// <summary>
/// Creates a criterion for Time of day.
/// </summary>
/// <param name="startTime">The start time. Date is ignored.</param>
/// <param name="endTime">The end time. Date is ignored.</param>
/// <param name="isNegated">Whether the criterion is negated.</param>
/// <returns>A new criterion instance.</returns>
public Criterion CreateTimeOfDayCriterion(DateTime startTime, DateTime endTime, bool isNegated = false)
{
//// "\"{\\\"From\\\":\\\"9:00 AM\\\",\\\"To\\\":\\\"5:00 PM\\\"}\""
string criterionValue = @"""{{\""From\"":\""{0:h:mm tt}\"",\""To\"":\""{1:h:mm tt}\""}}""".Arrange(startTime, endTime);
Criterion criterion = new Criterion()
{
CriterionName = "TimeOfDay",
CriterionValue = criterionValue,
CriterionDisplayValue = "From {0:h:mm tt} To {1:h:mm tt}".Arrange(startTime, endTime),
CriterionTitle = "Time of day",
IsNegated = isNegated
};
return criterion;
}
}
}
view raw PersonalizationApi_TimeOfDay.cs hosted with ❤ by GitHub

Create criterion by page visit duration

Similar to the Time of day criterion, when working with Page visit duration criterion, you need to pass two values to specify min and max duration. You also specify the time unit.

using System;
using Telerik.Sitefinity.Personalization.Impl.Model;
namespace SitefinityWebApp.Documentation.Samples.Personalization
{
public class PersonalizationApi_VisitDuration
{
/// <summary>
/// Creates a criterion for Visit Duration.
/// </summary>
/// <param name="minDuration">Minimum visit duration during the period.</param>
/// <param name="maxDuration">Maximum visit duration during the period.</param>
/// <param name="timeUnit">Time unit. Use the constants.</param>
/// <param name="period">The period of the visit. Use the constants.</param>
/// <param name="isNegated">Whether the criterion is negated.</param>
/// <returns>A new criterion instance.</returns>
public Criterion CreateVisitDurationPageCriterion(int minDuration, int maxDuration, string timeUnit, string period, bool isNegated = false)
{
//// "{\"From\":\"5\",\"To\":\"999\",\"TimeUnit\":\"seconds\",\"Period\":\"lastweek\"}"
string criterionValue = "\"{{\\\"From\\\":\\\"{0}\\\",\\\"To\\\":\\\"{1}\\\",\\\"TimeUnit\\\":\\\"{2}\\\",\\\"Period\\\":\\\"{3}\\\"}}\""
.Arrange(minDuration, maxDuration, timeUnit, period);
string criterionDisplayValue = "From {0} To {1} {2}".Arrange(minDuration, maxDuration, timeUnit);
Criterion criterion = new Criterion()
{
CriterionName = "VisitDuration",
CriterionValue = criterionValue,
CriterionDisplayValue = criterionDisplayValue,
CriterionTitle = "Visit duration",
IsNegated = isNegated
};
return criterion;
}
}
}
view raw PersonalizationApi_VisitDuration.cs hosted with ❤ by GitHub

NOTE: Supported values for time unit are “seconds” or “minutes”.

Create criterion by visited page URL
using System;
using Telerik.Sitefinity.Personalization.Impl.Model;
namespace SitefinityWebApp.Documentation.Samples.Personalization
{
public class PersonalizationApi_VisitedURL
{
/// <summary>
/// Creates a criterion for Visited page.
/// </summary>
/// <param name="url">The URL of the visited page. For example: "http://localhost:8800/about-us".</param>
/// <param name="isNegated">Whether the criterion is negated.</param>
/// <returns>A new criterion instance.</returns>
public Criterion CreateVisitedPageCriterion(string url, bool isNegated = false)
{
//// {"Url":"http://localhost:8800/about-us","Mode":"Url"}
string criterionValue = "{{\"Url\":\"{0}\",\"Mode\":\"Url\"}}".Arrange(url);
Criterion criterion = new Criterion()
{
CriterionName = "VisitedPage",
CriterionValue = criterionValue,
CriterionDisplayValue = url,
CriterionTitle = "Visited page",
IsNegated = isNegated
};
return criterion;
}
}
}
view raw PersonalizationApi_VisitedURL.cs hosted with ❤ by GitHub

Want to learn more?

Increase your Sitefinity skills by signing up for our free trainings. Get Sitefinity-certified at Progress Education Community to boost your credentials.

Get started with Integration Hub | Sitefinity Cloud | Sitefinity SaaS

This free lesson teaches administrators, marketers, and other business professionals how to use the Integration hub service to create automated workflows between Sitefinity and other business systems.

Web Security for Sitefinity Administrators

This free lesson teaches administrators the basics about protecting yor Sitefinity instance and its sites from external threats. Configure HTTPS, SSL, allow lists for trusted sites, and cookie security, among others.

Foundations of Sitefinity ASP.NET Core Development

The free on-demand video course teaches developers how to use Sitefinity .NET Core and leverage its decoupled architecture and new way of coding against the platform.

Was this article helpful?

Next article

Associate characteristics to segments