Documentação

Magicgate separa o tráfego de bots de usuários reais, avaliando cada visitante em relação a um conjunto configurável de filtros. A plataforma retorna um veredicto – ‘branco’ (bot/crawler/unwanted) ou ‘oferta’ (usuário real) – em menos de 10 milissegundos.

Existem dois modos de integração. API Mode permite enviar atributos de visitante por meio de um endpoint REST e receber um veredicto JSON de acordo com o qual seu aplicativo atua. Direct Mode cuida de tudo automaticamente: aponte seu domínio para Magicgate e os visitantes serão filtrados e redirecionados sem qualquer alteração de código de sua parte.

Este início rápido concentra-se em API Mode porque oferece maior controle e ciclo de feedback mais rápido durante o desenvolvimento. Quando estiver confortável, você pode mudar para Direct Mode para implantações de produção onde a integração de código zero é preferida.

Magicgate avalia cada visitante recebido em relação a um pipeline de detecção multicamadas. Cada filtro é executado de forma independente e contribui para o veredicto final. Toda a avaliação é concluída em menos de 10 milissegundos, garantindo zero latência perceptível para usuários reais.

O pipeline de detecção é dividido em várias categorias: verificações em nível de rede (reputação de IP, GeoIP, detecção de VPN/proxy/Tor, identificação de datacenter), verificações em nível de navegador (análise de agente de usuário, impressão digital de JavaScript, consistência de cabeçalho), verificações comportamentais (padrões de clique, velocidade de sessão, validação de referenciador) e verificações baseadas em lista (listas de bloqueio, listas de permissão, filtragem de ISP).

Cada filtro pode ser habilitado ou desabilitado individualmente por fluxo. Esse controle granular permite ajustar a detecção para diferentes fontes de tráfego. Por exemplo, uma campanha direcionada a usuários móveis dos EUA pode ativar GeoIP (somente nos EUA), detecção de VPN/proxy e verificação de dispositivos móveis, ao mesmo tempo que desativa a filtragem do ISP.

A filtragem GeoIP usa bancos de dados MaxMind hospedados localmente e atualizados semanalmente para pesquisas com latência zero. Você pode segmentar ou excluir tráfego por país, região ou cidade. O banco de dados abrange endereços IPv4 e IPv6 com 99,8% de precisão em nível de país.

A detecção de VPN, proxy e Tor combina vários bancos de dados comerciais e de código aberto. Magicgate mantém uma lista continuamente atualizada de nós de saída VPN conhecidos, servidores proxy públicos e privados, retransmissores de saída Tor e redes proxy residenciais. A detecção cobre os intervalos IPv4 e IPv6.

A detecção de datacenter identifica o tráfego originado de provedores de nuvem (AWS, GCP, Azure, DigitalOcean, OVH, Hetzner e mais de 200 outros). Isso é particularmente eficaz na captura de scripts automatizados e navegadores headless executados em máquinas virtuais.

A análise do agente do usuário analisa a string do agente do usuário em um banco de dados de rastreadores, bots e ferramentas automatizadas conhecidos. Ele também detecta inconsistências – por exemplo, um agente de usuário que afirma ser o Chrome no Windows, mas envia cabeçalhos específicos do Linux.

O filtro de lista de bloqueio permite manter listas personalizadas de endereços IP, intervalos de IP (notação CIDR) e padrões de agente de usuário que sempre devem ser classificados como bots. Por outro lado, o filtro de lista de permissões permite colocar IPs confiáveis ​​na lista de permissões (como sua própria infraestrutura de teste) que sempre devem passar.

A validação Referer verifica o cabeçalho HTTP Referer em relação aos padrões esperados. Você pode exigir que o tráfego venha de domínios específicos (por exemplo, Google, Facebook) ou bloquear o tráfego com referenciadores vazios, ausentes ou suspeitos.

Basicamente, o Magicgate é um roteador de tráfego. Cada visitante é avaliado em relação aos filtros configurados e recebe um veredicto: 'oferta' (usuário legítimo) ou 'branco' (bot, rastreador ou tráfego indesejado). O veredicto determina para onde o visitante é redirecionado.

A página de oferta é sua página de destino, página de oferta ou funil de conversão real – a página que você deseja que visitantes humanos reais vejam. A página branca é uma página isca ou benigna mostrada a bots, rastreadores e revisores de redes de anúncios. As páginas brancas comuns incluem postagens simples em blogs, artigos de notícias ou conteúdo informativo genérico.

