Hogyan Működik
A metin2.gg Vote Rewards API lehetővé teszi a Metin2 szerverednek, hogy automatikusan érzékelje, mikor szavaznak a játékosok, és játékbeli jutalmakat adjon. A folyamat egyszerű: a játékosok a metin2.gg-n szavaznak a karakternevükkel, és a szervered lekérdezi az API-nkat, hogy ellenőrizze és beváltsa ezeket a szavazatokat.
Két integrációs mód létezik — válaszd azt, amelyik megfelel a beállításodnak:
Polling (Ajánlott)
A szervered rendszeresen hívja az API-nkat új szavazatok ellenőrzéséhez. A legegyszerűbb megvalósítani — bármilyen Metin2 szerver beállítással működik. Csak adj hozzá egy HTTP kérést a játékszerver kódodhoz.
Webhooks (Haladó)
A metin2.gg azonnal értesítést küld a szerverednek, amint egy játékos szavaz. Valós idejű, de nyilvánosan elérhető HTTPS végpontot igényel a te oldaladon.
Hitelesítés
Minden API kéréshez szükség van egy API kulcsra, amelyet az X-API-Key fejlécen keresztül kell küldeni. A kulcsok formátuma mg_live_..., és a szerver paneledből generálhatók.
X-API-Key: mg_live_5bef...1a70Az API kulcsod egy szerverhez van kötve, és csak egyszer jelenik meg a generáláskor. Ha elveszíted, generálj újat a panelből (a régi kulcs azonnal érvénytelenné válik).
Hogyan Szerezheted Meg az API Kulcsod
- 1Menj a Panelem → Szervereim oldalra. Kattints a szervered nevére a kezelőoldal megnyitásához.
- 2A kezelőoldalon igazold a tulajdonjogot (DNS TXT rekord vagy meta tag), ha még nem tetted meg.
- 3Adj hozzá egy visszamutató linket a metin2.gg-re a szervered weboldalán a Partner státusz feloldásához.
- 4A szervered kezelőoldalán kattints az "API Beállítások" gombra. Majd kattints az "API Kulcs Generálása" gombra és másold ki — csak egyszer jelenik meg.
Szavazat Állapot Ellenőrzése
Ellenőrizd, hogy egy adott játékosnak van-e be nem váltott szavazata. Ha létezik függő szavazat, automatikusan beváltásra kerül (felhasználtként jelölve), így ugyanaz a szavazat nem váltható be kétszer.
GET /api/v1/vote/check?player_id=PlayerName HTTP/1.1
Host: metin2.gg
X-API-Key: mg_live_YOUR_KEY_HERELekérdezési Paraméterek
| Parameter | Type | Required | Description |
|---|---|---|---|
| player_id | string | Yes | A karakternév, amelyet a játékos szavazáskor használt. Kis- és nagybetű nem számít. |
Válasz
A játékosnak van be nem váltott szavazata (most beváltva)
{
"voted": true,
"player_id": "PlayerName",
"vote_id": "550e8400-e29b-41d4-a716-446655440000",
"voted_at": "2026-03-02T14:30:00Z"
}Nincs függő szavazat ehhez a játékoshoz
{
"voted": false
}Be Nem Váltott Szavazatok Listázása
Kérd le az összes be nem váltott szavazatot a szerveredhez. Hasznos kötegelt feldolgozáshoz — például egy cron feladat, amely 5 percenként fut és egyszerre ad jutalmakat az összes függő szavazatért.
GET /api/v1/vote/unclaimed?limit=50 HTTP/1.1
Host: metin2.gg
X-API-Key: mg_live_YOUR_KEY_HERELekérdezési Paraméterek
| Parameter | Type | Required | Description |
|---|---|---|---|
| limit | integer | No | Visszaadott szavazatok maximális száma (1–100, alapértelmezett 50). |
Válasz
{
"votes": [
{
"vote_id": "550e8400-e29b-41d4-a716-446655440000",
"player_id": "PlayerName",
"voted_at": "2026-03-02T14:30:00Z"
},
{
"vote_id": "660e8400-e29b-41d4-a716-446655440001",
"player_id": "AnotherPlayer",
"voted_at": "2026-03-02T14:32:00Z"
}
],
"total": 2
}Szavazatok Kötegelt Beváltása
Jelölj meg több szavazatot beváltottként egyetlen kérésben. Használd ezt az unclaimed végponttól kapott szavazatok feldolgozása után.
POST /api/v1/vote/claim HTTP/1.1
Host: metin2.gg
Content-Type: application/json
X-API-Key: mg_live_YOUR_KEY_HERE
{
"vote_ids": [
"550e8400-e29b-41d4-a716-446655440000",
"660e8400-e29b-41d4-a716-446655440001"
]
}Kérés Törzse (JSON)
| Parameter | Type | Required | Description |
|---|---|---|---|
| vote_ids | string[] | Yes | Beváltandó szavazat UUID-k tömbje. Kérésenként maximum 100. |
Válasz
{
"claimed": 2,
"failed": 0
}Webhooks
A polling helyett valós idejű push értesítéseket kaphatsz, amikor egy játékos szavaz. Konfiguráld a webhook URL-edet a szerver panelben az API Beállítások alatt.
Webhook Payload
POST https://your-server.com/api/vote-webhook HTTP/1.1
Content-Type: application/json
X-Metin2GG-Signature: a1b2c3d4e5f6...
{
"event": "vote.created",
"vote_id": "550e8400-e29b-41d4-a716-446655440000",
"server_id": "your-server-uuid",
"player_id": "PlayerName",
"voted_at": "2026-03-02T14:30:00Z",
"timestamp": "2026-03-02T14:30:01Z"
}Aláírás Ellenőrzése
Minden webhook kérés tartalmaz egy X-Metin2GG-Signature fejlécet, amely a nyers kéréstörzs HMAC-SHA256 hex kivonatát tartalmazza, az API titkos kulcsoddal aláírva. Mindig ellenőrizd ezt az aláírást, mielőtt megbíznál a payloadban.
import hmac
import hashlib
def verify_webhook(request_body: bytes, signature: str, secret: str) -> bool:
"""Verify the X-Metin2GG-Signature header."""
expected = hmac.new(
secret.encode("utf-8"),
request_body,
hashlib.sha256,
).hexdigest()
return hmac.compare_digest(expected, signature)
# Usage in your webhook handler:
# body = request.body (raw bytes)
# sig = request.headers["X-Metin2GG-Signature"]
# if not verify_webhook(body, sig, "your_api_secret"):
# return HttpResponse(status=403)<?php
function verifyWebhook(string $body, string $signature, string $secret): bool {
$expected = hash_hmac('sha256', $body, $secret);
return hash_equals($expected, $signature);
}
// Usage in your webhook handler:
// $body = file_get_contents('php://input');
// $sig = $_SERVER['HTTP_X_METIN2GG_SIGNATURE'] ?? '';
// if (!verifyWebhook($body, $sig, 'your_api_secret')) {
// http_response_code(403);
// exit('Invalid signature');
// }Metin2 Integráció: Python Parancs
Helyezd el ezt a scriptet a játékszervered Python parancsrendszerében. Amikor egy játékos beírja a /reward parancsot a játékban, ellenőrzi a metin2.gg-t függő szavazat után és megadja a jutalmat.
# vote_reward.py — Drop into your game server's command scripts
# Works with Python 2.7+ (common in Metin2 servers)
import json
import os
METIN2GG_API_KEY = "mg_live_YOUR_KEY_HERE"
METIN2GG_API_URL = "https://metin2.gg/api/v1/vote/check"
def check_vote(player_name):
"""Check if player has a pending vote and auto-claim it."""
url = "%s?player_id=%s" % (METIN2GG_API_URL, player_name)
# Method 1: Use urllib2 (Python 2) or urllib.request (Python 3)
try:
try:
import urllib2
req = urllib2.Request(url)
req.add_header("X-API-Key", METIN2GG_API_KEY)
resp = urllib2.urlopen(req, timeout=5)
data = json.loads(resp.read())
except ImportError:
import urllib.request
req = urllib.request.Request(url)
req.add_header("X-API-Key", METIN2GG_API_KEY)
resp = urllib.request.urlopen(req, timeout=5)
data = json.loads(resp.read().decode("utf-8"))
return data.get("voted", False)
except Exception:
pass
# Method 2: Fallback to curl (works even with broken SSL)
try:
cmd = 'curl -s -H "X-API-Key: %s" "%s"' % (METIN2GG_API_KEY, url)
raw = os.popen(cmd).read()
data = json.loads(raw)
return data.get("voted", False)
except Exception:
return None
# Example usage in your game command handler:
# def cmd_reward(player):
# result = check_vote(player.GetName())
# if result is True:
# player.GiveItem(50011, 10) # Example: 10x Dragon God Coins
# player.ChatInfoMessage("Vote reward claimed!")
# elif result is False:
# player.ChatInfoMessage("No pending vote. Vote at metin2.gg!")
# else:
# player.ChatInfoMessage("Could not reach metin2.gg. Try again.")Metin2 Integráció: Quest Fájl (Lua)
Ez a quest fájl létrehoz egy NPC interakciót, ahol a játékosok ellenőrizhetik szavazási állapotukat. Egy szerveroldali parancsot hív meg, amely kiváltja a Python szavazat-ellenőrzést.
quest vote_reward begin
state start begin
when login or letter begin
send_letter("Vote Reward")
end
when button or info begin
say_title("Vote Reward")
say("")
say("Vote for our server on metin2.gg")
say("and claim your reward here!")
say("")
local s = select("Check My Vote", "How to Vote", "Close")
if s == 1 then
-- Triggers the Python command that checks the API
cmdchat("checkvote "..pc.get_name())
elseif s == 2 then
say_title("How to Vote")
say("")
say("1. Open metin2.gg in your browser")
say("2. Find our server page")
say("3. Enter your character name")
say("4. Click the Vote button")
say("5. Come back here to claim your reward!")
say("")
end
end
end
endMetin2 Integráció: PHP Web Panel
Ha a szerverednek van web panelje (PHP alapú), használd ezt a kódrészletet a szavazatok ellenőrzéséhez és beváltásához a panelből. Bármilyen PHP 7+ környezetben működik cURL-lel.
<?php
/**
* check_vote.php — Vote check for PHP-based web panels
* Requires PHP 7.0+ with cURL extension
*/
$apiKey = "mg_live_YOUR_KEY_HERE";
$playerName = $_GET["player"] ?? "";
if (empty($playerName)) {
echo json_encode(["error" => "Missing player name"]);
exit;
}
// Check vote status
$ch = curl_init(
"https://metin2.gg/api/v1/vote/check?player_id=" . urlencode($playerName)
);
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => ["X-API-Key: $apiKey"],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 10,
CURLOPT_SSL_VERIFYPEER => true,
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode !== 200) {
echo json_encode(["error" => "API returned HTTP $httpCode"]);
exit;
}
$data = json_decode($response, true);
if ($data["voted"] ?? false) {
// Player has voted — grant reward via your game DB
// Example: INSERT INTO player.reward_queue (player, item_vnum, count) ...
echo json_encode([
"success" => true,
"message" => "Vote reward granted!",
"vote_id" => $data["vote_id"],
]);
} else {
echo json_encode([
"success" => false,
"message" => "No pending vote found.",
]);
}Sebességkorlátozások és Hibakódok
Az API sebességkorlátozásokat alkalmaz a tisztességes használat biztosítására. Jelenlegi korlátok:
- 60 requests per minute per API key
- 1,000 requests per hour per API key
| Állapot | Leírás |
|---|---|
| 200 OK | Kérés sikeres. |
| 400 Bad Request | Hiányzó vagy érvénytelen paraméterek. Ellenőrizd a player_id vagy vote_ids formátumát. |
| 401 Unauthorized | Hiányzó vagy érvénytelen API kulcs. Győződj meg róla, hogy tartalmazza az X-API-Key fejlécet. |
| 403 Forbidden | Az API hozzáférés letiltva — általában azért, mert a visszamutató link eltávolításra került. Add vissza a visszamutató linket és ellenőrizd. |
| 404 Not Found | A végpont nem létezik. Ellenőrizd újra az URL útvonalat. |
| 429 Too Many Requests | Sebességkorlát túllépve. Várj és próbáld újra a Retry-After fejléc értéke (másodpercben) után. |
| 500 Internal Server Error | Valami hiba történt a mi oldalunkon. Próbáld újra néhány másodperc múlva. |
Újrapróbálkozási Stratégia
On 429 errors, read the Retry-After header (value in seconds) and wait before retrying. For 500 errors, retry with exponential backoff (1s, 2s, 4s).
Hibaelhárítás GYIK
Minden kérésnél 401 Unauthorized-ot kapok
Győződj meg róla, hogy az API kulcsot az X-API-Key fejlécben küldöd (nem lekérdezési paraméterként vagy a törzsben). A kulcsnak mg_live_ előtaggal kell kezdődnie.
Az API azt mondja voted: false, de a játékos állítja, hogy szavazott
A játékos lehet, hogy a karakterneve megadása nélkül szavazott, vagy más nevet használt. Ellenőrizd a szavazási link URL-jét — tartalmaznia kell a ?player_id=PONTOS_NÉV részt. A nevek nem különböztetik meg a kis- és nagybetűket.
403 Forbidden-t kapok
Az API hozzáférésed szünetel, valószínűleg azért, mert a metin2.gg-re mutató visszamutató link eltávolításra került a weboldaladról. Add vissza és kattints a panelben a 'Ellenőrzés Most' gombra az újraellenőrzéshez.
Tesztelhetem az API-t valódi szavazatok nélkül?
Jelenleg nincs sandbox mód. Szavazz a saját szervered listáján egy teszt karakternévvel, hogy ellenőrizd az integrációt végig.
A Python scriptem nem tud csatlakozni (időtúllépés vagy SSL hiba)
A legtöbb Metin2 szerver Python 2.7-et használ, amelynek elavultak az SSL tanúsítványai. Használd a Python példában mutatott os.popen('curl ...') tartalékot, vagy frissítsd a szervered Python CA csomagját.
Milyen gyakran kell pollingolnom az API-t?
A /check végpontnál (játékosonként): hívd meg, amikor a játékos kéri a jutalmát (pl. /reward parancs). A /unclaimed-nél (kötegelt): 3–5 percenként cron-nal ideális. Ne pollingolj percenként egynél többször.
Több szerver megoszthat egy API kulcsot?
Nem. Minden API kulcs egy szerver listához van kötve. Ha több szervert üzemeltetsz, generálj mindegyikhez külön kulcsot a megfelelő panel oldalakról.
Mi történik, ha a webhook végpontom nem elérhető?
A metin2.gg legfeljebb 5 alkalommal próbálja újra a sikertelen webhook kézbesítéseket exponenciális visszalépéssel. Ha minden próba sikertelen, a szavazat be nem váltott marad, és továbbra is lekérhető a polling végpontokon keresztül.
Készen Állsz az Integrációra?
Add hozzá a szerveredet a metin2.gg-hez, generálj egy API kulcsot és kezdd el jutalmakkal ellátni a szavazókat percek alatt.