Vote for Us integration guide
Players click your vote badge, vote on GameListZone, and your server receives a signed request to hand out the in-game reward. Votes rank your server on its game page every month. Setup takes about ten minutes from your dashboard → Votes.
1. The vote link
https://gamelistzone.com/vote/<SERVER_ID>
https://gamelistzone.com/vote/<SERVER_ID>?u=<PLAYER>SERVER_IDis permanent: it never changes, even if your server is renamed. Copy it from Dashboard → Votes.upre-fills the player name so the vote can be rewarded: 1–32 characters, letters (any alphabet), digits, spaces and_ - . [ ]. URL-encode it.- One vote per server every 12 hours per player (IP, account or name). Captcha protected. Owners cannot vote for their own server.
- The ranking is monthly (UTC) and restarts on the 1st. To rank, the link must be on the page of your listed Website URL. We check it every hour.
2. The badge
Paste this on your website. Keep the link exactly as it is, because the hourly check looks for it.
<a href="https://gamelistzone.com/vote/YOUR_SERVER_ID" target="_blank" rel="noopener" title="Vote for Your Server on GameListZone"><img src="https://gamelistzone.com/api/widget/vote/YOUR_SERVER_ID.svg" width="240" height="60" alt="Vote for Your Server on GameListZone - Lineage 2 private server" style="border:0"></a>A smaller button: ?style=button (180×36). A plain text link:
<a href="https://gamelistzone.com/vote/YOUR_SERVER_ID" target="_blank" rel="noopener">Vote for Your Server</a> on <a href="https://gamelistzone.com/" target="_blank" rel="noopener">GameListZone</a>The image shows your rank and votes this month and refreshes every 5 minutes.
3. Reward postback
When a player votes with a name, we call your Postback URL. GET sends the fields in the query string. POST sends them as application/x-www-form-urlencoded. POST is recommended, because GET leaves the signature in your access logs.
| username | The in-game name the player typed (1-32 chars). Only votes with a name are posted. |
| vote_id | Unique id of this vote. Reward once per vote_id: it is your replay and retry guard. |
| voted_at | Unix timestamp (seconds) of the vote. |
| ip_hash | 32 hex chars, stable per visitor and server. Never an IP address. |
| signature | hex HMAC-SHA256(secret, vote_id + "|" + username + "|" + voted_at). |
- Answer any 2xx within 5 seconds. Anything else (including redirects and timeouts) is retried, up to 3 attempts over about 6 minutes.
- Reward once per
vote_id. A retry or a replayed request carries the same id. - Reject a
voted_atolder than 24 hours. - “Send test” in the dashboard posts
vote_id=test,username=GLZTest, signed with your real secret. Answer it with 2xx without granting anything. - The URL must be a public http(s) address. Private and internal hosts are refused.
Check your implementation
With this secret and these fields, your code must compute exactly this signature:
secret = 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
vote_id = cmglzfixture0000000000001
username = PlayerOne
voted_at = 1761350400
signature = 7394b160b5a92a720696b36e745a24e7908a03b1068cb760501da909c9d91c634. PHP: Lineage 2 (L2J, aCis, Lucera)
<?php
// GameListZone vote reward postback -> Lineage 2 (Lucera / L2Scripts / Overworld "items_delayed").
// GameListZone dashboard -> Votes: Postback URL = https://your-site.com/glz-postback.php, Method = POST.
// aCis / L2J Mobius have no items_delayed: keep the verification and the dedupe exactly as
// they are and replace the last INSERT with your pack's delayed-item or mail delivery
// (L2J Mobius names the character id column charId instead of obj_Id).
declare(strict_types=1);
const GLZ_SECRET = 'PASTE_YOUR_REWARD_SECRET'; // dashboard -> Votes -> Reward secret
const MAX_AGE_S = 86400; // ignore votes older than 24h
const REWARD_ITEM = 57; // item id (57 = Adena)
const REWARD_COUNT = 1000000;
$p = (($_SERVER['REQUEST_METHOD'] ?? 'GET') === 'POST') ? $_POST : $_GET;
$voteId = (string)($p['vote_id'] ?? '');
$username = (string)($p['username'] ?? '');
$votedAt = (string)($p['voted_at'] ?? '');
$sig = (string)($p['signature'] ?? '');
$expected = hash_hmac('sha256', $voteId . '|' . $username . '|' . $votedAt, GLZ_SECRET);
if (!hash_equals($expected, $sig)) { http_response_code(403); exit('bad signature'); }
if ($voteId === 'test') { exit('ok'); } // the dashboard "Send test" button
if (!ctype_digit($votedAt) || abs(time() - (int)$votedAt) > MAX_AGE_S) { exit('stale'); }
$db = new PDO('mysql:host=127.0.0.1;dbname=l2gs;charset=utf8mb4', 'l2user', 'l2pass', [
PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
]);
// Run once:
// CREATE TABLE glz_vote_rewards (vote_id VARCHAR(64) PRIMARY KEY, char_name VARCHAR(35) NOT NULL, rewarded_at DATETIME NOT NULL);
$char = $db->prepare('SELECT obj_Id FROM characters WHERE char_name = ? LIMIT 1');
$char->execute([$username]);
$ownerId = $char->fetchColumn();
if ($ownerId === false) { exit('unknown character'); } // 200: a retry cannot create it
$db->beginTransaction();
$once = $db->prepare('INSERT IGNORE INTO glz_vote_rewards (vote_id, char_name, rewarded_at) VALUES (?, ?, UTC_TIMESTAMP())');
$once->execute([$voteId, $username]);
if ($once->rowCount() === 0) { $db->rollBack(); exit('already rewarded'); } // replay or retry
$db->prepare("INSERT INTO items_delayed (owner_id, item_id, count, payment_status, description) VALUES (?, ?, ?, 0, 'GameListZone vote')")
->execute([$ownerId, REWARD_ITEM, REWARD_COUNT]);
$db->commit();
echo 'ok';
5. PHP: AzerothCore / TrinityCore (SOAP)
<?php
// GameListZone vote reward postback -> AzerothCore via SOAP (TrinityCore: use 'urn:TC').
// worldserver.conf: SOAP.Enabled = 1, SOAP.IP = "127.0.0.1", SOAP.Port = 7878
// GameListZone dashboard -> Votes: Postback URL = https://your-site.com/glz-postback.php, Method = POST.
// GameListZone waits 5 seconds for an answer, so keep this script fast.
declare(strict_types=1);
const GLZ_SECRET = 'PASTE_YOUR_REWARD_SECRET';
const MAX_AGE_S = 86400;
const SOAP_USER = 'GLZREWARDS'; // a dedicated GM account (security level 3) used only here
const SOAP_PASS = 'change-me';
const REWARD = '49426:2'; // itemId:count (49426 = Emblem of Frost)
$p = (($_SERVER['REQUEST_METHOD'] ?? 'GET') === 'POST') ? $_POST : $_GET;
$voteId = (string)($p['vote_id'] ?? '');
$username = (string)($p['username'] ?? '');
$votedAt = (string)($p['voted_at'] ?? '');
$sig = (string)($p['signature'] ?? '');
$expected = hash_hmac('sha256', $voteId . '|' . $username . '|' . $votedAt, GLZ_SECRET);
if (!hash_equals($expected, $sig)) { http_response_code(403); exit('bad signature'); }
if ($voteId === 'test') { exit('ok'); } // the dashboard "Send test" button
if (!ctype_digit($votedAt) || abs(time() - (int)$votedAt) > MAX_AGE_S) { exit('stale'); }
// WoW character names are 2-12 letters. This also keeps anything else out of the GM command.
if (!preg_match('/^[A-Za-z]{2,12}$/', $username)) { exit('bad name'); }
$db = new PDO('mysql:host=127.0.0.1;dbname=acore_characters;charset=utf8mb4', 'acore', 'acore', [
PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
]);
// Run once:
// CREATE TABLE glz_vote_rewards (vote_id VARCHAR(64) PRIMARY KEY, char_name VARCHAR(12) NOT NULL, rewarded_at DATETIME NOT NULL);
$char = $db->prepare('SELECT guid FROM characters WHERE name = ? LIMIT 1');
$char->execute([$username]);
if ($char->fetchColumn() === false) { exit('unknown character'); }
$db->beginTransaction();
$once = $db->prepare('INSERT IGNORE INTO glz_vote_rewards (vote_id, char_name, rewarded_at) VALUES (?, ?, UTC_TIMESTAMP())');
$once->execute([$voteId, $username]);
if ($once->rowCount() === 0) { $db->rollBack(); exit('already rewarded'); }
$soap = new SoapClient(null, [
'location' => 'http://127.0.0.1:7878/',
'uri' => 'urn:AC',
'style' => SOAP_RPC,
'login' => SOAP_USER,
'password' => SOAP_PASS,
'connection_timeout' => 4,
]);
try {
$soap->executeCommand(new SoapParam(
sprintf('.send items %s "Vote reward" "Thanks for voting on GameListZone!" %s', $username, REWARD),
'command'
));
} catch (SoapFault $e) {
$db->rollBack();
http_response_code(502); // not 2xx: GameListZone retries
exit('soap error');
}
$db->commit();
echo 'ok';
6. Node.js / Express
// GameListZone vote reward postback -> Node.js / Express.
// npm install express | GLZ_SECRET=<reward secret> node glz-postback.js
// GameListZone dashboard -> Votes: Postback URL = https://your-site.com/glz-postback, Method = POST.
const crypto = require('crypto');
const express = require('express');
const GLZ_SECRET = process.env.GLZ_SECRET;
const MAX_AGE_S = 86400;
const rewarded = new Set(); // demo only: use a UNIQUE vote_id column in your database
function verifyGlzPostback(p, secret) {
const expected = crypto
.createHmac('sha256', secret)
.update(String(p.vote_id) + '|' + String(p.username) + '|' + String(p.voted_at))
.digest('hex');
const a = Buffer.from(expected);
const b = Buffer.from(String(p.signature || ''));
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
const app = express();
app.use(express.urlencoded({ extended: false }));
app.all('/glz-postback', (req, res) => {
const p = req.method === 'POST' ? req.body : req.query;
if (!verifyGlzPostback(p, GLZ_SECRET)) return res.status(403).send('bad signature');
if (p.vote_id === 'test') return res.send('ok'); // the dashboard "Send test" button
const age = Date.now() / 1000 - Number(p.voted_at);
if (!(Math.abs(age) <= MAX_AGE_S)) return res.send('stale');
if (rewarded.has(p.vote_id)) return res.send('already rewarded');
rewarded.add(p.vote_id);
// deliverReward(p.username) -- your game's mail / item delivery goes here
return res.send('ok');
});
app.listen(3005);
7. Pull check (account panels)
Prefer polling? Ask whether a player voted in the last 12 hours. Call it server-to-server only: never from browser JavaScript, because the header carries your secret. Pass an opaque id you can map back (for example m{ACCOUNT_ID}), never the account login: it ends up in the player's browser history and in our logs.
GET https://gamelistzone.com/api/vote/check?server=<SERVER_ID>&u=<PLAYER>
X-GLZ-Vote-Key: <REWARD_SECRET>
200 {"voted":true,"voteId":"…","votedAt":"…","nextVoteAt":"…"}
200 {"voted":false,"voteId":null,"votedAt":null,"nextVoteAt":null}
401 wrong key or unknown server · 429 more than 120 checks/min for one server<?php
// Account panels: confirm a GameListZone vote with the pull check instead of a postback.
// Show the player: https://gamelistzone.com/vote/<SERVER_ID>?u=m<ACCOUNT_ID>
// Use an opaque id you can map back, never the account login (it ends up in browser history).
function glzVote(string $serverId, string $player, string $secret): ?array
{
$url = 'https://gamelistzone.com/api/vote/check?server=' . rawurlencode($serverId)
. '&u=' . rawurlencode($player);
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_TIMEOUT => 8,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_HTTPHEADER => ['X-GLZ-Vote-Key: ' . $secret],
]);
$body = curl_exec($ch);
$code = (int)curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($body === false || $code !== 200) {
return null; // fail closed: wrong key (401), rate limit (429), network error
}
$data = json_decode((string)$body, true);
if (!is_array($data) || ($data['voted'] ?? false) !== true || !is_string($data['voteId'] ?? null)) {
return null;
}
return $data; // ['voted' => true, 'voteId' => ..., 'votedAt' => ..., 'nextVoteAt' => ...]
}
// Credit ONCE per $data['voteId'] (UNIQUE KEY on it), never once per time slot: a vote keeps
// answering voted=true for 12 rolling hours, so a slot-based key would pay one vote twice.