Intégration du vote

Metin2-Help enregistre et valide le vote. Le site de votre serveur identifie le joueur, accorde la récompense dans son propre système et confirme le traitement. Nous ne recevons pas les identifiants de jeu et nous ne modifions ni pièces ni objets.

Guide pour Apache, Nginx, Laravel, WordPress et Cloudflare

La soumission, la publication approuvée, le vote, le widget standard et l'API de base sont gratuits. Il n'y a pas d'abonnement.

Enregistrez le serveur — Un compte connecté remplit le formulaire et le soumet pour vérification, ou le conserve comme brouillon.
Vérifiez le domaine — Publiez le jeton dans /.well-known/metin2-help-verify.txt ou dans un enregistrement DNS TXT. Un modérateur peut le confirmer manuellement.
Obtenez l'approbation — Seul un serveur approuvé avec une propriété vérifiée peut générer une clé API.
Générez la clé — La clé n'est affichée qu'une seule fois. Stockez-la sur le serveur, pas dans le navigateur des joueurs.
Installez le script — L'exemple PHP crée un intent et, séparément, lit les votes non réclamés.
Créez l'intent — Votre site envoie l'identifiant du joueur et reçoit une URL avec un jeton opaque. Le jeton expire dans 30 minutes.
Envoyez le joueur — Le joueur se connecte sur Metin2-Help et vote. Ouvrir l'URL n'est pas un vote.
Vérifiez les votes — Vous interrogez les votes non réclamés avec la clé du serveur.
Accordez la récompense — Vous l'accordez dans votre propre base de données ou système. Metin2-Help ne l'accorde pas.
Confirmez — Vous envoyez les IDs des votes traités. Répéter la même confirmation ne crée pas de second reçu.
Réessayez après une erreur — Si la confirmation n'arrive pas, le vote reste non réclamé et vous pouvez réessayer. La livraison dans le jeu n'est pas exactly-once.
Faites tourner la clé — La rotation révoque immédiatement l'ancienne clé. Mettez le script à jour avant l'appel suivant.

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

Que dois-je installer sur mon site ?

L'ID public du serveur, affiché sur la page d'édition.
La clé API, uniquement lorsqu'elle est générée, stockée dans votre backend.
Le lien de vote simple, qui peut figurer dans un bouton HTML et n'identifie pas un joueur.
Le flux de vote avec récompense, qui nécessite votre backend.
L'exemple PHP, que vous adaptez à la récompense locale.
Les endpoints API ci-dessous.
La requête des votes non réclamés et la réclamation, une fois la récompense locale enregistrée.

Lien de vote simple

Il peut être placé dans un bouton HTML. Il ne contient pas d'ID joueur et n'accorde pas de récompense à lui seul.

Vote avec récompense

Votre site identifie le joueur connecté.
Il crée un intent via l'API et reçoit vote_url.
Il redirige le joueur vers vote_url. L'ouvrir n'est pas un vote.
Après le vote, vous interrogez les votes non réclamés.
Vous accordez la récompense dans votre propre système et l'enregistrez localement par Vote ID.
Vous confirmez le traitement. Répéter la même confirmation ne crée pas de second enregistrement.

already_claimed signifie seulement que Metin2-Help a enregistré la confirmation. Cela ne prouve pas que la récompense locale a été accordée. Votre journal unique par Vote ID en est la preuve. Si la récompense et le journal partagent une base de données, conservez-les dans une seule transaction. Si ce n'est pas possible, reprenez depuis le journal ; il ne s'agit pas d'une livraison exactly-once dans le jeu.

Systèmes de type Vote4Coins

Le lien Vote4Coins sur la page d'intégration du serveur a la forme https://metin2-help.com/api/vote/{public_id}/{token}/ID. Le token n'est pas la clé API. Remplacer ID ouvre la page pour ce compte, mais ne crée pas d'intent de vote et ne confirme pas de récompense. Si ID reste inchangé, le vote n'est pas rattaché à un joueur. Une récompense confirmée nécessite la connexion avancée.

Certains sites n'acceptent qu'un callback de la forme https://your-website/api/vote4coins/callback/INDEX?username=PLAYER&key=SECRET. Cette forme est un exemple. Ce n'est pas un endpoint Metin2-Help et ce n'est pas une vraie clé.

Metin2-Help n'appelle pas automatiquement un callback arbitraire du propriétaire. L'API actuelle utilise un intent de vote, un vote validé, du polling et une confirmation de claim.

Un système qui n'accepte qu'une URL de callback nécessite un adaptateur sur le backend du propriétaire ou un support explicite du protocole. Metin2-Help ne modifie pas votre site et n'accède pas à la base de données du jeu.

PHP personnalisé : l'exemple de script peut être exécuté à la demande ou par cron. Laravel : le même client HTTP dans une commande planifiée. Cron : interrogez et confirmez après que le journal local a enregistré la récompense.

Sans modifier le cœur du jeu, vous pouvez conserver le journal et la récompense dans une base que vous contrôlez. La livraison au compte de jeu reste gérée par votre code.

Termes différents

Vote URL. La page qu'un joueur ouvre pour voter. Un vote simple utilise la page publique. Un vote avec récompense utilise vote_url renvoyé à votre backend, avec un token opaque.

API verification URL. Un endpoint que votre site interroge pour savoir si un vote existe. Sur Metin2-Help, il s'agit de l'API avec la clé dans un en-tête, pas d'une URL contenant la clé.

