GameTopBase
Strona główna

Nagradzaj graczy za głosy

Gracze głosują na Twój serwer w GameTopBase, a Ty dajesz im nagrodę w grze. Ta strona wyjaśnia, jak zrobić to bezpiecznie: nagradzane są tylko prawdziwe głosy i każdy tylko raz.

Jak to działa

  1. 1Gracz otwiera Twój link do głosowania z nazwą swojego konta w grze.
  2. 2GameTopBase sprawdza, czy to człowiek i czy w ciągu ostatnich 12 godzin nie oddano już głosu (ani z tego adresu IP, ani z tego konta).
  3. 3Głos zostaje zapisany i liczy się w rankingu.
  4. 4Jeśli podano adres URL postbacku, GameTopBase wysyła do Twojego serwera powiadomienie podpisane Twoim sekretem.
  5. 5Twój serwer sprawdza podpis, upewnia się, że ten głos nie został jeszcze nagrodzony, i wydaje nagrodę.

Wydawaj nagrodę tylko wtedy, gdy przyjdzie postback z poprawnym podpisem, albo po potwierdzeniu głosu przez API sprawdzania. Nigdy dlatego, że gracz twierdzi, że zagłosował, i nigdy z poziomu przeglądarki.

1. Link do głosowania

Kieruj graczy pod ten link (ze strony WWW, z launchera, z Discorda lub komendą w grze):

https://gametopbase.com/pl/serwery/<twoj-serwer>/glosuj?username=<konto>

<twoj-serwer> to ostatnia część adresu strony serwera, razem z numerem: na przykład w …/serwery/123-craftnation jest to 123-craftnation. Do podpisywania powiadomień używaj „Identyfikatora strony serwera” z panelu, z sekcji „Integracja głosowania”: to ten z chwili utworzenia strony i nie zmienia się po zmianie nazwy.

ParametrOpis
usernameOpcjonalny. Nazwa konta w grze, które otrzyma nagrodę: od 1 do 32 znaków (litery, cyfry, spacja, _ - .). Jeśli link ją zawiera, pole jest od razu wypełnione.

Bez nazwy konta głos tak samo liczy się w rankingu, ale nie ma kogo nagrodzić: twój serwer nie dostaje powiadomienia (postback nie jest wysyłany).

W linku celowo jest tylko username. Link otwiera gracz w swojej przeglądarce, więc mógłby zmienić dowolne dane w adresie URL: adres IP GameTopBase pobiera z rzeczywistego połączenia, a resztę (vote_id, datę, podpis) generuje na swoim serwerze. Twój serwer otrzymuje to wszystko później, w podpisanym postbacku.

W panelu, w sekcji „Promuj swój serwer”, znajdziesz przycisk i link gotowe do skopiowania.

2. Prawdziwe głosy: co sprawdza GameTopBase

Zanim głos zostanie policzony, GameTopBase sprawdza na swoim serwerze (nie w przeglądarce gracza):

  • Człowiek, nie bot
    Weryfikacja Cloudflare Turnstile, podpisany formularz, który wygasa, oraz niewidoczna pułapka na boty.
  • Jeden głos na IP
    Z jednego adresu IP można zagłosować na Twój serwer tylko raz na 12 godzin, a w całym serwisie oddać maksymalnie 20 głosów na godzinę.
  • Jeden głos na konto
    Jednemu kontu w grze zalicza się tylko jeden głos na 12 godzin, nawet przy głosowaniu z innych adresów IP lub przez VPN. Wielkość liter nie ma znaczenia: „Gracz” i „gracz” to to samo konto.
  • Prawdziwy adres IP
    Adres IP pochodzi z rzeczywistego połączenia, a nie z tego, co wysyła przeglądarka, więc nie da się go sfałszować, aby zagłosować więcej razy.
  • Podpisane powiadomienie
    Każdy postback zawiera utworzony Twoim sekretem podpis HMAC-SHA256, który obejmuje wszystkie dane: nie da się go podrobić ani zmienić.
  • Prywatność
    GameTopBase przechowuje adres IP głosującego przez 12 miesięcy, aby wykrywać oszustwa, i widzi go tylko administracja serwisu. Poza serwisem adres IP głosującego otrzymuje wyłącznie Twój serwer, w postbacku.

3. Postback: powiadomienie dla Twojego serwera

Podaj adres URL swojego skryptu w panelu serwera, w sekcji „Integracja głosowania”. Po zapisaniu każdego głosu GameTopBase wysyła żądanie GET na ten adres URL z następującymi parametrami:

