Get Leaderboard Data

The get leaderboard data method retrieves detailed rankings and player information for a specific leaderboard. This is used to display current standings and player positions.

Overview

The getLeaderboardData method:

• Retrieves detailed leaderboard rankings
• Supports pagination for large leaderboards
• Returns player scores, ranks, and metadata
• Provides filtering and sorting options

Method Signature

public function getLeaderboardData(
    string $gameID, 
    string $leaderboardID, 
    int $collectionType = 1, 
    int $maxResults = 20, 
    int $page = 0
): array

Parameters

Required Parameters

• gameID (String) - The Game ID for the leaderboard
• leaderboardID (String) - The Leaderboard ID to retrieve data for

Optional Parameters

• collectionType (int) - Type of data to collect

  • Default: 1
  • Options: 1 (current rankings), 2 (historical data)

• maxResults (int) - Maximum number of results per page

  • Default: 20
  • Range: 1 to 100

• page (int) - Page number for pagination

  • Default: 0
  • Starts from 0

Return Value

Returns an array containing:

• Leaderboard metadata - Leaderboard details and settings
• Player rankings - Player scores, ranks, and information
• Pagination info - Total results and current page
• Statistics - High scores, averages, and participation data

Basic Usage

Get Basic Leaderboard Data

use Veniso\Moitribe\Sdk\modules\classes\MoitribeApi;

$moitribe = new MoitribeApi([
    'gameid' => 'your-game-id',
    'channelid' => 'your-channel-id',
    'playerid' => 'player-123'
]);

