Leaderboards

The leaderboards capability submits scores to your Lens's leaderboard and opens Snapchat's own leaderboard panel, where players see how they rank.

Only Lenses that have a leaderboard set up see the capability. Check snapchat.isSupported('leaderboards') after init(), and hide leaderboard features when it's false.

Submit a score

const { bestScore } = await snapchat.leaderboards.submitScore({
  leaderboardId: 'main',
  score: 1200,
});

• leaderboardId is the ID of a board set up for your Lens.
• score must be an integer. Any other number rejects with ERR_INVALID_PARAMS, so round times and distances first.
• Higher scores rank first. If lower is better, as in a time trial, pass ordering: 'ascending' with every submission.

bestScore in the result is the player's best score on that board, as the server recorded it. It can be missing, so treat it as optional:

// A time trial: lower is better, so say so on every submission.
const { bestScore } = await snapchat.leaderboards.submitScore({
  leaderboardId: 'fastest-lap',
  score: Math.round(lapSeconds * 1000), // integers only
  ordering: 'ascending',
});
if (bestScore !== undefined) bestLabel.textContent = `Best: ${bestScore} ms`;

Show the leaderboard

show() opens the Lens's leaderboard panel. Submit a score first, so the panel has data to show. show() rejects with ERR_INTERNAL when the panel can't open or the board's data doesn't load in time.

At game over

Submit the final score, then show the leaderboard, and keep the game going if either call fails:

async function showLeaderboard(score) {
  if (!snapchat.isSupported('leaderboards')) return;
  try {
    await snapchat.leaderboards.submitScore({
      leaderboardId: 'main',
      score: Math.round(score),
    });
    await snapchat.leaderboards.show();
  } catch (e) {
    console.warn('Leaderboard unavailable:', e.message);
  }
}

LeaderboardsAPI in the API reference lists every parameter and return value.