ParametrTypOpis
usernametekstKonto w grze wpisane przez gracza (bez konta postback nie jest wysyłany).
iptekstAdres IP, z którego oddano głos (IPv4 lub IPv6).
timestampliczba całkowitaCzas wysłania jako znacznik czasu Unix (w sekundach). Zmienia się przy każdej ponownej próbie.
vote_idtekstUnikalny identyfikator głosu. Nie zmienia się przy ponownych próbach ani między Twoimi adresami URL.
signaturetekstPodpis HMAC-SHA256 w zapisie szesnastkowym (64 znaki).
https://twoja-gra.com/vote.php?username=jugador123&ip=203.0.113.7&timestamp=1767225600&vote_id=cm4x9k2p00001&signature=<64 hex>
  • Twój skrypt ma 5 sekund na odpowiedź.
  • Przekierowania nie są obsługiwane: podaj docelowy adres URL, najlepiej z https.
  • Powiadomienia są wysyłane tylko na adresy publiczne (localhost i sieci wewnętrzne nie są dozwolone).
  • Żądanie wychodzi z serwera GameTopBase przez IPv4 i przedstawia się nagłówkiem User-Agent „GameTopBase-Postback/1.0”. Jeśli Twoja strona ma ochronę przed botami (Cloudflare lub inną), przepuść je: zobacz „Przetestuj integrację”.

4. Weryfikuj każde powiadomienie

Zanim skrypt cokolwiek wyda, musi wykonać te sprawdzenia w podanej kolejności:

  1. Podpis: oblicz HMAC-SHA256 swoim sekretem z tekstu poniżej i porównaj wynik z signature, używając porównania w stałym czasie (hash_equals w PHP, timingSafeEqual w Node).
  2. Data: odrzuć powiadomienie, jeśli timestamp różni się od Twojego czasu o więcej niż 5 minut. Dzięki temu stare, skopiowane powiadomienie jest bezużyteczne.
  3. Konto: jeśli username przyjdzie puste (nie powinno), odpowiedz 200 i niczego nie wydawaj.
  4. Tylko raz: przed wydaniem nagrody zapisz vote_id w tabeli z kluczem unikalnym. Jeśli już tam był, to ponowna próba: odpowiedz 200 i nie nagradzaj drugi raz.
  5. Nagroda: wydaj ją kontu username.
  6. Odpowiedź: zwróć kod 2xx (na przykład 200).

Podpisywany tekst (wartości dokładnie w takiej postaci, w jakiej przychodzą, rozdzielone dwukropkami):

signature = HMAC-SHA256(sekret, "serwer:username:ip:timestamp:vote_id")  →  hex

Sekret znajdziesz w panelu, w sekcji „Integracja głosowania”. Jest przeznaczony wyłącznie dla Twojego serwera: nigdy nie umieszczaj go w launcherze, na stronie WWW ani w kliencie gry.

Pełny przykład w PHP

<?php
// vote.php: odbiera powiadomienie o głosie z GameTopBase i wydaje nagrodę.
// Podaj adres URL tego pliku jako „adres URL postbacku” w panelu GameTopBase.

const GAMETOP_SECRET = 'TWOJ_SEKRET_Z_PANELU'; // Panel > Integracja głosowania > Sekret
const GAMETOP_SERVER = 'twoj-serwer';          // identyfikator strony serwera: znajdziesz go w panelu, w sekcji „Integracja głosowania”

$user   = $_GET['username']  ?? '';
$ip     = $_GET['ip']        ?? '';
$ts     = $_GET['timestamp'] ?? '';
$voteId = $_GET['vote_id']   ?? '';
$sig    = $_GET['signature'] ?? '';

// 1. Podpis dowodzi, że powiadomienie pochodzi z GameTopBase i że nikt nie zmienił żadnych danych.
$expected = hash_hmac('sha256', GAMETOP_SERVER . ":$user:$ip:$ts:$voteId", GAMETOP_SECRET);
if (!is_string($sig) || !hash_equals($expected, $sig)) {
    http_response_code(403);
    exit('nieprawidlowy podpis');
}

// 2. Tylko świeże powiadomienia: stare, skopiowane jest bezużyteczne.
if (!ctype_digit($ts) || abs(time() - (int) $ts) > 300) {
    http_response_code(403);
    exit('powiadomienie wygaslo');
}

// 3. Bez konta głos liczy się w rankingu, ale nie ma kogo nagrodzić.
if ($user === '') {
    http_response_code(200);
    exit('ok');
}

// 4. Każdy głos jest nagradzany tylko raz. vote_id nie zmienia się przy ponownych próbach: zapisuje się go PRZED
//    wydaniem nagrody w kolumnie z kluczem unikalnym, więc dwa jednoczesne powiadomienia nie nagrodzą dwa razy.
//    CREATE TABLE gametop_votes (vote_id VARCHAR(40) PRIMARY KEY, username VARCHAR(32), rewarded_at DATETIME);
$db = new PDO('mysql:host=localhost;dbname=twoja_gra', 'uzytkownik', 'haslo');
$stmt = $db->prepare('INSERT IGNORE INTO gametop_votes (vote_id, username, rewarded_at) VALUES (?, ?, NOW())');
$stmt->execute([$voteId, $user]);
if ($stmt->rowCount() === 0) {
    http_response_code(200); // nagroda już wydana (to ponowna próba): nie wydaje się jej drugi raz
    exit('ok');
}