Callback. Une adresse sur votre domaine qu'un système externe appellerait après un vote. Metin2-Help n'appelle pas automatiquement un callback choisi dans un autre logiciel.

Postback. Le même type d'appel inverse, souvent un GET ou un POST vers votre site. Une table Vote4Coins peut afficher son propre postback, pas le lien de vote que vous avez saisi.

Player ID. L'identifiant du compte depuis le site du serveur. Dans le lien Vote4Coins, il remplace le segment ID uniquement si ce site effectue le remplacement. Dans l'intégration avancée, le backend l'envoie comme player_ref. Metin2-Help ne vérifie pas qu'il existe dans le jeu.

Username. Il peut avoir la même valeur que player_ref si c'est l'identifiant que vous utilisez. Metin2-Help ne vérifie pas qu'il existe dans le jeu.

API key. Le secret que votre backend utilise pour s'authentifier auprès de Metin2-Help. Il n'est affiché qu'une fois et ne doit pas figurer dans le HTML.

Callback secret. Un secret appartenant au système de votre site. Ce n'est pas la clé API Metin2-Help et il ne doit pas nous être envoyé.

Vote Intent. L'enregistrement temporaire qui lie un joueur à un vote qui n'a pas encore eu lieu.

Claim. Votre confirmation que vous avez traité le Vote ID. À lui seul, cela ne prouve pas que la récompense a atteint le jeu.

Ce qu'on peut établir à propos de Vote4Coins

Le nom Vote4Coins couvre plusieurs implémentations avec des protocoles différents. Il n'existe pas de contrat public unique que Metin2-Help puisse déclarer compatible.

Certaines toplists envoient un POST JSON à un callback configuré par le propriétaire, avec un userid, un timestamp et un hash. D'autres attendent que le site du propriétaire interroge une API et reçoive 0 ou 1. D'autres encore génèrent, sur le domaine du propriétaire, un endpoint de callback pour chaque inscription.

Un tableau montrant des adresses de la forme https://your-website/api/vote4coins/callback/0?username={username}&key=SECRET affiche, par cette forme, des endpoints de votre site. Ce ne sont pas les liens de vote saisis et ce ne sont pas des endpoints Metin2-Help. Des clés différentes pour différentes lignes sont cohérentes avec des secrets générés localement, un par ligne.

Cette observation n'a pas été vérifiée dans le panneau privé d'un site, et aucune requête n'a été envoyée à ces adresses. Ne la traitez pas comme une description de toutes les installations.

Metin2-Help n'appelle pas ces callbacks. Son propre webhook est séparé, facultatif, désactivé par défaut, uniquement en HTTPS, et seulement vers l'adresse enregistrée dans l'éditeur du serveur, avec une signature HMAC. Il ne remplace pas un postback Vote4Coins.

Si votre installation peut appeler une API HTTPS avec un en-tête X-API-Key, adaptez le backend au contrat ci-dessus. Si elle n'accepte qu'un postback reçu sur son propre callback, vous avez besoin d'un adaptateur sur votre site : l'adaptateur vérifie le vote auprès de Metin2-Help et alors seulement peut notifier le système local. Metin2-Help ne fait pas cet appel.

Pour savoir ce que votre installation peut faire, consultez sa documentation : si elle accepte un client HTTP avec en-tête personnalisé, seulement une URL de vote, ou seulement un postback entrant. Sans ce détail, l'intégration ne peut pas être considérée comme fonctionnelle.

Que dois-je copier, et où ?

A. Je veux seulement des votes de classement. Copiez le lien public simple ou un widget. Ne copiez pas la clé API.

B. J'ai un site PHP et je peux modifier le backend. Placez la clé et le Public ID dans la configuration du serveur, puis utilisez l'exemple PHP : intent, vote_url, votes non réclamés, récompense locale, claim.

C. J'ai Vote4Coins et je peux appeler une API personnalisée. Votre backend doit être adapté au contrat Metin2-Help. Ne collez pas la clé dans un champ de callback.

D. J'ai Vote4Coins qui n'accepte qu'un postback. Metin2-Help n'appelle pas ce postback. Sans adaptateur sur votre site, les récompenses automatiques ne sont pas disponibles.

E. Je ne peux pas modifier le code du site. Vous pouvez coller le lien Vote4Coins dans le champ existant. Si le site ne remplace pas ID, le vote n'est pas lié à un joueur. Une récompense confirmée reste liée à l'intégration avancée.

Le lien Vote4Coins et l'identifiant

Le lien se termine par ID. Un site qui remplace ID ouvre la page pour ce compte, mais ne crée pas d'intent de vote. Un site qui laisse ID inchangé n'associe pas le vote à un joueur. Le token dans le lien n'est pas la clé API. Une récompense confirmée reste liée à la connexion avancée : un intent créé par le site, un vote confirmé et un claim.

Vote simple : le joueur ouvre la page et vote, sans ID joueur associé.

Vote avec récompense : votre site crée l'intent, et la récompense n'est accordée de votre côté qu'après confirmation.

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 signifie que la clé est manquante ou incorrecte. 403 signifie un autre serveur, un serveur non approuvé ou une propriété non vérifiée. 404 correspond à un intent absent. 422 à un identifiant invalide. 429 est la limite de débit.

Le webhook est facultatif et reste désactivé tant que vous ne l'activez pas. La signature est HMAC-SHA256 sur l'horodatage, le nonce et le corps. Le polling reste la méthode de récupération. Nous n'envoyons pas vers des adresses internes.

La promotion payante n'est pas active et ne modifie pas l'ordre des votes.

Télécharger l'exemple 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