Esta separação é essencial para a proteção da campanha. Revisores de conformidade da rede de anúncios, bots fraudulentos de cliques e concorrentes veem a página em branco, enquanto usuários genuínos de seu público-alvo acessam a página de oferta. O roteamento acontece de forma transparente e na velocidade do fio.

Em Direct Mode, o roteamento é totalmente automático. Você aponta o DNS do seu domínio para Magicgate, e a plataforma cuida de todo o ciclo de vida da solicitação: recebe o visitante, avalia os filtros e emite um redirecionamento HTTP (302 por padrão) para o destino apropriado. O visitante nunca vê uma página intermediária.

Em API Mode, seu aplicativo chama o endpoint /api/v1/check com atributos de visitante e recebe uma resposta JSON contendo o veredicto e o URL de redirecionamento recomendado. Seu aplicativo então lida com o redirecionamento sozinho. Isso lhe dá controle total sobre a experiência do usuário – você pode adicionar lógica personalizada, registro ou teste A/B antes de redirecionar.

Magicgate suporta três modos de exibição para rotear visitantes. 'Redirecionar' (padrão) emite um redirecionamento HTTP para o URL de destino. 'Proxy' exibe o conteúdo da página de destino no URL original sem alterar a barra de endereço do navegador. 'Iframe' carrega a página de destino dentro de um iframe no URL original. O modo de exibição é configurável por fluxo.

Os veredictos são processados de forma síncrona e armazenados em cache brevemente para lidar com solicitações rápidas e sucessivas do mesmo visitante (por exemplo, carregamento de recursos da página após o redirecionamento inicial). O TTL do cache é configurável por fluxo, com padrão de 30 segundos.

Magicgate oferece dois modos de integração distintos, cada um projetado para diferentes casos de uso e requisitos técnicos. A escolha do modo certo afeta a complexidade da implantação, o controle sobre a experiência do usuário e a sobrecarga operacional.

API Mode é uma integração programática. Seu aplicativo envia uma solicitação POST para o endpoint /api/v1/check com atributos do visitante (endereço IP, agente do usuário, referenciador, etc.) e recebe uma resposta JSON contendo o veredicto. Seu código então cuida do roteamento - redirecionando os bots para a página em branco e permitindo a passagem de usuários reais. Este modo exige que você escreva o código de integração, mas oferece controle total sobre o fluxo de solicitação.

Direct Mode é uma integração de nível DNS. Você configura os registros DNS do seu domínio (CNAME a proxy.magicgate.io ou ALIAS/ANAME para domínios raiz) para apontar para Magicgate. Quando um visitante chega, Magicgate intercepta a solicitação de forma transparente, avalia o visitante e emite um redirecionamento HTTP para a página de oferta ou para a página em branco. Nenhuma alteração de código é necessária em seu aplicativo – toda a camada de filtragem e roteamento fica na frente do seu servidor de origem.

Vantagens do API Mode: Controle total sobre a lógica de roteamento. Você pode adicionar processamento personalizado entre o recebimento do veredicto e o redirecionamento do usuário - registro em log, atribuição de teste A/B, configuração de cookie, eventos analíticos ou lógica condicional com base nos metadados do veredicto. API Mode funciona com qualquer pilha de back-end e não requer alterações em DNS. Também é ideal para aplicativos de página única (SPAs), onde o JavaScript do lado do cliente faz a chamada de verificação.

Desvantagens do API Mode: Requer alterações de código em seu aplicativo. Você precisa lidar com a chamada de API, casos de erro (tempo limite, limites de taxa) e lógica de redirecionamento. A chamada de API adiciona um percurso de ida e volta de rede ao tempo de carregamento da página (normalmente de 10 a 50 ms, dependendo da proximidade geográfica da borda do Magicgate).

Vantagens Direct Mode: Zero alterações de código. Aponte seu DNS e configure seu fluxo – os visitantes são filtrados e redirecionados automaticamente. Direct Mode é mais rápido para o usuário final porque não há ida e volta extra da API; a filtragem acontece na borda como parte da resolução DNS e da solicitação HTTP inicial. Ele também lida com todos os casos extremos (tempo limite, novas tentativas) de forma transparente.

Desvantagens do Direct Mode: Menos controle sobre o processo de roteamento. Você não pode injetar lógica personalizada entre o veredicto e o redirecionamento. As alterações DNS se propagam lentamente (minutos a horas), o que torna o teste e a reversão mais lentos. Direct Mode requer que sua página branca e página de oferta sejam acessíveis por meio de URLs públicos.

