如何将 Magicgate 与我的网站集成？

您有两个选择：API Mode（通过 POST 请求发送访客数据并接收 JSON 判定结果）或 Direct Mode（将域名 DNS 指向 Magicgate，无需修改代码即可自动完成过滤）。

什么是流程以及如何创建流程？

流程定义了您的流量过滤规则。您可以在仪表板中创建流程，选择过滤器（GeoIP、VPN 检测、机器人拦截等），设置落地页和白页 URL，并选择展示模式。

如何使用Magicgate REST API？

从仪表板设置生成 API key，然后将带有访问者属性（IP、用户代理、引荐来源等）的 POST 请求发送到 /api/v1/check 端点。 API 返回包含过滤决策的 JSON 判决。

有哪些过滤器可用以及它们如何工作？

Magicgate 提供 28 种以上过滤器，包括 GeoIP（国家/地区定位）、VPN/proxy/Tor 检测、机器人和爬虫阻止、设备指纹识别、ISP 过滤、引用验证和自定义阻止列表。每个过滤器都可以按流切换。

过滤响应时间有多快？

Magicgate 会在 10 毫秒内完成每次访客检查。所有检测数据库都部署在本地，可实现零延迟查询，确保访客几乎感受不到等待。

平台指南

文档

集成和配置 Magicgate 以满足您的流量过滤需求所需的一切。

部分 1

快速入门

5 分钟内即可启动并运行 Magicgate。本指南将引导您创建第一个流量、配置基本过滤器以及使用 API 进行测试。

Magicgate 通过根据一组可配置的过滤器评估每个访问者，将机器人流量与真实用户分开。该平台会在 10 毫秒内返回一个判决——“白色”（机器人/crawler/unwanted）或“报价”（真实用户）。

有两种集成模式。 API Mode 允许您通过 REST 端点发送访问者属性并接收应用程序执行操作的 JSON 判决。 Direct Mode 自动处理一切：将您的域名指向 Magicgate，访客将被过滤和重定向，而无需您更改任何代码。

本快速入门重点关注API Mode，因为它在开发过程中为您提供最多的控制和最快的反馈循环。一旦您感到舒服，您可以切换到 Direct Mode 进行生产部署，其中首选零代码集成。

步骤

1
在 magicgate.io 注册并验证您的电子邮件地址。您将登陆带有全新工作区的仪表板。
2
导航到流并单击“创建流”。为其指定一个描述性名称（例如“着陆页 - 美国流量”）。选择 API Mode 作为积分类型。
3
配置至少一个过滤器。对于基本设置，启用 GeoIP（目标国家/地区）和机器人检测（阻止已知爬虫）。您可以稍后添加更多过滤器。
4
设置优惠页面 URL（真实用户应登陆的位置）和白页 URL（机器人重定向的位置）。
5
节省流量。从“设置”页面复制流标签和您的 API key。
6
使用 cURL 或您首选的 HTTP 客户端发送测试请求（请参阅下面的示例）。
7
检查仪表板“分析”选项卡，查看您的测试请求及其结论和过滤器细分。

Free计划包括每月 5,000 个检查、1 个流程和 4 个基本过滤器（GeoIP、阻止列表、User-Agent、Referer）。升级到 Starter 或更高版本以解锁所有 29 个以上过滤器和附加流程。

代码示例

cURL

curl -X POST https://api.magicgate.io/api/v1/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "label": "my-campaign",
    "ip_address": "203.0.113.42",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
    "referer": "https://google.com"
  }'

# Response:
# {
#   "verdict": "offer",
#   "url": "https://example.com/landing",
#   "display_mode": "redirect",
#   "filter_reason": "",
#   "processing_ms": 8
# }

部分 2

机器人检测

了解 Magicgate 如何使用 29 多个可配置过滤器、实时 IP 情报和行为分析来识别机器人流量并对其进行分类。

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 多个其他提供商）的流量。这对于捕获在虚拟机上运行的自动化脚本和无头浏览器特别有效。

用户代理分析根据已知爬虫、机器人和自动化工具的数据库来解析访问者的用户代理字符串。它还可以检测不一致的情况——例如，一个用户代理声称是 Windows 上的 Chrome，但发送的是 Linux 特定的标头。

阻止列表过滤器可让您维护应始终被分类为机器人的 IP 地址、IP 范围（CIDR 表示法）和用户代理模式的自定义列表。相反，白名单过滤器可让您将应始终通过的可信 IP（例如您自己的测试基础设施）列入白名单。

