Документація

Magicgate відокремлює трафік ботів від реальних користувачів, оцінюючи кожного відвідувача за настроюваним набором фільтрів. Платформа повертає вердикт — «білий» (bot/crawler/unwanted) або «пропозиція» (справжній користувач) — менш ніж за 10 мілісекунд.

Є два режими інтеграції. API Mode дозволяє надсилати атрибути відвідувача через кінцеву точку REST і отримувати вердикт JSON, згідно з яким діє ваша програма. Direct Mode обробляє все автоматично: наведіть свій домен на Magicgate, і відвідувачі будуть відфільтровані та перенаправлені без будь-яких змін коду з вашого боку.

Цей короткий початок зосереджено на API Mode, оскільки він дає вам найбільший контроль і найшвидший цикл зворотного зв’язку під час розробки. Коли вам буде зручно, ви можете перейти на Direct Mode для робочих розгортань, де бажана інтеграція без коду.

Magicgate оцінює кожного вхідного відвідувача за багаторівневим конвеєром виявлення. Кожен фільтр працює незалежно та вносить свій внесок у остаточний вердикт. Уся оцінка завершується менш ніж за 10 мілісекунд, забезпечуючи нульову відчутну затримку для реальних користувачів.

Конвеєр виявлення поділяється на кілька категорій: перевірки на рівні мережі (репутація IP, GeoIP, VPN/proxy/Tor виявлення, ідентифікація центру обробки даних), перевірки на рівні браузера (аналіз агента користувача, цифровий відбиток JavaScript, узгодженість заголовків), поведінкові перевірки (шаблони кліків, швидкість сеансу, перевірка реферера) і перевірки на основі списків (чорні списки, дозволені списки, фільтрація ISP).

Кожен фільтр можна окремо ввімкнути або вимкнути для кожного потоку. Цей детальний елемент керування дозволяє точно налаштувати виявлення для різних джерел трафіку. Наприклад, кампанія, націлена на користувачів мобільних пристроїв у США, може ввімкнути GeoIP (лише в США), VPN/проксі-сервер і перевірку мобільних пристроїв, вимкнувши фільтрацію ISP.

Фільтрація GeoIP використовує локальні бази даних MaxMind, які оновлюються щотижня для пошуку без затримки. Ви можете націлити або виключити трафік за країною, регіоном або містом. База даних охоплює адреси IPv4 та IPv6 із точністю 99,8% на рівні країни.

Виявлення VPN, проксі та Tor об’єднує кілька комерційних і відкритих баз даних. Magicgate постійно оновлює список відомих вузлів виходу VPN, загальнодоступних і приватних проксі-серверів, ретрансляторів виходу Tor і домашніх проксі-мереж. Виявлення охоплює діапазони IPv4 і IPv6.

Виявлення центру обробки даних визначає трафік, що надходить від хмарних провайдерів (AWS, GCP, Azure, DigitalOcean, OVH, Hetzner та понад 200 інших). Це особливо ефективно для виявлення автоматизованих сценаріїв і безголових браузерів, що працюють на віртуальних машинах.

Аналіз агента користувача аналізує рядок агента користувача відвідувача з базою даних відомих сканерів, ботів і автоматизованих інструментів. Він також виявляє невідповідності — наприклад, агент користувача, який видає себе за Chrome у Windows, але надсилає заголовки, специфічні для Linux.

Фільтр чорного списку дозволяє підтримувати власні списки IP-адрес, діапазонів IP (нотація CIDR) і шаблонів агентів користувачів, які завжди слід класифікувати як ботів. І навпаки, фільтр дозволеного списку дає змогу додавати в білий список довірені IP-адреси (наприклад, вашу власну інфраструктуру тестування), які завжди повинні проходити.

Перевірка Referer перевіряє заголовок HTTP Referer на очікувані шаблони. Ви можете вимагати, щоб трафік надходив із певних доменів (наприклад, Google, Facebook) або блокувати трафік із порожніми, відсутніми або підозрілими реферерами.

За своєю суттю Magicgate є маршрутизатором трафіку. Кожен відвідувач оцінюється за вашими налаштованими фільтрами та отримує вердикт: «пропозиція» (законний користувач) або «білий» (бот, сканер або небажаний трафік). Вердикт визначає, куди буде перенаправлений відвідувач.

Сторінка пропозиції – це ваша фактична цільова сторінка, сторінка пропозиції або конверсія – сторінка, яку бажають бачити справжні відвідувачі. Біла сторінка – це приманка або доброякісна сторінка, яка показується роботам, сканерам і рецензентам рекламних мереж. Звичайні білі сторінки містять прості публікації в блогах, новинні статті або загальний інформаційний вміст.