Uma abordagem híbrida também é possível. Use Direct Mode para suas páginas de destino principais (onde a integração de código zero é uma prioridade) e API Mode para endpoints específicos que precisam de tratamento de veredicto personalizado (por exemplo, envios de formulários, endpoints de API ou fluxos de checkout).

Cada conta Magicgate tem acesso a um domínio compartilhado (go.magicgate.io) para uso imediato. Os planos Starter e superiores podem adicionar domínios personalizados para URLs de marca e sinais de confiança aprimorados com redes de anúncios.

Os domínios personalizados permitem que você use seu próprio URL (por exemplo, track.yourbrand.com) em vez do domínio compartilhado. Isso é importante para a conformidade dos anúncios: muitas redes de anúncios são mais tolerantes com o tráfego proveniente de domínios de marca, em vez de domínios de rastreamento compartilhados.

Magicgate suporta subdomínios (track.yourbrand.com) e domínios raiz (yourbrand.com). Subdomínios são recomendados porque não interferem na configuração DNS do seu site principal e são mais fáceis de gerenciar.

A verificação de domínio usa registros CNAME apontando para proxy.magicgate.io. Ao adicionar um domínio, você configura um registro CNAME do seu domínio para proxy.magicgate.io. Para domínios raiz que não suportam registros CNAME, use um registro ALIAS ou ANAME apontando para proxy.magicgate.io. Magicgate verifica a propriedade verificando se o registro DNS é resolvido corretamente para o endpoint do proxy.

Os certificados SSL são provisionados automaticamente por meio do Let's Encrypt após a conclusão da propagação do DNS. Magicgate cuida da emissão, renovação e instalação de certificados. Seu domínio personalizado servirá o tráfego via HTTPS com um certificado válido minutos após a configuração do DNS.

Para usuários do Cloudflare, certifique-se de que o proxy (nuvem laranja) esteja desabilitado para o registro CNAME que aponta para Magicgate. O proxy da Cloudflare intercepta o tráfego antes que ele chegue ao Magicgate, o que pode interferir na avaliação do visitante. Defina o registro para o modo 'Somente DNS' (nuvem cinza).

Você também pode comprar domínios diretamente no mercado Magicgate. Esses domínios são pré-configurados e prontos para uso imediato – não é necessária configuração ou verificação de DNS. O mercado oferece uma seleção de domínios limpos adequados para campanhas de tráfego.

Webhooks permite que você receba notificações HTTP POST em tempo real quando eventos importantes ocorrem em sua conta Magicgate - como alterações de fluxo, verificação de domínio ou atualizações de pagamento.

Magicgate suporta eventos de webhook em várias categorias: eventos de fluxo (flow.created, flow.updated, flow.deleted), eventos de domínio (domain.added, domain.verified, domain.deleted, domain.registration_failed), eventos de página branca (white_page.ready, white_page.failed, white_page.deleted), eventos de lista negra (blacklist.created, blacklist.updated, blacklist.deleted), eventos API key (apikey.created, apikey.deleted, apikey.activated, apikey.deactivated), eventos de carteira (wallet.credited, wallet.debited), eventos de assinatura (subscription.changed, subscription.canceled, subscription.plan_changed e mais), eventos de cobrança (payment.completed, payment.failed) e eventos de suporte (ticket.created, ticket.replied, ticket.resolved, ticket.closed).

Cada entrega de webhook inclui três cabeçalhos de segurança: X-Webhook-Signature (resumo hexadecimal HMAC-SHA256), X-Webhook-Timestamp (carimbo de data e hora Unix) e X-Webhook-ID (identificador de endpoint). A assinatura cobre o carimbo de data/hora e o corpo juntos - calculado como HMAC-SHA256(segredo, carimbo de data/hora + '.' + corpo) - o que evita ataques de adulteração e repetição. Você deve verificar a assinatura e rejeitar solicitações com carimbos de data/hora anteriores a 5 minutos. O segredo de assinatura é gerado quando você cria o endpoint do webhook e é exibido uma vez – armazene-o com segurança.

Magicgate tenta novamente entregas de webhook com falha. Se o seu endpoint retornar um código de status diferente de 2xx ou não responder em 10 segundos, a entrega será repetida. Depois que todas as tentativas forem esgotadas, o evento será marcado como com falha e a contagem de falhas do endpoint será incrementada.

As cargas úteis Webhook são codificadas em JSON com a estrutura: { id, event, timestamp, data }. O campo 'evento' contém a string do tipo de evento (por exemplo, 'domain.verified'), 'id' é um ID de entrega exclusivo para idempotência, 'timestamp' é uma data e hora ISO 8601 e 'dados' contém detalhes específicos do evento.

