How to Set Up a Vote Callback

[Rage]

RSPS Vote Callback Setup Guide

Super Detailed – Database Driven – RSPS & RuneTopic Friendly

---

What This Guide Covers

This guide will walk you through every step of setting up a vote callback system for your RSPS, using a database-driven method. There is enough detail here that you can follow it even if you have never set up a callback before.

By the end, you will have:

• A MySQL table that stores votes.
• A PHP callback script that your toplist calls when a player votes.
• A clear understanding of how to hook that table into your RSPS claim system (claimvote command, login check, etc).
• Testing steps and troubleshooting tips, so you can confirm everything works.

This is designed to work nicely alongside your RuneTopic setup or other RSPS tools.

Step 0 – Requirements

Before you start, make sure you have:

• Web hosting with PHP and MySQL (this can be the same host as your website).
• Access to phpMyAdmin or another MySQL client.
• Your RSPS database details (host, username, password, database name).
• Access to your RSPS source code to add the claimvote logic.
• Access to your toplist control panel where you can set the callback URL.

Tip: Your RSPS server usually already connects to a MySQL database for things like highscores, vote logs, etc. We will use the same connection or a similar one.

Step 1 – Create the Vote Table in MySQL

We need a table that will store each incoming vote. The callback script will insert one row per vote.

1.1 – SQL to Create the Table

In phpMyAdmin or your MySQL tool, select your RSPS database (for example server), go to the SQL tab, and run this:

CREATE TABLE IF NOT EXISTS vote_rewards (
    id INT AUTO_INCREMENT PRIMARY KEY,
    username VARCHAR(32) NOT NULL,
    given TINYINT(1) NOT NULL DEFAULT 0,
    timestamp INT NOT NULL,
    site_id INT DEFAULT 0
);
    

1.2 – What Each Column Means

• id – Unique ID for each vote (makes it easy to update rows).
• username – The RSPS username that voted.
• given – Whether the reward has been claimed:
  • 0 = Vote is unclaimed (player has not claimed reward yet).
  • 1 = Vote is claimed (reward already given).
• timestamp – When the vote was received (UNIX time, seconds since 1970).
• site_id – Optional, useful if you add multiple toplists later (1 = Site A, 2 = Site B, etc).

Important: Do not change the column names unless you also change them in the PHP script and in your RSPS claimvote code.

Step 2 – Create the PHP Callback Script

This PHP file will be called by your toplist when a player finishes voting. Its job is very simple:

• Read the username from the request (for example, ?user=SomeName).
• Check that the request came from your toplist IP.
• Insert a new row into vote_rewards with given = 0.

2.1 – Full Callback Script (with Configuration)

Create a new file on your PC called callback.php and paste this inside:

<?php
// ---------------------------------------------------------
// CONFIGURATION SECTION – CHANGE THESE VALUES
// ---------------------------------------------------------

// Database connection details
$dbHost = "localhost";     // Usually 'localhost'
$dbUser = "root";          // Your MySQL username
$dbPass = "password";      // Your MySQL password
$dbName = "server";        // Your RSPS database name

// Toplist IPs that are allowed to call this script
$allowedIps = array(
    "123.123.123.123"      // Replace with your toplist's real IP
    // You can add more IPs here if needed
);

// Parameter name used by the toplist for username
// Common ones are: 'user', 'username', 'player'
$usernameParam = "user";

// ---------------------------------------------------------
// DO NOT CHANGE BELOW UNLESS YOU KNOW WHAT YOU ARE DOING
// ---------------------------------------------------------

// 1. Check that we got a username parameter
if (!isset($_GET[$usernameParam])) {
    // No username provided
    die("No username specified");
}

$username = trim($_GET[$usernameParam]);

// Basic sanity check
if ($username === "") {
    die("Empty username");
}

// 2. Validate the IP address of the caller
$remoteIp = $_SERVER["REMOTE_ADDR"];

if (!in_array($remoteIp, $allowedIps)) {
    // Request is NOT from an allowed IP
    // You can log this if you want
    die("Invalid IP");
}

// 3. Connect to the MySQL database
$connection = mysqli_connect($dbHost, $dbUser, $dbPass, $dbName);

if (mysqli_connect_errno()) {
    // Database connection failed
    die("Database connection failed: " . mysqli_connect_error());
}

// 4. Prepare data for insertion
$timestamp = time();
$siteId    = 1; // Optional: set this per toplist if you use multiple sites

// 5. Use a prepared statement to insert the row safely
$stmt = mysqli_prepare(
    $connection,
    "INSERT INTO vote_rewards (username, given, timestamp, site_id) VALUES (?, 0, ?, ?)"
);

if (!$stmt) {
    die("Prepare failed: " . mysqli_error($connection));
}

mysqli_stmt_bind_param($stmt, "sii", $username, $timestamp, $siteId);

if (!mysqli_stmt_execute($stmt)) {
    die("Execute failed: " . mysqli_stmt_error($stmt));
}

mysqli_stmt_close($stmt);
mysqli_close($connection);

// 6. Output success message (the toplist may check this)
echo "OK";

?>
    

2.2 – Things You MUST Change

