#
**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