Você pode configurar vários endpoints de webhook por conta, cada um inscrito em diferentes tipos de eventos. Isso permite rotear eventos de domínio para seu pipeline de implantação e eventos de cobrança para seu sistema de contabilidade, por exemplo.

Magicgate usa um modelo de cobrança baseado em carteira. Você adiciona fundos à sua carteira por meio de depósitos criptográficos e sua assinatura é renovada automaticamente a partir do saldo da carteira a cada ciclo de cobrança. Isso elimina a necessidade de cobranças recorrentes no cartão e fornece controle total sobre seus gastos.

Três provedores de pagamento são suportados: CCPayment, NowPayments e TransVoucher. Cada provedor oferece suporte a Bitcoin, Ethereum, USDT, USDC e mais de 50 criptomoedas adicionais. Quando você inicia um depósito, um endereço de pagamento e um valor são gerados. Assim que o blockchain confirmar a transação, o saldo da sua carteira será atualizado automaticamente.

Os planos determinam seus limites de recursos: verificações por mês, número de fluxos, regras por fluxo, acesso à API, domínios personalizados e muito mais. Você pode visualizar os planos disponíveis sem autenticação. O upgrade ou downgrade entra em vigor imediatamente – o saldo não utilizado do período atual é rateado e creditado de volta em sua carteira.

As assinaturas podem ser mensais ou anuais. As assinaturas anuais oferecem um desconto. Você pode cancelar a qualquer momento – a assinatura permanece ativa até o final do período de cobrança atual. Retomar uma assinatura cancelada a restaura sem criar uma nova.

A carteira rastreia todas as transações: depósitos, cobranças de assinatura, reembolsos e créditos proporcionais. Cada transação inclui um tipo de referência e ID que a vincula ao evento originador (depósito, renovação de assinatura, mudança de plano, etc.).

O painel Magicgate é o seu painel de controle central para gerenciar fluxos de tráfego, monitorar análises e definir configurações de conta. Depois de fazer login, você acessa a página Visão geral, que mostra um resumo das principais métricas da sua conta.

A página Visão geral exibe o total de verificações processadas, distribuição de veredicto (oferta versus branco), fluxos ativos e atividades recentes. Um gráfico de série temporal mostra o volume de tráfego nas últimas 24 horas, 7 dias ou 30 dias. Isso lhe dá uma noção imediata da saúde do tráfego e da eficácia da filtragem.

A seção Fluxos é onde você cria e gerencia fluxos de tráfego. Cada fluxo representa uma configuração de filtragem distinta: um conjunto de filtros, uma URL de página de oferta, uma URL de página em branco e configurações de integração (API Mode ou Direct Mode). Você pode ter vários fluxos para diferentes campanhas, landing pages ou fontes de tráfego.

Na visualização detalhada de cada fluxo, você pode ver análises por fluxo: total de verificações, detalhamento do veredicto, taxas de acerto do filtro, distribuição geográfica e principais referenciadores. Esses dados granulares ajudam a otimizar as configurações de filtro para cada campanha específica.

A seção Analytics fornece uma visão abrangente de todos os fluxos. Os gráficos incluem tendências de veredictos ao longo do tempo, eficácia do filtro (que filtros acionam com mais frequência), mapas de calor geográficos mostrando a origem do tráfego, falhas de dispositivos e navegadores e padrões de tráfego por hora. Todos os gráficos suportam filtragem por intervalo de datas e filtragem específica de fluxo.

A seção Domínios lista todos os domínios configurados (compartilhados e personalizados). Para cada domínio, você pode ver seu status (ativo, verificação pendente, erro de DNS), status do certificado SSL e fluxos associados. As verificações de integridade do domínio são executadas automaticamente e alertam você se problemas de DNS ou SSL forem detectados.

A seção Configurações contém configurações para toda a conta. Chaves de API: gere e gerencie API keys com datas de expiração opcionais. Webhooks: configure endpoints de webhook e visualize logs de entrega. Provedores: adicione e gerencie provedores de pagamento e DNS. Faturamento: visualize o saldo da carteira, o histórico de recargas e o status da assinatura. Equipe: convide membros da equipe com acesso baseado em função (usuário, administrador).

O painel suporta temas claros e escuros, com a alternância de temas no canto superior direito. Todas as páginas são responsivas e funcionam em dispositivos móveis, embora a experiência em desktop forneça visualizações de dados mais abrangentes.