Chunks Used in Chat #43

# **Introduction** This user guide describes what analytics buckets are and how ad events are stored in the buckets for various Ad configuration settings, such as Max Interstitial Ad Units, Max Rewarded Videos Ad Units, Impressions Restrictions, and Ad slots configurations.   * * * # **What Analytics Buckets Represent** **Analytics Bucket** are logical divisions of events (e.g., ad requests) stored by the Game Server. Each bucket stores **up to the 50 most recent CPM values** that meet specific criteria (e.g., successful or failed ad requests). Please see the following image to understand how CPM values are stored in **each bucket**. See the [Available Analytics Buckets](https://tripledotstudios.atlassian.net/wiki/spaces/KB/pages/4317282308/Analytics+Buckets#Available-Analytics-Buckets) section below to find out the number of buckets currently available for storing CPM events.   **When do the CPM Values expire?** - If the player hasn’t been active in a **14** day period, all the CPM values will be cleared, as they will be considered a churned player. - If a player comes back after **14** days, Game Server will start collecting new CPM values for the player from scratch and apply the formulas accordingly. - All CPM values older than **30** days will be cleared (regardless of when the user has been active the last time). When this is done, the size of the list for the player will simply go down to contain only the CPM values that are less than 30 days old. # Available Analytics Buckets Different Analytics Buckets are available for different settings. In total ten (10) buckets are available but only a few or a combination of few buckets are used for each setting pertaining to CPM calculations. **Analytics Buckets for Interstitials (5 in number)** - Max Analytics Buckets: 3 in number (0,1, and 2) - Meta Analytics Bucket: 1 - Google Analytics Bucket: 1 **Analytics Buckets for Rewarded Videos (5 in number)** - Max Analytics Buckets: 3 in number (0,1, and 2) - Meta Analytics Bucket: 1 - Google Analytics Bucket: 1 Refer to the [Setting up CPM Floor](/wiki/spaces/KB/pages/4304109569/Setting+up+Ad+Units#Setting-the-CPM-Floor) section to know more about how CPM values are calculated. CPM calculations are configured for the following Ad configurations settings: - Max Interstitials Ad Units - Max Rewarded Videos Ad Units - Impressions Restrictions - Ad Slots ## **Event Bucket Assignment** - The Game Server receives a list of ad events from the client. - These events are then evaluated against certain parameters to determine whether they should be stored and, if so, which bucket they should go into. - If an event doesn’t meet the criteria, it is ignored. **Event Buckets for Max Interstitials Ad Units**  **Event Buckets for Max Rewarded Videos Ad Units**  ## **Key Parameters Used to Route Events** A decision is made for each event using the following metadata: - **Event name** (e.g., Ad\_Request\_Success\_Interstitial) - **Mediation platform** (e.g., Max, google, Meta) - **Network** (used only for Max, e.g., exclude: facebook) - **Error code** (used only for Max for failed requests coded 1009, 1001. All failed requests are stored with all other error codes EXCEPT code 1009 and 1001 ) - **Ad unit tag** (used only for Max. 0, 1, 2 : routes events to MAX bucket 0/1/2) * * * ## **Event Bucket Details** | **Bucket Name** | **Applicable Ad Type** | **Mediation** | **Accepted Event Types** | **Conditions** | **Stored Data** | | --- | --- | --- | --- | --- | --- | | **MAX Event Buckets (0, 1, 2)** | Interstitial | max | Ad\_Request\_Success\_Interstitial Ad\_Request\_FailedToLoad\_Interstitial | adunit\_tag = 0 Bucket 0 adunit\_tag=:Bucket 1 adunit\_tag = 2 or missing: Bucket 2  network ≠ facebook | CPM = revenue × 1000  Timestamp (date and time)  is\_fb flag | | **Google Interstitial Event Bucket** | Interstitial | google / google\_postbid | Ad\_Impression\_Interstitial | Event name = Ad\_Impression\_Interstitial mediation = google or google\_postbid | CPM = revenue × 1000  Timestamp (date and time)  is\_fb flag | | **Meta Interstitial Event Bucket** | Interstitial | meta | Ad\_Impression\_Interstitial | Event name = Ad\_Impression\_Interstitial mediation = meta | CPM = revenue × 1000  Timestamp (date and time)  is\_fb flag | | **MAX Rewarded Video Bucket (0,1,2)** | Rewarded Video | max | Ad\_Call\_Success\_Rewarded Ad\_Request\_FailedToLoad\_Rewarded | adunit\_tag = 0 Bucket 0 adunit\_tag=:Bucket 1 adunit\_tag = 2 or missing: Bucket 2  network ≠ facebook | CPM = revenue × 1000  Timestamp (date and time)  is\_fb flag | | **Google Rewarded Video Bucket** | Rewarded Video | google / google\_postbid | Ad\_Impression\_Rewarded | Event name = Ad\_Impression\_Rewarded mediation = google or google\_postbid | CPM = revenue × 1000  Timestamp (date and time)  is\_fb flag | | **Meta Rewarded Video Bucket** | Rewarded Video | meta | Ad\_Impression\_Rewarded | Event name = Ad\_Impression\_Rewarded mediation = meta | CPM = revenue × 1000  Timestamp (date and time)  is\_fb flag | * * * ## **Examples** **Example 1:** json `{ "name": "Ad_Request_Success_Interstitial", "mediation": "max", "network": "AppLovin", "adunit_tag": 0 } ` Routed to: **MAX Bucket 0** * * * **Example 2:** json `{ "name": "Ad_Request_FailedToLoad_Interstitial", "mediation": "max", "network": "Facebook" } ` **Not stored** : network is excluded (Facebook). * * * **Example 3:** json `{ "name": "Ad_Impression_Interstitial", "mediation": "google" } ` Routed to: **Google Interstitial Bucket** * * * ## Example for how Buckets are Used for Max Interstitial Ad Units The Max Interstitial Ad Units setting can be configured on the configurations page. 1. Navigate to the **Configurations** page and open the **Interstitials** tab. 2. Enable the **Max Interstitials Ad Units** setting. 3. Add ad unit and input the following data:  The Edit Ad Unit ID config appears. The selected bucket determines the value of the adunit\_tag key included in events sent from the ad unit to the Game Server. For MAX-mediated events, this tag defines which storage bucket the event should be placed into. When formula-based CPM floor calculation is enabled, the MAX bucket associated with this tag will be used as the source of CPM values.  For this example, let us assume that the following buckets have the listed number of events: - MAX Interstitial Event bucket 0: 3 Events - MAX Interstitial Event bucket 1: 3 Events MAX Interstitial Event bucket 2: 3 Events - Google Interstitial Event Bucket: Not applicable for this event setting - Meta Interstitial Event Bucket: Not applicable for this event setting The calculation **uses only MAX Bucket 0** (as per the selected config). **Source Events from Bucket 0** Events stored in Bucket 0: - Event 1: CPM = 6 - Event 2: CPM = 5 - Event 3: CPM = 5 **Formula Configuration Rules** Two key formula parameters: - **Minimum Ad Requests to Apply Formula = 3** - **Ad Requests to Use in Formula = 4** **CPM Calculation** - Average the CPMs of the last 3 events: - Multiply by percentage coefficient (set to 1.1): Final CPM floor sent to client = 5.87  The same logic applies to **MAX Rewarded Video Ad units** , using **Rewarded Video (RV) events** stored in the corresponding **RV event buckets**. The calculation follows the same formula-based behaviour as with interstitial events.