// 5. >>> TUTAJ WYDAJESZ NAGRODĘ kontu $user <<<
//    To jedyne miejsce, w którym głos jest zweryfikowany i przychodzi po raz pierwszy.
try {
    daj_nagrode($user); // Twój kod: monety, przedmioty, dni VIP...
} catch (Throwable $e) {
    // W razie błędu znacznik jest usuwany, a odpowiedzią jest błąd: GameTopBase ponowi próbę (serwery premium).
    $db->prepare('DELETE FROM gametop_votes WHERE vote_id = ?')->execute([$voteId]);
    http_response_code(500);
    exit('error');
}

// 6. Odpowiedz 2xx: GameTopBase uzna powiadomienie za dostarczone.
http_response_code(200);
echo 'ok';

Ten sam przykład w Node.js (Express)

const crypto = require("crypto");
const express = require("express");
const app = express();

const GAMETOP_SECRET = "TWOJ_SEKRET_Z_PANELU"; // Panel > Integracja głosowania > Sekret
const GAMETOP_SERVER = "twoj-serwer";

app.get("/gametop/vote", async (req, res) => {
  const q = (name) => (typeof req.query[name] === "string" ? req.query[name] : "");
  const user = q("username"), ip = q("ip"), ts = q("timestamp"), voteId = q("vote_id"), sig = q("signature");

  // 1. Podpis: z GameTopBase i bez zmian
  const expected = crypto.createHmac("sha256", GAMETOP_SECRET)
    .update(GAMETOP_SERVER + ":" + user + ":" + ip + ":" + ts + ":" + voteId)
    .digest("hex");
  if (sig.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.status(403).send("nieprawidlowy podpis");
  }

  // 2. Tylko świeże powiadomienia
  if (!/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > 300) {
    return res.status(403).send("powiadomienie wygaslo");
  }

  // 3. Bez konta nie ma kogo nagradzać
  if (user === "") return res.send("ok");

  // 4. Tylko raz na vote_id: zapisz go z kluczem unikalnym PRZED wydaniem nagrody
  const firstTime = await saveVoteId(voteId, user); // Twój kod: false, jeśli już istniał
  if (!firstTime) return res.send("ok");

  // 5. >>> TUTAJ WYDAJESZ NAGRODĘ kontu user <<<
  try {
    await giveReward(user); // Twój kod
  } catch (e) {
    await deleteVoteId(voteId); // dzięki temu ponowna próba (premium) może go nagrodzić
    return res.status(500).send("error");
  }

  // 6. Odpowiedź 2xx
  res.send("ok");
});

app.listen(8080);

5. Odpowiedzi i ponowne próby

KodOpis
2xxPowiadomienie odebrane. Nie jest wysyłane ponownie.
Inny kod lub brak odpowiedzi w ciągu 5 sSerwery premium: ponowne próby po 1, 5 i 30 minutach (4 próby), z tym samym vote_id i nowym podpisem. W panelu zobaczysz każde dostarczenie z wynikiem ostatniej próby.
Bez premiumPowiadomienie jest wysyłane tylko raz. Jeśli Twój serwer nie działał, skorzystaj awaryjnie z API sprawdzania. Jeśli powiadomienie nie dotrze, damy Ci znać powiadomieniem i e-mailem (najwyżej raz dziennie na serwer).

Serwery premium mogą dodać do 2 dodatkowych adresów URL postbacku: wszystkie otrzymują ten sam vote_id, więc możesz używać kilku bez podwójnego nagradzania.

6. Przetestuj integrację i rozwiąż problemy

W panelu, w sekcji „Integracja głosowania”, kliknij „Wyślij test”. GameTopBase wyśle na Twój adres postback powiadomienie podpisane tak jak prawdziwe, z kontem „gametopbase-test” i vote_id zaczynającym się od „test-”, i od razu pokaże, co odpowiedział Twój serwer i co sprawdzić. Skrypt nie powinien nagradzać tego konta. Test możesz wykonać, zanim strona serwera zostanie opublikowana.

Link do głosowania i prawdziwe powiadomienia zaczynają działać po opublikowaniu strony serwera. Dopóki strona czeka na sprawdzenie, link do głosowania zwraca „nie znaleziono strony”.

