Integrare voturi

Metin2-Help înregistrează și validează votul. Website-ul serverului tău identifică jucătorul, acordă recompensa în sistemul propriu și confirmă procesarea. Nu trimitem credențiale de joc și nu modificăm monede sau iteme.

Ghid pentru Apache, Nginx, Laravel, WordPress și Cloudflare

Înscrierea, publicarea aprobată, votul, widgetul standard și API-ul de bază sunt gratuite. Nu există abonament.

Înregistrează serverul — Contul autentificat completează formularul și îl trimite spre moderare sau îl păstrează ca ciornă.
Verifică domeniul — Publică tokenul în fișierul /.well-known/metin2-help-verify.txt sau într-un TXT DNS. Moderatorul poate confirma manual.
Primește aprobarea — Doar un server aprobat și cu proprietatea verificată poate genera cheia API.
Generează cheia — Cheia se afișează o singură dată. O păstrezi pe server, nu în browserul jucătorilor.
Instalează scriptul — Exemplul PHP creează intenția și, separat, citește voturile neconfirmate.
Creează intenția — Website-ul tău trimite identificatorul jucătorului și primește un URL cu token opac. Tokenul expiră în 30 de minute.
Trimite jucătorul — Jucătorul se autentifică pe Metin2-Help și votează. Deschiderea URL-ului nu este un vot.
Verifică voturile — Interoghezi voturile neconfirmate cu cheia serverului.
Acordă recompensa — O acorzi în baza sau în sistemul tău. Metin2-Help nu o acordă.
Confirmă — Trimiți Vote ID-urile procesate. Aceeași confirmare repetată nu creează o a doua înregistrare.
Reia la eroare — Dacă confirmarea nu ajunge, votul rămâne neconfirmat și îl poți relua. Nu promitem livrare exact o singură dată către joc.
Rotește cheia — Rotirea revocă cheia veche imediat. Actualizezi scriptul înainte de următorul apel.

API

POST /api/v1/servers/{public_id}/vote-intents
GET /api/v1/vote-intents/{intent_id}
GET /api/v1/servers/{public_id}/votes/unclaimed
POST /api/v1/servers/{public_id}/votes/claim
GET /api/v1/servers/{public_id}/stats
GET /api/v1/servers/{public_id}/integration

Ce trebuie să instalez pe website-ul meu?

Public ID-ul serverului, vizibil în editare.
Cheia API, doar în momentul generării, păstrată în backend.
Linkul de vot simplu, care poate sta într-un buton HTML și nu identifică jucătorul.
Fluxul de vot cu recompensă, care are nevoie de backendul tău.
Exemplul PHP, pe care îl adaptezi pentru recompensa locală.
Endpointurile API de mai jos.
Interogarea voturilor neconfirmate și confirmarea lor după ce recompensa locală a fost înregistrată.

Link de vot simplu

Poate fi pus într-un buton HTML. Nu conține identificatorul jucătorului și nu acordă automat o recompensă.

Vot cu recompensă

Website-ul tău identifică jucătorul autentificat.
Creează intenția prin API și primește vote_url.
Redirecționează jucătorul către vote_url. Deschiderea nu este un vot.
După vot, interoghezi voturile neconfirmate.
Acorzi recompensa în sistemul tău și o notezi local pe Vote ID.
Confirmi procesarea. O confirmare repetată nu creează o a doua înregistrare.

Răspunsul already_claimed arată doar că Metin2-Help a înregistrat confirmarea. Nu dovedește că recompensa locală a fost acordată. Jurnalul tău unic pe Vote ID este dovada. Dacă recompensa și jurnalul sunt în aceeași bază, ține-le în aceeași tranzacție. Dacă nu poți face asta atomic, reia din jurnal; nu promitem exact-once către joc.

Sisteme de tip Vote4Coins

Linkul Vote4Coins din pagina de integrare a serverului are forma https://metin2-help.com/api/vote/{public_id}/{token}/ID. Tokenul nu este cheia API. Înlocuirea lui ID deschide pagina pentru acel cont, dar nu creează intenția de vot și nu confirmă recompensa. Dacă ID rămâne neschimbat, votul nu este asociat unui jucător. Recompensa confirmată cere conexiunea avansată.