Example for how Buckets are Used for Impressions Restrictions Setting The Impressions Restrictions setting can be configured on the configurations page. 1. Navigate to the Configurations page and open the Interstitials tab. 2. Enable the Impressions Restrictions setting. 3. Add a unit and input the following data:   **Source Buckets Used: Events from all buckets are used for this setting.** - MAX Interstitial Buckets: 0, 1, and 2 - Google Interstitial Event Bucket - Meta Interstitial Event Bucket - All buckets contribute CPM data - Events are sorted by timestamp **Combining and Sorting Events** All events from the buckets are: - Merged into a single list - Sorted chronologically by timestamp This ensures that only the most recent events are used for formula application. **Formula Parameters** - **Min Ad Requests to Apply Formula = 3** - **Ad Requests to Use in Formula = 4** Selected CPMs (from latest 4 events): 5, 5, 6, 6 **Calculation Logic** Formula: CPM floor=(45+5+6+6​)×1.1=422​×1.1=5.5×1.1=6.06 **Final CPM Floor Sent = 6.06** This setting is currently not available for Rewarded videos * * * ## Example for how Buckets are Used for Ad Slots The Ad slots setting can be configured on the Ads page. 1. Navigate to the Ad Slots page. 2. Add a unit and input the following data:  The Ad unit mediation here is Max and the specified Max Analytics Bucket for this example is: 0. You can jump to the configuration through the link besides the selected Max ID.   **Source Buckets Used:** This setting uses events from one MAX bucket + Google bucket + Meta bucket - MAX Interstitial Buckets: 0, 1, or 2 - Google Interstitial Event Bucket - Meta Interstitial Event Bucket - 1 bucket for Max, 1 bucket for Google and 1 bucket for Meta contribute CPM data - Events are sorted by timestamp **Combining and Sorting Events** All events from the buckets are: - Merged into a single list - Sorted chronologically by timestamp This ensures that only the most recent events are used for formula application. **Formula Parameters** - **Min Ad Requests to Apply Formula = 3** - **Ad Requests to Use in Formula = 4** Selected CPMs (from latest 4 events): 5, 6, 5, 5 **Calculation Logic** Formula: CPM floor=(5+5+5+6​)/4×1.1=5.775 **Final CPM Floor Sent = 5.775** The same logic applies to **Ad slots** , using **Rewarded Video (RV) events** stored in the corresponding **RV event buckets**. The calculation follows the same formula-based behaviour as with interstitial events. * * * ## **Managing Multiple Ad Units and Buckets for CPM Floor Calculation** This section explains how to configure **multiple Ad Units and Ad Slots** , and how CPM floors are calculated using **event buckets** from MAX, Google, and Meta networks. It covers logic for bucket assignment, fallback flows, formula use, and nesting within Ad Slot Banks. ### **Multiple Ad Units per Configuration** You can assign **multiple Ad Units** to the following settings: - MAX Interstitial Ad Units - MAX Rewarded Video Ad Units - Ad Slots (Interstitials) - Ad Slots (Rewarded Videos) Each Ad Unit is configured independently and can have: - Its own **CPM floor** - Its own **MAX analytic bucket** - Its own **formula calculation logic** **Note:** Google and Meta events are always considered for CPM calculation for Ad Slots (both Interstitials and Rewarded Videos) and are **not limited by the MAX bucket selection**. ### **Bucket Assignment and CPM Storage for Max Interstitials and Rewarded Videos Ad Unit Setting** - Each Ad Unit's events are sent only to the **MAX buckets specified** in the MAX Analytic Buckets setting. - Example: **CPM Floor Options per Ad Unit** Each Ad Unit can define its CPM floor using one of the following methods: **a. Static Value (Fallback CPM)** - A fixed floor value you set manually. **b. Percentile-Based CPM Floor** - Uses historical CPM data stored on the Game Server (GS). - Requires Use Percentile enabled. **c. Formula-Based Calculation** - Averages or Median CPMs from recent events across selected buckets. - Uses defined event count and coefficient rules. - Pulls data from: **Only 1 bucket is used for formula calculation: The selected MAX bucket** **Event collection must be explicitly enabled for each game; it is not enabled by default.** ### **Ad Slot Structure and Behaviour** **Multiple Ad Units per Ad Slot** - Ad Units are initiated **in order** (sequential fallback). - If an ad is not filled (no Ad is uploaded), the system proceeds to the **next Ad Unit**. - Once all Ad Units are tried, the client **restarts from the first**. - This loop continues until: - Each Ad Unit can have its own request limit. For example: **Multiple Ad Slots in Ad Slot Banks** - A single **Ad Slot Bank** can contain **multiple Ad Slots**. - Each Ad Slot has its own **independent list of Ad Units**. - Ad Slot Bank is selected in the **Ads Config** section. - **Each Ad Slot** can: **Nested Ad Slots** - **Nesting is supported up to 4 levels**. - Each Ad Slot can have **only one child**. - Example: - If Ad Slot 1 serves an ad, the next request will try Ad Slot 1.1. - At the top level, **up to 10 Ad Slots** can run **in parallel**. - **Ad Unit ID configs must be unique** within a single Ad Slot Bank. **CPM Floor Options per Ad Unit in each Ad slot** Each Ad Unit can define its CPM floor using one of the following methods: **a. Static Value (Fallback CPM)** - A fixed floor value you set manually. **b. Percentile-Based CPM Floor** - Uses historical CPM data stored on the Game Server (GS). - Requires Use Percentile enabled. **c. Formula-Based Calculation** - Averages or median CPMs from recent events across selected buckets. - Uses defined event count and coefficient rules. - Pulls data from: **3 buckets are used for formula calculation: The selected MAX bucket+ 1 Google bucket +1 Meta bucket** **Impression Restriction Behaviour** The **Impression Restriction** setting relies on events across all buckets. (All five buckets that is 3 Max buckets + 1 Google bucket +1 Meta bucket) However, **some buckets may be empty** if: 1. Ad Units are configured to send events only to specific buckets (e.g., Bucket 1 and 2, not 0). 2. The system has just started and hasn’t collected events yet. Buckets without events are **ignored** during restriction logic. Only buckets containing **valid CPM events** are used in the calculation. **Summary** | **Feature** | **Behaviour** | | Ad Units per Slot | Sequential fallback | | CPM Floor Options | Static, Percentile, Formula | | Buckets Used | MAX (selected), Google, Meta | | Unique Constraint | Ad Unit IDs must be unique within a Bank | | Nesting Limit | 4 levels max | To learn more about Ad Configuration , CPM Calculation, and Analytics Buckets, refer to this Miro board: link: [https://miro.com/app/board/uXjVJY-ADCU=/](https://miro.com/app/board/uXjVJY-ADCU=/) Password: Ad\_Config\_Miro

