What are Segments?

Segments allow you to create partitions for different users and apply various rules to different areas of the platform. Segments offer you an extra dimension of flexibility for precisely customizing player experience and behavior.

FAQs? You can review Frequently Asked Questions about setting up and managing Segments.

Segmentation Tutorials? Check out the Segmentation tutorials where you can find worked examples of how to set up and work with Segmentation.

Segmentation Use Cases

Here's two use cases where Segmentation comes in very useful:

1. Let's suppose I have an international blockbuster game with players connecting from different parts of the World. In order to offer a more personalized experience for my players, I might want to segment players by region or country. I can create a Segment based on country and then use different Segment Values for the countries my players are situated in. When added to such a Segment, the players will receive a different experience. For example, each Segment Value (country in this case) could have its own values assigned for:

2. What about language? A much simpler and customizable method than Geo Locations would be to introduce a language Segment. Based on the user's Segment Values for a language Segment, users could receive messages for new high scores, Challenges, and team invitations all in their respective native languages, as well as customizing the name and descriptions of Leaderboards, Challenges, Achievements, and so on.

What can I Segment?

1. You can segment many of the configurables you create for your game:

2. You can also segment any of the Currencies in your game:

Game-Scope and Object-Scope Segmentation

This topic explains how to set up and manage Segments and Segment Queries which you can then use across the platform to impose segmentation across different kinds of configuration objects. For example, you might create a Country Segment, add Segment Values to it, and then create a Segment Query using Country Segment/Value pairings. You could then use that Segment Query to impose segmentation on your players to differentiate their game experience based on their country of registration:

We can think of this way of imposing differentiated player experience of common configurable objects as game-scope segmentation.

However, you can also impose segmentation directly on individual configuration objects and bypass the need to set up any game-scope Segmentation. This direct or object-scope segmentation is then confined to differentiating player experience of that specific configuration object. For details of how to segment a specific configuration object directly with examples, see this tutorial

Managing Segment Configurations

To create and edit Segments, go to Configurator > Segments and select the Segments tab. Existing Segments are listed:

You can use the following options (highlighted above):

Creating a Segment and Adding Segment Values

You can add multiple Segments and for each Segment you can define multiple values.

1. On the Segments tab, click Add. The page adjusts:

2. Enter the details of the new Segment:

3. To add values to the Segment, under Values click Add.

4. Enter a Short Code, Name, and Description for each Segment Value that you add:

In this example, we've added 6 Values for our Country Segment:

Building Segment Queries

You can build Segment Queries to define rules which determine which players are subjected to a specific segmentation of a configuration object in your game:

Setting Segment Query Filters

When you create the Segment Queries you want to use for segmenting your game's configuration objects, you can first select just those filters you want to use for building queries:

1. Go to Configurator>Segments and select the Segments Queries tab.

2. Click Segment Query Filters:

The Segment Query Filters panel appears:

3. Select the Segment Query Filters you want to use when building your Segment Queries:

4. If you want to add custom filters for building your Segment Queries, click Add:

5. Click to Save your Segment Query Filters selection.

Tutorial! For more details on how to set up and work with custom Segment Query Filters, see this tutorial

Adding Segment Queries

When you've selected Segment Query Filters, you can start to build Segment Queries.

Here, we'll build two Segment Queries that we'll use below to segment an Achievement:

1. Go to Configurator>Segments and select the Segment Queries tab.

2. Click to Add a new query.

3. Enter the details of the new Segment Query:

4. Use the drop-downs to build the query you want:

5. Click to Save and Close the new Segment Query.

6. Repeat the above steps to create a second Segment Query:

7. Click to Save and Close this second new Segment Query:

Custom Scripts for Segment Queries? Note that you can click a checkbox to Enable custom script and further refine your Segment Query. For detail of how to do this, see below.

Assigning Segments Values to Players Using Cloud Code

You can assign Segment Values to your players using Cloud Code:

Here's an example of how to do this by attaching Cloud Code to the AuthenticationResponse. We assign a Country Segment/Value pair to each player when they Authenticate on the portal:

