Player Buckets and Audience Groups

Version 19

Updated 3 months ago

4 chunks

View in Confluence

Content

Introduction

In this guide you’ll learn:

What are Player Buckets and Audience Groups
Creating Player Buckets
Creating Audience Groups
Configuring Audience Groups from Player Buckets
User Allocation to Audience Groups
Accessing Audience Groups in Game Server
Adding Holdout Groups to Notifier

Table of Contents

Player Buckets

Player Buckets are a tool for segmenting the player base in a consistent and scalable way.

Each player is automatically assigned a single bucket value between 0 and 99 at the time of user creation.
Admins can define Player Bucket Groups by specifying a range of bucket values, for example: 0–19, 20–49, or 50–99.
A player is considered part of a Player Bucket Group if their individual bucket value falls within the defined range.
These groups are then used in various features such as:
Minimum Value (0): Represents the lowest segment in the range, typically including the first group of players in a given allocation.
Maximum Value (99): Represents the highest segment, covering the full possible range of player assignments.

For example, if you define a range of 0-10, it means that players assigned to buckets within this range (0 to 10) will be included in the targeted group. This means that when assigning players to targeted groups for recurring events, the system uses their Account ID mod 100. This means that the last two digits of the Account ID determine which bucket they fall into.
This mechanism ensures an even distribution of players across different event groups while maintaining consistency in targeting.

While the term "Player Bucket" refers to both the individual value and the group definition, they serve distinct roles:

The player bucket value is a single number (e.g. 23) assigned to the player.
A Player Bucket Group is a defined range used to group players (e.g. 20–29).

Accessing the Player Buckets

Log into the Harmony platform.
On the left sidebar, navigate to Players.
Click on Buckets.

Create a Player Bucket in Harmony

Follow these steps to create a new Player Bucket in Harmony :

Click the [+ New] button.
Enter a Name for the bucket in the provided text field.
From the Type dropdown, select one of the following types:
Audience groups
Experiments
Others
Refer to the Player Bucket Types section below for more details.
In the Bucket Lower Bound field, enter the starting range (e.g., 1).
In the Bucket Upper Bound field, enter the ending range (e.g., 6).
Click the Save button in the top right corner.
If you need to cancel, click the Cancel button.

Your new Player Bucket is now created and will be available in the system for further use.

Player Bucket Types

To provide more flexibility and avoid conflicts in targeting, Player Buckets now support bucket types.

These types define where a bucket can be used and ensure that overlapping buckets are avoided within the same context.

Each Player Bucket now includes a type that determines where it can be applied:

| Type | Can Be Used In |

| --- | --- |

| Audience groups | Only in Audience Groups |

| Experiments | Only in Experiments |

| Others | In all other entities, except Audience Groups/Experiments |

Buckets of the same type cannot overlap.
A player can belong to up to 3 buckets, but only one per type.

System Behaviour

Existing Buckets are automatically assigned the type Audience groups.
When Edge systems fetch player bucket data, the bucket type is returned along with the bucket assignment.
Buckets assigned to players respect type limits (no duplicates per type).

Editing a Player Bucket

Select the bucket you want to edit.
Once you are in the Edit Player Bucket screen, you will see the following fields:
Modify the required fields as needed

Saving Changes

After making the necessary updates, click the Save button in the top-right corner.
If you decide not to make changes, click Cancel to exit without saving.

Ensure that bucket boundaries do not overlap with existing buckets to prevent conflicts.
Buckets cannot be edited if they are linked to any entity, whether active or inactive. If a bucket is tied to an inactive audience group, review is required before making adjustments.

Using Player Buckets in Segments

Players Buckets can be used in the Segment Builder, allowing users to build segments based on pre-configured player buckets.
Builder is a visual interface that allows users to create and manage conditions using a structured, rule-based format instead of manually writing plain text conditions.

An admin user can also use the player bucket in the text conditions. Here is the format : player_bucket(id, 8) == true where id is the ID of the configured player bucket