Referer 验证根据预期模式检查 HTTP Referer 标头。您可以要求流量来自特定域（例如 Google、Facebook），或者阻止引用网址为空、缺失或可疑的流量。

谨慎使用激进的过滤器组合。同时启用太多限制性过滤器可能会增加误报——合法用户可能会被错误地归类为机器人。从一些核心过滤器（GeoIP + 机器人检测）开始，并在仪表板中分析流量模式时添加更多过滤器。

过滤器的可用性取决于您的计划。Free计划包括 4 个基本过滤器（GeoIP、阻止列表、User-Agent、Referer）。Starter及以上版本可解锁所有 29 个以上过滤器，包括VPN/代理检测、数据中心识别和行为分析。

使用“分析”选项卡查看过滤器性能。每项检查都会显示触发的过滤器及其原因，帮助您随着时间的推移微调配置。

代码示例

cURL

# Check a visitor with full attributes for bot detection
curl -X POST https://api.magicgate.io/api/v1/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "label": "my-campaign",
    "ip_address": "203.0.113.42",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
    "referer": "https://www.google.com/search?q=example"
  }'

# Response with verdict and detection details:
# {
#   "verdict": "offer",
#   "url": "https://example.com/offer",
#   "display_mode": "redirect",
#   "filter_reason": "",
#   "processing_ms": 8,
#   "country_code": "US",
#   "is_vpn": false,
#   "is_bot": false,
#   "is_datacenter": false
# }

部分 3

流量路由

了解 Magicgate 如何根据过滤器判断将访客引导至正确的目的地。了解白页与优惠页面模型、重定向机制和判决处理。

Magicgate 的核心是一个流量路由器。根据您配置的过滤器对每个访问者进行评估，并分配一个结论：“提供”（合法用户）或“白色”（机器人、爬虫或不需要的流量）。判决决定访问者被重定向到哪里。

优惠页面是您的实际登陆页面、优惠页面或转化渠道——您希望真实的访问者看到的页面。白页是向机器人、爬虫和广告网络审核者显示的诱饵或良性页面。常见的白页包括简单的博客文章、新闻文章或一般信息内容。

这种分离对于竞选保护至关重要。广告网络合规审核人员、点击欺诈机器人和竞争对手会看到白页，而目标受众中的真正用户则会到达优惠页面。路由透明地以线速进行。

在 Direct Mode 中，路由完全自动化。您只需将域名的 DNS 指向 Magicgate，平台就会处理整个请求生命周期：接收访客、评估过滤器，并向合适的目标发出 HTTP 重定向（默认 302）。访客不会看到任何中间页面。

在 API Mode 中，您的应用会使用访客属性调用 /api/v1/check 端点，并接收包含判定结果和推荐重定向 URL 的 JSON 响应。随后由您的应用自行处理重定向。这样您就能完全掌控用户体验，例如在重定向前加入自定义逻辑、日志记录或 A/B 测试。

Magicgate 支持三种显示模式来路由访客。 “重定向”（默认）发出到目标 URL 的 HTTP 重定向。 “代理”在原始 URL 处提供目标页面内容，而不更改浏览器地址栏。 “iframe”在原始 URL 上的 iframe 内加载目标页面。每个流的显示模式都是可配置的。

判决被同步处理并短暂缓存，以处理来自同一访问者的快速连续请求（例如，初始重定向后加载页面资源）。每个流的缓存 TTL 可配置，默认为 30 秒。

Direct Mode 自动处理路由，零代码更改。如果您不需要自定义重定向逻辑，Direct Mode是最简单的集成路径。有关详细比较，请参阅 API 与 Direct Mode 部分。

考虑在 API Mode 中实现失败打开逻辑：如果Magicgate API 无法访问，让访问者进入优惠页面而不是显示错误。短暂的 API 中断不应阻止合法流量。

避免重定向链。如果您的优惠页面本身重定向（例如，重定向到本地化版本），则访问者会经历多次跳转。在 Magicgate 中配置最终目标 URL 以最大限度地减少延迟。

代码示例

cURL

# API Mode: Get verdict and redirect URL
curl -X POST https://api.magicgate.io/api/v1/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "label": "my-campaign",
    "ip_address": "203.0.113.42",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
  }'

# Successful response:
# {
#   "verdict": "offer",
#   "url": "https://example.com/offer",
#   "display_mode": "redirect",
#   "filter_reason": "",
#   "processing_ms": 8
# }

