Configure Leaderboards

To create a leaderboard, go to Ways to Earn > Leaderboards and select Create and configure the following options.

Leaderboard score

The Leaderboard Score defines how a user's score is calculated, and therefore how users are ranked in the leaderboard. When you configure the leaderboard score, set the Progress Counter to one of four options:

• User Attribute value: Users are ranked in leaderboards based on a user attribute value, like total_tokens_won. Select the attribute under Score User Attribute.

• +1 with every event: Users are ranked based on the number of times they trigger an event. Select the event under Desired Action.

  Each time a user triggers that event, their score increases by 1. You can also add further conditions to the event trigger. For example, if you select a bets_executed event and add a requirement that its amount property is greater than 50, the leaderboard ranks users by how many bets over 50 they have placed.

• Accumulative (by event field): Users are ranked based on the sum of a numeric field from an event. You specify an event (Desired Action), and then specify the Event field path you want to accumulate. For example, if your selected event is bet_executed and the field is amount, then users are ranked on the leaderboard based on the amount added up across every bet they place.

If you want a leaderboard score that resets to 0 periodically, use the +1 with every event or Accumulative (by event field) options. See Rewards below for how the rotation period controls this.

• Custom Expression: Users are ranked by a mathjs formula you write yourself. The formula runs each time the specified event occurs, and combines the user's existing score with details from that event to calculate the new score.

  Available variables are: currentProgress (the user's score before this event), event (the event that just occurred, including its payload), extras (context about the user and quest), and storage (read-only).

  For example, currentProgress + 1 adds one point per qualifying event.

Set Start At and End At to define when the leaderboard is active. If you leave these fields empty, the leaderboard runs indefinitely. The end date also shows in the Ends At column of the Leaderboards list.

Tiering

Tiering lets you configure a single leaderboard that automatically splits into separate leaderboards for different groups of users, based on a user attribute or segment you choose.

For example, without tiering, a leaderboard with 1,000 users would rank all 1,000 users against each other. If you tier that same leaderboard by level, and you have 5 levels, it splits into 5 separate leaderboards, one per level, so users only compete against others in their own level (around 200 users each).

Tiering is optional. If you don't need to split a leaderboard into groups, you can leave this section empty.

Before you set up tiering

Before you set up tiering, consider the following:

• Rewards apply per leaderboard, not per program.

  • For example, without tiering, a leaderboard might reward position 1 with 500 tokens, positions 2 to 5 with 250 tokens, and positions 6 to 10 with 150 tokens.

  • If you tier users into 5 leaderboards, this full set of rewards is given out 5 times over, once per leaderboard.

• Do not tier by an attribute that can take many different values, such as total quests completed. An attribute with too many possible values can split users into a large number of small leaderboards, leading to over-rewarding, since each leaderboard pays out its own set of rewards.

User Requirements

Specify which users are eligible to take part in this leaderboard.

• Add a requirement to define which user groups can access the leaderboard, for example Level ≥ 3.

• Select Require users to opt in before they can score if users must accept the leaderboard before they take part. You cannot change this setting after you save the leaderboard.

  When enabled, users see an option to accept or decline the leaderboard in your loyalty widget. If you’re configuring a leaderboard with a rotation period, users only need to accept once and they’ll stay.

Rewards

Specify the Rewards that users receive and how often these rewards are issued.

• Rotation Period: The Rotation Period determines when these rewards are given out. For example, if you select a rotation period of 1 week, users receive a reward every week for their leaderboard position.

  Options range from 10 minutes to 4 weeks, or Until completion.

  If you select Until Completion, your users are rewarded at the Ends At date you specify under Leaderboard Score.

• Rewards: Select Add Reward, then set a From position and to range and choose a reward type. See Loyalty Reward Types for more information on the different reward types and how to configure them.

The following table shows an example reward configuration for a leaderboard

What happens when a leaderboard rotates

On a leaderboard with a Rotation Period, users who took part in one cycle are automatically entered into the next, whether or not the leaderboard requires opt-in.

Each new cycle starts them at 0, or at their current attribute value on a User Attribute value leaderboard. They appear in the ranking from the start of the cycle and are rewarded for their final position, like any other participant.

When a cycle ends, its final results are saved: each participant's final score, position, and tier at the time rewards were given out. By default, only the most recent completed cycle is kept, for up to 30 days. To keep a longer history, contact your account manager. If you delete a leaderboard, its saved results are also deleted.

These past-cycle results do not appear in the loyalty widget or the dashboard. To show them in your own front end, use the Loyalty API:

• Get the archived cycles of a leaderboard lists the saved cycles of a leaderboard, newest first.

• Get the current player result in an archived cycle returns the player's final score, position, and opt-in time in one saved cycle.

• Get all leaderboards for the current player with includeEnded=true also lists leaderboards whose end date has passed.

Presentation

Specify how the leaderboard appears to users in the loyalty widget.

• Title: The title of the leaderboard in the loyalty widget.

• Description: The description of the leaderboard displayed to users. You can use markdown formatting to style descriptions with bold, italic, or more.

• Blocked description: The message shown to users who do not meet the participation criteria you set. For example, if your leaderboard is only for users on level 2 or higher, the blocked description could be You need to be level 2 or above to access and take part in the leaderboard.

• Score label: The label shown in the widget for what the leaderboard is ranking users by. For example, if the leaderboard ranks users by bets made, the score label could be Bets.

• Image: Upload an image for the leaderboard.

• Payload for event on click: Provide a URL to direct users to a specific location on your website or app when they select the leaderboard. For example, you can add a link that takes users directly to a live betting page if your leaderboard ranks are based on bets made.

Select Submit to save the leaderboard.