Follow these steps to use Player Buckets when defining segment rules:

In the left menu, expand Segmentation.
Click on Segments to open the segment management screen.
In the segment creation/editing view, locate the Builder section.
Click on Select attribute to open the attribute dropdown menu.
Scroll through the dropdown list and select Player Bucket as the attribute.
Select the relevant Player Bucket.
After selecting Player Bucket , configure the condition by specifying values or operators (e.g., equal to, greater than, less than).
This ensures only players within the defined bucket range meet the segment criteria.
Click Add rule to include additional conditions using other attributes.
Click Save in the top-right corner to apply the conditions.
If needed, click Cancel to discard changes.

Validation Rules

Overlapping Player Buckets :
Player Bucket Validation :

Audience Groups

Audience Groups consist of Holdout and Rollout groups, enabling structured user segmentation for feature releases, and experiments. Players allocated to an audience group are not assigned to A/B experiments. You can only allocate players to active audience groups that fall within their designated start and end dates. If an audience group is deactivated while a player belongs to it, the player will no longer be treated as part of that group and will instead receive the default configuration like any other player.

However, if the group is later reactivated, the player’s allocation will be restored, and they will once again receive the audience group’s configuration.

For example, if a group is active from January 1st to March 31st, and a player is allocated to it on January 1st, but the group is deactivated on February 1st, the player will stop receiving the audience group’s settings from that date (including any overrides or experiment configurations). If the group is reactivated on February 14th, the player will immediately regain the audience group settings.

Holdout vs. Rollout Audience Groups

Holdout Groups

Used to exclude specific players from certain features or experiments.
Players in holdout groups do not receive updates or configurations applied to other users.
Useful for measuring the impact of new changes by comparing holdout users with those in rollout groups.

Rollout Groups

Used for gradual feature deployment or experimentation.
Players in rollout groups receive specific updates, configurations, or feature activations based on segmentation rules.
Helps manage risk by rolling out changes incrementally before full release.

Accessing the Audience Groups Page on Harmony

Log in to Harmony.
Navigate to Audience Groups in the left-hand navigation menu.

Creating a New Audience Group

Click the "+ New" button on the Audience Groups page.
Fill in the required fields as per the form:
Click Save to create the group.

Editing an Audience Group

Editable Fields:

Name : Update if needed.
Status : Change to one of the available statuses.
End Date : Can be updated, but the new date cannot be in the past.

Steps:

Select the group you want to edit from the list.
Click the Edit button.
Update the fields that are editable (as listed above).
Click Save to apply changes.

Note: Groups that are within their active time range (between Start and End Date) have limited editable fields (Name, Status, and End Date).

Duplicating an Audience Group

Select the group you want to duplicate.
Click the Duplicate button.
A Duplicate Audience Group pop-up will appear.
Rename the Duplicate:

The system automatically assigns a name by appending "Copy" to the original name.
Edit the name if needed.

Confirm the Duplication:

Click Confirm to create the duplicate Audience Group.
Click Cancel if you want to discard the action.
The duplicated group will:
Edit and activate the duplicated group as needed.

User Allocation to Audience Groups

Players are allocated to audience groups to refine the results of A/B experiments. To improve the accuracy and reliability of A/B experiment results by ensuring that players are grouped in a way that minimises external influences. Allocating players to audience groups helps create controlled testing conditions, making it easier to measure the true impact of new features or configurations without interference from outside factors.

Allocation follows specific rules based on player activity and group configurations.

Allocation Rules

Players are allocated to audience groups only when they come online.
A player is allocated to an audience group if they meet the following criteria:
Allocation starts on the start date and ends when:

Special Cases:

When the end date is reached , players are removed from the holdout/rollout group.
If allocation is paused , players who were already allocated stay in the group until the end date, but no new players are allocated.
The database stores which group each player has been allocated to.
Only new players are allocated to audience groups.
If group buckets are edited after the start date :