Jeśli Twoja strona korzysta z ochrony przed botami (Cloudflare w trybie „Under Attack”, Bot Fight Mode, własna reguła lub podobna usługa), może ona zatrzymać powiadomienie, zanim dotrze do skryptu. Dodaj regułę przepuszczającą żądania, których User-Agent zawiera „GameTopBase-Postback”, albo wyłącz ochronę dla adresu skryptu. W Cloudflare: Bezpieczeństwo → WAF → Reguły niestandardowe → akcja „Pomiń”.

Co widzisz podczas testuCo zrobić
Serwer odpowiedział poprawnie (2xx)Wszystko gotowe: gdy gracz zagłosuje, skrypt otrzyma powiadomienie.
Ochrona przed botami zatrzymała powiadomieniePowiadomienie nie dotarło do skryptu. Przepuść „GameTopBase-Postback” zgodnie z opisem powyżej.
Skrypt je odrzucił (401 lub 403)Prawie zawsze chodzi o podpis. Użyj sekretu i identyfikatora strony serwera dokładnie tak, jak są podane w panelu, i podpisuj serwer:username:ip:timestamp:vote_id wartościami w takiej postaci, w jakiej przychodzą.
Pod tym adresem nic nie ma (404)Adres postback jest błędnie wpisany albo pliku nie ma na serwerze.
Przekierowanie (301, 302…)Powiadomienia nie podążają za przekierowaniami. Wpisz adres docelowy, z https oraz z „www” lub bez.
Błąd skryptu (500)Powiadomienie dotarło, ale skrypt nie zdołał go przetworzyć. Sprawdź dziennik błędów serwera WWW.
Brak odpowiedzi w ciągu 5 sekundSerwer nie działa albo odpowiada zbyt wolno.

7. API sprawdzania

Zapytaj GameTopBase o głos ze swojego serwera. Przydaje się do potwierdzenia postbacku, do wydawania nagrody komendą w grze albo awaryjnie, gdy powiadomienie nie dotarło.

Wyślij sekret w nagłówku Authorization: Bearer <sekret>. Nigdy w adresie URL: tam trafiłby do logów dostępu.

ParametrOpis
vote_idCzy ten głos istnieje? Bez limitu czasu. Najbezpieczniejszy sposób potwierdzenia postbacku.
usernameCzy z tego konta oddano głos w ciągu ostatnich 12 godzin? Wielkość liter nie ma znaczenia.
ipCzy z tego adresu IP oddano głos w ciągu ostatnich 12 godzin?

W każdym zapytaniu użyj jednego z trzech, razem z server=<twoj-serwer>.

curl -H "Authorization: Bearer <sekret>" \
  "https://gametopbase.com/api/v1/vote-check?server=<twoj-serwer>&vote_id=cm4x9k2p00001"

curl -H "Authorization: Bearer <sekret>" \
  "https://gametopbase.com/api/v1/vote-check?server=<twoj-serwer>&username=jugador123"

{
  "voted": true,
  "voteId": "cm4x9k2p00001",
  "username": "jugador123",
  "votedAt": "2026-10-25T10:00:00.000Z",
  "nextVoteAt": "2026-10-25T22:00:00.000Z"
}
PoleOpis
votedtrue, jeśli znaleziono głos.
voteIdIdentyfikator głosu (ten sam, który przychodzi w postbacku) lub null.
usernameKonto, z którego oddano głos, lub null.
votedAtData głosu (ISO 8601, UTC) lub null.
nextVoteAtKiedy będzie można zagłosować ponownie, lub null.
KodOpis
200Zapytanie poprawne (voted może mieć wartość true lub false).
400Brakuje vote_id, username lub ip albo format jest nieprawidłowy.
401Serwer nie istnieje lub sekret jest nieprawidłowy.

Nagroda za pomocą komendy w grze

Jeśli nie używasz postbacku: gdy gracz wpisze /nagroda, wyślij zapytanie z username. Jeśli voted ma wartość true, a tego voteId nie ma w Twojej tabeli nagrodzonych głosów, zapisz go i wydaj nagrodę. To ta sama zasada co w kroku 4: jeden voteId, jedna nagroda.

8. Lista kontrolna bezpieczeństwa

  • Sekret przechowuj tylko na swoim serwerze. Jeśli wycieknie, kliknij „Wygeneruj ponownie” w panelu: poprzedni natychmiast przestaje działać.
  • Zawsze sprawdzaj podpis i datę, nawet jeśli adres URL Twojego skryptu jest tajny.
  • Przed wydaniem nagrody zapisz vote_id z kluczem unikalnym: to właśnie zapobiega podwójnemu nagradzaniu.
  • Nie wydawaj nagród z poziomu przeglądarki ani dlatego, że gracz twierdzi, że zagłosował.
  • Używaj https w adresie URL postbacku.