Loading...

Last updated: Aug 02 2018

Area: Episerver Profile Store Applies to versions: 1.6.0 and higher

Segments

This topic shows how to get, filter, create, and replace segments using the Episerver Profile Store API. A segment is a dynamic collection of profiles matching conditions based on filter or query, such as visitors that previously responded to a campaign.

In this topic

How it works

Profile Store has two types of segments:

Segments created from Insight cannot be modified from the Profile Store API. Both types can be used as Visitor Group criteria, and can be exported to generate a profile reports.

Segment properties

The segment request contains the following property fields.

  • SegmentId. Required. The ID of the segment.
  • Name. The segment name.
  • Scope.  Required. The segment scope does not have to be a registered scope; it can be any non-empty string value.
  • SegmentManager. The segment manager.
  • ProfileQuery. The query in OData $filter format; used in a segment created by Profile API.

    OData $filter format has the following form: [Profile property] [OData logical operator] [value].

    OData logical operators include eqnegtgeltleandornot. An example of ProfileQuery is:

    Name eq profile1
    • [Profile property] is case-sensitive.
    • Using string type properties with comparable operators such as gtgeltle may yield the wrong result.
    • When filtering an array, no additional brackets are needed. For example:
      FavoredBy eq "user1", "user2" (OR logic) or FavoredBy eq "user1" AND FavoredBy eq "user2"
  • ProfileFilter. The object specifies a profile filter; used in a segment created by Insight API.
  • MatchingProfiles. The number of profiles matching the segment at the moment when the segment was created or updated last time. This value is also recalculated, and the current number of matching profiles is included in the result when loading specific segment by ID using Profile Store API.

    Note: This value is not re-evaluated, and it is not updated when listing segments.

  • AvailableForPersonalization. A boolean that indicates that this segment is available for using in visitor group.
  • Archived. The boolean that indicates a segment as archived since a segment cannot be deleted.
  • FavoredBy. The list of users that mark this segment as their favorite segment.
  • CreatedDate. The created date.
  • ModifiedDate. The modified date.

Example

{
    "Name": "string",
    "Description": "string",
    "Scope": "string",
    "SegmentManager": "string",
    "ProfileQuery": "string"
}

Segment methods

Get segment

Endpoint: GET api/v1.0/segments/{id}

Returns HTTP 200 OK with the segment specified by {id}.

Example of response body:

{
    "SegmentId": "2259a8f6-22b4-4166-9334-96fcfb3d40d6",
    "Name": "Profile with name Admin",
    "Scope": "default",
    "SegmentManager": "user1",
    "ProfileQuery": "Name eq Admin",
    "ProfileFilter": null,
    "MatchingProfiles": 2,
    "AvailableForPersonalization": false,
    "Archived": false,
    "FavoredBy": ["user1", "user2"],
    "CreatedDate": 2018-01-01T05:34:18,
    "ModifiedDate": 2018-01-01T05:34:18
}

Note: ProfileQuery is null if the segment is created via InsightUI. ProfileFilter is also null if the segment is created via ProfileAPI.

Query segments

Endpoint: GET api/v1.0/segments

Similar to TrackEvent and Profile, Segment can also get segments based on OData query. The result window size is limited and must fit the top 10000 records, so the sum of $skip and $top values must be less than 10000.

NoteMatchingProfiles value is not re-evaluated, and it is not updated when listing segments.

Create segment

Endpoint: POST api/v1.0/segments

Example of request body:

{
    "Name": "Profile with name Admin", // Required
    "Description": "Match all profile with name is 'Admin'",
    "Scope": "default", // Required, Scope just act as a filter, 
          // which means if a scope is not exist, the result will be empty instead of giving error
    "SegmentManager": "user1",
    "ProfileQuery": "Name eq Admin" // Required.
}

Example of response body:

{
    "SegmentId": "2259a8f6-22b4-4166-9334-96fcfb3d40d6",
    "Name": "Profile with name Admin",
    "Scope": "default",
    "SegmentManager": "user1",
    "ProfileQuery": "Name eq Admin",
    "MatchingProfiles": 2,
    "AvailableForPersonalization": false,
    "Archived": false,
    "FavoredBy": ["user1", "user2"],
    "CreatedDate": 2018-01-01T05:34:18,
    "ModifiedDate": 2018-01-01T05:34:18
}

Replace segment

Endpoint: PUT api/v1.0/segments/{id}

  • If segment ID not exists, the API creates a new segment;  otherwise, it is replaced.
  • If the segment is created by InsightUI, you cannot update that segment with the profile API.

Example of request body:

{
    "Name": "Profile with more than 10 visits", // Required
    "Description": "Profile with more than 10 visits",
    "Scope": "3542003a-1518-4a28-99f1-303a7e74f888", // Required, Scope just act as a filter, 
        // which means if a scope is not exist, the result will be empty instead of giving error
    "SegmentManager": "user1",
    "ProfileQuery": "Visits gt 10" // Required.
}

Example of response body:

{
    "SegmentId": "a91e87e4-f7e6-46b4-b96c-4a3dc089f8d9",
    "Name": "Profile with more than 10 visits",
    "Scope": "3542003a-1518-4a28-99f1-303a7e74f888",
    "SegmentManager": "user1",
    "ProfileQuery": "Visits gt 10",
    "MatchingProfiles": 5,
    "AvailableForPersonalization": false,
    "Archived": false,
    "FavoredBy": [],
    "CreatedDate": 2018-01-01T04:11:45,
    "ModifiedDate": 2018-01-01T04:11:45
}

Related topic


Do you have feedback on this documentation? Send an email to documentation@episerver.com. For development-related questions and discussions, refer to our Forums on https://world.episerver.com/forum/