部分 4

API Mode 与 Direct Mode

比较Magicgate提供的两种集成模式。了解何时使用 API Mode 实现最大程度的控制以及何时 Direct Mode 提供最简单的部署路径。

Magicgate 提供两种不同的集成模式，每种模式都针对不同的用例和技术要求而设计。选择正确的模式会影响您的部署复杂性、对用户体验的控制以及运营开销。

API Mode 是一种程序化集成方式。您的应用会向 /api/v1/check 端点发送包含访客属性（IP 地址、User-Agent、Referer 等）的 POST 请求，并接收带有判定结果的 JSON 响应。随后由您的代码负责路由：将机器人重定向到白页，让真实用户继续访问。此模式需要您编写集成代码，但可以完全掌控请求流程。

Direct Mode 是一种 DNS 级集成方式。您需要将域名的 DNS 记录配置为指向 Magicgate（子域使用 CNAME 指向 proxy.magicgate.io，根域可使用 ALIAS/ANAME）。当访客到达时，Magicgate 会透明地拦截请求、评估访客，并将其通过 HTTP 重定向发送到优惠页或白页。您的应用无需做任何代码修改，因为整个过滤与路由层都位于源服务器之前。

API Mode优点：完全控制路由逻辑。您可以在接收判决和重定向用户之间添加自定义处理 - 日志记录、A/B 测试分配、cookie 设置、分析事件或基于判决元数据的条件逻辑。 API Mode 适用于任何后端堆栈，不需要 DNS 更改。它也非常适合客户端 JavaScript 进行检查调用的单页应用程序 (SPA)。

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 端点或结账流程）。

开发时从API Mode开始，方便测试和调试。切换到Direct Mode进行生产部署，其中简单性和性能是优先考虑的。

两种模式都使用相同的过滤器管道并产生相同的结论。唯一的区别在于如何触发检查以及如何处理重定向。

使用 Direct Mode 时，请确保您的源服务器不可通过 IP 地址公开访问。如果机器人可以绕过您域的 DNS 并直接攻击您的源站，则过滤层将被完全绕过。

代码示例

cURL

# ---- API Mode: Manual check + redirect ----
# Send visitor data and receive a verdict
curl -X POST https://api.magicgate.io/api/v1/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "label": "my-campaign",
    "ip_address": "203.0.113.42",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
    "referer": "https://google.com"
  }'

# ---- Direct Mode: DNS configuration ----
# Point your domain to Magicgate's proxy:
# CNAME  landing.example.com  ->  proxy.magicgate.io
# For root domains that don't support CNAME, use ALIAS/ANAME:
# ALIAS  landing.example.com  ->  proxy.magicgate.io
# No API calls needed -- Magicgate handles everything at the edge.

部分 5

域名管理

将自定义域添加到您的 Magicgate 帐户、配置 DNS 记录并管理域验证。包括 Cloudflare 集成和 SSL 证书处理。

每个 Magicgate 帐户都可以访问共享域 (go.magicgate.io) 以供立即使用。Starter计划及更高版本可以为品牌 URL 添加自定义域，并通过广告网络改进信任信号。

自定义域允许您使用自己的 URL（例如，track.yourbrand.com）而不是共享域。这对于广告合规性非常重要 - 许多广告网络对来自品牌域而不是共享跟踪域的流量更加宽松。

Magicgate 支持子域 (track.yourbrand.com) 和根域 (yourbrand.com)。建议使用子域，因为它们不会干扰主网站的 DNS 配置并且更易于管理。

域验证使用指向 proxy.magicgate.io 的 CNAME 记录。添加域时，您可以将域中的 CNAME 记录配置为 proxy.magicgate.io。对于不支持 CNAME 记录的根域，请改用指向 proxy.magicgate.io 的 ALIAS 或 ANAME 记录。 Magicgate 通过检查 DNS 记录是否正确解析到代理端点来验证所有权。

DNS 传播完成后，SSL 证书将通过 Let's Encrypt 自动配置。 Magicgate 处理证书颁发、更新和安装。您的自定义域将在 DNS 配置后几分钟内使用有效证书通过 HTTPS 提供流量。

对于 Cloudflare 用户，请确保针对指向 Magicgate 的 CNAME 记录禁用代理（橙色云）。 Cloudflare 的代理会在流量到达 Magicgate 之前拦截流量，这可能会干扰访问者评估。将记录设置为“仅 DNS”（灰云）模式。