Це розділення є важливим для захисту кампанії. Рецензенти відповідності рекламних мереж, шахрайські роботи та конкуренти бачать білу сторінку, тоді як справжні користувачі з вашої цільової аудиторії потрапляють на сторінку пропозиції. Маршрутизація відбувається прозоро та на швидкості дроту.

У Direct Mode маршрутизація повністю автоматична. Ви вказуєте DNS свого домену на Magicgate, і платформа обробляє весь життєвий цикл запиту: приймає відвідувача, оцінює фільтри та створює перенаправлення HTTP (302 за замовчуванням) до відповідного пункту призначення. Відвідувач ніколи не бачить проміжної сторінки.

У API Mode ваша програма викликає кінцеву точку /api/v1/check з атрибутами відвідувача та отримує відповідь JSON, що містить вердикт і рекомендовану URL-адресу перенаправлення. Потім ваша програма сама обробляє переспрямування. Це дає вам повний контроль над користувальницьким досвідом — ви можете додати спеціальну логіку, журналювання або A/B-тестування перед перенаправленням.

Magicgate підтримує три режими відображення для маршрутизації відвідувачів. "Перенаправлення" (за замовчуванням) створює перенаправлення HTTP на цільову URL-адресу. «Проксі» обслуговує вміст цільової сторінки за вихідною URL-адресою без зміни адресного рядка браузера. «Iframe» завантажує цільову сторінку всередину iframe за вихідною URL-адресою. Режим відображення налаштовується для кожного потоку.

Вердикти обробляються синхронно та ненадовго кешуються для обробки швидких послідовних запитів від одного відвідувача (наприклад, завантаження ресурсів сторінки після початкового перенаправлення). TTL кешу можна налаштувати для кожного потоку, за замовчуванням 30 секунд.

Magicgate пропонує два різні режими інтеграції, кожен з яких призначений для різних випадків використання та технічних вимог. Вибір правильного режиму впливає на складність розгортання, контроль над взаємодією користувача та операційні витрати.

API Mode — це програмна інтеграція. Ваша програма надсилає запит POST до кінцевої точки /api/v1/check з атрибутами відвідувача (IP-адреса, агент користувача, реферер тощо) і отримує відповідь JSON, що містить вердикт. Потім ваш код обробляє маршрутизацію, перенаправляючи ботів на білу сторінку та пропускаючи реальних користувачів. Цей режим вимагає від вас написання коду інтеграції, але дає вам повний контроль над потоком запитів.

Direct Mode є інтеграцією рівня DNS. Ви налаштовуєте записи DNS свого домену (від CNAME до proxy.magicgate.io або ALIAS/ANAME для кореневих доменів), щоб вони вказували на Magicgate. Коли відвідувач приходить, Magicgate прозоро перехоплює запит, оцінює відвідувача та видає перенаправлення HTTP або на сторінку пропозиції, або на білу сторінку. У вашій програмі не потрібно змінювати код — увесь рівень фільтрації та маршрутизації знаходиться перед вашим вихідним сервером.

Переваги API Mode: Повний контроль над логікою маршрутизації. Ви можете додати спеціальну обробку між отриманням вердикту та перенаправленням користувача – ведення журналу, призначення A/B-тесту, налаштування файлів cookie, події аналітики або умовну логіку на основі метаданих вердикту. API Mode працює з будь-яким внутрішнім стеком і не вимагає змін DNS. Він також ідеально підходить для односторінкових програм (SPA), де клієнтський JavaScript виконує перевірку.

Недоліки API Mode: Вимагає змін коду у вашій програмі. Вам потрібно обробляти виклик API, випадки помилок (тайм-аути, обмеження швидкості) і логіку перенаправлення. Виклик API додає час завантаження вашої сторінки в обидва кінці мережі (зазвичай 10-50 мс залежно від географічної близькості до краю Magicgate).

Переваги Direct Mode: нульові зміни коду. Наведіть свій DNS і налаштуйте свій потік - відвідувачі фільтруються та переспрямовуються автоматично. Direct Mode є швидшим для кінцевого користувача, оскільки немає додаткового API-переходу; фільтрація відбувається на межі як частина вирішення DNS та початкового запиту HTTP. Він також прозоро обробляє всі крайні випадки (тайм-аути, повторні спроби).

Недоліки Direct Mode: Менший контроль над процесом маршрутизації. Ви не можете вставити спеціальну логіку між вердиктом і перенаправленням. Зміни DNS поширюються повільно (від хвилин до годин), що уповільнює тестування та відкат. Direct Mode вимагає, щоб ваша біла сторінка та сторінка пропозиції були доступні через публічні URL-адреси.

