The Leaderboard addon allows you to register your users’ scores from marketing games, and then present a leaderboard of the highest scores. It’s a simple but powerful addon to any marketing game.
How To Setup
To enable and configure the Leaderboard Addon:
- Open the Store on the left sidebar of the Editor
- Search for “Leaderboard”
- Drag the Leaderboard addon onto your project to enable it
- Create a new Leaderboard addon and give it a name, e.g. Quiz Top Scores
- Check the settings below and configure the addon
Participation Data
Participation data is data that is collected with the Participate action.
Apart from score and ranking, you can define other participation data fields. You will be able to collect data for these fields when using the Participate action, as well as display them both for the current participant, as well as on the leaderboard.
Examples of common participation data fields you might wish to add and use:
- a username for public display
- an avatar for public display, uploaded or selected
- the number of times the user played
Multiple Participations
Default: Update participation
There are two options for when a user participates more then once:
- Update participation – all collected participation data and score for that user will are overwritten with the new values
- Create new participation – a new participation is created, independent from the previous participations
Connect with Account Addon
Default: None
A User ID is required for a user to have an entry on a leaderboard. This User ID is used to identify the user’s participation or participations, so that they may for example be updated.
You can however choose to connect with an instance of the Account addon. Make sure an instance of the Account addon is enabled and you will be able to select it on the drop-down of this setting.
Then simply follow the instructions on how to setup and use the Account addon.
Leaderboard Mode
Default: Single
Single
In this mode, the leaderboard shows the individual participations with highest scores.
Team
Team mode is used when individual participants belong to a team which they are playing and submitting their scores for.
If you enable team mode:
- the Participate action will require a Team value to be provided
- the leaderboard data field will include different values: Team Name, Team score, Team Average Score, Ranking, Ranking % and Number of Participants
- an extra participants leaderboard data field is provided which can show individual participants, including filtering and ranking for a specific team.
- the data fields Participant Team, Number of Teams and Average Team Score become available
Participating in Multiple Teams
Requirements: only available if the multiple participations option is set to Update Participation, and the leaderboard mode is set to Teams.
Default: One team only
One team only
In this mode, when a user who has already participated in one team then participates on a different team, their previous participation will be erased and the score and number of participants respectfully deducted from the original team.
Multiple teams
In this mode, a user can participate on multiple teams and each time they participate the participation is updated accordingly.
Actions
Once your Leaderboard addon is enabled and configured, you get access to the following actions which you can use to interact with the addon:
Get the status and last participation score for the current user, updating the following Leaderboard addon data fields:
- Participant Status
- Participant Score
- Participant Ranking (if Single mode is enabled)
- Participant Ranking % (if Single mode is enabled)
- Participant Team (if Team mode is enabled)
| Outcomes | Has not participated. You can run actions if the user has not yet participated. Has participated. You can run actions if the user has already participated. |
Creates a new leaderboard participation for User ID with the data defined in Participation data; or if the current user has already participated and the multiple participations setting is set to update participation, then it updates the existing participation.
The Participate action will also update the following Leaderboard addon data fields: Participant Status, Participant Score, Participant Ranking, Participant Ranking % and Participant Team (if team mode is enabled).
| Settings | User ID. Select a value from a data field to be the User ID that will identify the participation. This setting only appears if the Leaderboard addon is not connected to an Account addon. Data. Select values for each data field of those you have defined under Participation Data if any, in the Leaderboard Addon settings. Team. Select a value to be the team the user is participating for. This setting only appears if the leaderboard mode setting is set to Team. |
Updates the leaderboard in single mode with the latest (max. 10) top scoring participations and their respective data. Also populates Number of Participants and Average Participant Score data fields.
Updates the teams leaderboard in team mode with the latest (max. 10) top scoring teams and their respective data. Also populates Number of Teams and Average Team Score data fields.
Updates the participants leaderboard in team mode with the latest (max. 10) top scoring participations and their respective data. You can use the Team setting to show and rank only participants from a given team. Also populates Number of Participants and Average Participant Score data fields.
| Settings | Team. You can pass a team name to filter for. If you do, the team participants leaderboard will only show and rank participants from the given team. You can call this action again with a different team to change which team you are viewing. If you call this action with no team (empty text) it returns the top participants regardless of team. |
Datafields
The following data fields are available on the Leaderboard addon:
The Number of Participants data field shows the total number of individual participations so far, regardless if single or team mode. This field changes value when:
- (single) the Update Leaderboard action is executed
- (team) the Update Participants Leaderboard action is executed
This field changes value when:
- (single) the Update Leaderboard action is executed
- (team) the Update Participants Leaderboard action is executed
The Participant Status data field informs if the user has already participated or not.
This field changes value when:
- the Check Participation action is executed
- or the Participate action is executed
| Unknown | Check Participation action has not been executed yet. |
| Has Participated | The user has participated at least once. |
| Has Not Participated | The user has no participations. |
The Participant Score data field presents the participant’s most recently recorded score. This field changes value when:
- the Check Participation action is executed and the user has participated
- or the Participate action is executed
The Participant Ranking data field presents the participant’s most recently recorded ranking. This field changes value when:
- the Check Participation action is executed and the user has participated
- or the Participate action is executed
The Participant Ranking data field presents the participant’s most recently recorded ranking in top percentage (e.g. You are among top 5%). This field changes value when:
- the Check Participation action is executed and the user has participated
- or the Participate action is executed
This data field displays the participant’s most recently recorded participation’s team. It is only available if the leaderboard mode is set to Team.
The Number of Teams data field shows the total number of teams that have participated so far (team mode only). This field changes value when:
- (team) the Update Team Leaderboard action is executed
Presenting the Leaderboard
To present your Leaderboard:
- Add a Catalog Presenter from the tools menu on the left editor sidebar to anywhere on your project
- Select the Leaderboard from the drop-down on the Select Catalog popup
- Right-click the newly added Catalog Presenter and rename it to for example HighScores. This will be important when selecting data fields on the next step.
- Now select Enter to edit… from its context menu, or simply double click the component, and design a leaderboard entry.
- You now have access to a set of data fields from the component you named on step 3 to populate each entry.
For example when using Rich Text you can add [data] in between the text and if you named the component HighScores, you can now search and find “Participant Score from HighScores”, to show that value within the text.
The set of data fields available to populate leaderboard entries will be different for single mode and for the two leaderboards available in team mode.
Leaderboard entry data fields available in Single mode
- Participant Score
- Participant Ranking
- Participant Ranking (%)
- All other fields defined in the Participation data setting
Leaderboard entry data fields available in Team mode’s Team Leaderboard:
- Team Name
- Team Score
- Team Average Score (internal per Team)
- Team Ranking
- Team Ranking (%)
- Number of Team Participants
Leaderboard entry data fields available in Team mode’s Participants Leaderboard:
- Team Name
- Participant Score
- Participant Ranking
- Participant Ranking (%)
- All other fields defined in the Participation data setting
One Addon, Multiple Pages
You can unbind a Leaderboard addon from a project, so that it can be enabled on any number of projects at the same time. You should only do this if you wish to use a Leaderboard addon in multiple projects.
To allow users to participate in the same leaderboard across marketing games and campaigns:
- Open the Addons menu on the right sidebar of the Editor
- Enable the Account addon and click Edit Settings
- Click to enter the Account addon you wish to use, or create a new one
- Click the three dots menu on the top right corner
- Select Unbind from page and then click “Yes, unbind this Account addon”
Important: This change is irreversible.