help.dot.vu
  1. Home
  2. The Editor
  3. Addons
  4. Leaderboard Addon
Searching...

Leaderboard Addon

Contents
  1. How To Setup
    1. Participation Data
    2. Multiple Participations
    3. Connect with Account Addon
    4. Leaderboard Mode
      1. Single
      2. Team
    5. Participating in Multiple Teams
      1. One team only
      2. Multiple teams
  2. Actions
  3. Datafields
  4. Presenting the Leaderboard
  5. One Addon, Multiple Pages

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:

  1. Open the Store on the left sidebar of the Editor
  2. Search for “Leaderboard”
  3. Drag the Leaderboard addon onto your project to enable it
  4. Create a new Leaderboard addon and give it a name, e.g. Quiz Top Scores
  5. 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:

Check Participation

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.

Participate

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.

Update Leaderboard (single mode only)

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.

Update Team Leaderboard (team mode only)

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.

Update Participants Leaderboard (team mode only)

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:

Number of Participants

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

Average Participant Score

This field changes value when:

  • (single) the Update Leaderboard action is executed
  • (team) the Update Participants Leaderboard action is executed

Participant Status

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.

Participant Score

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

Participant Ranking (single mode only)

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

Participant Ranking % (single mode only)

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

Participant Team (team mode only)

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.

Number of Teams (team mode only)

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

Average Team Score (team mode only)

This field changes value when:

  • (team) the Update Team Leaderboard action is executed

Presenting the Leaderboard

To present your Leaderboard:

  1. Add a Catalog Presenter from the tools menu on the left editor sidebar to anywhere on your project
  2. Select the Leaderboard from the drop-down on the Select Catalog popup
  3. 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.
  4. Now select Enter to edit… from its context menu, or simply double click the component, and design a leaderboard entry.
  5. 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:

  1. Open the Addons menu on the right sidebar of the Editor
  2. Enable the Account addon and click Edit Settings
  3. Click to enter the Account addon you wish to use, or create a new one
  4. Click the three dots menu on the top right corner
  5. Select Unbind from page and then click “Yes, unbind this Account addon”

Important: This change is irreversible.

Updated on November 22, 2021
Tagged: account addonaddonleaderboard

Was this article helpful?

Yes No

Related Articles

  • Custom API addon
  • Report Addon
  • Lists Addon
  • URL Data Addon
  • Datastore Addon
  • Referrals Addon

Contents

  1. How To Setup
    1. Participation Data
    2. Multiple Participations
    3. Connect with Account Addon
    4. Leaderboard Mode
      1. Single
      2. Team
    5. Participating in Multiple Teams
      1. One team only
      2. Multiple teams
  2. Actions
  3. Datafields
  4. Presenting the Leaderboard
  5. One Addon, Multiple Pages
© 2021 Dot Marketing ApS. All rights reserved.