Unele website-uri acceptă doar un callback de forma https://website-ul-tau/api/vote4coins/callback/INDEX?username=PLAYER&key=SECRET. Acesta este un exemplu de formă, nu un endpoint Metin2-Help și nu conține o cheie reală.

Metin2-Help nu apelează automat un callback arbitrar furnizat de owner. API-ul actual folosește intenția de vot, votul validat, interogarea și confirmarea claim.

Un sistem care acceptă exclusiv callback URL are nevoie de un adaptor pe backendul ownerului sau de suport explicit pentru protocol. Metin2-Help nu modifică website-ul tău și nu accesează baza jocului.

PHP custom: scriptul de exemplu poate rula la cerere sau din cron. Laravel: același client HTTP într-o comandă programată. Cron: rulezi interogarea și confirmarea după ce jurnalul local a înregistrat recompensa.

Fără modificări în nucleul jocului poți păstra jurnalul și recompensa într-o bază separată pe care o controlezi. Livrarea în contul de joc rămâne codul tău.

Termeni diferiți

Vote URL. Pagina pe care jucătorul o deschide ca să voteze. La votul simplu este pagina publică. La votul cu recompensă este vote_url primit de backend, cu token opac.

API verification URL. Un endpoint pe care website-ul tău îl întreabă dacă un vot există. La Metin2-Help acesta este API-ul cu cheia în header, nu un URL care conține cheia.

Callback. O adresă pe domeniul tău, pe care un sistem extern ar apela-o după un vot. Metin2-Help nu apelează automat un callback ales de tine în alt software.

Postback. Același tip de apel invers, adesea prin GET sau POST către website-ul tău. Tabelul unui Vote4Coins poate afișa postback-ul propriu, nu linkul de vot pe care l-ai introdus.

Player ID. Identificatorul contului de pe website-ul serverului. În linkul Vote4Coins înlocuiește segmentul ID doar dacă website-ul face această înlocuire. În integrarea avansată, backendul îl trimite ca player_ref. Metin2-Help nu verifică existența lui în joc.

Username. Poate fi același lucru cu player_ref, dacă tu îl folosești ca identificator. Metin2-Help nu verifică existența lui în joc.

API key. Secretul cu care backendul tău se autentifică la Metin2-Help. Se arată o singură dată și nu intră în HTML.

Callback secret. Un secret al sistemului de pe website-ul tău. Nu este cheia API Metin2-Help și nu trebuie trimis către noi.

Vote Intent. Înregistrarea temporară care leagă un jucător de un vot care încă nu s-a întâmplat.

Claim. Confirmarea ta că ai procesat Vote ID-ul. Nu dovedește, singură, că recompensa a ajuns în joc.

Ce s-a putut stabili despre Vote4Coins

Numele Vote4Coins acoperă mai multe implementări, cu protocoale diferite. Nu există un singur contract public pe care Metin2-Help să îl poată declara compatibil.

Unele toplist-uri trimit un POST JSON către un callback configurat de owner, cu userid, timestamp și un hash. Altele cer ca website-ul ownerului să interogheze un API și să primească 0 sau 1. Altele generează, pe domeniul ownerului, câte un endpoint de callback pentru fiecare înregistrare.

Un tabel care arată adrese de forma https://website-ul-tau/api/vote4coins/callback/0?username={username}&key=SECRET afișează, după forma lor, endpointuri ale website-ului tău. Nu sunt linkurile de vot introduse și nu sunt endpointuri Metin2-Help. Chei diferite pentru înregistrări diferite sunt compatibile cu secrete generate local, câte unul pe rând.

Această observație nu a fost verificată în panoul unui website privat și nu s-a trimis nicio cerere către astfel de adrese. Nu o trata ca pe o descriere a tuturor instalărilor.

Metin2-Help nu apelează aceste callbackuri. Webhookul propriu este separat, opțional, oprit implicit, doar HTTPS și doar către adresa salvată în editarea serverului, cu semnătură HMAC. Nu înlocuiește un postback Vote4Coins.

Dacă instalarea ta poate apela un API HTTPS cu header X-API-Key, adaptezi backendul la contractul de mai sus. Dacă acceptă doar un postback primit la callbackul ei, ai nevoie de un adaptor pe website-ul tău: adaptorul verifică votul la Metin2-Help și abia apoi poate anunța sistemul local. Metin2-Help nu face acest apel.

