Skip to main content

Quickstart

Get your first leaderboard running in 5 minutes.

Prerequisites​

  • An ASCND account (sign up free)
  • Node.js 18+ (for TypeScript SDK)

Step 1: Create a Leaderboard​

  1. Log in to your ASCND Dashboard
  2. Click "Create Leaderboard"
  3. Configure your leaderboard:
    • Name: e.g., "High Scores"
    • Sort Order: Higher is better (or lower for time-based)
    • Reset Period: All-time, daily, weekly, or monthly
  4. Copy your Leaderboard ID (starts with lb_)

Step 2: Get an API Key​

  1. Go to API Keys in the dashboard
  2. Click "Create API Key"
  3. Give it a name (e.g., "Game Client")
  4. Copy the key - you won't see it again!
Keep your API key secret

Never expose your API key in client-side code that gets shipped to players. Use it server-side or in your game's backend.

Step 3: Install the SDK​

npm install @ascnd/client

Step 4: Submit Your First Score​

import { createClient } from '@ascnd/client';

// Initialize the client
const client = createClient({
  apiKey: process.env.ASCND_API_KEY,
});

// Submit a score
async function submitScore(playerId: string, score: number) {
  const result = await client.submitScore({
    leaderboardId: 'lb_your_leaderboard_id',
    playerId: playerId,
    score: BigInt(score),
  });

  console.log(`Score submitted! Rank: #${result.rank}`);

  if (result.isNewBest) {
    console.log('New personal best!');
  }

  return result;
}

// Example usage
await submitScore('player_alice', 50000);

Step 5: Fetch the Leaderboard​

// Get top 10 scores
const leaderboard = await client.getLeaderboard({
  leaderboardId: 'lb_your_leaderboard_id',
  limit: 10,
});

console.log('Top scores:');
for (const entry of leaderboard.entries) {
  console.log(`#${entry.rank} - ${entry.playerId}: ${entry.score}`);
}

Step 6: Check a Player's Rank​

// Get a specific player's position
const playerRank = await client.getPlayerRank({
  leaderboardId: 'lb_your_leaderboard_id',
  playerId: 'player_alice',
});

if (playerRank.rank) {
  console.log(`Player rank: #${playerRank.rank}`);
  console.log(`Percentile: ${playerRank.percentile}`);
} else {
  console.log('Player not on leaderboard yet');
}

Next Steps​