Можливий також гібридний підхід. Використовуйте Direct Mode для ваших головних цільових сторінок (де інтеграція з нульовим кодом є пріоритетом) і API Mode для конкретних кінцевих точок, які потребують спеціальної обробки висновків (наприклад, надсилання форм, кінцеві точки API або потоки оформлення).

Кожен обліковий запис Magicgate має доступ до спільного домену (go.magicgate.io) для негайного використання. Плани для Starter і вище можуть додавати власні домени для фірмових URL-адрес і покращувати сигнали довіри за допомогою рекламних мереж.

Користувацькі домени дозволяють використовувати власну URL-адресу (наприклад, track.yourbrand.com) замість спільного домену. Це важливо для відповідності реклами — багато рекламних мереж більш поблажливі до трафіку, що надходить із фірмових доменів, ніж із спільних доменів відстеження.

Magicgate підтримує як субдомени (track.yourbrand.com), так і кореневі домени (yourbrand.com). Рекомендовано використовувати субдомени, оскільки вони не заважають конфігурації DNS вашого основного веб-сайту та ними легше керувати.

Перевірка домену використовує записи CNAME, що вказують на proxy.magicgate.io. Коли ви додаєте домен, ви налаштовуєте запис CNAME зі свого домену на proxy.magicgate.io. Для кореневих доменів, які не підтримують записи CNAME, замість цього використовуйте запис ALIAS або ANAME, що вказує на proxy.magicgate.io. Magicgate перевіряє право власності, перевіряючи, чи запис DNS правильно вирішує кінцеву точку проксі.

Сертифікати SSL надаються автоматично через Let's Encrypt після завершення розповсюдження DNS. Magicgate займається видачею, оновленням і встановленням сертифікатів. Ваш власний домен обслуговуватиме трафік через HTTPS із дійсним сертифікатом протягом кількох хвилин після налаштування DNS.

Для користувачів Cloudflare переконайтеся, що проксі (помаранчева хмара) вимкнено для запису CNAME, який вказує на Magicgate. Проксі-сервер Cloudflare перехоплює трафік до того, як він досягне Magicgate, що може заважати оцінці відвідувачів. Встановіть для запису режим «лише DNS» (сіра хмара).

Ви також можете придбати домени безпосередньо через ринок Magicgate. Ці домени попередньо налаштовані та готові до використання негайно – налаштування чи перевірка DNS не потрібні. Ринок пропонує вибір чистих доменів, придатних для кампаній трафіку.

Webhooks дозволяє отримувати сповіщення HTTP POST у режимі реального часу, коли у вашому обліковому записі Magicgate відбуваються важливі події, як-от зміни потоку, підтвердження домену чи оновлення платежів.

Magicgate підтримує події webhook у кількох категоріях: події потоку (flow.created, flow.updated, flow.deleted), події домену (domain.added, domain.verified, domain.deleted, domain.registration_failed), події білої сторінки (white_page.ready, white_page.failed, white_page.deleted), події чорного списку (blacklist.created, blacklist.updated, blacklist.deleted), події API key (apikey.created, apikey.deleted, apikey.activated, apikey.deactivated), події гаманця (wallet.credited, wallet.debited), події підписки (subscription.changed, subscription.canceled, subscription.plan_changed тощо), події виставлення рахунків (payment.completed, payment.failed) і події підтримки (ticket.created, ticket.replied, ticket.resolved, ticket.closed).

Кожна доставка webhook включає три заголовки безпеки: X-Webhook-Signature (шістнадцятковий дайджест HMAC-SHA256), X-Webhook-Timestamp (мітка часу Unix) і X-Webhook-ID (ідентифікатор кінцевої точки). Підпис охоплює мітку часу й тіло разом — обчислюється як HMAC-SHA256(секрет, мітка часу + '.' + тіло), — що запобігає як підробці, так і атакам відтворення. Ви повинні перевірити підпис і відхилити запити з часовими мітками старше 5 хвилин. Секрет підпису генерується, коли ви створюєте кінцеву точку вебхуку, і відображається один раз – зберігайте його безпечно.

Magicgate повторює спробу невдалої доставки через вебхук. Якщо ваша кінцева точка повертає код статусу, відмінний від 2xx, або не відповідає протягом 10 секунд, доставка повторюється. Після того, як усі спроби вичерпано, подія позначається як невдала, а кількість помилок кінцевої точки збільшується.

Корисне навантаження Webhook закодовано в JSON зі структурою: { id, event, timestamp, data }. Поле «event» містить рядок типу події (наприклад, «domain.verified»), «id» — це унікальний ідентифікатор доставки для ідемпотентності, «timestamp» — це дата й час за стандартом ISO 8601, а «data» містить деталі, що стосуються події.