您还可以直接通过 Magicgate 市场购买域名。这些域已预先配置并可立即使用——无需 DNS 设置或验证。该市场提供了一系列适合流量活动的干净域名。

步骤

1
导航至“设置”>“域”，然后单击“添加域”。输入您的自定义域（例如，track.yourbrand.com）。
2
在您的 DNS 提供商处添加 CNAME 记录：名称 = 您的域，值 = proxy.magicgate.io。对于根域，如果您的提供商不支持顶级域上的 CNAME，请使用 ALIAS/ANAME。 DNS 传播最多可能需要 24 小时。
3
单击 Magicgate 仪表板中的“验证 DNS”。验证后，将自动配置 SSL 证书。您的域状态更改为“活动”。

如果您使用 Cloudflare，请将 CNAME 记录设置为“仅限 DNS”（灰色云）。 Cloudflare 的代理模式将在流量到达 Magicgate 之前拦截流量，从而阻止正确的访问者评估。

SSL 证书在 DNS 传播后自动配置。无需手动上传证书。证书在到期前会自动续订。

使用子域 (track.yourbrand.com) 而不是根域。子域名更容易配置，不会影响您的主网站，并且直接支持 CNAME 记录。

代码示例

cURL

# Verify DNS configuration using dig
# Check CNAME record points to Magicgate proxy
dig CNAME track.yourbrand.com +short
# Expected: proxy.magicgate.io.

# Check SSL certificate is provisioned
curl -vI https://track.yourbrand.com 2>&1 | grep "SSL certificate"
# Expected: SSL certificate verify ok

部分 6

Webhook 配置

设置网络钩子以接收交通事件的实时通知。了解负载结构、重试逻辑、签名验证和事件类型。

当您的 Magicgate 帐户发生重要事件（例如流量更改、域验证或付款更新）时，Webhooks 可让您接收实时 HTTP POST 通知。

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 分钟的请求。签名密钥是在您创建 Webhook 端点时生成的，并显示一次 - 安全地存储它。

Magicgate 重试失败的 Webhook 传送。如果您的终端返回非 2xx 状态代码或在 10 秒内未响应，则会重试传送。在用尽所有重试后，事件将被标记为失败，并且端点的失败计数会增加。

Webhook 有效负载采用 JSON 编码，结构如下：{ id, event, timestamp, data }。 “event”字段包含事件类型字符串（例如“domain.verified”），“id”是幂等性的唯一传递 ID，“timestamp”是 ISO 8601 日期时间，“data”包含特定于事件的详细信息。

您可以为每个帐户配置多个 Webhook 端点，每个端点订阅不同的事件类型。例如，这使您可以将域事件路由到部署管道，并将计费事件路由到会计系统。

步骤

1
导航到 Magicgate 仪表板中的设置 > Webhooks。
2
单击“添加端点”并输入您的 Webhook URL（必须是 HTTPS）。
3
选择您想要接收的事件类型（flow.created、domain.verified、payment.completed 等）。
4
复制创建后显示的签名密钥。将其存储在您的环境变量中。
5
在您的服务器上实现一个 Webhook 处理程序，用于接收 POST 请求并验证签名。
6
使用仪表板中的“发送测试事件”按钮测试 Webhook。
7
在 Webhook 日志选项卡中监视传送状态以验证是否成功接收。

始终使用 HMAC-SHA256 以及您的签名密钥和 X-Webhook-Timestamp 来验证 X-Webhook-Signature 标头。签名包含时间戳 + '.' + 主体可防止篡改和重放攻击。切勿在未经验证的情况下处理 Webhook 有效负载。

使用事件 ID 字段实现幂等性。如果重试 Webhook，将再次发送相同的事件 ID。跟踪已处理的事件 ID 以避免处理重复项。

Webhook 端点必须使用 HTTPS。配置过程中会拒绝 HTTP 端点。请确保您的 SSL 证书有效，且不是自签名证书。

代码示例

cURL