• $dbHost, $dbUser, $dbPass, $dbName – Set these to match your MySQL login.
• $allowedIps – Replace 123.123.123.123 with your toplist’s IP address.
• $usernameParam – If your toplist sends ?username= or ?player= instead of ?user=, change it accordingly.
• $siteId – If you only have one site, leave it as 1. If you add more sites later, you can use different IDs.

Important: The callback script never gives in-game rewards directly. It only inserts rows into the database. Your RSPS will handle rewards separately using the claimvote logic.

Step 3 – Upload the Script and Get the Callback URL

3.1 – Upload the File

• Connect to your webhost using FTP or File Manager.
• Upload callback.php into a public folder (for example, /public_html/vote/).

3.2 – Example Callback URL

If your domain is example.com and you uploaded to /public_html/vote/, your URL will be:

https://example.com/vote/callback.php
    

We will enter this URL into your toplist settings in the next step.

3.3 – Quick Manual Test

Before touching your toplist, test the script manually:

1. In your browser, visit:
   https://example.com/vote/callback.php?user=TestUser
2. You should see: Invalid IP (this is good – it means the script runs, but rejects your IP because it is not the toplist IP).
3. Now temporarily add your own IP to $allowedIps, refresh that URL, and you should see OK.
4. Check your vote_rewards table – you should see a row with username = TestUser.
5. Remove your IP again from $allowedIps so only the toplist IP stays.

Step 4 – Configure the Toplist Callback

Now you need to tell your toplist where to send the callback after a vote is completed.

4.1 – In Your Toplist Panel

The exact names vary per site, but you are looking for settings like:

• Callback URL / Postback URL / Vote Callback
• Success URL or Return URL (not always needed)

In the Callback URL field, enter the full URL to your script, for example:

https://example.com/vote/callback.php
    

4.2 – Username Parameter

Some toplists let you choose how the username is sent:

• ?user=USERNAME
• ?username=USERNAME
• ?player=USERNAME

Match this with your $usernameParam value from the PHP script.

4.3 – Test Callback in the Toplist

Many toplists have a Test Callback button in their panel. Use it:

• Click Test or Send Test Callback.
• Check your vote_rewards table – you should see a new row with their test username.
• If they show the callback response, it should say OK.

Step 5 – Add Claim Logic to Your RSPS

Now the database is filling with votes. The last step is to make your RSPS:

• Check the vote_rewards table for that player.
• Give rewards for any rows where given = 0.
• Set those rows to given = 1 so they cannot be claimed again.

5.1 – Basic Claim Algorithm (Human Explanation)

1. Player types ::claimvote (or your command name).
2. Server connects to the same MySQL database.
3. Server runs:
   SELECT * FROM vote_rewards WHERE username = playerName AND given = 0;
4. If there are 0 rows: tell player "You have no votes to claim."
5. If there are 1 or more rows:
   • Give rewards (points, items, keys, etc).
   • Run:
     UPDATE vote_rewards SET given = 1 WHERE id = thatRowId;
     for each row.

5.2 – Example SQL Queries

Find all unclaimed votes for a player:

SELECT * FROM vote_rewards
WHERE username = 'PlayerNameHere'
  AND given = 0;
    

Mark a specific vote row as claimed:

UPDATE vote_rewards
SET given = 1
WHERE id = 123;
    

In your RSPS code, you would replace PlayerNameHere with the logged-in player's username, and 123 with the actual id from the row.

Note: Every server base is slightly different, so the Java code will vary, but the logic above is always the same: SELECT unclaimed rows → give rewards → UPDATE them as given.

Step 6 – Full Testing Checklist

1. Visit the callback URL manually with your own IP allowed:
   • https://example.com/vote/callback.php?user=TestUser
   • Confirm you see OK.
   • Check database – row for TestUser should exist.
2. Remove your IP from $allowedIps so only toplist is trusted.
3. Use the Test Callback button in your toplist panel:
   • Check database for test rows.
4. Log in to your RSPS as that username.
5. Type ::claimvote (or your command) and confirm:
   • You receive the correct rewards.
   • The rows in vote_rewards change from given = 0 to given = 1.

Step 7 – Common Problems & Fixes

Problem 1 – No rows appear in vote_rewards

• Check that your callback.php is reachable in the browser.
• Check your database credentials ($dbHost, $dbUser, $dbPass, $dbName).
• Check $allowedIps – make sure the toplist IP is correct.
• Check that your toplist callback URL matches your script URL exactly (https vs http, www vs non-www).

Problem 2 – Rows exist, but claimvote gives nothing

• Make sure your RSPS is connecting to the same database and not a local test DB.
• Run the SELECT query manually in MySQL with the username you are testing.
• Check that your claim logic uses given = 0 and then updates rows to given = 1.

Problem 3 – Player can claim the same vote multiple times

• Make sure you are running the UPDATE vote_rewards SET given = 1 query after each reward.
• Verify in the database that given actually changes to 1.

Problem 4 – Callback sometimes responds with errors

• If you see messages like "Prepare failed" or "Execute failed", double-check that your table name and columns are spelled correctly.
• Enable basic logging by writing errors to a file if needed (for advanced debugging).

---

Your Vote Callback System Is Now Fully Set Up

You now have a professional, database-driven vote system that works great with RSPS and RuneTopic.