Ca să știi ce poate instalarea ta, verifică în documentația ei: acceptă un client HTTP cu header propriu, doar un URL de vot, sau doar un postback primit. Fără acest detaliu nu se poate spune că integrarea funcționează.

Ce trebuie să copiez și unde?

A. Vreau doar voturi în clasament. Copiezi linkul public simplu sau un widget. Nu copiezi cheia API.

B. Am website PHP și pot modifica backendul. Pui cheia și Public ID-ul în configurația serverului, apoi folosești exemplul PHP: intenție, vote_url, voturi neconfirmate, recompensă locală, claim.

C. Am Vote4Coins și pot apela un API propriu. Backendul tău trebuie adaptat la contractul Metin2-Help. Nu lipi cheia într-un câmp de callback.

D. Am Vote4Coins care acceptă doar postback. Metin2-Help nu apelează acel postback. Fără un adaptor pe website-ul tău, recompensarea automată nu este disponibilă.

E. Nu am acces la codul website-ului. Poți lipi linkul Vote4Coins în câmpul existent. Dacă website-ul nu înlocuiește ID, votul nu este legat de un jucător. Recompensa confirmată rămâne la integrarea avansată.

Linkul Vote4Coins și identificatorul

Linkul se termină cu ID. Website-ul care înlocuiește ID deschide pagina pentru acel cont, dar nu creează o intenție de vot. Website-ul care lasă ID neschimbat nu asociază un jucător. Tokenul din link nu este cheia API. Recompensa confirmată rămâne la conexiunea avansată: intenție creată de website, vot confirmat și claim.

Vot simplu: jucătorul deschide pagina și votează, fără legătură cu un player ID.

Vot cu recompensă: website-ul tău creează intenția, iar recompensa se acordă doar la tine după confirmare.

POST /vote-intents

{
  "player_ref": "Hero.1",
  "idempotency_key": "player-hero-1-try"
}

{
  "intent_id": "0123456789abcdef01234567",
  "vote_url": "https://metin2-help.com/servere/{slug}/vot/{token}",
  "expires_at": "2026-11-14 02:00:00",
  "status": "pending"
}

POST /votes/claim

{ "vote_ids": [120] }

{ "data": [{ "vote_id": 120, "result": "claimed" }] }

401 înseamnă cheie lipsă sau greșită. 403 înseamnă alt server, server neaprobat sau proprietate neverificată. 404 este o intenție inexistentă. 422 este un identificator invalid. 429 este limita de ritm.

Webhookul este opțional și rămâne oprit până îl activezi. Semnătura este HMAC-SHA256 pe timestamp, nonce și corp. Pollingul rămâne metoda de recuperare. Nu trimitem către adrese interne.

Promovarea plătită nu este activă și nu schimbă ordinea voturilor.

Descarcă exemplul PHP

<?php

/**
 * Exemplu de adaptat pe website-ul serverului privat.
 * Metin2-Help confirmă votul. Recompensa se acordă doar în sistemul tău.
 * Nu pune cheia în JavaScript sau în pagini publice.
 * Acest client nu apelează un callback Vote4Coins. Recompensa rămâne în sistemul tău.
 *
 * Variabile de mediu:
 * M2H_API_KEY, M2H_SERVER_ID, M2H_REWARD_DSN, M2H_REWARD_USER, M2H_REWARD_PASSWORD
 */

declare(strict_types=1);

const M2H_API = 'https://metin2-help.com';

function m2h_request(string $method, string $path, ?array $body = null): array
{
    $key = getenv('M2H_API_KEY');
    $server = getenv('M2H_SERVER_ID');
    if (!is_string($key) || $key === '' || !is_string($server) || $server === '') {
        throw new RuntimeException('Configurația API lipsește.');
    }
    $url = M2H_API . str_replace('{server}', rawurlencode($server), $path);
    $ch = curl_init($url);
    if ($ch === false) {
        throw new RuntimeException('Clientul HTTP nu a pornit.');
    }
    $headers = ['Accept: application/json', 'X-API-Key: ' . $key];
    $options = [
        CURLOPT_CUSTOMREQUEST => $method,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 15,
        CURLOPT_PROTOCOLS => CURLPROTO_HTTPS,
    ];
    if ($body !== null) {
        $headers[] = 'Content-Type: application/json';
        $options[CURLOPT_POSTFIELDS] = json_encode($body, JSON_UNESCAPED_SLASHES);
    }
    $options[CURLOPT_HTTPHEADER] = $headers;
    curl_setopt_array($ch, $options);
    $raw = curl_exec($ch);
    $code = (int) curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);
    $decoded = is_string($raw) ? json_decode($raw, true) : null;
    if (!is_array($decoded)) {
        throw new RuntimeException('Răspuns API invalid, HTTP ' . $code);
    }
    $decoded['_http'] = $code;

    return $decoded;
}

