Ссылка для голосования

Формат

https://l2nx.top/{tenantSlug}/vote?ref={ref}&server={serverSlug}

Часть	Обязательна	Смысл
tenantSlug	да	Slug вашего проекта, тот же, что в https://l2nx.top/{tenantSlug}.
ref	нет	Ваш идентификатор этого голоса. Возвращается без изменений в вебхуке и в ленте.
server	нет	Slug одного из ваших серверов. Предвыбирает его на странице голосования; игрок может сменить.

Оба query-параметра необязательны. Голос по ссылке без ref тоже идёт в рейтинг, но узнать, кто голосовал, вы не сможете.

Ссылка без языка открывает страницу на языке игрока. Чтобы задать язык явно, добавьте его в путь: https://l2nx.top/en/{tenantSlug}/vote, /ru/, /uk/ или /es/. Query-параметры сохраняются.

Если slug проекта сменится, старые ссылки перенаправят на новый адрес вместе с ref и server.

Что передавать в ref

ref — непрозрачная строка: l2nx.top сохраняет её и возвращает, больше ничего.

• До 128 символов, без управляющих символов. Более длинный ref не даст проголосовать. Ограничьтесь символами A-Z a-z 0-9 - _, тогда значение не нужно URL-кодировать.
• Не обрезается и не меняется. Пустой ref считается отсутствующим.
• Стабильный и ваш. По нему вы должны найти игрока, когда голос вернётся.

Рекомендуемый вариант — id попытки голосования: когда игрок хочет проголосовать, сгенерируйте случайный id (например, UUID), сохраните его вместе с аккаунтом игрока и передайте в ref. Когда придёт голос, найдите id и наградите аккаунт один раз.

Это лучше, чем класть в ссылку id аккаунта напрямую:

• игрок видит ссылку и может её изменить: случайный id не угадать, а id аккаунта можно подменить чужим;
• вы можете отклонять значения ref, которые никогда не выдавали, и уже награждённые попытки.

Осторожно

Ссылку видят игрок, история браузера и данные l2nx.top. Никогда не кладите в ref адреса e-mail, логины, имена персонажей, пароли, токены сессий и любые другие персональные или секретные данные.

На сайте

Сформируйте ссылку на сервере для вошедшего игрока и покажите её кнопкой.

vote-link.php

<?php
// $attemptId: random id stored with the player's account, e.g. bin2hex(random_bytes(16))
$link = 'https://l2nx.top/myproject/vote?' . http_build_query([
    'ref' => $attemptId,
    'server' => 'x100',
]);
?>
<a href="<?= htmlspecialchars($link) ?>" target="_blank" rel="noopener">Проголосовать за нас на l2nx.top</a>

vote-link.js

// attemptId: random id stored with the player's account, e.g. crypto.randomUUID()
const link = new URL("https://l2nx.top/myproject/vote");
link.searchParams.set("ref", attemptId);
link.searchParams.set("server", "x100");

Ссылка без игрока, для баннера или публичной страницы:

banner.html

<a href="https://l2nx.top/myproject/vote" target="_blank" rel="noopener"
  >Проголосовать за нас на l2nx.top</a
>

В игре

Голосуют в браузере, поэтому игре достаточно показать игроку его личную ссылку. Типичные варианты:

• кнопка голосования в Community Board или диалоге NPC, которая открывает страницу голосования на вашем сайте;
• команда в чате, которая создаёт попытку и выводит личную ссылку.

Создайте попытку на своей стороне в этот момент, так же как на сайте, и выдайте награду по пришедшему голосу.

Как получить голос обратно

• Вебхуки: l2nx.top присылает каждый голос на ваш эндпоинт, обычно в течение нескольких секунд.
• Лента голосов: опрашивайте Integration API, чтобы забрать пропущенные голоса.

Эндпоинт вебхука и API key для ленты настраиваются по запросу: см. Получение доступа.