Skip to main content

Leaderboard SDK

The Leaderboard SDK provides methods to manage leaderboards and leaderboard entries for your applications on the GetJar platform.

Initialization​

import { Configuration, Leaderboard } from '@eightpointio/getjar-iap-sdk';

const config = new Configuration({
  basePath: 'url',
  headers: { 'x-api-key': 'key' }
});

const leaderboardClient = new Leaderboard(config);

Methods​

getLeaderboard​

Retrieves a leaderboard for an application.

Parameters:

  • appId (string): Application ID
  • isActive (boolean, optional): Filter by active status

Returns: Promise<ILeaderboard>

const leaderboard = await leaderboardClient.getLeaderboard('app-123', true);

getLeaderboardEntries​

Retrieves leaderboard entries with optional filtering and pagination.

Parameters:

  • appId (string): Application ID
  • filters (IQueryLeaderboardRequest, optional): Query parameters
    • scope (LeaderboardScope): Entry scope (top/nearby/all)
    • userId (string): Filter by user ID
    • range (number): Number of entries around user (for nearby scope)
    • limit (number): Items per page
    • page (number): Page number
    • sortOrder (SortOrderEnum): Sort order
    • startDate (string): Filter from date
    • endDate (string): Filter to date

Returns: Promise<PaginatedResponse<ILeaderboardEntry> & { userEntry?, userRank? }>

const entries = await leaderboardClient.getLeaderboardEntries('app-123', {
  scope: LeaderboardScope.TOP,
  limit: 10,
  page: 1
});

console.log(entries.items);
console.log(entries.userEntry);
console.log(entries.userRank);

getCurrentEntries​

Retrieves entries based on current scores.

Parameters:

  • appId (string): Application ID
  • filters (IQueryLeaderboardRequest, optional): Query parameters

Returns: Promise<PaginatedResponse<ILeaderboardEntry> & { userEntry?, userRank? }>

const entries = await leaderboardClient.getCurrentEntries('app-123', {
  limit: 20,
  page: 1
});

getTotalEntries​

Retrieves entries based on total scores.

Parameters:

  • appId (string): Application ID
  • filters (IQueryLeaderboardRequest, optional): Query parameters

Returns: Promise<PaginatedResponse<ILeaderboardEntry> & { userEntry?, userRank? }>

const entries = await leaderboardClient.getTotalEntries('app-123', {
  limit: 20,
  page: 1
});

getDailyEntries​

Retrieves entries for a specific date.

Parameters:

  • appId (string): Application ID
  • date (string): Date in YYYY-MM-DD format
  • filters (IQueryLeaderboardRequest, optional): Query parameters

Returns: Promise<PaginatedResponse<ILeaderboardEntry> & { userEntry?, userRank? }>

const entries = await leaderboardClient.getDailyEntries('app-123', '2025-01-15', {
  limit: 10
});

getUserEntry​

Retrieves a specific user's leaderboard entry.

Parameters:

  • appId (string): Application ID
  • userId (string): User ID

Returns: Promise<ILeaderboardEntry>

const entry = await leaderboardClient.getUserEntry('app-123', 'user-456');

getUserDailyHistory​

Retrieves a user's daily leaderboard history.

Parameters:

  • appId (string): Application ID
  • userId (string): User ID
  • filters (object, optional): Filter parameters
    • startDate (string): Start date (YYYY-MM-DD)
    • endDate (string): End date (YYYY-MM-DD)
    • page (number): Page number
    • limit (number): Items per page

Returns: Promise<PaginatedResponse<IDailyLeaderboardEntry>>

const history = await leaderboardClient.getUserDailyHistory('app-123', 'user-456', {
  startDate: '2025-01-01',
  endDate: '2025-01-31',
  limit: 31
});

Types​

LeaderboardScope​

enum LeaderboardScope {
  TOP = 'top',
  NEARBY = 'nearby',
  ALL = 'all'
}

ILeaderboard​

interface ILeaderboard {
  leaderboardId: string;
  appId: string;
  name: string;
  description?: string;
  category?: string;
  tags?: string[];
  resetSchedule?: {
    type: 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'SEASONAL' | 'CUSTOM';
    resetAt?: string;
    timezone?: string;
    preserveHistory?: boolean;
  };
  isActive: boolean;
  startAt?: Date;
  endAt?: Date;
  stats?: LeaderboardStats;
  metadata?: Record<string, any>;
  createdAt: Date;
  updatedAt: Date;
}

ILeaderboardEntry​

interface ILeaderboardEntry {
  leaderboardEntryId: string;
  leaderboardId: string;
  appId: string;
  userId: string;
  currentScore: number;
  totalScore: number;
  bestDailyScore?: number;
  currentRank?: number;
  totalRank?: number;
  displayName?: string;
  avatarUrl?: string;
  totalDaysPlayed: number;
  currentStreak: number;
  bestStreak: number;
  lastPlayDate?: string;
  metadata?: Record<string, any>;
  createdAt: Date;
  updatedAt: Date;
}

IDailyLeaderboardEntry​

interface IDailyLeaderboardEntry {
  dailyEntryId: string;
  leaderboardId: string;
  appId: string;
  userId: string;
  entryDate: string;
  score: number;
  rank?: number;
  displayName?: string;
  avatarUrl?: string;
  metadata?: Record<string, any>;
  platform?: Platform;
  createdAt: Date;
  updatedAt: Date;
}

LeaderboardStats​

interface LeaderboardStats {
  totalEntries: number;
  uniquePlayers: number;
  averageScore: number;
  medianScore: number;
  topScore: number;
  lastUpdatedAt: string;
}

PaginatedResponse​

interface PaginatedResponse<T> {
  items: T[];
  pagination: {
    total: number;
    page: number;
    limit: number;
    totalPages: number;
    hasNextPage: boolean;
    hasPreviousPage: boolean;
  };
}