function m2h_start(string $playerRef): array
{
    if (!preg_match('/^[A-Za-z0-9_.:@-]{1,64}$/', $playerRef)) {
        throw new InvalidArgumentException('Identificatorul jucătorului nu este acceptat.');
    }

    return m2h_request('POST', '/api/v1/servers/{server}/vote-intents', [
        'player_ref' => $playerRef,
        'idempotency_key' => bin2hex(random_bytes(16)),
    ]);
}

function m2h_reward_pdo(): PDO
{
    return new PDO(
        (string) getenv('M2H_REWARD_DSN'),
        (string) getenv('M2H_REWARD_USER'),
        (string) getenv('M2H_REWARD_PASSWORD'),
        [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]
    );
}

/**
 * Înlocuiește corpul acestei funcții cu recompensa serverului tău.
 * Dacă recompensa și jurnalul sunt în aceeași bază, ține-le în aceeași tranzacție.
 * Dacă sunt sisteme diferite, păstrează jurnalul local înainte de confirmare
 * și reia din jurnal la următoarea rulare. Metin2-Help nu promite livrare unică
 * către joc; confirmarea repetată a aceluiași Vote ID nu mai creează o confirmare nouă.
 */
function m2h_grant_local(PDO $pdo, int $voteId, string $playerRef): void
{
    $pdo->beginTransaction();
    try {
        $seen = $pdo->prepare('INSERT INTO owner_vote_rewards (vote_id, player_ref, granted_at) VALUES (?, ?, ?)');
        $seen->execute([$voteId, $playerRef, gmdate('Y-m-d H:i:s')]);
        // Exemplu de înlocuit: $pdo->prepare('UPDATE account SET coins = coins + ? WHERE id = ?')->execute([10, $playerRef]);
        $pdo->commit();
    } catch (PDOException $exception) {
        if ($pdo->inTransaction()) {
            $pdo->rollBack();
        }
        if ((string) $exception->getCode() !== '23000') {
            throw $exception;
        }
    }
}

function m2h_poll(): void
{
    $pdo = m2h_reward_pdo();
    $pdo->exec('CREATE TABLE IF NOT EXISTS owner_vote_rewards (vote_id BIGINT NOT NULL PRIMARY KEY, player_ref VARCHAR(64) NOT NULL, granted_at DATETIME NOT NULL)');
    $cursor = 0;
    do {
        $page = m2h_request('GET', '/api/v1/servers/{server}/votes/unclaimed?limit=50&cursor=' . $cursor);
        $rows = $page['data'] ?? [];
        $ids = [];
        foreach ($rows as $row) {
            if (!is_array($row) || empty($row['vote_id']) || empty($row['player_ref'])) {
                continue;
            }
            m2h_grant_local($pdo, (int) $row['vote_id'], (string) $row['player_ref']);
            $ids[] = (int) $row['vote_id'];
        }
        if ($ids !== []) {
            $claim = m2h_request('POST', '/api/v1/servers/{server}/votes/claim', ['vote_ids' => $ids]);
            foreach ($claim['data'] ?? [] as $result) {
                // already_claimed nu dovedește recompensa locală. Dovada este rândul din owner_vote_rewards.
                if (($result['result'] ?? '') === 'rejected') {
                    error_log('Metin2-Help a respins vote_id ' . (int) ($result['vote_id'] ?? 0));
                }
            }
        }
        $cursor = (int) ($page['next_cursor'] ?? 0);
    } while ($cursor > 0);
}

if (PHP_SAPI === 'cli' && isset($argv[1]) && $argv[1] === 'poll') {
    m2h_poll();
}

API