if(Spark.getPlayer() !== null){
   var request = new SparkRequests.AccountDetailsRequest().Send();
   switch (request){
       case "CN":
           Spark.getPlayer().setSegmentValue("COUNTRY_SEG", "CN_COUNTRY_SEGVAL")
        case "JP":
           Spark.getPlayer().setSegmentValue("COUNTRY_SEG", "JP_COUNTRY_SEGVAL")
        case "NZ":
           Spark.getPlayer().setSegmentValue("COUNTRY_SEG", "NZ_COUNTRY_SEGVAL")
        case "PL":
           Spark.getPlayer().setSegmentValue("COUNTRY_SEG", "PL_COUNTRY_SEGVAL")
        case "RU":
           Spark.getPlayer().setSegmentValue("COUNTRY_SEG", "RU_COUNTRY_SEGVAL")
        case "GB":
           Spark.getPlayer().setSegmentValue("COUNTRY_SEG", "UK_COUNTRY_SEGVAL")


When users authenticate by submitting an AuthenticationRequest, this code will execute when the AuthenticationResponse is sent back from the platform and ensures that they are assigned the appropriate Segment/Value pair based on their geographical location.

Checking Segment Assignment

You can quickly check that the Cloud Code you use to assign Segment/Value pairs to your players is working:

1. Go to the Test Harness and submit an AuthenticationRequest.

2. Go to NoSQL Explorer and under System open the player Collection.

3. Submit a query to Find the player you've just authenticated on the platform in the Test Harness.

4. Open the player details in the Output panel. You'll see the Segment/Value pair under segments:

Segmenting Configuration Objects across the Portal

Within the portal, you can segment your configuration to set different parameters for different Segments. For example, you can have:

In this example, we'll segment an Achievement using the two Segment Queries we built above.

1. Go to Configurator>Achievements.

2. Click to edit an Achievement you want to segment.

3. Click Segment. The Segment Configuration panel opens:

4. Click Add Segment.

5. Enter the alternative values you want to use for the segmentable Achievement fields and which will be applied to players put into this Segment:

Using Calculated Segment Values? Instead of entering an absolute value as an alternative segmented value for a Currency award, you can use a calculated value. For example, if the original Currency value is 100, you can use +20 or -20 to make the alternative segmented value 120 or 80. Secondly, you can enter a calculated value by percentage. For example, if the original Currency value is 100, you can enter +15% or -15% to make the alternative segmented value 115 or 85. If you use calculated values for segmenting named Currencies in your game, the calculation is represented as: +20 x Currency Name - this means 20 will be added to the normal currency value.

Compounding Calculated Values! If you intend to run Experiments against configurables you have segmented using calculated values, you must be careful when also using calculated values for your experimental variant values - see below for details on this issue.

6. Use the drop-down to select the Segment Query you want to use to determine which players are put into this segment of the Achievement:

7. Click Add Segment again and add a second Segment for the Achievement:

8. Click to Save and Close the Achievement segmentation.

Using Custom Scripts to Refine Segment Queries

When building Segment Queries, you can use a simple custom JavaScript in addition to any rules you define to impose segmentation of configuration objects on your players:

Custom Script Constraints

There are some design constraints when using a custom script to refine your Segment Query:

Example Custom Script for Segment Query

In this example, we take one of the Segment Queries we built above and select Enable custom script:

Enabling/Disabling/Re-Enabling for Custom Scripts? If you enable to add a custom script and enter and save a script for your query but you then uncheck to disable the script and save, your previously entered script will not have been retained if you then re-enable for the custom script.

Working with Segmented Fields View

When you've segmented a configurable in your game and added segments, you can exploit an alternative view which allows you to view and edit the segmented values by Field and add a new Segment directly.

1. Open a configurable object to which you've added multiple segments and click the Segment button in the Edit page. The Segment Configuration panel opens - here, we re-open the Achievement to which we added two Segments earlier:

2. Click the Segment icon on the Field for which you want to view the segmented values. A Segment Field panel opens for the Field - here we selected for the Achievement's Name Field values:

3. To view the segmented values for other Fields, click the Segment icon. The Segment Field panel adjusts to list the segment values for that Field. Here, we've clicked to view the segment values for the Currency 1 Award Field:

4. You can edit your Segments from this view and add new ones:

5. Click to Save your changes.

Ordering Segment Configuration

Segmented values within the portal can be ordered - simply click and hold on the Reorder icon and drag-and-drop a Segment to where you want it:

Why Order Segments?

If you apply more than one segment against a configurable and some of your players will fall into more than one segment, order the segments to ensure the correct segment values are applied to these "multi-segment" players:

Ordering Segments Example! For an example where ordering segments is important to achieve the right experience for your players, see Example 4 here.

Social Integration with Segments

One of the most powerful features of Segmentation is that it allows for different segment types to be socially connected to different games or apps. For example, players of different nationalities or language preferences could have segments which would socially connect them to a different version of a developer's app or game on Facebook or Twitter:

Segmentation and Running Experiments

If you have implemented segmentation for some of your configurables and also plan to set up and run Experiments where, under an Experiment, you vary the values of those segmented configurables, it's worth remembering that any calculated values under the segmentation might be compounded, if you then set up calculated values for the same configurables under the Experiment: