Skip to main content

Claim Tournament Rewards

The claim tournament rewards method allows players to claim their prizes and rewards after tournament completion. This is typically used when players finish in prize-eligible positions.

Overview​

The claimTournament method:

  • Claims tournament rewards for eligible players
  • Validates player's prize eligibility
  • Processes reward distribution
  • Returns status code indicating success or failure

Method Signature​

public function claimTournament(string $gameID, string $tournamentID): int

Parameters​

Required Parameters​

  • gameID (String) - The Game ID for the tournament
  • tournamentID (String) - The Tournament ID to claim rewards from

Return Value​

Returns an integer status code:

  • Positive value - Rewards claimed successfully
  • Zero or negative - Claim failed

Basic Usage​

Simple Reward Claim​

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

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

try {
    $result = $moitribe->tournRequestsHandler->claimTournament(
        'your-game-id',
        'tournament-123'
    );
    
    if ($result > 0) {
        echo "Rewards claimed successfully!\n";
        echo "Claim ID: " . $result . "\n";
    } else {
        echo "Failed to claim rewards\n";
        echo "Error code: " . $result . "\n";
    }
    
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

Reward Claim with Validation​

function claimTournamentRewards($gameId, $tournamentId, $playerId) {
    global $moitribe;
    
    try {
        // First check if player is eligible for rewards
        $tournamentData = $moitribe->tournRequestsHandler->getTournamentData(
            $gameId,
            $tournamentId,
            1, // current rankings
            100, // get enough results to find player
            0
        );
        
        $playerRanking = null;
        foreach ($tournamentData['rankings'] as $index => $player) {
            if ($player->getId() === $playerId) {
                $playerRanking = [
                    'rank' => $index + 1,
                    'player' => $player,
                    'prize' => $player->getPrize()
                ];
                break;
            }
        }
        
        if (!$playerRanking) {
            return ['success' => false, 'message' => 'Player did not participate in this tournament'];
        }
        
        if (!$playerRanking['prize']) {
            return ['success' => false, 'message' => 'Player is not eligible for rewards (rank: ' . $playerRanking['rank'] . ')'];
        }
        
        // Check if tournament has ended
        $tournament = $tournamentData['tournament'];
        if ($tournament->getStatus() !== 'ended') {
            return ['success' => false, 'message' => 'Tournament has not ended yet'];
        }
        
        // Claim rewards
        $result = $moitribe->tournRequestsHandler->claimTournament($gameId, $tournamentId);
        
        if ($result > 0) {
            return [
                'success' => true,
                'message' => 'Rewards claimed successfully',
                'claim_id' => $result,
                'prize' => $playerRanking['prize'],
                'rank' => $playerRanking['rank']
            ];
        } else {
            return ['success' => false, 'message' => 'Failed to claim rewards'];
        }
        
    } catch (Exception $e) {
        error_log("Reward claim error: " . $e->getMessage());
        return ['success' => false, 'message' => 'Server error occurred'];
    }
}

// Usage
$result = claimTournamentRewards('your-game-id', 'tournament-123', 'player-456');

if ($result['success']) {
    echo "Success: " . $result['message'] . "\n";
    echo "Rank: " . $result['rank'] . "\n";
    echo "Prize: " . $result['prize'] . "\n";
} else {
    echo "Error: " . $result['message'] . "\n";
}

Integration Examples​

Tournament Reward System​

class TournamentRewardManager {
    private $moitribe;
    private $gameId;
    
    public function __construct($moitribe, $gameId) {
        $this->moitribe = $moitribe;
        $this->gameId = $gameId;
    }
    
    public function getPlayerRewards($playerId) {
        try {
            // Get player's tournament history
            $history = $this->moitribe->tournRequestsHandler->getTournamentHistory($this->gameId);
            $availableRewards = [];
            
            foreach ($history as $tournament) {
                if ($tournament->getStatus() === 'ended') {
                    $eligibility = $this->checkRewardEligibility($tournament->getId(), $playerId);
                    
                    if ($eligibility['eligible'] && !$eligibility['claimed']) {
                        $availableRewards[] = [
                            'tournament_id' => $tournament->getId(),
                            'tournament_name' => $tournament->getName(),
                            'player_rank' => $eligibility['rank'],
                            'prize' => $eligibility['prize'],
                            'end_date' => $tournament->getEndDate()
                        ];
                    }
                }
            }
            
            return $availableRewards;
            
        } catch (Exception $e) {
            error_log("Error getting player rewards: " . $e->getMessage());
            return [];
        }
    }
    
    public function claimReward($tournamentId, $playerId) {
        try {
            // Validate eligibility before claiming
            $eligibility = $this->checkRewardEligibility($tournamentId, $playerId);
            
            if (!$eligibility['eligible']) {
                return [
                    'success' => false,
                    'message' => $eligibility['reason']
                ];
            }
            
            if ($eligibility['claimed']) {
                return [
                    'success' => false,
                    'message' => 'Rewards already claimed for this tournament'
                ];
            }
            
            // Claim the reward
            $result = $this->moitribe->tournRequestsHandler->claimTournament(
                $this->gameId,
                $tournamentId
            );
            
            if ($result > 0) {
                // Log the claim
                $this->logRewardClaim($tournamentId, $playerId, $eligibility['prize'], $result);
                
                return [
                    'success' => true,
                    'message' => 'Reward claimed successfully',
                    'claim_id' => $result,
                    'prize' => $eligibility['prize']
                ];
            } else {
                return [
                    'success' => false,
                    'message' => 'Failed to claim reward',
                    'error_code' => $result
                ];
            }
            
        } catch (Exception $e) {
            error_log("Reward claim error: " . $e->getMessage());
            return [
                'success' => false,
                'message' => 'Server error occurred'
            ];
        }
    }
    
    private function checkRewardEligibility($tournamentId, $playerId) {
        try {
            $tournamentData = $this->moitribe->tournRequestsHandler->getTournamentData(
                $this->gameId,
                $tournamentId,
                1,
                100,
                0
            );
            
            $playerRanking = null;
            foreach ($tournamentData['rankings'] as $index => $player) {
                if ($player->getId() === $playerId) {
                    $playerRanking = [
                        'rank' => $index + 1,
                        'player' => $player,
                        'prize' => $player->getPrize()
                    ];
                    break;
                }
            }
            
            if (!$playerRanking) {
                return ['eligible' => false, 'reason' => 'Player did not participate'];
            }
            
            if (!$playerRanking['prize']) {
                return [
                    'eligible' => false, 
                    'reason' => 'No prize for rank ' . $playerRanking['rank'],
                    'rank' => $playerRanking['rank']
                ];
            }
            
            // Check if already claimed (this would typically be tracked in your database)
            $claimed = $this->isRewardAlreadyClaimed($tournamentId, $playerId);
            
            return [
                'eligible' => true,
                'claimed' => $claimed,
                'rank' => $playerRanking['rank'],
                'prize' => $playerRanking['prize']
            ];
            
        } catch (Exception $e) {
            return ['eligible' => false, 'reason' => 'Error checking eligibility'];
        }
    }
    
    private function isRewardAlreadyClaimed($tournamentId, $playerId) {
        // Check your local database for existing claims
        // This is a placeholder - implement based on your system
        return false;
    }
    
    private function logRewardClaim($tournamentId, $playerId, $prize, $claimId) {
        $logData = [
            'claim_id' => $claimId,
            'tournament_id' => $tournamentId,
            'player_id' => $playerId,
            'prize' => $prize,
            'claimed_at' => date('Y-m-d H:i:s')
        ];
        
        error_log("Reward claimed: " . json_encode($logData));
    }
}

// Usage
$rewardManager = new TournamentRewardManager($moitribe, 'your-game-id');

// Get available rewards for player
$rewards = $rewardManager->getPlayerRewards('player-123');

echo "Available Rewards:\n";
foreach ($rewards as $reward) {
    echo "- {$reward['tournament_name']}: {$reward['prize']} (Rank: {$reward['player_rank']})\n";
}

// Claim a specific reward
$claimResult = $rewardManager->claimReward('tournament-456', 'player-123');

if ($claimResult['success']) {
    echo "Reward claimed: {$claimResult['prize']}\n";
} else {
    echo "Claim failed: {$claimResult['message']}\n";
}

Web Reward Claim Handler​

function handleRewardClaimRequest() {
    global $moitribe;
    
    if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
        http_response_code(405);
        echo json_encode(['error' => 'Method not allowed']);
        return;
    }
    
    $input = json_decode(file_get_contents('php://input'), true);
    
    if (!isset($input['tournament_id']) || !isset($input['player_id'])) {
        http_response_code(400);
        echo json_encode(['error' => 'Missing required fields']);
        return;
    }
    
    $tournamentId = $input['tournament_id'];
    $playerId = $input['player_id'];
    $gameId = $input['game_id'] ?? 'your-game-id';
    
    try {
        // Validate request
        if (empty($tournamentId) || empty($playerId)) {
            throw new InvalidArgumentException('Tournament ID and Player ID are required');
        }
        
        // Claim reward
        $result = $moitribe->tournRequestsHandler->claimTournament($gameId, $tournamentId);
        
        if ($result > 0) {
            http_response_code(200);
            echo json_encode([
                'success' => true,
                'message' => 'Reward claimed successfully',
                'claim_id' => $result
            ]);
        } else {
            http_response_code(400);
            echo json_encode([
                'success' => false,
                'message' => 'Failed to claim reward',
                'error_code' => $result
            ]);
        }
        
    } catch (InvalidArgumentException $e) {
        http_response_code(400);
        echo json_encode(['success' => false, 'message' => $e->getMessage()]);
    } catch (Exception $e) {
        http_response_code(500);
        echo json_encode(['success' => false, 'message' => 'Server error occurred']);
        error_log("Reward claim API error: " . $e->getMessage());
    }
}