Scenario 1: Allocation Between Start Date and End Date

Group Status : Always shown as Active from the start date to the end date
Deactivation after the end date.

Scenario 2: Allocation Between Start Date and Inactivation Date (Early End)

Group Status : Shows as Active initially, then Inactive after early manual inactivation (before end date).

Scenario 3: Allocation Between Activation Date and End Date (Late Start)

Group Status : Initially Inactive , changes to Active when manually activated.

Troubleshooting

| Issue | Cause | Solution |

| Unable to Save Group | Overlapping player buckets or time range. | Adjust the player buckets or start/end dates to avoid overlaps. |

| Cannot Edit Fields | Group is in its active time range. | Only Name, Status, and End Date can be edited during this time. |

| Player Bucket Warning | Inconsistent data input | Ensure the upper bound is not smaller than the lower bound. |

Audience Groups: Archiving Workflow

Deactivating Groups

Start Date: The group becomes Active on the start date, and allocations begin.
End Date: When the end date is reached, the group does not immediately become inactive.
Ended audience groups are automatically deactivated by the system once a day.

Key Points:

Groups become Inactive after their End Date (UTC) when the cron job runs.
Once Inactive , no new players are allocated, but past allocations remain.

Archiving Groups

Manual Archiving:

Users can manually set a group to Archive in the UI.
The group stays in the Archive status for 7 days.

Automatic Archiving :

The system checks daily for groups in the Archive state for 7 days.
After 7 days, the group is moved to Permanently Archived.

Permanently Archived Groups:

Data Cleanup: Player allocation data is deleted from the database.
Analytics: Data remains available in Snowflake , but the group cannot be restored in Harmony.

Reactivating Archived Groups

Users can restore an Archived group and set it back to Active.
Restored groups:

Conditions:

The group must not be in the Permanently Archived state.
Reactivation restores all original configurations and allocation rules.

System Workflow Summary

Deactivating:

UI: Groups transition from Active → Inactive after the End Date , based on the cron job.
Server: A daily cron job ensures that groups with past end dates are deactivated.

Archiving:

UI: Users can manually move a group to Archive. After 7 days , it becomes Permanently Archived.
Server: The cron job moves archived groups to Permanently Archived and deletes player allocation data.

Key Notes:

Groups will only be permanently archived if they have been in the Archive status for 7 consecutive days.
Reactivated groups will resume functioning as active groups, maintaining previous player allocations while including new players based on the defined rules.
This workflow ensures seamless automation of group status transitions and minimal manual intervention.

Accessing Audience Groups in GS
Audience Groups in Game Server (GS) allow for targeted feature rollouts and experiment segmentation by grouping players based on predefined criteria.

Configuring Audience Groups in GS ensures that the right set of players receives specific settings, enabling more controlled testing and personalisation.

Navigate to Game Settings in the GS interface.
Click the “Audience Groups” button in the settings list view.

The system will open a new page listing all available Audience Groups as they are configured in Harmony.

Audience Groups List View

The Audience Groups list view contains the following columns:

| Column | Description |

| --- | --- |

| ID | Unique identifier for the Audience Group. |

| Player Service ID | Unique identifier for the Audience Group in Harmony |

| Name | Name of the Audience Group. |

| Status | Current status of the group (e.g., Active, Scheduled, Ended). |

| Group Type | Indicates whether it is a Holdout or Rollout group. |

| Start Date | The date when the Audience Group becomes active. |

| End Date | The date when the Audience Group is deactivated. |

| Updated at (UTC) | Date, UTC time and name of the user at the time of the update. |

| Actions | Provides an Edit option for modifying the group. |

Sorting Rules

Active groups appear at the top.
Within active groups, sorting is based on the Start Date (latest first).

Filters Available

Users can filter the Audience Groups using the following criteria:
Status
Group Name
ID
Type
Start Date
End Date

Editing an Audience Group

Click on the Edit button under the Actions column for an Audience Group.
The Edit View opens, displaying: