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

Magicgate отделяет трафик ботов от трафика реальных пользователей, оценивая каждого посетителя с помощью настраиваемого набора фильтров. Платформа выдает вердикт — либо «белый» (бот/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-адресу. Режим отображения настраивается для каждого потока.

Вердикты обрабатываются синхронно и кратковременно кэшируются для обработки быстрых последовательных запросов от одного и того же посетителя (например, загрузка ресурсов страницы после первоначального перенаправления). Срок жизни кэша настраивается для каждого потока, значение по умолчанию составляет 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 поддерживает события веб-перехватчика в нескольких категориях: события потока (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, subscribe.plan_changed и т. д.), события выставления счетов (payment.completed, payment.failed) и события поддержки (ticket.created, ticket.replied, ticket.resolved, ticket.closed).

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

Magicgate повторяет неудачную попытку доставки веб-перехватчика. Если ваша конечная точка возвращает код состояния, отличный от 2xx, или не отвечает в течение 10 секунд, доставка повторяется. После того, как все повторные попытки исчерпаны, событие помечается как неудачное, и счетчик неудач конечной точки увеличивается.

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

Вы можете настроить несколько конечных точек веб-перехватчика для каждой учетной записи, каждая из которых подписана на разные типы событий. Это позволяет, например, направлять события домена в конвейер развертывания, а события выставления счетов — в вашу систему учета.

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

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

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

Подписка может быть ежемесячной или ежегодной. При годовой подписке предоставляется скидка. Вы можете отменить ее в любой момент — подписка остается активной до конца текущего расчетного периода. Возобновление отмененной подписки восстанавливает ее без создания новой.

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

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

На странице «Обзор» отображается общее количество обработанных проверок, распределение вердиктов (предложение против белого), активные потоки и недавние действия. Диаграмма временных рядов показывает объем трафика за последние 24 часа, 7 или 30 дней. Это дает вам немедленное представление о состоянии вашего трафика и эффективности фильтрации.

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

В подробном представлении каждого потока вы можете увидеть аналитику по каждому потоку: общее количество проверок, разбивку вердиктов, показатели попадания в фильтры, географическое распределение и основные источники ссылок. Эти подробные данные помогут вам оптимизировать настройки фильтров для каждой конкретной кампании.

Раздел «Аналитика» предоставляет комплексное представление обо всех потоках. Диаграммы включают тенденции вынесения вердиктов с течением времени, эффективность фильтров (которые фильтры срабатывают чаще всего), географические тепловые карты, показывающие происхождение трафика, поломки устройств и браузеров, а также почасовую структуру трафика. Все диаграммы поддерживают фильтрацию по диапазону дат и фильтрацию по потоку.

В разделе «Домены» перечислены все настроенные домены (общие и пользовательские). Для каждого домена вы можете увидеть его статус (активный, ожидающий проверки, ошибка DNS), статус SSL-сертификата и связанные потоки. Проверки работоспособности домена выполняются автоматически и предупреждают вас об обнаружении проблем с DNS или SSL.

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

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