// Route handler
if (strpos($_SERVER['REQUEST_URI'], '/api/tournament/claim-reward') !== false) {
    handleRewardClaimRequest();
}

Error Handling​

Common Error Scenarios​

  • Tournament not found - Invalid tournament ID
  • Player not eligible - Player didn't win a prize
  • Already claimed - Rewards already claimed by player
  • Tournament not ended - Tournament still in progress
  • Network issues - API communication problems

Error Handling Example​

function safeClaimReward($gameId, $tournamentId) {
    global $moitribe;
    
    try {
        if (empty($gameId) || empty($tournamentId)) {
            throw new InvalidArgumentException("Game ID and Tournament ID are required");
        }
        
        $result = $moitribe->tournRequestsHandler->claimTournament($gameId, $tournamentId);
        
        if ($result > 0) {
            return ['success' => true, 'claim_id' => $result];
        } else {
            $errorMessage = $this->getClaimErrorMessage($result);
            return ['success' => false, 'message' => $errorMessage, 'error_code' => $result];
        }
        
    } catch (InvalidArgumentException $e) {
        return ['success' => false, 'message' => $e->getMessage()];
    } catch (Exception $e) {
        error_log("Reward claim error: " . $e->getMessage());
        return ['success' => false, 'message' => 'Failed to claim reward'];
    }
}

function getClaimErrorMessage($errorCode) {
    switch ($errorCode) {
        case 0:
            return 'Failed to claim reward';
        case -1:
            return 'Tournament not found';
        case -2:
            return 'Player not eligible for rewards';
        case -3:
            return 'Rewards already claimed';
        case -4:
            return 'Tournament has not ended yet';
        default:
            return 'Unknown error occurred';
    }
}

Best Practices​

  1. Validate Eligibility

    • Check player's final ranking
    • Verify prize eligibility
    • Confirm tournament has ended

  2. Prevent Duplicate Claims

    • Track claimed rewards in your database
    • Check claim history before processing
    • Implement claim cooldowns if needed

  3. Provide Clear Feedback

    • Show specific prize information
    • Display player's final rank
    • Explain eligibility requirements

  4. Log Claim Events

    • Track all reward claims
    • Monitor for unusual patterns
    • Maintain audit trails