# Test webhook endpoint manually
# Headers match what Magicgate sends: X-Webhook-Signature, X-Webhook-Timestamp, X-Webhook-ID
TIMESTAMP=$(date +%s)
BODY='{"id":"evt_1234567890","event":"domain.verified","timestamp":"2024-01-15T10:30:00Z","data":{"domain":"track.yourbrand.com"}}'
SECRET="your_webhook_secret"
SIGNATURE=$(echo -n "${TIMESTAMP}.${BODY}" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

curl -X POST https://your-server.com/webhooks/magicgate \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: $SIGNATURE" \
  -H "X-Webhook-Timestamp: $TIMESTAMP" \
  -H "X-Webhook-ID: endpoint-uuid-here" \
  -d "$BODY"

部分 7

账单与付款

了解 Magicgate 基于钱包的计费模型、支持的支付提供商和计划管理。通过仪表板管理您的订阅和存款。

Magicgate 使用基于钱包的计费模型。您可以通过加密货币存款向您的钱包添加资金，并且您的订阅会在每个计费周期从钱包余额中自动续订。这消除了经常性卡费用的需要，并提供对您的支出的完全控制。

支持三种支付提供商：CCPayment、NowPayments 和 TransVoucher。每个提供商都支持比特币、以太坊、USDT、USDC 和 50 多种其他加密货币。当您发起存款时，会生成付款地址和金额。一旦区块链确认交易，您的钱包余额就会自动更新。

计划决定您的功能限制：每月检查、流数量、每个流的规则、API 访问、自定义域等等。您无需身份验证即可查看可用计划。升级或降级立即生效——当前期间未使用的余额将按比例分配并存回您的钱包。

订阅可以按月或按年。每年订阅可享受折扣。您可以随时取消——订阅在当前计费周期结束之前保持有效。恢复已取消的订阅会恢复该订阅，而无需创建新订阅。

钱包跟踪所有交易：存款、订阅费、退款和按比例分配积分。每笔交易都包含一个参考类型和 ID，将其链接到原始事件（存款、订阅续订、计划更改等）。

步骤

1
使用公共 /billing/plans 端点检查可用计划，找到适合您需求的计划。
2
注册并导航至仪表板中的“设置”>“账单”。
3
向您的钱包添加资金：点击“存款”，选择支付提供商和加密货币，输入金额。
4
使用生成的地址完成加密支付。您的钱包会在区块链确认后更新。
5
订阅计划。订阅费将从您的钱包余额中扣除。
6
在“账单”部分监控您的钱包余额和交易历史记录。
7
设置低余额警报，以确保您的钱包有足够的资金用于下次续订。

将您的钱包余额保持在计划的每月费用之上，以避免服务中断。如果续订时钱包余额不足，订阅将暂停，直至补充资金。

代码示例

cURL

# List available plans (public -- no auth required)
curl -s https://api.magicgate.io/api/v1/billing/plans | jq '.data'

# Check enabled payment providers (public)
curl -s https://api.magicgate.io/api/v1/billing/providers | jq '.data'
# { "ccpayment": true, "nowpayments": true, "transvoucher": false }

部分 8

仪表板使用情况

有效地导航 Magicgate 仪表板。了解分析视图、流量管理、设置面板以及如何实时监控流量过滤。

Magicgate 仪表板是您的中央控制面板，用于管理流量、监控分析和配置帐户设置。登录后，您将进入“概述”页面，其中显示您帐户的关键指标的摘要。

概述页面显示已处理的支票总数、判决分布（报价与白色）、活动流程和最近的活动。时间序列图显示过去 24 小时、7 天或 30 天的流量。这可以让您立即了解流量健康状况和过滤有效性。

流量部分是您创建和管理流量的地方。每个流代表一个不同的过滤配置——一组过滤器、一个报价页面 URL、一个白页 URL 和集成设置（API Mode 或 Direct Mode）。您可以为不同的营销活动、着陆页或流量来源设置多个流。

在每个流的详细信息视图中，您可以查看每个流的分析：检查总数、判决细目、过滤器命中率、地理分布和热门引荐来源网址。这些详细数据可帮助您优化每个特定营销活动的过滤器设置。

分析部分提供所有流程的全面视图。图表包括随时间变化的判决趋势、过滤器有效性（最常触发的过滤器）、显示流量来源的地理热图、设备和浏览器故障以及每小时流量模式。所有图表都支持日期范围过滤和特定于流的过滤。

域部分列出了所有已配置的域（共享域和自定义域）。对于每个域，您可以查看其状态（活动、待验证、DNS 错误）、SSL 证书状态和关联的流。域运行状况检查会自动运行，并在检测到 DNS 或 SSL 问题时向您发出警报。

设置部分包含帐户范围的配置。 API 密钥：生成和管理具有可选到期日期的 API key。 Webhooks：配置 webhook 端点并查看传输日志。提供商：添加和管理支付和DNS提供商。账单：查看钱包余额、充值历史和订阅状态。团队：邀请具有基于角色的访问权限的团队成员（用户、管理员）。

仪表板支持浅色和深色主题，主题切换位于右上角。尽管桌面体验提供了最全面的数据视图，但所有页面都是响应式的并且可以在移动设备上运行。

免费计划的分析数据保留 90 天，付费计划的分析数据保留 365 天。在数据转出保留窗口之前，从“分析”部分将数据导出为 CSV 或 JSON。

使用 Analytics 中的“比较”功能来叠加两个日期范围。这对于通过比较前后流量模式来测量过滤器配置更改的影响非常有用。

API keys 授予对您帐户的流量检查功能的完全访问权限。像对待密码一样对待它们：永远不要将它们提交给版本控制，使用环境变量，并定期轮换它们。

curl -X POST https://api.magicgate.io/api/v1/check \ -H "Content-Type: application/json" \ -H "X-API-Key: your_api_key_here" \ -d '{ "label": "my-campaign", "ip_address": "203.0.113.42", "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36", "referer": "https://google.com" }' # Response: # { # "verdict": "offer", # "url": "https://example.com/landing", # "display_mode": "redirect", # "filter_reason": "", # "processing_ms": 8 # }

# Check a visitor with full attributes for bot detection curl -X POST https://api.magicgate.io/api/v1/check \ -H "Content-Type: application/json" \ -H "X-API-Key: your_api_key_here" \ -d '{ "label": "my-campaign", "ip_address": "203.0.113.42", "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36", "referer": "https://www.google.com/search?q=example" }' # Response with verdict and detection details: # { # "verdict": "offer", # "url": "https://example.com/offer", # "display_mode": "redirect", # "filter_reason": "", # "processing_ms": 8, # "country_code": "US", # "is_vpn": false, # "is_bot": false, # "is_datacenter": false # }

# API Mode: Get verdict and redirect URL curl -X POST https://api.magicgate.io/api/v1/check \ -H "Content-Type: application/json" \ -H "X-API-Key: your_api_key_here" \ -d '{ "label": "my-campaign", "ip_address": "203.0.113.42", "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)" }' # Successful response: # { # "verdict": "offer", # "url": "https://example.com/offer", # "display_mode": "redirect", # "filter_reason": "", # "processing_ms": 8 # }

# ---- API Mode: Manual check + redirect ---- # Send visitor data and receive a verdict curl -X POST https://api.magicgate.io/api/v1/check \ -H "Content-Type: application/json" \ -H "X-API-Key: your_api_key_here" \ -d '{ "label": "my-campaign", "ip_address": "203.0.113.42", "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)", "referer": "https://google.com" }' # ---- Direct Mode: DNS configuration ---- # Point your domain to Magicgate's proxy: # CNAME landing.example.com -> proxy.magicgate.io # For root domains that don't support CNAME, use ALIAS/ANAME: # ALIAS landing.example.com -> proxy.magicgate.io # No API calls needed -- Magicgate handles everything at the edge.

# Verify DNS configuration using dig # Check CNAME record points to Magicgate proxy dig CNAME track.yourbrand.com +short # Expected: proxy.magicgate.io. # Check SSL certificate is provisioned curl -vI https://track.yourbrand.com 2>&1 | grep "SSL certificate" # Expected: SSL certificate verify ok

# Test webhook endpoint manually # Headers match what Magicgate sends: X-Webhook-Signature, X-Webhook-Timestamp, X-Webhook-ID TIMESTAMP=$(date +%s) BODY='{"id":"evt_1234567890","event":"domain.verified","timestamp":"2024-01-15T10:30:00Z","data":{"domain":"track.yourbrand.com"}}' SECRET="your_webhook_secret" SIGNATURE=$(echo -n "${TIMESTAMP}.${BODY}" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}') curl -X POST https://your-server.com/webhooks/magicgate \ -H "Content-Type: application/json" \ -H "X-Webhook-Signature: $SIGNATURE" \ -H "X-Webhook-Timestamp: $TIMESTAMP" \ -H "X-Webhook-ID: endpoint-uuid-here" \ -d "$BODY"

# List available plans (public -- no auth required) curl -s https://api.magicgate.io/api/v1/billing/plans | jq '.data' # Check enabled payment providers (public) curl -s https://api.magicgate.io/api/v1/billing/providers | jq '.data' # { "ccpayment": true, "nowpayments": true, "transvoucher": false }