try {
    $leaderboardData = $moitribe->leaderboardRequestsHandler->getLeaderboardData(
        'your-game-id',
        'leaderboard-123'
    );
    
    echo "Leaderboard: " . $leaderboardData['leaderboard']->getName() . "\n";
    echo "Total Players: " . $leaderboardData['total_players'] . "\n";
    echo "Current Rankings:\n";
    
    foreach ($leaderboardData['rankings'] as $index => $player) {
        $rank = $index + 1;
        echo "$rank. " . $player->getName() . " - Score: " . $player->getScore() . "\n";
    }
    
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

Get Paginated Leaderboard Data

function getLeaderboardRankings($gameId, $leaderboardId, $page = 0, $pageSize = 50) {
    global $moitribe;
    
    try {
        $data = $moitribe->leaderboardRequestsHandler->getLeaderboardData(
            $gameId,
            $leaderboardId,
            1, // current rankings
            $pageSize,
            $page
        );
        
        return [
            'success' => true,
            'rankings' => $data['rankings'] ?? [],
            'total_players' => $data['total_players'] ?? 0,
            'current_page' => $page,
            'page_size' => $pageSize,
            'total_pages' => ceil(($data['total_players'] ?? 0) / $pageSize),
            'leaderboard_info' => $data['leaderboard'] ?? null
        ];
        
    } catch (Exception $e) {
        error_log("Error getting leaderboard data: " . $e->getMessage());
        return ['success' => false, 'error' => $e->getMessage()];
    }
}

// Usage
$page = isset($_GET['page']) ? (int)$_GET['page'] : 0;
$result = getLeaderboardRankings('your-game-id', 'leaderboard-456', $page);

if ($result['success']) {
    echo "Page " . ($result['current_page'] + 1) . " of " . $result['total_pages'] . "\n";
    echo "Total players: " . $result['total_players'] . "\n";
    
    foreach ($result['rankings'] as $index => $player) {
        $rank = ($result['current_page'] * $result['page_size']) + $index + 1;
        echo "$rank. " . $player->getName() . " - " . $player->getScore() . "\n";
    }
} else {
    echo "Error: " . $result['error'] . "\n";
}

Integration Examples

Leaderboard Display System

class LeaderboardDisplay {
    private $moitribe;
    private $gameId;
    
    public function __construct($moitribe, $gameId) {
        $this->moitribe = $moitribe;
        $this->gameId = $gameId;
    }
    
    public function displayLeaderboard($leaderboardId, $options = []) {
        try {
            $pageSize = $options['page_size'] ?? 20;
            $page = $options['page'] ?? 0;
            $showPlayerInfo = $options['show_player_info'] ?? true;
            $highlightPlayer = $options['highlight_player'] ?? null;
            
            $data = $this->moitribe->leaderboardRequestsHandler->getLeaderboardData(
                $this->gameId,
                $leaderboardId,
                1,
                $pageSize,
                $page
            );
            
            if (empty($data['rankings'])) {
                return $this->renderEmptyLeaderboard($data['leaderboard']);
            }
            
            return $this->renderLeaderboard($data, $highlightPlayer, $showPlayerInfo);
            
        } catch (Exception $e) {
            error_log("Leaderboard display error: " . $e->getMessage());
            return $this->renderError('Failed to load leaderboard');
        }
    }
    
    private function renderLeaderboard($data, $highlightPlayer, $showPlayerInfo) {
        $leaderboard = $data['leaderboard'];
        $rankings = $data['rankings'];
        
        $html = "<div class='leaderboard-container'>";
        $html .= "<header class='leaderboard-header'>";
        $html .= "<h2>" . htmlspecialchars($leaderboard->getName()) . "</h2>";
        $html .= "<div class='leaderboard-stats'>";
        $html .= "<span class='total-players'>{$data['total_players']} Players</span>";
        $html .= "<span class='last-updated'>Updated: " . date('M j, Y H:i', strtotime($leaderboard->getLastUpdated())) . "</span>";
        $html .= "</div>";
        $html .= "</header>";
        
        $html .= "<table class='leaderboard-table'>";
        $html .= "<thead><tr>";
        $html .= "<th>Rank</th><th>Player</th><th>Score</th>";
        
        if ($showPlayerInfo) {
            $html .= "<th>Level</th><th>Games Played</th>";
        }
        
        $html .= "</tr></thead>";
        $html .= "<tbody>";
        
        foreach ($rankings as $index => $player) {
            $rank = $index + 1;
            $isHighlighted = $highlightPlayer && $player->getId() === $highlightPlayer;
            $rowClass = $isHighlighted ? 'highlighted' : '';
            $rankClass = $this->getRankClass($rank);
            
            $html .= "<tr class='$rowClass $rankClass'>";
            $html .= "<td class='rank'>$rank</td>";
            $html .= "<td class='player'>" . htmlspecialchars($player->getName()) . "</td>";
            $html .= "<td class='score'>" . number_format($player->getScore()) . "</td>";
            
            if ($showPlayerInfo) {
                $html .= "<td class='level'>" . $player->getLevel() . "</td>";
                $html .= "<td class='games-played'>" . $player->getGamesPlayed() . "</td>";
            }
            
            $html .= "</tr>";
        }
        
        $html .= "</tbody></table>";
        $html .= "</div>";
        
        return $html;
    }
    
    private function renderEmptyLeaderboard($leaderboard) {
        return "<div class='empty-leaderboard'>
            <h2>" . htmlspecialchars($leaderboard->getName()) . "</h2>
            <p>No players have scored on this leaderboard yet.</p>
            <p>Be the first to set a high score!</p>
        </div>";
    }
    
    private function renderError($message) {
        return "<div class='error-message'>$message</div>";
    }
    
    private function getRankClass($rank) {
        if ($rank === 1) return 'rank-1';
        if ($rank === 2) return 'rank-2';
        if ($rank === 3) return 'rank-3';
        if ($rank <= 10) return 'top-10';
        if ($rank <= 100) return 'top-100';
        return '';
    }
}

// Usage
$display = new LeaderboardDisplay($moitribe, 'your-game-id');

// Display leaderboard with current player highlighted
$playerId = 'player-123';
echo $display->displayLeaderboard('leaderboard-456', [
    'highlight_player' => $playerId,
    'show_player_info' => true,
    'page_size' => 25
]);

Leaderboard Analytics

function analyzeLeaderboard($gameId, $leaderboardId) {
    global $moitribe;
    
    try {
        $data = $moitribe->leaderboardRequestsHandler->getLeaderboardData(
            $gameId,
            $leaderboardId,
            1,
            1000, // Get large sample for analytics
            0
        );
        
        $rankings = $data['rankings'] ?? [];
        $totalPlayers = count($rankings);
        
        if ($totalPlayers === 0) {
            return ['error' => 'No data available for analysis'];
        }
        
        // Calculate statistics
        $scores = array_column($rankings, 'score');
        $highScore = max($scores);
        $lowScore = min($scores);
        $averageScore = array_sum($scores) / $totalPlayers;
        $medianScore = $this->calculateMedian($scores);
        
        // Score distribution
        $scoreRanges = [
            '0-100' => 0, '101-500' => 0, '501-1000' => 0,
            '1001-5000' => 0, '5001-10000' => 0, '10001+' => 0
        ];
        
        foreach ($scores as $score) {
            if ($score <= 100) $scoreRanges['0-100']++;
            elseif ($score <= 500) $scoreRanges['101-500']++;
            elseif ($score <= 1000) $scoreRanges['501-1000']++;
            elseif ($score <= 5000) $scoreRanges['1001-5000']++;
            elseif ($score <= 10000) $scoreRanges['5001-10000']++;
            else $scoreRanges['10001+']++;
        }
        
        // Top performers
        $top10 = array_slice($rankings, 0, 10);
        $top100 = array_slice($rankings, 0, 100);
        
        return [
            'leaderboard_name' => $data['leaderboard']->getName(),
            'total_players' => $totalPlayers,
            'statistics' => [
                'high_score' => $highScore,
                'low_score' => $lowScore,
                'average_score' => round($averageScore, 2),
                'median_score' => $medianScore,
                'score_distribution' => $scoreRanges
            ],
            'top_performers' => [
                'top_10' => $top10,
                'top_100' => $top100
            ],
            'data_quality' => [
                'players_with_scores' => count(array_filter($scores, function($score) { return $score > 0; })),
                'zero_scores' => count(array_filter($scores, function($score) { return $score == 0; })),
                'unique_scores' => count(array_unique($scores))
            ]
        ];
        
    } catch (Exception $e) {
        error_log("Leaderboard analysis error: " . $e->getMessage());
        return ['error' => 'Failed to analyze leaderboard'];
    }
}

function calculateMedian($scores) {
    sort($scores);
    $count = count($scores);
    $middle = floor($count / 2);
    
    if ($count % 2 == 0) {
        return ($scores[$middle - 1] + $scores[$middle]) / 2;
    } else {
        return $scores[$middle];
    }
}

// Usage
$analytics = analyzeLeaderboard('your-game-id', 'leaderboard-456');

if (!isset($analytics['error'])) {
    echo "Analytics for: " . $analytics['leaderboard_name'] . "\n";
    echo "Total Players: " . $analytics['total_players'] . "\n";
    echo "High Score: " . $analytics['statistics']['high_score'] . "\n";
    echo "Average Score: " . $analytics['statistics']['average_score'] . "\n";
    echo "Median Score: " . $analytics['statistics']['median_score'] . "\n";
    
    echo "Score Distribution:\n";
    foreach ($analytics['statistics']['score_distribution'] as $range => $count) {
        echo "$range: $count players\n";
    }
} else {
    echo "Error: " . $analytics['error'] . "\n";
}

Error Handling

Common Error Scenarios

• Invalid leaderboard ID - Leaderboard doesn't exist
• Invalid game ID - Game doesn't exist
• Access denied - No permission to view leaderboard
• Pagination errors - Invalid page or page size parameters
• Network issues - API communication problems

Error Handling Example

function safeGetLeaderboardData($gameId, $leaderboardId, $page = 0, $pageSize = 20) {
    global $moitribe;
    
    try {
        if (empty($gameId) || empty($leaderboardId)) {
            throw new InvalidArgumentException("Game ID and Leaderboard ID are required");
        }
        
        if ($page < 0 || $pageSize < 1 || $pageSize > 100) {
            throw new InvalidArgumentException("Invalid pagination parameters");
        }
        
        $data = $moitribe->leaderboardRequestsHandler->getLeaderboardData(
            $gameId,
            $leaderboardId,
            1,
            $pageSize,
            $page
        );
        
        return [
            'success' => true,
            'data' => $data
        ];
        
    } catch (InvalidArgumentException $e) {
        return [
            'success' => false,
            'error' => 'Invalid input: ' . $e->getMessage()
        ];
    } catch (Exception $e) {
        error_log("Leaderboard data API error: " . $e->getMessage());
        return [
            'success' => false,
            'error' => 'Failed to retrieve leaderboard data'
        ];
    }
}

Best Practices

1. Implement Pagination

   • Use pagination for leaderboards with many players
   • Show reasonable page sizes (20-50 results)
   • Provide navigation between pages

2. Cache Leaderboard Data

   • Leaderboard data changes frequently during active periods
   • Cache for short periods (1-5 minutes)
   • Invalidate cache when new scores are submitted

3. Display Rankings Efficiently

   • Show top rankings prominently
   • Highlight current player's position
   • Use visual indicators for special ranks

4. Handle Large Datasets

   • Use pagination to avoid memory issues
   • Consider progressive loading for large leaderboards
   • Implement search and filtering options

Related Methods

• List Leaderboards - Find available leaderboards
• Submit Leaderboard Score - Submit scores to update rankings
• Submit Tournament Score - Submit tournament-specific scores