## 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 1. Log into the Harmony platform. 2. On the left sidebar, navigate to **Players**. 3. Click on **Buckets**. ### Create a Player Bucket in Harmony Follow these steps to create a new Player Bucket in **Harmony** : 1. Click the **[+ New]** button. 2. Enter a **Name** for the bucket in the provided text field. 3. From the Type dropdown, select one of the following types: Audience groups Experiments Others Refer to the [Player Bucket Types](https://tripledotstudios.atlassian.net/wiki/spaces/KB/pages/3981377538/Player+Buckets+and+Audience+Groups#Player-Bucket-Types) section below for more details. 4. In the **Bucket Lower Bound** field, enter the starting range (e.g., 1). 5. In the **Bucket Upper Bound** field, enter the ending range (e.g., 6). 6. Click the **Save** button in the top right corner. 7. 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 1. Select the bucket you want to edit. 2. Once you are in the **Edit Player Bucket** screen, you will see the following fields: 3. Modify the required fields as needed ### Saving Changes 1. After making the necessary updates, click the **Save** button in the top-right corner. 2. 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: 1. In the left menu, expand **Segmentation**. 2. Click on **Segments** to open the segment management screen. 3. In the segment creation/editing view, locate the **Builder** section. 4. Click on **Select attribute** to open the attribute dropdown menu. 5. Scroll through the dropdown list and select **Player Bucket** as the attribute. 6. Select the relevant Player Bucket. 7. After selecting **Player Bucket** , configure the condition by specifying values or operators (e.g., equal to, greater than, less than). 8. This ensures only players within the defined bucket range meet the segment criteria. 9. Click **Add rule** to include additional conditions using other attributes. 10. Click **Save** in the top-right corner to apply the conditions. 11. If needed, click **Cancel** to discard changes. ### Validation Rules - **Overlapping Player Buckets** : - **Player Bucket Validation** :