Content
Introduction
In this guide, you’ll learn…
What are Events?
Configuring Events in Hawk
One Time Events
Recurring Events
Creating Event Types
Configuring Activities
Sticky Events
Event Archiving Mechanism
A/B Testing Events
Table of Contents
Navigation Help for the User Guide
1. What are Events?
Events are a dynamic live-ops feature designed to engage players by offering them the opportunity to complete specific actions within a limited timeframe to earn rewards. These events create a sense of urgency and excitement, encouraging players to participate actively in the game.
At the core of each event are activities : the specific tasks or challenges that players must complete to qualify for rewards.
These activities are customisable, allowing to tailor the experience for different segments of players based on their behaviour, preferences, or progression level.
Events can be scheduled to reach players at different times, providing flexibility in how and when they are rolled out.
Events can also be leveraged in A/B Experiments to test and refine various aspects of gameplay and reward structures.
2. Configuring Events
When setting up an event configuration, you’ll define key parameters such as the event's duration and the specific player segments that will participate in the event.
This ensures that the event is tailored to run for the right amount of time and targets the appropriate groups of players.
In addition, Admin users can create event types to help the client developers interpret, which event is in use and the parameters the event requires.
Beyond these foundational settings, each game offers unique activities — like Objectives, Leaderboards, Races, and Collection Sets that can also be customised within Hawk.
2.1. Setting up Configurations
Under Configuration , you can create and configure your event (one-time or recurring), and you can also configure A/B Experiments for Events.
2.2. Event Structure
The structure of one-time and recurring events is largely similar, and both share several core components:
Event Fields : Shared fields are presented in a common table below, with clear indication of which apply to both event types or only one.
Parameters : Both types use the same base parameters. Recurring events may include additional advanced options. Learn More here.
Activities : Configured similarly for both types. More on activity setup here.
Recurring events include additional configuration for defining recurrence patterns.
To explore this further, see Recurring Events Configuration.
Event Fields table
Event Fields
| #### Field Name | Validations and Notes | Mandatory or Optional | Description |
| --- | --- | --- | --- |
| Name | Text input | MANDATORY | Name of the configuration |
| Priority | Numeric Input | MANDATORY | If a player is assigned to two different configurations of the same event type, they will typically receive the one with the higher priority. However, depending on the Event type configuration, the client can receive multiple configurations for the same event type. |
| Status | Dropdown options: - Active - Inactive - Temporarily Archived Default: Inactive | MANDATORY | Status of the Configuration. It is pre-selected to be inactive but can be altered. After a week of an Event having the Temporarily Archived status, it automatically gets the Permanently Archived status. See the Event Status Flow section below. |
| Availability | Dropdown options: - Test - Live Default: Test | MANDATORY | The availability of the configuration (test/live). It is pre-selected to be Test but can be altered. The “ Availability “ field has 2 value’s variants: 1. Test - served only to players with “ Test “ profile flag 2. Live - available for all players |
| Scheduling Time Type | Dropdown options: - Player’s local time - UTC (Coordinated Universal Time) Default: Player’s local time | MANDATORY | Time to send the Event to players. It is pre-selected to Player’s local time but can be altered. Events configured in Player Local Time will start to be served based on players location, and the UTC will start to be served to all players at the same time. |
| Preload At (Only for One-time Events) | Date/time picker Format: dd/mm/yyyy HH (24H) Default: Current time | MANDATORY | During the preload period , the event is delivered to the client. If the event type restricts serving only one event, the event defined for preload will still be served. Preloading begins at the configured preload start time. At that moment, players are assigned to segments, and this assignment is locked for the duration of the event. Even if players move to different segments afterward, they will continue to receive the preloaded event until the next preload cycle occurs.In the preload period, the event is served to the client. If event type has restriction to serve only one event, the preload will be still be served |
| Start At | Date/time picker Format: dd/mm/yyyy | MANDATORY | Determines when the event starts. |
| End Date (Only for One-time Events) | Dropdown options: - Last Activity - Custom Custom.End At: Date/time picker Format: dd/mm/yyyy HH (24H) | Custom.End At: OPTIONAL MANDATORY Only when Last Activity is selected. | Determines when the event ends. There are 2 options offered: - Last Activity: The Event will automatically finish when the last activity is finished. - Custom : Allows you to select a custom date to end the Event. Selecting this option will allow you to specify the date and time for ending the event. - When the “Custom“ option is selected, the End At field appears. |
| Event Type | Dropdown: - <event type 1> - <event type 2> - … - <event type n> | MANDATORY | Only one event type can be selected. However, one or more event types might be available for selection based on the number of events types configured for the game. This field identifies which type the event belongs to. Event type defines what parameters event has, as well as configuration mechanisms consistent across events that belong to that type, like max number of events returned to client. For a new Event type, you will have to request the Hawk team to configure it. The definition of the parameters for the new event type is a joint effort between Client Team, Business Analysts, and Product Managers. The new event type comprises a list of parameters that the Client Development Team will receive from Hawk in JSON format. Please agree on the parameters before requesting configuration of a new Event type. Properly designed parameters (on event or activity level) can simplify future growth of your events. Strong Recommendation: Discuss with the Hawk team before implementation of a new event to make sure that optimal solution will be achieved. |
| Segment Type | Dropdown: - All Players - Specific Segments Segments Field: Dropdown with multiple selection possibilities. | OPTIONAL Specific Segments.Segments: MANDATORY | The segment of users who will receive the Configuration. You can select either “All Players”, or create configurations for “Specific Segments”. When you select the “Specific Segments” option from the dropdown, another dropdown for selecting segments appears. From this dropdown, you can select multiple segments. If you select more than one segment, the system will use the logical operator OR to determine the recipients. To know more about segments, read the guide here |
| Occurrence preload offset (Only for Recurring Events) | Time picker Format: Hours, Minutes, Seconds | MANDATORY | Default: 1 Hour |
2.3. One Time event
One-time events are single-instance events that are configured to happen at a specific time, date, and duration. One-time events are designed for scenarios where a specific in-game activity is meant to run for a limited, predetermined period.
Perform the following steps to configure a one-time event:
Navigate to Configurations, and click [+Add Configurations] in the upper right corner.
Click One time event.
Fill in the fields to create a configuration:
Expand the Event fields
section above for more details.
Once you configure Event fields, you are ready to configure rest of your event properties.
Notice that Parameters of your event will appear after selection of event type parameter in event fields.
- Click the [+Serve the configuration to players toggle] to inactivate the configuration. Players will not be served this particular configuration and the parameters section will no longer be displayed.
Default: the toggle is on and the configuration is active and will be served to players.
If a player qualifies for an event where a configuration isn’t served, and there is another event of the same type with higher priority after the player was already allocated to the previous event, the player will not receive the second event’s configuration.
The main use case for this toggle is A/B experiment, where you can control which variant will receive the configuration, and which will not.
Parameters: The parameters section comprises a list of parameters with Name, Key, Value, Type, and Default Value fields that are defined in event.
You can modify the pre-defined Value fields however the rest of the fields can only be modified at the time of configuring the event type. Refer to the Parameters User Guide for more details.Next, click [+Add Activity] to configure your activity type. A new section will open where you will be able to select:
Once you’re done with your configuration, click [Save] on the bottom left side of the screen.
The event appears in the Events Configurations list. From the events list, you can edit, duplicate, and delete the event if needed. [
]
Players are assigned to a segment during the preload, and even if they change segments, they will stay in the previously assigned event until the next preload of an event!
Do you need support?
If you need support, you can obtain the Entity Variant ID from any Event. This will help the Hawk team identify your issue better and provide more accurate support!
2.3. Recurring Event
The recurring event feature allows you to configure events that automatically repeat over a specified time frame without the need for repeated manual configurations.
This feature is useful when you want to create events that span multiple days or occur periodically without setting each event individually.
The Recurring Events Configuration is explained in detail here.
What are Activities?
Activities are the building blocks of an event. They define what players actually do during the event. Whether it's completing objectives, competing in races, or climbing leaderboards, each activity type brings a unique challenge or reward. Activities help shape the player experience and keep events engaging and dynamic.
To learn more about the different activity types and how to configure them, head over to the Configuring Activities section.
2.4. Onboarding Event
Onboarding Events are designed to guarantee a complete player experience. Unlike recurring or one-off events, Onboarding Events are triggered at the right moment for the player (e.g., after reaching a specific level).
Since recurring events may not align with when a player reaches eligibility, onboarding events ensure they still get the full experience. For example, if a recurring event spans 2 days, a player reaching level 10 during cooldown would miss it. Onboarding Events solve this by triggering the event as soon as the player becomes eligible.
The Onboarding Events Configuration is explained in detail here.
2.5. Onboarding vs One-off vs Recurring Events
| Feature / Behaviour | Onboarding Events | One-off Events | Recurring Events |
| --- | --- | --- | --- |
| Purpose | Ensure full event experience when player qualifies | Run once globally at a scheduled time | Repeat periodically based on defined schedule |
| Triggered By | Player reaching a condition (e.g., level unlock) | Predefined date/time | Calendar-based recurrence |
| Start Time | Defined but triggered per player | Fixed UTC time | Fixed UTC time |
| Player Segmentation | Optional (e.g., by segment or all players) | Supported | Supported |
| Duration Field | Auto-calculated (sum of activity durations) | Manually defined | Manually defined |
| Can Be Deleted if Active | No | Yes | Yes |
| Activity Segmentation | Not supported (single CDN URL per onboarding event) | Supported | Supported |
| Supports Collection Set Activity | Not allowed | Allowed | Allowed |
| Appears in "In Use" References | Yes (events, activities, bundles, files, localisations) | Yes | Yes |
| CRUD Support | Yes (Delete disabled when Active) | Full CRUD | Full CRUD |
| Best Use Case | Personalized onboarding experience per player | Launches, limited-time offers | Weekly/monthly events |
3. Sticky Behaviour of Events
What Are Sticky Events?
Sticky Events ensure continuity in event participation even if a player changes segments. Once allocated, players remain in the even until it ends, even if a higher-priority event is available within the same event type.
Recurring Events: A recurring event typically spans a long duration, but players are only "stuck" to individual occurrences of the event. Once a player receives an occurrence, they continue to see and interact with it for the rest of that occurrence's duration, even if their segment changes. The sticky behaviour applies only to the occurrence, not the full event.
Event Type Constraint: The number active events at a time depend on the number specified in the “max number returned” field.
Applicability
Sticky Events apply to all activity types except Races (see Exceptions for Races below).
Onboarding Events do not exhibit sticky behaviour.
Preload Process
Preloading ensures event configurations are sent to the client before the event starts , preventing interruptions when segment changes occur. However, it does not affect the player's experience until the event becomes active.
Event Allocation Logic
Same Segment: Events follow a priority system, where ongoing events continue until they end.
Segment Change: Players keep receiving their allocated event even after transitioning to a different segment.
Handling Multiple Events: Sticky Events ensure smooth transitions across segment changes while maintaining proper event allocation.
Sticky Event Scenarios
Case 1: No Segment Change
Player starts in Segment A and receives Event 1.
A new event ( Event 2 ) with higher priority begins, but the player continues with Event 1 until it ends.
After Event 1 ends, the player receives Event 2.
Case 2: Player Changes Segments
Scenario 1: Sticky Event and Preload Not Served
Player starts in Segment A and receives Event 1 (preloaded).
During Event 1 , the player moves to Segment B.
Event 2 begins before Event 1 ends , but its Preload ends before Event 1 completes.
Result: Player receives Event 2 only after Event 1 ends , but without Preload data for Event 2.
Scenario 2: Sticky Event and Preload Served for Partial Duration
Player starts in Segment A and receives Event 2.
Event 3 begins before Event 2 ends.
The player moves to Segment C during the overlap of Events 2 and 3.
Preload for Event 3 remains active when the player changes segments but ends before Event 2 completes.
Result: Player continues receiving Event 2 , then receives Event 3 after Event 2 ends, with partial data.
Scenario 3: Sticky Event and Preload Served for Entire Duration
Player starts in Segment A and receives Event 2.
Before Event 3’s Preload starts , the player moves to Segment C.
Event 3 begins while Event 2 is still active.
Preload for Event 3 remains fully available until Event 2 ends.
Result: Player continues with Event 2 , then receives Event 3 with full Preload data.
Conclusion: Sticky Events persist across segment changes, but Preload availability depends on when the segment change occurs relative to event timing.
Exceptions for Races
Race-Specific Rules
Race activities follow a different set of rules compared to other activities. The Sticky Events feature does not apply in races to maintain the integrity and competitiveness of the event. In races, when a player changes segments, the currently active event is replaced by a new event.
Race Activity through an Example
In a non-sticky event system , event request triggers a recalculation , ensuring the system continuously adapts. It can either start serving a complete new configuration if player change the segment, or the same configuration but with recalculated bots speeds, if player’s attribute change
Race Activity Overview by Day
Day 1: The event begins, and segments are assigned. Requests trigger recalculations, but the player remains in the same segment.
Day 2: The player changes segments , prompting a recalculation. The new segment configuration is applied.
Day 3: Additional requests trigger segment recalculations. The player receives the updated race configuration.
Event End: The system finalises segment recalculations. Offline segment adjustments occur only in specific cases (Notification use only).
The race process depicted in the diagram is an example of a non-sticky event system. Every request for an event prompts a recalculation. This ensures that the system is always in a state of readiness to adapt.
Key Insights:
Non-Sticky Nature: Across all days, the system does not allow any event to persist without recalculation.
Dynamic Adaptability: The race process is designed to be responsive, recalculating and adjusting as needed to reflect the latest data.
Unsticking Player Allocation to an Event
Player allocation to an event is generally sticky, meaning once a player is allocated to an event, they remain in that allocation even if their segment changes.
However, for certain activities, it is possible to unstick a player's allocation. This action allows the player to be allocated again to a suitable event based on their current segment. The new allocation will also be sticky by default.
Non-Race Activities : Players remain in their initially allocated event unless explicitly unstuck.
Race Activities : Players are not automatically unstuck but can be manually unstuck to allow reallocation.
Note: Stickiness cannot be enabled or disabled as a setting. The only available action is to unstick a player's allocation, which permits reallocation based on updated conditions.
To unstick the enabled sticky events for non-race activities:
Navigate to Players > Search.
Select the relevant option from the first dropdown.
Search for the player based on any of the following attributes:
IDFV
Account ID
Install ID
User IDFrom the horizontal menu bar, click Events.
A list of allocated events appears for the player.Click the arrow to expand the relevant event.
4. Event Archiving Mechanism
The event archiving mechanism ensures that events transition through various states from creation until their archival, governed by specific timelines and automated processes. This mechanism supports the systematic retention and disposal of events, allowing for efficient resource management while maintaining accessibility to necessary data.
4.2. Event Status Flow
Active: The event begins in the active state and continues to remain active. During this period, it is fully functional, allowing event-related activities to occur. A daily archiving cronjob is scheduled to check for the event’s end date.
End Date and Grace Period: Upon reaching the event’s end date, the system initiates a “grace period” of 1 day. During this time, the event remains active while preparing for Temporary archival. The daily archiving cronjob continues to run, ensuring the event moves forward appropriately.
Temporary Archived: After the 1-day grace period, the event transitions to the Temporary Archive status. Events change their status to “temporary archive” if (time(now) >( end_date + grace period ) )While in the temporary archive, the event is no longer live for ongoing processes, but it remains accessible for administrative purposes. Players allocation remains untouched and can be restored.
Permanently Archived: After a 7-day period in the temporary archive, the event moves to the Permanent Archive. In this state, the event is stored long-term, no longer actively referenced by the system. However, archived data can be retrieved when necessary, to restore it the event must be duplicated as the permanently archived event is view only. Only configuration data can be restored, but not players allocations. Once event becomes permanently archived, it’s priority and name can be used in a new event.
4.3. Visual Representation of the Archiving Mechanism
The following diagram depicts the event lifecycle, from active to archived states, with archival timelines.
It provides an overview of the various transitions and the role of an automated cronjob in managing the process.
The diagram represents the event lifecycle and its transition phases:
Active (Live): The event starts and continues in an active state, with a scheduled “Daily deactivation cronjob” running.
End Date: Once the event’s end date is reached, the system initiates a 1-day “grace period.”
Temporary Archive: Following the grace period, the event is moved to a temporary archive.
Permanent Archive: After the temporary archiving phase of 7-days, the event is permanently archived for long-term storage. Here the clean up activities and event allocations occur.
4.4. Manual Status Change
Users can manually change status of event to “temporary archive”. An event which was manually archived will change it’s status to permanently archived after 8 days.
Perform the following steps to manually change the status of an event:
- On the Events Configuration page, click Archive for the relevant event.
Event which is manually temporarily archived will change it’s status to permanently archived after 8 days.
You can apply Status filters from the Filters section to find the events with the relevant status.
5. A/B Experiments in Events
Events are an A/B testable entity.
Check out this guide to learn how to create an experiment and assign your Event to an experiment.
Hawk A/B Experiments Notes:
If players are assigned to 2 experiments, they will first receive the one with higher priority.
You can add an Event to more than one experiment! In this case, the experiment with higher priority will be served first to players.
Currently, control variant applies universally across all experiments. This means that modifying the control variant in any experiment will automatically update it for all control variants across all experiments associated with this event. The base configuration (tab) serves as the control variant for all experiments within the event.
To do so, simply click [Add Experiment], and select another experiment.
Chunks 4
# **Introduction**
In this guide, you’ll learn…
- What are Events?
- Configuring Events in Hawk
- One Time Events
- Recurring Events
- Creating Event Types
- Configuring Activities
- Sticky Events
- Event Archiving Mechanism
- A/B Testing Events
**Table of Contents**
* * *
# Navigation Help for the User Guide
[https://tripledotstudios.atlassian.net/wiki/spaces/KB/whiteboard/4131192852?atl\_f=PAGETREE&whiteboard-linked-object=M3ul71m\_JN2hv9tqA\_D4J](https://tripledotstudios.atlassian.net/wiki/spaces/KB/whiteboard/4131192852?atl_f=PAGETREE&whiteboard-linked-object=M3ul71m_JN2hv9tqA_D4J)
# 1. What are Events?
**Events** are a dynamic **live-ops feature** designed to engage players by offering them the opportunity to complete specific actions within a limited timeframe to earn rewards. These events create a sense of urgency and excitement, encouraging players to participate actively in the game.
At the core of each event are **activities** : the specific tasks or challenges that players must complete to qualify for rewards.
These activities are customisable, allowing to tailor the experience for different segments of players based on their behaviour, preferences, or progression level.
Events can be scheduled to reach players at different times, providing flexibility in how and when they are rolled out.
Events can also be leveraged in **A/B Experiments** to test and refine various aspects of gameplay and reward structures.
# 2. Configuring Events
When setting up an event configuration, you’ll define key parameters such as the event's duration and the specific player segments that will participate in the event.
This ensures that the event is tailored to run for the right amount of time and targets the appropriate groups of players.
In addition, Admin users can create event types to help the client developers interpret, which event is in use and the parameters the event requires.
Beyond these foundational settings, each game offers unique activities — like Objectives, Leaderboards, Races, and Collection Sets that can also be customised within Hawk.
## 2.1. Setting up Configurations
Under **Configuration** , you can create and configure your event (one-time or recurring), and you can also configure A/B Experiments for Events.
## 2.2. Event Structure
The structure of **one-time** and **recurring** events is largely similar, and both share several core components:
- **Event Fields** : Shared fields are presented in a common [table below](https://tripledotstudios.atlassian.net/wiki/spaces/KB/pages/3583279198/Configuring+Events#Event-Fields-table), with clear indication of which apply to both event types or only one.
- **Parameters** : Both types use the same base parameters. _Recurring events_ may include additional advanced options. [Learn More here](https://tripledotstudios.atlassian.net/wiki/x/HoDV9Q?atlOrigin=eyJpIjoiZDg2OGU3ZDE4OGE4NDYxMWIwYmYxNzdjOGQ1MzdjYmEiLCJwIjoiYyJ9).
- **Activities** : Configured similarly for both types. [More on activity setup here](https://tripledotstudios.atlassian.net/wiki/x/CgCy2Q?atlOrigin=eyJpIjoiMjQ0MjFjNTdkMDEwNDU4Y2FkNDFiNThmYTA0ZmIwMTUiLCJwIjoiYyJ9).
Recurring events include additional configuration for defining recurrence patterns.
To explore this further, see [Recurring Events Configuration](https://tripledotstudios.atlassian.net/wiki/x/FgDU9Q?atlOrigin=eyJpIjoiZGQzZWFlZTI5Y2MyNGQxMTgyN2E0YzNjOWJhYzI2NmYiLCJwIjoiYyJ9).
### Event Fields table
Event Fields
| #### **Field Name** | **Validations and Notes** | **Mandatory or Optional** | **Description** |
| --- | --- | --- | --- |
| **Name** | Text input | MANDATORY | Name of the configuration |
| **Priority** | Numeric Input | MANDATORY | If a player is assigned to two different configurations of the same event type, they will typically receive the one with the higher priority. However, depending on the Event type configuration, the client can receive multiple configurations for the same event type. |
| **Status** | Dropdown options: - Active - Inactive - Temporarily Archived Default: Inactive | MANDATORY | Status of the Configuration. It is pre-selected to be inactive but can be altered. After a week of an Event having the Temporarily Archived status, it automatically gets the Permanently Archived status. See the Event [Status](https://tripledotstudios.atlassian.net/wiki/spaces/KB/pages/3583279198/Configuring+Events#4.2.-Event-Status-Flow) Flow section below. |
| **Availability** | Dropdown options: - Test - Live Default: Test | MANDATORY | The availability of the configuration (test/live). It is pre-selected to be Test but can be altered. The “ **Availability** “ field has 2 value’s variants: 1. Test - served only to players with “ **Test** “ profile flag 2. Live - available for all players |
| **Scheduling Time Type** | Dropdown options: - Player’s local time - UTC (Coordinated Universal Time) Default: Player’s local time | MANDATORY | Time to send the Event to players. It is pre-selected to Player’s local time but can be altered. Events configured in Player Local Time will start to be served based on players location, and the UTC will start to be served to all players at the same time. |
| **Preload At (Only for One-time Events)** | Date/time picker Format: dd/mm/yyyy HH (24H) Default: Current time | MANDATORY | During the **preload period** , the event is delivered to the client. If the event type restricts serving only one event, the event defined for preload will still be served. Preloading begins at the configured preload start time. At that moment, players are assigned to segments, and this assignment is locked for the duration of the event. Even if players move to different segments afterward, they will continue to receive the preloaded event until the next preload cycle occurs.In the preload period, the event is served to the client. If event type has restriction to serve only one event, the preload will be still be served |
| **Start At** | Date/time picker Format: dd/mm/yyyy | MANDATORY | Determines when the event starts. |
| **End Date (Only for One-time Events)** | Dropdown options: - Last Activity - Custom Custom.End At: Date/time picker Format: dd/mm/yyyy HH (24H) | **Custom.End At:** OPTIONAL MANDATORY Only when Last Activity is selected. | Determines when the event ends. There are 2 options offered: - **Last Activity:** The Event will automatically finish when the last activity is finished. - **Custom** : Allows you to select a custom date to end the Event. Selecting this option will allow you to specify the date and time for ending the event. - When the “Custom“ option is selected, the **End At** field appears. |
| **Event Type** | Dropdown: - \ - \ - … - \ | MANDATORY | Only one event type can be selected. However, one or more event types might be available for selection based on the number of events types configured for the game. This field identifies which type the event belongs to. Event type defines what parameters event has, as well as configuration mechanisms consistent across events that belong to that type, like max number of events returned to client. For a new Event type, you will have to request the Hawk team to configure it. The definition of the parameters for the new event type is a joint effort between Client Team, Business Analysts, and Product Managers. The new event type comprises a list of parameters that the Client Development Team will receive from Hawk in JSON format. Please agree on the parameters before requesting configuration of a new Event type. Properly designed parameters (on event or activity level) can simplify future growth of your events. **Strong Recommendation:** Discuss with the Hawk team before implementation of a new event to make sure that optimal solution will be achieved. |
| **Segment Type** | Dropdown: - All Players - Specific Segments Segments Field: Dropdown with multiple selection possibilities. | OPTIONAL **Specific Segments.Segments:** MANDATORY | The segment of users who will receive the Configuration. You can select either “All Players”, or create configurations for “Specific Segments”. When you select the “Specific Segments” option from the dropdown, another dropdown for selecting segments appears. From this dropdown, you can select multiple segments. If you select more than one segment, the system will use the logical operator OR to determine the recipients. To know more about segments, read the guide [here](/wiki/spaces/KB/pages/2884468783/Segmentation) |
| **Occurrence preload offset (Only for Recurring Events)** | Time picker Format: Hours, Minutes, Seconds | MANDATORY | Default: 1 Hour |
2.3. One Time event
**One-time events** are single-instance events that are configured to happen at a specific time, date, and duration. One-time events are designed for scenarios where a specific in-game activity is meant to run for a limited, predetermined period.
Perform the following steps to configure a one-time event:
1. Navigate to Configurations, and click **[+Add Configurations]** in the upper right corner.
2. Click One time event.
3. Fill in the fields to create a configuration:
Expand the [**Event fields**](https://tripledotstudios.atlassian.net/wiki/spaces/KB/pages/3583279198/Configuring+Events#Field-Name)  section above for more details.
 
Once you configure Event fields, you are ready to configure rest of your event properties.
Notice that Parameters of your event will appear after selection of event type parameter in event fields.
1. Click the [**+Serve the configuration to players toggle**] to inactivate the configuration. Players will not be served this particular configuration and the parameters section will no longer be displayed.
Default: the toggle is on and the configuration is active and will be served to players.
If a player qualifies for an event where a configuration isn’t served, and there is another event of the same type with higher priority after the player was already allocated to the previous event, the player will **not** receive the second event’s configuration.
The main use case for this toggle is A/B experiment, where you can control which variant will receive the configuration, and which will not.
1. **Parameters:** The parameters section comprises a list of parameters with Name, Key, Value, Type, and Default Value fields that are defined in event.
You can modify the pre-defined **Value** fields however the rest of the fields can only be modified at the time of configuring the event type. Refer to the [Parameters](https://tripledotstudios.atlassian.net/wiki/x/HoDV9Q?atlOrigin=eyJpIjoiZTY4OTg1MmZlMjFjNDMyNWE3NThjOTViZWQwOGFhOWUiLCJwIjoiYyJ9) User Guide for more details.
2. Next, click **[+Add Activity]** to configure your activity type. A new section will open where you will be able to select:
3. Once you’re done with your configuration, click **[Save]** on the bottom left side of the screen.
4. The event appears in the **Events Configurations** list. From the events list, you can edit, duplicate, and delete the event if needed. [ ]
**Players are assigned to a segment during the preload, and even if they change segments, they will stay in the previously assigned event until the next preload of an event!**
**Do you need support?**
If you need support, you can obtain the Entity Variant ID from any Event. This will help the Hawk team identify your issue better and provide more accurate support!
## 2.3. Recurring Event
The **recurring event** feature allows you to configure events that automatically repeat over a specified time frame without the need for repeated manual configurations.
This feature is useful when you want to create events that span multiple days or occur periodically without setting each event individually.
The Recurring Events Configuration is explained in detail [**here**](https://tripledotstudios.atlassian.net/wiki/x/FgDU9Q).
**What are Activities?**
Activities are the building blocks of an event. They define what players actually do during the event. Whether it's completing objectives, competing in races, or climbing leaderboards, each activity type brings a unique challenge or reward. Activities help shape the player experience and keep events engaging and dynamic.
To learn more about the different activity types and how to configure them, head over to the [**Configuring Activities**](https://tripledotstudios.atlassian.net/wiki/x/CgCy2Q) section.
## 2.4. Onboarding Event
Onboarding Events are designed to guarantee a complete player experience. Unlike recurring or one-off events, Onboarding Events are triggered at the right moment for the player (e.g., after reaching a specific level).
Since recurring events may not align with when a player reaches eligibility, onboarding events ensure they still get the full experience. For example, if a recurring event spans 2 days, a player reaching level 10 during cooldown would miss it. Onboarding Events solve this by triggering the event as soon as the player becomes eligible.
The Onboarding Events Configuration is explained in detail [**here**](https://tripledotstudios.atlassian.net/wiki/spaces/KB/pages/4367319345/Onboarding+Events?atlOrigin=eyJpIjoiZWU1OTZhNWI0MWU0NDYzMzk4MmU5ZDIxNGFkZjQ4NGIiLCJwIjoiYyJ9).
2.4. Onboarding Event
Onboarding Events are designed to guarantee a complete player experience. Unlike recurring or one-off events, Onboarding Events are triggered at the right moment for the player (e.g., after reaching a specific level).
Since recurring events may not align with when a player reaches eligibility, onboarding events ensure they still get the full experience. For example, if a recurring event spans 2 days, a player reaching level 10 during cooldown would miss it. Onboarding Events solve this by triggering the event as soon as the player becomes eligible.
The Onboarding Events Configuration is explained in detail [**here**](https://tripledotstudios.atlassian.net/wiki/spaces/KB/pages/4367319345/Onboarding+Events?atlOrigin=eyJpIjoiZWU1OTZhNWI0MWU0NDYzMzk4MmU5ZDIxNGFkZjQ4NGIiLCJwIjoiYyJ9).
## 2.5. Onboarding vs One-off vs Recurring Events
| **Feature / Behaviour** | **Onboarding Events** | **One-off Events** | **Recurring Events** |
| --- | --- | --- | --- |
| **Purpose** | Ensure full event experience when player qualifies | Run once globally at a scheduled time | Repeat periodically based on defined schedule |
| **Triggered By** | Player reaching a condition (e.g., level unlock) | Predefined date/time | Calendar-based recurrence |
| **Start Time** | Defined but triggered per player | Fixed UTC time | Fixed UTC time |
| **Player Segmentation** | Optional (e.g., by segment or all players) | Supported | Supported |
| **Duration Field** | Auto-calculated (sum of activity durations) | Manually defined | Manually defined |
| **Can Be Deleted if Active** | No | Yes | Yes |
| **Activity Segmentation** | Not supported (single CDN URL per onboarding event) | Supported | Supported |
| **Supports Collection Set Activity** | Not allowed | Allowed | Allowed |
| **Appears in "In Use" References** | Yes (events, activities, bundles, files, localisations) | Yes | Yes |
| **CRUD Support** | Yes (Delete disabled when Active) | Full CRUD | Full CRUD |
| **Best Use Case** | Personalized onboarding experience per player | Launches, limited-time offers | Weekly/monthly events |
* * *
# 3. Sticky Behaviour of Events
#### **What Are Sticky Events?**
Sticky Events ensure continuity in event participation even if a player changes segments. Once allocated, players remain in the even until it ends, even if a higher-priority event is available within the same event type.
- **Recurring Events:** A recurring event typically spans a long duration, but players are only "stuck" to individual occurrences of the event. Once a player receives an occurrence, they continue to see and interact with it for the rest of that occurrence's duration, even if their segment changes. The sticky behaviour applies only to the occurrence, not the full event.
- **Event Type Constraint:** The number active events at a time depend on the number specified in the “max number returned” field.
#### **Applicability**
- Sticky Events apply to all activity types **except Races** (see Exceptions for Races below).
- **Onboarding Events** do not exhibit sticky behaviour.
#### **Preload Process**
Preloading ensures event configurations are sent to the client **before the event starts** , preventing interruptions when segment changes occur. However, it does not affect the player's experience until the event becomes active.
#### **Event Allocation Logic**
- **Same Segment:** Events follow a priority system, where ongoing events continue until they end.
- **Segment Change:** Players keep receiving their allocated event even after transitioning to a different segment.
- **Handling Multiple Events:** Sticky Events ensure smooth transitions across segment changes while maintaining proper event allocation.
#### **Sticky Event Scenarios**
**Case 1: No Segment Change**
- Player starts in **Segment A** and receives **Event 1**.
- A new event ( **Event 2** ) with higher priority begins, but the player continues with **Event 1** until it ends.
- After **Event 1** ends, the player receives **Event 2**.
#### **Case 2: Player Changes Segments**
**Scenario 1: Sticky Event and Preload Not Served**
- Player starts in **Segment A** and receives **Event 1** (preloaded).
- During **Event 1** , the player **moves to Segment B**.
- **Event 2 begins before Event 1 ends** , but its **Preload ends before Event 1 completes**.
- **Result:** Player receives **Event 2 only after Event 1 ends** , but **without Preload data** for Event 2.
**Scenario 2: Sticky Event and Preload Served for Partial Duration**
- Player starts in **Segment A** and receives **Event 2**.
- **Event 3 begins before Event 2 ends**.
- The player **moves to Segment C** **during the overlap of Events 2 and 3**.
- **Preload for Event 3 remains active** when the player changes segments but ends before Event 2 completes.
- **Result:** Player **continues receiving Event 2** , then **receives Event 3 after Event 2 ends, with partial data**.
**Scenario 3: Sticky Event and Preload Served for Entire Duration**
- Player starts in **Segment A** and receives **Event 2**.
- Before **Event 3’s Preload starts** , the player **moves to Segment C**.
- **Event 3 begins while Event 2 is still active**.
- **Preload for Event 3 remains fully available until Event 2 ends**.
- **Result:** Player continues with **Event 2** , then receives **Event 3 with full Preload data**.
**Conclusion:** Sticky Events persist across segment changes, but Preload availability depends on when the segment change occurs relative to event timing.
### **Exceptions for Races**
#### **Race-Specific Rules**
Race activities follow a different set of rules compared to other activities. The Sticky Events feature does not apply in races to maintain the integrity and competitiveness of the event. In races, when a player changes segments, the currently active event is replaced by a new event.
#### Race Activity through an Example
In a **non-sticky event system** , **event request** triggers a **recalculation** , ensuring the system continuously adapts. It can either start serving a complete new configuration if player change the segment, or the same configuration but with recalculated bots speeds, if player’s attribute change
#### **Race Activity Overview by Day**
- **Day 1:** The event begins, and segments are assigned. Requests trigger recalculations, but the player remains in the same segment.
- **Day 2:** The player **changes segments** , prompting a recalculation. The new segment configuration is applied.
- **Day 3:** Additional requests trigger segment recalculations. The player receives the **updated race configuration**.
- **Event End:** The system finalises segment recalculations. **Offline segment adjustments occur only in specific cases (Notification use only).**
The race process depicted in the diagram is **an example** of a non-sticky event system. Every request for an event prompts a recalculation. This ensures that the system is always in a state of readiness to adapt.
**Key Insights:**
- **Non-Sticky Nature:** Across all days, the system does not allow any event to persist without recalculation.
- **Dynamic Adaptability:** The race process is designed to be responsive, recalculating and adjusting as needed to reflect the latest data.
### **Unsticking Player Allocation to an Event**
Player allocation to an event is generally sticky, meaning once a player is allocated to an event, they remain in that allocation even if their segment changes.
However, for certain activities, it is possible to **unstick** a player's allocation. This action allows the player to be allocated again to a suitable event based on their current segment. The new allocation will also be sticky by default.
- **Non-Race Activities** : Players remain in their initially allocated event unless explicitly unstuck.
- **Race Activities** : Players are not automatically unstuck but can be manually unstuck to allow reallocation.
> Note: Stickiness cannot be enabled or disabled as a setting. The only available action is to **unstick** a player's allocation, which permits reallocation based on updated conditions.
To unstick the enabled sticky events for non-race activities:
- Navigate to **Players \> Search**.
- Select the relevant option from the first dropdown.
- Search for the player based on any of the following attributes:
IDFV
Account ID
Install ID
User ID
- From the horizontal menu bar, click **Events**.
A list of allocated events appears for the player.
- Click the arrow to expand the relevant event.
4. Event Archiving Mechanism
The event archiving mechanism ensures that events transition through various states from creation until their archival, governed by specific timelines and automated processes. This mechanism supports the systematic retention and disposal of events, allowing for efficient resource management while maintaining accessibility to necessary data.
### 4.2. Event Status Flow
1. **Active:** The event begins in the active state and continues to remain active. During this period, it is fully functional, allowing event-related activities to occur. A daily archiving cronjob is scheduled to check for the event’s end date.
2. **End Date and Grace Period:** Upon reaching the event’s end date, the system initiates a “grace period” of 1 day. During this time, the event remains active while preparing for Temporary archival. The daily archiving cronjob continues to run, ensuring the event moves forward appropriately.
3. **Temporary Archived:** After the 1-day grace period, the event transitions to the Temporary Archive status. Events change their status to “temporary archive” if **(time(now) \>( end\_date + grace period** **) )**While in the temporary archive, the event is no longer live for ongoing processes, but it remains accessible for administrative purposes. Players allocation remains untouched and can be restored.
4. **Permanently Archived:** After a 7-day period in the temporary archive, the event moves to the Permanent Archive. In this state, the event is stored long-term, no longer actively referenced by the system. However, archived data can be retrieved when necessary, to restore it the event must be duplicated as the permanently archived event is view only. Only configuration data can be restored, but not players allocations. Once event becomes permanently archived, it’s priority and name can be used in a new event.
### 4.3. Visual Representation of the Archiving Mechanism
The following diagram depicts the event lifecycle, from active to archived states, with archival timelines.
It provides an overview of the various transitions and the role of an automated cronjob in managing the process.
The diagram represents the event lifecycle and its transition phases:
- **Active (Live):** The event starts and continues in an active state, with a scheduled “Daily deactivation cronjob” running.
- **End Date:** Once the event’s end date is reached, the system initiates a 1-day “grace period.”
- **Temporary Archive:** Following the grace period, the event is moved to a temporary archive.
- **Permanent Archive:** After the temporary archiving phase of 7-days, the event is permanently archived for long-term storage. Here the clean up activities and event allocations occur.
### 4.4. Manual Status Change
Users can manually change status of event to “temporary archive”. An event which was manually archived will change it’s status to permanently archived after **8** days.
Perform the following steps to manually change the status of an event:
1. On the **Events Configuration** page, click **Archive** for the relevant event.
Event which is manually temporarily archived will change it’s status to permanently archived after **8** days.
You can apply **Status** filters from the **Filters** section to find the events with the relevant status.
## 5. A/B Experiments in Events
Events are an A/B testable entity.
Check out [this guide](/wiki/spaces/KB/pages/3319988247/A+B+Experiments+in+Hawk) to learn how to create an experiment and assign your Event to an experiment.
**Hawk A/B Experiments Notes:**
- If players are assigned to 2 experiments, they will first receive the one with higher priority.
- You can add an Event to more than one experiment! In this case, the experiment with higher priority will be served first to players.
- Currently, control variant applies universally across all experiments. This means that modifying the control variant in any experiment will automatically update it for all control variants across all experiments associated with this event. The base configuration (tab) serves as the control variant for all experiments within the event.
- To do so, simply click **[Add Experiment]**, and select another experiment.
* * *