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
- 1Gracz otwiera Twój link do głosowania z nazwą swojego konta w grze.
- 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).
- 3Głos zostaje zapisany i liczy się w rankingu.
- 4Jeśli podano adres URL postbacku, GameTopBase wysyła do Twojego serwera powiadomienie podpisane Twoim sekretem.
- 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.
| Parametr | Opis |
|---|---|
| username | Opcjonalny. 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 botWeryfikacja Cloudflare Turnstile, podpisany formularz, który wygasa, oraz niewidoczna pułapka na boty.
- Jeden głos na IPZ 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 kontoJednemu 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 IPAdres 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 powiadomienieKaż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:
| Parametr | Typ | Opis |
|---|---|---|
| username | tekst | Konto w grze wpisane przez gracza (bez konta postback nie jest wysyłany). |
| ip | tekst | Adres IP, z którego oddano głos (IPv4 lub IPv6). |
| timestamp | liczba całkowita | Czas wysłania jako znacznik czasu Unix (w sekundach). Zmienia się przy każdej ponownej próbie. |
| vote_id | tekst | Unikalny identyfikator głosu. Nie zmienia się przy ponownych próbach ani między Twoimi adresami URL. |
| signature | tekst | Podpis HMAC-SHA256 w zapisie szesnastkowym (64 znaki). |
https://twoja-gra.com/vote.php?username=jugador123&ip=203.0.113.7×tamp=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:
- 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).
- 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.
- Konto: jeśli username przyjdzie puste (nie powinno), odpowiedz 200 i niczego nie wydawaj.
- 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.
- Nagroda: wydaj ją kontu username.
- 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
| Kod | Opis |
|---|---|
| 2xx | Powiadomienie odebrane. Nie jest wysyłane ponownie. |
| Inny kod lub brak odpowiedzi w ciągu 5 s | Serwery 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 premium | Powiadomienie 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 testu | Co zrobić |
|---|---|
| Serwer odpowiedział poprawnie (2xx) | Wszystko gotowe: gdy gracz zagłosuje, skrypt otrzyma powiadomienie. |
| Ochrona przed botami zatrzymała powiadomienie | Powiadomienie 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 sekund | Serwer 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.
| Parametr | Opis |
|---|---|
| vote_id | Czy ten głos istnieje? Bez limitu czasu. Najbezpieczniejszy sposób potwierdzenia postbacku. |
| username | Czy z tego konta oddano głos w ciągu ostatnich 12 godzin? Wielkość liter nie ma znaczenia. |
| ip | Czy 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"
}| Pole | Opis |
|---|---|
| voted | true, jeśli znaleziono głos. |
| voteId | Identyfikator głosu (ten sam, który przychodzi w postbacku) lub null. |
| username | Konto, z którego oddano głos, lub null. |
| votedAt | Data głosu (ISO 8601, UTC) lub null. |
| nextVoteAt | Kiedy będzie można zagłosować ponownie, lub null. |
| Kod | Opis |
|---|---|
| 200 | Zapytanie poprawne (voted może mieć wartość true lub false). |
| 400 | Brakuje vote_id, username lub ip albo format jest nieprawidłowy. |
| 401 | Serwer 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.