Segments

How to group and manage like users.

Overview

Segments are a powerful way to group users based on any defined criteria or characteristics.

Segments can both be used within a rule's conditions (see Segment Conditions->) to determine eligibility, as well as being the output of a rule, eg. when a rule is used to segment users based on some defined activity or goal.

Segments can therefore be used in a variety of ways, including enabling more effective and efficient allocation of incentives to targeted groups, more personalized communications, or in a variety of lifecycle management and segmentation programs.

How Segmentation Works

Users can be added to or removed from segments in four different ways:

1. Output Operation of a Rule: Users can be added or removed from a segment based on rule logic. For instance, a rule might specify that any user who completes a certain action gets placed into a segment

2. Manual Update: Users can be individually added, removed, or suspended from a Segment by admins

3. Bulk Update: Users can be added, removed, or suspended in bulk from one or more Segments using the CSV update tool

4. Segments API: The Segments API can listen for certain activities or behaviors on your platform and automatically add a user to, or remove them from a given Segment

Creating Segments

Segments are created in the Segments section of the Network Manager. Follow these steps to create a new segment:

Creating a New Segment

1. Navigate to Side Menu -> Incentives -> Segments -> New Segment

2. There are several required inputs to create your Segment:

Input	Description
Segment Name	A descriptive name for the segment. Be specific as this is the name used when creating rules.
Short ID	A unique identifier for the Segment will be created automatically. Will be referenced if you're using the Segments API.
Description	A clear, specific description of the segment's purpose. This is for internal use only.
Visibility	By default, segments are not visible to their members. You can choose to make a segment visible to its members by marking “Segment Visible to Members.”

Segments versus Badges.

When a Segment is created, an associated Badge Award is also automatically created. This Badge will show up to users in the Segment only when you have chosen to make the Segment visible to its members (or otherwise separately award this Badge). You can customize this Badge by heading to Side Menu -> Incentives -> Awards -> Status & Badges.

Adding or Removing Users From Segments

Users can be added or removed from segments in four ways: rule execution, manual updates, bulk updates, or using the Segments API->.

1. Rule Execution

A user can be added to or removed from a Segment as an output operation when a rule successfully executes. To do this, create and configure a rule to award or revoke a Segment upon successful evaluation of a rule. Once you've created a Segments, it'll be available to select in the Output Operation dropdown when you're creating a rule.

2. Manual Updates

You can directly add, remove, or suspend a user from a Segment.

1. Navigate to Side Menu -> Incentives -> Segments -> [Choose your segment] -> Manage -> Segment Detail page

2. At the bottom of the page, you're able to search for any user in your Network by email:

   1. When a member is in a Segment, a green circle will appear next to their name.

   2. If a member is suspended from a segment, a yellow circle will appear instead.

   3. If a user is not in the segment, there will be no circle next to their name.

3. To add, remove, or suspend a user, search for the user by email and click "Add" or "Remove"

4. To suspend or unsuspend a member, click the yellow 'X' (to suspend) or green check mark (to unsuspend) to the right of screen.

3. Bulk Updates

You can add, remove, or suspend one or multiple users from one or multiple Segments simultaneously using a CSV file upload.

Bulk updating Segments

1. Navigate to the "Bulk Update" tab on either the Segments overview page or the Segment Detail page.

2. You’ll see a CSV upload prompt.

3. Please upload a CSV in the below format. You can search for your file or drag and drop.

4. After performing a bulk update, there are three possible outcomes:

   1. Success: This screen indicates all rows were successfully updated.

   2. Failure: If this screen appears, no action was taken on any rows. This likely indicates an error in the upload or the format of the upload.

   3. Partial Success: Some rows were successfully updated, but some were not. The dialogue box will indicate the reason for failure and which rows failed. For example, if a user was already in the state/segment specified in the upload, no action will be taken on them. In this case, you may need to re-upload the rows that did not successfully execute.

Bulk Update Segment: File Format

Important: when you use both the bulk upload tool and segments API, this will override any future rule executions that attempt to put a user into or remove a user from a group.

If you do not want future rule executions to be overriden by bulk changes like API and bulk upload, make sure you also include a separate row with user_status = 'reset' for that user alongside your 'add' or 'block' action in a separate row. This will have the effect of adding or blocking the user as intended, but then allowing automated rule executions to work as normal going forward.

user	segment_id	user_status
[e-mail]	1	add
[e-mail]	3	block
[e-mail]	3	reset

Bulk Segment Update Success Screen

Remove duplicates: when bulk updating one or more Segment(s) using a CSV, you’ll need to ensure that no two rows in your CSV have the same value pairs for columns 1 and 2, otherwise only the last row with this value pair will successfully execute (since you are trying to perform the same or different action on the same user and Segment).

Segments API

Users can also be added, removed, or suspended from a Segment through the Segments API. This is a great way to automate segmentation for cases where there are a large number of Segments or rules that would need to be created. For example, applying Segments to users who viewed one of thousands of different product categories would otherwise require creating a rule for each category. For more detail, see the Segments API->

Relationship between Segments & Awards

Segments and Awards share a close relationship in Village. Each time you create a Segment, a corresponding badge Award is created. You can decide whether or not this Segment (in the form of the corresponding badge award) is visible to a user by making the Segment visible to users.

This relationship means that your user segmentation logic can also act as award logic when you want to celebrate or communicate a user's entry or exit from a Segment.

Segment Expiration

In some cases, you may want a Segment to expire a given number of days after it was awarded. This is a common use case for Segments that track time since an event occurred to a set of users. For instance, a 'New User - 30 Days' segment might be applied to a user when they sign up but expire 30 days later. Thus you know that anyone in this Segment signed up in the last 30 days.

Expiration for a Segment needs to be configured on the associated Segment Badge. Navigate to Side Menu -> Incentives -> Awards -> Status & Badges -> [Select the relevant Segment] -> Manage

Editing Segments

To edit a segment, navigate to Side Menu -> Incentives -> Segments -> [choose the Segment you wish to edit] -> Manage -> Segment Detail page

1. Click the purple edit icon in the top right of the Segment Detail page.

2. On the edit page, you can modify any of the inputs you made when creating the segment.

Exporting Segments

To export a Segment, navigate to Side Menu -> Incentives -> Segments -> [Choose the relevant Segment] -> Manage -> Segment Detail page

1. Click the purple "Export Data" button. This will download a CSV containing user and status information for this Segment.

Duplicating Segments

To create a copy of an existing Segment:

1. Click the purple "Duplicate" icon next to the Segment you wish to duplicate.

2. You'll need to change the Segment name to distinguish it from the original Segment.

Deleting Segments

To delete a Segment:

1. Click the red "Delete" button to the right of the Segment you wish to delete.

2. Remember, you cannot delete a Segment that is part of an active rule. To delete, first deactivate the rule or remove the Segment from the Output Operation of the rule.