--- title: "Configure Leaderboards" slug: "configure-leaderboards" updated: 2026-07-16T09:59:33Z published: 2026-07-16T09:59:33Z canonical: "docs.xtremepush.com/configure-leaderboards" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.xtremepush.com/llms.txt > Use this file to discover all available pages before exploring further. # 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 three 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_esecuted` 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. > [!TIP] > 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. Set **Start At** and **End At** to define when the leaderboard is active. If you leave these fields empty, the leaderboard runs indefinitely. ## 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). > [!TIP] > Tiering is optional. If you don't need to split a leaderboard into groups, you can leave this section empty. > [!WARNING] > 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 5 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 changes often, such as total quests completed. A highly dynamic attribute creates too many leaderboards, which can lead to over-rewarding users. ## Participation 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. When enabled, users see an option to accept or decline the leaderboard in your loyalty widget. This is useful for compliance scenarios. ## Rewards Specify the the **Rewards** that user 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**. > [!TIP] > 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](/documentation/docs/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 | From position | To position | Reward | | --- | --- | --- | | 1 | 1 | 100 tokens | | 2 | 5 | 50 tokens and 2 quests | | 6 | 10 | 30 tokens and 1 quest | | 11 | 25 | 20 tokens | | 26 | 50 | 15 tokens | | 51 | 75 | 10 tokens | | 76 | 100 | 2 quests | ## 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.