This blogpost introduces segments and describes how segments can be managed using Profile Store API and Insight. Using segments in CMS personalization and in Intelligent Campaign is outlined.
What is segment
A segment is a dynamic collection of visitor profiles that match certain criteria. Defining a segment is defining conditions or filters that profiles should match. Simple segment example: users who came to a website today.
Segments are dynamic
Please note that example segment above is dynamic. Probably it is a different group of users every day. Some users might be the part of this segment yesterday, but today they do not match the segment if they have not visited the website. Returning visitors will still be the part of this segment tomorrow.
Segments are based on profiles
Segments are based on profile data and filters/conditions can be defined for profile properties. Currently (version 1.6.0) it is not possible to define a segment based on tracking events. Visitor statistics should be aggregated and stored in the visitor profile to be used when matching segment rules.
Managing Segments
There are 2 ways to manage segments (and 2 target user groups):
- Using Insight UI (marketers)
- Using Profile Store API (developers)
Most of segment operations are available using both options, however there are some differences described below.
Creating segments
Creating Segments in Insight UI
Marketer can filter profiles by Contact information, Last Seen date and Country facets in Profiles section of Insight UI. Entering a query in the search box performs the search based on visitor name and on profile Info collection that may contains email address, company name etc.
Selected filters in Insight UI can be saved as a segment. Insight suggests proper segment name based on the current set of filters and allows making the new segment available in visitor groups. Current user name is stored in the SegmentManager field.
Creating segments in the Insight is limited by available UI facets. Selected combination of filters is stored as JSON in ProfileFilter segment property.
Please note that in current version 1.6.0 segments created in Insight UI are not tied to specific scope and can be used to slice profiles in all scopes.
Creating Segments in Profile Store API
Segment can be created by POST request to /segments endpoint of Profile Store API. Segment JSON data is passed in the request body.
Note: filter to match profiles is defined in ProfileQuery property (unlike segments created in Insight UI that store filters in the ProfileFilter segment property).
The syntax for ProfileQuery is described in Filtering, paging, and sorting article and in Microsoft Rest API Guidelines.
POST api/v1.0/segments
{
"Name": "Episerver Employees",
"Scope": "default",
"ProfileQuery": "Info.Company eq Episerver",
"AvailableForPersonalization": true
}
Name, Scope and ProfileQuery values are required.
The new created segment data is returned in the 201 Created response body:
{
"SegmentId": "912f2150-82b5-5fa7-88c4-2d42fa700ac8",
"Scope": "default",
"SegmentManager": null,
"ProfileQuery": "Info.Company eq Episerver",
"AvailableForPersonalization": true,
"Archived": false,
"FavoredBy": [],
"Name": "Episerver Employees",
"CreatedDate": "2018-10-12T16:16:25.2186793Z",
"ModifiedDate": "2018-10-12T17:22:11.3000335Z",
"MatchingProfiles": 4
}
Please note that any segment created using Profile Store API is always scoped and can be used to match profiles in the corresponding scope.
The main advantage of creating segment using API is that developer is not limited by available filters in the Insight UI. ProfileQuery is defined in the same way as filter when querying profiles and can include conditions for several properties in the profile data model, including information in the dynamic Payload object.
It enables developers to aggregate values specific to customer business, store it in profile payload and create custom segments based on custom data.
/segments endpoint returns 400 Bad Request or 500 Server Error if provided segment definition is invalid or error happens when creating a segment.
Loading Segment Data
Viewing Segment in Insight UI
Segments are listed in the Segments section of Insight UI. Marketer uses simple filtering to view segments managed by current user, recently created, favorited, archived or all segments.
Clicking on the segment opens segments details and the list of profiles that currently match this segment.
Querying segments in Profile Store API
Developers can query existing segments by GET request to /segments endpoint of Profile Store API. Basic filtering, paging and sorting is supported according to the Microsoft Rest API Guidelines.
$filter querystring parameter is used to define a filtering expression that will be evaluated for segments. The following logical operators are supported within $filter expression: eq, ne, gt, ge, lt, le, and, or, not.
Please see Microsoft Rest API Guidelines and Filtering, paging, and sorting article for more examples and details about querying profiles, events and segments in Profile Store API.
For example, the following should request 2 latest segments defined in the default scope by specific user:
GET api/v1.0/segments?$filter=Scope eq default and SegmentManager eq marketer@example.com&$orderBy=CreatedDate DESC&$top=2
The returned result 200 Ok contains the collection of segments that match defined filter, the number of returned items based on $top value and the total number of matching segments (first segment is created using API and the second is created in Insight UI):
{
"items": [
{
"SegmentId": "912f2150-82b5-5fa7-88c4-2d42fa700ac8",
"Scope": "default",
"SegmentManager": "marketer@example.com",
"ProfileQuery": "Info.Company eq Episerver",
"AvailableForPersonalization": true,
"Archived": false,
"FavoredBy": [],
"Name": "Episerver Employees",
"CreatedDate": "2018-10-14T21:16:25.2186793Z",
"ModifiedDate": "2018-10-14T21:22:11.3000335Z",
"MatchingProfiles": 4
},
{
"SegmentId": "1e2987f2-3285-4b72-83b8-1b50b1e29613",
"Scope": "default",
"SegmentManager": "marketer@example.com",
"ProfileFilter": {
"Rules": [
{
"Text": {
"Field": "Country",
"Method": "IsExactly",
"Value": "DE"
}
},
{
"And": {}
},
{
"Text": {
"Field": "ContactInformation",
"Method": "IsExactly",
"Value": "Known"
}
},
{
"And": {}
},
{
"Date": {
"Field": "LastSeen",
"Method": "Within",
"Values": [
"OneWeek"
]
}
}
]
},
"AvailableForPersonalization": true,
"Archived": false,
"FavoredBy": [],
"Name": "Identified from Germany last seen within 1 week",
"Description": null,
"CreatedDate": "2018-09-28T15:01:54.6417241Z",
"ModifiedDate": "2018-09-28T15:01:54.6417241Z",
"MatchingProfiles": 15
}
],
"total": 5,
"count": 2
}
Please note that the number of matching profiles returned for each segment in the list is not re-calculated. MatchingProfiles property value is the number of patching profiles at the moment when the segment was created or updated last time.
In case of error or invalid request the error message and code 500 or 400 are returned. For example, invalid filter syntax:
GET /api/v1.0/Segments?$filter=SegmentManager == test@example.com
400 Bad Request response is returned:
{
"error": {
"code": "400",
"message": "Invalid comparison phrase \"SegmentManager == test@example.com\"",
"target": "",
"details": []
}
}
Getting segment data in Profile Store API
Specific segment data can be loaded by specifying the segment ID:
GET api/v1.0/segments/912f2150-82b5-5fa7-88c4-2d42fa700ac8
MatchingProfiles property value is re-evaluated when loading single segment data, it is the current number of matching profiles now:
{
"SegmentId": "912f2150-82b5-5fa7-88c4-2d42fa700ac8",
"Scope": "default",
"SegmentManager": "marketer@example.com",
"ProfileQuery": "Info.Company eq Episerver",
"AvailableForPersonalization": true,
"Archived": false,
"FavoredBy": [],
"Name": "Episerver Employees",
"CreatedDate": "2018-10-12T16:16:25.2186793Z",
"ModifiedDate": "2018-10-12T17:22:11.3000335Z",
"MatchingProfiles": 183
}
Updating Segments
Editing in Insight UI
Segment editing is partially supported in Insight UI. Editing menu is available by clicking on corresponding icon in segment list and in segment details view.
Inline editing is enabled for segment name and description when viewing segment details.
Currently changing the segment filters to match profiles is not supported in the Insight UI.
Updating in Profile Store API
Existing segment can be completely replaced/overridden by PUT request to /segments endpoint and specifying the segment ID. For example, here we put a new segment data that includes description:
PUT api/v1.0/segments/912f2150-82b5-5fa7-88c4-2d42fa700ac8
{
"Name": "Episerver Employees",
"Description": "All profiles that have Episerver value in Info.Company property",
"Scope": "default",
"ProfileQuery": "Info.Company eq Episerver",
"AvailableForPersonalization": true,
"SegmentManager": "marketer@example.com"
}
PUT request creates a new segment if there is no existing segment with specified ID.
Like POST method, the response body contains new segment data.
Please note that updating/replacing segments that were created in the Insight UI is not supported in the Profile Store API. Technically it means that a segment cannot be updated using Profile Store API if segment ProfileFilter property is not null.
Removing Segments
Deleting segments is not supported in the current versions (1.6.0) of both Insight UI and Profile Store API. The main reason is that removing a segment may cause problems if deleted segment is used anywhere in the application, for example in visitor groups or any other integration. Removing segments may be implemented later.
Archiving Segments
Archiving is a way to hide segments that are not actively used in Insight UI. These segments can be found in Archived section of Segments view.
Using Segment
Personalization Using Segments
NuGet package Episerver.Insight.Cms provides the Insight segment visitor group criterion. Insight API base URL and subscription key must be defined in appsettings episerver:profiles.InsightApiBaseUrl and episerver:profiles.InsightApiSubscriptionKey.
After installing the package and updating configuration, Insight segment criterion can be used when creating a visitor group. The list contains existing segments that have property value AvailableForPersonalization=true (available in visitor group in Insight UI).
Selecting a segment means that visitor should be the part of visitor group if his/her profile matches segment (fits the segment filters).
Archived segments cannot be selected when creating a new visitor group, however it still works for personalization if it was selected in the visitor group criterion before archiving the segment.
For example, marketer filters profiles by Country, creates a segment of visitors from Germany, adds Insight criterion in the visitor group settings and select this segment. Now this visitor group can be used to personalize content, for example to invite visitors from Germany to subscribe to newsletters for German clients.
Segment in Intelligent Campaign
Intelligent Campaign is another good example of using segments. When creating a campaign, marketer can add the Insight Segment node in the working area and select a segment that should be used to filter recipients when sending campaign message.
Using segments in Campaign enables dynamic recipient targeting based on profiles information.
Implement your own integration!
I hope that developers will build new products and integrations on top of Profile Store. I’m looking forward to see your custom segments, personalization, visitor classification, activity analysis, integrations with CRM/ERP/whatever systems, websites and offline stores. Your feedback is very welcome!