Ви можете налаштувати кілька кінцевих точок вебхуку на обліковий запис, кожна з яких підписана на різні типи подій. Це дає змогу скеровувати події домену до конвеєра розгортання, а події виставлення рахунків — до системи обліку, наприклад.

Magicgate використовує платіжну модель на основі гаманця. Ви додаєте кошти у свій гаманець за допомогою криптовалютних депозитів, і ваша підписка автоматично поновлюється з балансу гаманця під час кожного платіжного циклу. Це усуває необхідність повторного стягнення плати з картки та забезпечує повний контроль над вашими витратами.

Підтримуються три платіжні системи: CCPayment, NowPayments і TransVoucher. Кожен постачальник підтримує Bitcoin, Ethereum, USDT, USDC і понад 50 додаткових криптовалют. Коли ви ініціюєте депозит, генерується платіжна адреса та сума. Коли блокчейн підтвердить транзакцію, баланс вашого гаманця оновлюється автоматично.

Плани визначають обмеження ваших функцій: перевірки на місяць, кількість потоків, правила для кожного потоку, доступ до API, спеціальні домени тощо. Ви можете переглядати доступні плани без автентифікації. Оновлення чи пониження набуває чинності негайно — невикористаний баланс поточного періоду розподіляється пропорційно та повертається у ваш гаманець.

Підписка може бути місячною або річною. Річна підписка пропонує знижку. Ви можете будь-коли скасувати підписку — підписка залишається активною до кінця поточного розрахункового періоду. Відновлення скасованої підписки відновлює її без створення нової.

Гаманець відстежує всі транзакції: депозити, плату за підписку, відшкодування та пропорційні кредити. Кожна транзакція містить контрольний тип та ідентифікатор, що пов’язує її з початковою подією (депозит, поновлення підписки, зміна плану тощо).

Інформаційна панель Magicgate — це ваша центральна панель керування для керування потоками трафіку, моніторингу аналітики та налаштування параметрів облікового запису. Після входу ви потрапляєте на сторінку огляду, на якій відображається зведення ключових показників вашого облікового запису.

Сторінка огляду відображає загальну кількість оброблених перевірок, розподіл вердиктів (пропозиція проти білого), активні потоки та нещодавню активність. Графік часових рядів показує обсяг трафіку за останні 24 години, 7 або 30 днів. Це дає вам миттєве уявлення про стан трафіку та ефективність фільтрації.

У розділі «Потоки» ви створюєте потоки руху та керуєте ними. Кожен потік представляє окрему конфігурацію фільтрації — набір фільтрів, URL-адресу сторінки пропозиції, URL-адресу білої сторінки та налаштування інтеграції (API Mode або Direct Mode). Ви можете мати кілька потоків для різних кампаній, цільових сторінок або джерел трафіку.

У детальному перегляді кожного потоку ви можете переглянути аналітику кожного потоку: загальну кількість перевірок, розбивку вердиктів, коефіцієнти збігів фільтрів, географічний розподіл і найпопулярніші реферери. Ці детальні дані допомагають оптимізувати налаштування фільтра для кожної окремої кампанії.

Розділ Аналітика надає повне уявлення про всі потоки. Діаграми включають тенденції вердикту з часом, ефективність фільтрів (які фільтри спрацьовують найчастіше), географічні теплові карти, що показують походження трафіку, розбивку пристроїв і веб-переглядачів, а також погодинні моделі трафіку. Усі діаграми підтримують фільтрацію діапазону дат і фільтрацію за певним потоком.

У розділі Domains перераховані всі налаштовані домени (спільні та власні). Для кожного домену можна переглянути його статус (активний, очікує перевірки, помилка DNS), статус сертифіката SSL і пов’язані потоки. Перевірки справності домену запускаються автоматично та сповіщають вас, якщо виявлено проблеми з DNS або SSL.

Розділ «Параметри» містить налаштування для всього облікового запису. Ключі API: створюйте та керуйте API key з додатковими термінами дії. Webhooks: налаштування кінцевих точок вебхука та перегляд журналів доставки. Постачальники: додайте постачальників платежів і DNS і керуйте ними. Платежі: перегляд балансу гаманця, історії поповнень і статусу підписки. Команда: запросіть учасників команди з рольовим доступом (користувач, адміністратор).

Інформаційна панель підтримує як світлі, так і темні теми з перемикачем теми у верхньому правому куті. Усі сторінки адаптивні та працюють на мобільних пристроях, хоча робочий стіл забезпечує найповніший перегляд даних.