# Build a leaderboard

> Rank players by their best score or fastest time and show a shared Top list across devices. Learn when a local score is enough, when you need a shared leaderboard, and how to build one with Firebase in PandaSuite.

https://docs.pandasuite.com/essentials/gamification/leaderboard/

**A leaderboard ranks players by a result (a high score, sorted from highest to lowest, or a best time, sorted from lowest to highest) and shows everyone the same Top list. This guide explains when you need a leaderboard and how to build one with PandaSuite and Firebase.**

#### In this guide

- Local score vs shared leaderboard
- Prerequisites
- Capture a result when the level or quiz ends
- Compile and sort the results
- Display the Top list and "Your score"
- Alternative: store results in Airtable

## Local score vs shared leaderboard

Before building anything, decide which experience you need:

- **Local score (single device).** The score is stored and displayed only on the player's own device, for example in a [variable](https://docs.pandasuite.com/essentials/data/variables/) or the PandaSuite database. This is enough to show a player their own best score or to drive a scenario, but each player only sees their own results. See [Score](https://docs.pandasuite.com/essentials/gamification/score/).
- **Shared leaderboard (across devices).** Results from every player are sent to a central source, compiled, sorted, and displayed as a common ranking. This is what you need for a public Top list, a contest, or a time-trial that compares players.

The rest of this guide builds a shared leaderboard with **Firebase**. If you prefer a simpler backend without user accounts, see the Airtable alternative at the end.

## Prerequisites

- A Firebase project connected with **Firebase Session**, plus an **Authentication** form so each result is tied to a user identity. See [Create a Firebase project](https://docs.pandasuite.com/essentials/integrations/create-a-firebase-project/) and [Save user data in Firebase](https://docs.pandasuite.com/essentials/integrations/save-user-data-in-firebase/).
- A way to measure the result you want to rank: a score you increment, or a timer you stop when the level ends. See [Score](https://docs.pandasuite.com/essentials/gamification/score/).

## Capture a result when the level or quiz ends

1. When the level or quiz finishes, compute the value you want to rank on (a final `score` or a `timeMs`) and store it in a variable. See [Score](https://docs.pandasuite.com/essentials/gamification/score/).
2. On the completion trigger, add the action **Interact with a database** > **Session Firebase** > **Modify the data**, to save the result (and the player's best value) on their user document.

## Compile and sort the results

> **Note**
>
> By default, **Firebase Session** rules limit each player to their own `users/{uid}` document, so the app cannot read other players' scores. The ranking is built in a shared, publicly readable `leaderboards` document, kept up to date by a server step (an automation or a Cloud Function) rather than on each device.

Set up an automation such as **Make (Integromat)**, **Zapier**, or a Cloud Function to keep the ranking up to date:

1. When the level ends, PandaSuite sends the result to the automation, using the [HTTP](https://docs.pandasuite.com/essentials/components/http/) or webhook component (`alias`, `score`, `levelId`, `finishedAt`).
2. The automation adds this new result to the set of results already saved.
3. It sorts the full set, best first (scores descending, times ascending), and keeps only the Top N.
4. It saves this Top N as a single `leaderboards` document that the app reads to display the ranking.

See [Connect to Make (Integromat)](https://docs.pandasuite.com/essentials/integrations/connect-to-make-integromat/).

## Display the Top list and "Your score"

- Insert a [Collection](https://docs.pandasuite.com/essentials/data/collection/) component and bind it to the sorted Top list. In the item template, bind text blocks to `alias` and `score`.
- To control the order inside the app, use [Sort a collection](https://docs.pandasuite.com/essentials/data/sort-a-collection/) (Descending for high scores, Ascending for best times).
- To always show players their own result even when they are not in the Top list, bind a separate text block to their personal best, from **Firebase Session** data.

### Verify the flow

- Play a level or quiz, finish it, and confirm the result reaches Firestore.
- Check that the compiled Top list updates.
- Open the leaderboard screen: you should see a sorted Top list and your own best result, even when you are outside the Top N.

## Alternative: store results in Airtable

If you do not need user accounts, Airtable is simpler to set up and to moderate by hand:

1. Create a table with one row per result (`alias`, `score`, `levelId`, `finishedAt`).
2. Save each result from the app with the [HTTP](https://docs.pandasuite.com/essentials/components/http/) component. For secure writes, send through an automation or proxy rather than exposing a write key in the app.
3. Display the table with a [Collection](https://docs.pandasuite.com/essentials/data/collection/) component. Airtable can return records already sorted and limited through its API, so you can often skip the server-side sort.

See [Connect to Airtable](https://docs.pandasuite.com/essentials/integrations/connect-to-airtable/).

## See also

- [Score](https://docs.pandasuite.com/essentials/gamification/score/)
- [Sort a collection](https://docs.pandasuite.com/essentials/data/sort-a-collection/)
- [Save user data in Firebase](https://docs.pandasuite.com/essentials/integrations/save-user-data-in-firebase/)
- [Connect to Airtable](https://docs.pandasuite.com/essentials/integrations/connect-to-airtable/)