Running Totals
You can use Running Totals to process Events using the GameSparks scoring and ranking systems.
FAQs? You can review Frequently Asked Questions about working with Running Totals.
Running Totals for Simple and Advanced Leaderboards
It's important to understand right at the outset that there are two ways you can set up Running Totals for your Leaderboards:
1. Running Totals for Simple Leaderboards. You don't need to configure a specific Running Total when you're creating simple Leaderboards, because the Default Aggregation Type on the Event Attribute screen will have auto-created your Running Total as a System Generated Running Total:
- When you add an Event and configure Attributes for the Event, the Attributes automatically become available to be used as Running Totals for your Leaderboards - for how to do this, see Events.
Event Attributes not Available as Running Totals! There is an exception - If you select Used in Script as the Default Aggregation Type for an Event Attribute, then the Event/Attribute will not be available as a Running Total for your Leaderboards.
2. Running Totals for Advanced Leaderboards. For more advanced scenarios - such as a Leaderboard for "Most Improved Player in Last [x] Weeks" - you'll need to add new User Configured custom Running Totals:
- You can add User Configured Running Totals with the required Collectors on the Running Totals tab on the Configurator>Leaderboards page in the portal - see the following section for how to do this.
- If you want to build a team-based Leaderboard, you'll first need to create a User Configured custom Running Total that is linked to the Team type you want to use and then select that Team type for your Leaderboard - see Creating a Team Leaderboard.
IMPORTANT: Event/Attributes with Used in Script Default Aggregation Types ARE available for User Configured Running Totals! Event/Attributes with a Default Aggregation Type set to Used In Script are not available as Running Totals when you configure a Leaderboard's fields. However, they are available for setting up the Collectors for User Configured Running Totals. This is because the Calculation Type you select for a Running Total's Collector always overrides the Default Aggregation Type selected for the Event/Attribute.
Managing Running Total Configurations
The Running Totals tab on the Configurator>Leaderboards page displays a list of existing User Configured Running Totals and allows you to create new Running Totals and edit or delete (non-system type) existing ones:
You can use the following options (highlighted above):
- Add - Add a new Running Total.
- Edit Running Total.
- Delete Running Total.
When a player posts an Event to the platform, all Running Totals associated with the Event are processed. An important concept is that of a Group Attribute.
- Running Totals without a Group Attribute maintain a single record for each player that has submitted an Event that matches the criteria specified. This record can then be used within a Leaderboard to create various types of Leaderboards.
- When a Running Total has a Group Attribute(s) set, there is a record maintained for a group of Attributes by user.
Creating a Running Total Configuration
Click to Add a new User Configured Running Total. The page adjusts:
You can enter the details of the new Running Total:
- Short Code - Enter a Short Code of the Running Total, which is used by the API to allow you to identify which Running Total you want to call.
- Name - Enter the name of the Running Total, which is used to identify it in the portal if you have more than one Running Total.
- Event - Select the Event this Running Total will process - the Attributes configured for the Event you select will then be available for selection as Collectors for the Running Total.
- Team - Select the Type of Running Total (Player or Team). If a Team is not selected, then it's a Player Running Total
- Group By - Select which Attributes from the Event should be used for grouping. The Running Total will use this Attribute to group other Attributes. This will lead to a Running Total with an entry per Attribute/user combination. A typical use case would be where you want to track each player's highest score relative to each level of your game, not simply each player's highest score across all game levels.
Adding Collectors for Running Totals
If you want a User Configured Running Total to be available for use on your game's Leaderboards, you must add Collectors. To add Collectors to your Running Total, click Add:
Each Running Total Collector has the following fields:
- Attribute - Select the Event Attribute that the Running Total will capture and process.
- Calculation Type:
- Maximum - The Running Total will be created to track the maximum value posted.
- Minimum - The Running Total will be created to track the minimum value posted.
- Sum - The Running Total will be created to add all the values posted together.
- Count - The Running Total will be created to count the number of times the player has called the Event.
- Last - The Running Total will be created to track the last value posted.
- Supplemental - A Running Total will be created with no value calculated. You can use this when you want to store some extra information within the game context but do not want this to affect the Leaderboard ranking. (For example, in a racing game you can keep note of weather conditions on the track as well as player lap times but changing weather conditions do not affect the player's Leaderboard ranking.)
Filter Type & Filter Value - Allows you to define an optional filter for values tracked (<, >, * , and so on). Events posted that do not match the filter are ignored.
Calculation Type Overrides Default Aggregation Type! Note that the aggregation setting you select for a Running Total Collector's Calculation Type will override the Default Aggregation Type you originally selected for the Event/Attribute on which the Running Total is based. This means that even if you set up the Event/Attribute with a Default Aggregation Type set as Used In Script, it will be available to be used as a Collector for a User Configured Running Total.