Game List Zone

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.

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.

usernameThe in-game name the player typed (1-32 chars). Only votes with a name are posted.
vote_idUnique id of this vote. Reward once per vote_id: it is your replay and retry guard.
voted_atUnix timestamp (seconds) of the vote.
ip_hash32 hex chars, stable per visitor and server. Never an IP address.
signaturehex 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_at older 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 = 7394b160b5a92a720696b36e745a24e7908a03b1068cb760501da909c9d91c63

4. 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.