Documentazione

Magicgate separa il traffico bot dagli utenti reali valutando ogni visitatore rispetto a una serie configurabile di filtri. La piattaforma restituisce un verdetto - "bianco" (bot/crawler/unwanted) o "offerta" (utente reale) - in meno di 10 millisecondi.

Esistono due modalità di integrazione. API Mode ti consente di inviare attributi del visitatore tramite un endpoint REST e ricevere un verdetto JSON su cui agisce la tua applicazione. Direct Mode gestisce tutto automaticamente: punta il tuo dominio su Magicgate e i visitatori verranno filtrati e reindirizzati senza alcuna modifica al codice da parte tua.

Questo avvio rapido si concentra su API Mode perché ti offre il massimo controllo e il ciclo di feedback più veloce durante lo sviluppo. Una volta che ti senti a tuo agio, puoi passare a Direct Mode per le distribuzioni di produzione in cui si preferisce l'integrazione senza codice.

Magicgate valuta ogni visitatore in entrata rispetto a una pipeline di rilevamento a più livelli. Ogni filtro funziona in modo indipendente e contribuisce al verdetto finale. L'intera valutazione viene completata in meno di 10 millisecondi, garantendo una latenza percettibile pari a zero per gli utenti reali.

La pipeline di rilevamento è suddivisa in diverse categorie: controlli a livello di rete (reputazione IP, GeoIP, rilevamento VPN/proxy/Tor, identificazione del data center), controlli a livello di browser (analisi user-agent, impronte digitali JavaScript, coerenza delle intestazioni), controlli comportamentali (modelli di clic, velocità di sessione, convalida dei referrer) e controlli basati su elenchi (liste di blocco, liste consentite, filtro ISP).

Ciascun filtro può essere abilitato o disabilitato individualmente per flusso. Questo controllo granulare ti consente di ottimizzare il rilevamento per diverse sorgenti di traffico. Ad esempio, una campagna indirizzata agli utenti mobili statunitensi potrebbe abilitare GeoIP (solo Stati Uniti), rilevamento VPN/proxy e verifica dei dispositivi mobili, disabilitando al tempo stesso il filtro ISP.

Il filtraggio GeoIP utilizza database MaxMind ospitati localmente aggiornati settimanalmente per ricerche a latenza zero. Puoi targetizzare o escludere il traffico per Paese, regione o città. Il database copre gli indirizzi IPv4 e IPv6 con una precisione a livello nazionale del 99,8%.

Il rilevamento VPN, proxy e Tor combina più database commerciali e open source. Magicgate mantiene un elenco continuamente aggiornato di nodi di uscita VPN conosciuti, server proxy pubblici e privati, relè di uscita Tor e reti proxy residenziali. Il rilevamento copre sia gli intervalli IPv4 che IPv6.

Il rilevamento del data center identifica il traffico proveniente dai provider cloud (AWS, GCP, Azure, DigitalOcean, OVH, Hetzner e oltre 200 altri). Ciò è particolarmente efficace nel catturare script automatizzati e browser headless in esecuzione su macchine virtuali.

L'analisi dello user-agent analizza la stringa dello user-agent del visitatore rispetto a un database di crawler, bot e strumenti automatizzati noti. Rileva anche incoerenze, ad esempio un agente utente che afferma di essere Chrome su Windows ma invia intestazioni specifiche di Linux.

Il filtro blocklist ti consente di mantenere elenchi personalizzati di indirizzi IP, intervalli IP (notazione CIDR) e modelli user-agent che dovrebbero sempre essere classificati come bot. Al contrario, il filtro della lista consentita ti consente di inserire nella whitelist gli IP attendibili (come la tua infrastruttura di test) che dovrebbero sempre passare.

La convalida del referer controlla l'intestazione HTTP Referer rispetto ai modelli previsti. Puoi richiedere che il traffico provenga da domini specifici (ad esempio Google, Facebook) o bloccare il traffico con referer vuoti, mancanti o sospetti.

Fondamentalmente, Magicgate è un router di traffico. Ogni visitatore viene valutato rispetto ai filtri configurati e gli viene assegnato un verdetto: "offerta" (utente legittimo) o "bianco" (bot, crawler o traffico indesiderato). Il verdetto determina dove viene reindirizzato il visitatore.

La pagina dell'offerta è la tua vera pagina di destinazione, pagina di offerta o canalizzazione di conversione: la pagina che vuoi che i visitatori reali vedano. La Pagina Bianca è una pagina esca o benigna mostrata a bot, crawler e revisori di reti pubblicitarie. Le pagine bianche comuni includono semplici post di blog, articoli di notizie o contenuti informativi generici.

Questa separazione è essenziale per la protezione della campagna. I revisori della conformità della rete pubblicitaria, i bot per frode sui clic e i concorrenti vedono la pagina bianca, mentre gli utenti autentici del tuo pubblico di destinazione raggiungono la pagina dell'offerta. Il routing avviene in modo trasparente e alla velocità del cavo.

In Direct Mode, il routing è completamente automatico. Indichi il DNS del tuo dominio a Magicgate e la piattaforma gestisce l'intero ciclo di vita della richiesta: ricevi il visitatore, valuta i filtri ed emetti un reindirizzamento HTTP (302 per impostazione predefinita) alla destinazione appropriata. Il visitatore non vede mai una pagina intermedia.

In API Mode, la tua applicazione chiama l'endpoint /api/v1/check con gli attributi del visitatore e riceve una risposta JSON contenente il verdetto e l'URL di reindirizzamento consigliato. L'applicazione gestisce quindi il reindirizzamento stesso. Ciò ti dà il pieno controllo sull'esperienza utente: puoi aggiungere logica personalizzata, registrazione o test A/B prima del reindirizzamento.

Magicgate supporta tre modalità di visualizzazione per instradare i visitatori. 'Reindirizzamento' (impostazione predefinita) invia un reindirizzamento HTTP all'URL di destinazione. "Proxy" fornisce il contenuto della pagina di destinazione all'URL originale senza modificare la barra degli indirizzi del browser. "Iframe" carica la pagina di destinazione all'interno di un iframe sull'URL originale. La modalità di visualizzazione è configurabile per flusso.

I verdetti vengono elaborati in modo sincrono e memorizzati brevemente nella cache per gestire le richieste successive rapide dello stesso visitatore (ad esempio, il caricamento delle risorse della pagina dopo il reindirizzamento iniziale). Il TTL della cache è configurabile per flusso, con un valore predefinito di 30 secondi.

Magicgate offre due modalità di integrazione distinte, ciascuna progettata per casi d'uso e requisiti tecnici diversi. La scelta della modalità corretta influisce sulla complessità della distribuzione, sul controllo sull'esperienza utente e sul sovraccarico operativo.

API Mode è un'integrazione programmatica. La tua applicazione invia una richiesta POST all'endpoint /api/v1/check con gli attributi del visitatore (indirizzo IP, agente utente, referrer, ecc.) e riceve una risposta JSON contenente il verdetto. Il tuo codice gestisce quindi il routing, reindirizzando i bot alla pagina bianca e consentendo il passaggio agli utenti reali. Questa modalità richiede la scrittura del codice di integrazione ma ti offre il controllo completo sul flusso di richieste.

Direct Mode è un'integrazione di livello DNS. Configura i record DNS del tuo dominio (da CNAME a proxy.magicgate.io o ALIAS/ANAME per i domini root) in modo che puntino a Magicgate. Quando arriva un visitatore, Magicgate intercetta in modo trasparente la richiesta, valuta il visitatore ed emette un reindirizzamento HTTP alla pagina dell'offerta o alla pagina bianca. Non sono necessarie modifiche al codice della tua applicazione: l'intero livello di filtraggio e routing si trova davanti al tuo server di origine.

Vantaggi API Mode: controllo completo sulla logica di routing. Puoi aggiungere un'elaborazione personalizzata tra la ricezione del verdetto e il reindirizzamento dell'utente: registrazione, assegnazione di test A/B, impostazione dei cookie, eventi di analisi o logica condizionale basata sui metadati del verdetto. API Mode funziona con qualsiasi stack di backend e non richiede modifiche a DNS. È ideale anche per applicazioni a pagina singola (SPA) in cui JavaScript lato client effettua la chiamata di controllo.

Svantaggi API Mode: richiede modifiche al codice nell'applicazione. È necessario gestire la chiamata API, i casi di errore (timeout, limiti di velocità) e la logica di reindirizzamento. La chiamata API aggiunge un viaggio di andata e ritorno della rete al tempo di caricamento della pagina (in genere 10-50 ms a seconda della vicinanza geografica al bordo di Magicgate).

Vantaggi Direct Mode: zero modifiche al codice. Punta il tuo DNS e configura il tuo flusso: i visitatori vengono filtrati e reindirizzati automaticamente. Direct Mode è più veloce per l'utente finale perché non è previsto un andata e ritorno API aggiuntivo; il filtraggio avviene sul bordo come parte della risoluzione DNS e della richiesta iniziale HTTP. Gestisce inoltre tutti i casi limite (timeout, nuovi tentativi) in modo trasparente.

Svantaggi Direct Mode: minore controllo sul processo di routing. Non è possibile inserire logica personalizzata tra il verdetto e il reindirizzamento. Le modifiche DNS si propagano lentamente (da minuti a ore), il che rende i test e il rollback più lenti. Direct Mode richiede che la pagina bianca e la pagina dell'offerta siano accessibili tramite URL pubblici.

È anche possibile un approccio ibrido. Utilizza Direct Mode per le tue pagine di destinazione principali (dove l'integrazione zero-code è una priorità) e API Mode per endpoint specifici che richiedono una gestione del verdetto personalizzata (ad esempio invii di moduli, endpoint API o flussi di pagamento).

Ogni account Magicgate ha accesso a un dominio condiviso (go.magicgate.io) per un utilizzo immediato. I piani Starter e superiori possono aggiungere domini personalizzati per URL brandizzati e segnali di fiducia migliorati con le reti pubblicitarie.

I domini personalizzati ti consentono di utilizzare il tuo URL (ad esempio, track.yourbrand.com) invece del dominio condiviso. Questo è importante per la conformità degli annunci: molte reti pubblicitarie sono più indulgenti nei confronti del traffico proveniente da domini brandizzati piuttosto che da domini di monitoraggio condivisi.

Magicgate supporta sia i sottodomini (track.yourbrand.com) che i domini root (yourbrand.com). I sottodomini sono consigliati perché non interferiscono con la configurazione DNS del tuo sito web principale e sono più facili da gestire.

La verifica del dominio utilizza record CNAME che puntano a proxy.magicgate.io. Quando aggiungi un dominio, configuri un record CNAME dal tuo dominio su proxy.magicgate.io. Per i domini root che non supportano i record CNAME, utilizza invece un record ALIAS o ANAME che punta a proxy.magicgate.io. Magicgate verifica la proprietà controllando che il record DNS si risolva correttamente nell'endpoint proxy.

I certificati SSL vengono forniti automaticamente tramite Let's Encrypt al termine della propagazione DNS. Magicgate gestisce l'emissione, il rinnovo e l'installazione dei certificati. Il tuo dominio personalizzato servirà il traffico su HTTPS con un certificato valido entro pochi minuti dalla configurazione DNS.

Per gli utenti Cloudflare, assicurati che il proxy (nuvola arancione) sia disabilitato per il record CNAME che punta a Magicgate. Il proxy di Cloudflare intercetta il traffico prima che raggiunga Magicgate, il che può interferire con la valutazione dei visitatori. Imposta il record sulla modalità "Solo DNS" (nuvola grigia).

Puoi anche acquistare domini direttamente tramite il marketplace di Magicgate. Questi domini sono preconfigurati e pronti per l'uso immediato: non è richiesta alcuna configurazione o verifica DNS. Il marketplace offre una selezione di domini puliti adatti alle campagne di traffico.

Webhooks ti consente di ricevere notifiche POST HTTP in tempo reale quando si verificano eventi importanti nel tuo account Magicgate, ad esempio modifiche del flusso, verifica del dominio o aggiornamenti dei pagamenti.

Magicgate supporta eventi webhook in più categorie: eventi di flusso (flow.created, flow.updated, flow.deleted), eventi di dominio (domain.added, domain.verified, domain.deleted, domain.registration_failed), eventi di pagina bianca (white_page.ready, white_page.failed, white_page.deleted), eventi blacklist (blacklist.created, blacklist.updated, blacklist.deleted), eventi API key (apikey.created, apikey.deleted, apikey.activated, apikey.deactivated), eventi portafoglio (wallet.credited, wallet.debited), eventi di abbonamento (subscription.changed, subscription.canceled, membership.plan_changed e altro), eventi di fatturazione (payment.completed, payment.failed) ed eventi di supporto (ticket.created, ticket.replied, ticket.resolved, ticket.closed).

Ogni consegna di webhook include tre intestazioni di sicurezza: X-Webhook-Signature (digest esadecimale HMAC-SHA256), X-Webhook-Timestamp (timestamp Unix) e X-Webhook-ID (identificatore dell'endpoint). La firma copre insieme il timestamp e il corpo, calcolato come HMAC-SHA256(segreto, timestamp + '." + corpo), il che impedisce sia la manomissione che gli attacchi di riproduzione. Dovresti verificare la firma e rifiutare le richieste con timestamp più vecchi di 5 minuti. Il segreto della firma viene generato quando crei l'endpoint webhook e viene visualizzato una volta: archivialo in modo sicuro.

Magicgate riprova a effettuare consegne di webhook non riuscite. Se il tuo endpoint restituisce un codice di stato diverso da 2xx o non risponde entro 10 secondi, la consegna viene ritentata. Una volta esauriti tutti i tentativi, l'evento viene contrassegnato come non riuscito e il conteggio degli errori dell'endpoint viene incrementato.

I payload Webhook sono codificati JSON con la struttura: { id, event, timestamp, data }. Il campo "evento" contiene la stringa del tipo di evento (ad esempio "domain.verified"), "id" è un ID di consegna univoco per idempotenza, "timestamp" è un datetime ISO 8601 e "data" contiene dettagli specifici dell'evento.

È possibile configurare più endpoint webhook per account, ciascuno sottoscritto a diversi tipi di eventi. Ciò ti consente, ad esempio, di instradare gli eventi del dominio alla pipeline di distribuzione e gli eventi di fatturazione al tuo sistema di contabilità.

Magicgate utilizza un modello di fatturazione basato sul portafoglio. Aggiungi fondi al tuo portafoglio tramite depositi crittografici e il tuo abbonamento si rinnova automaticamente dal saldo del portafoglio ad ogni ciclo di fatturazione. Ciò elimina la necessità di addebiti ricorrenti sulla carta e fornisce il pieno controllo sulla spesa.

Sono supportati tre fornitori di servizi di pagamento: CCPayment, NowPayments e TransVoucher. Ogni fornitore supporta Bitcoin, Ethereum, USDT, USDC e oltre 50 criptovalute aggiuntive. Quando effettui un deposito, vengono generati un indirizzo di pagamento e un importo. Una volta che la blockchain conferma la transazione, il saldo del tuo portafoglio si aggiorna automaticamente.

I piani determinano i limiti delle funzionalità: controlli al mese, numero di flussi, regole per flusso, accesso API, domini personalizzati e altro ancora. Puoi visualizzare i piani disponibili senza autenticazione. L'upgrade o il downgrade hanno effetto immediato: il saldo non utilizzato del periodo corrente viene ripartito proporzionalmente e riaccreditato sul tuo portafoglio.

Gli abbonamenti possono essere mensili o annuali. Gli abbonamenti annuali offrono uno sconto. Puoi annullare in qualsiasi momento: l'abbonamento rimane attivo fino alla fine del periodo di fatturazione corrente. Il ripristino di un abbonamento annullato lo ripristina senza crearne uno nuovo.

Il portafoglio tiene traccia di tutte le transazioni: depositi, spese di abbonamento, rimborsi e crediti proporzionali. Ogni transazione include una tipologia di riferimento e un ID che la collega all'evento di origine (deposito, rinnovo dell'abbonamento, cambio di piano, ecc.).

La dashboard di Magicgate è il tuo pannello di controllo centrale per la gestione dei flussi di traffico, il monitoraggio delle analisi e la configurazione delle impostazioni dell'account. Dopo aver effettuato l'accesso, arrivi alla pagina Panoramica che mostra un riepilogo delle metriche chiave del tuo account.

La pagina Panoramica mostra gli assegni totali elaborati, la distribuzione del verdetto (offerta vs bianco), i flussi attivi e l'attività recente. Un grafico di serie temporali mostra il volume del traffico nelle ultime 24 ore, 7 giorni o 30 giorni. Questo ti dà un'idea immediata dello stato del tuo traffico e dell'efficacia del filtraggio.

La sezione Flussi è il luogo in cui crei e gestisci i flussi di traffico. Ogni flusso rappresenta una configurazione di filtro distinta: un insieme di filtri, un URL della pagina dell'offerta, un URL della pagina bianca e impostazioni di integrazione (API Mode o Direct Mode). Puoi avere più flussi per diverse campagne, pagine di destinazione o sorgenti di traffico.

All'interno della visualizzazione dettagliata di ciascun flusso, puoi visualizzare l'analisi per flusso: controlli totali, suddivisione del verdetto, percentuali di successo del filtro, distribuzione geografica e referrer principali. Questi dati granulari ti aiutano a ottimizzare le impostazioni del filtro per ciascuna campagna specifica.

La sezione Analisi fornisce una visione completa di tutti i flussi. I grafici includono le tendenze del verdetto nel tempo, l'efficacia dei filtri (quali filtri si attivano più spesso), mappe di calore geografiche che mostrano l'origine del traffico, i guasti del dispositivo e del browser e i modelli di traffico orario. Tutti i grafici supportano il filtraggio dell'intervallo di date e il filtraggio specifico del flusso.

La sezione Domini elenca tutti i domini configurati (condivisi e personalizzati). Per ciascun dominio puoi visualizzarne lo stato (attivo, in attesa di verifica, errore DNS), lo stato del certificato SSL e i flussi associati. I controlli di integrità del dominio vengono eseguiti automaticamente e ti avvisano se vengono rilevati problemi DNS o SSL.

La sezione Impostazioni contiene la configurazione a livello di account. Chiavi API: genera e gestisci API key con date di scadenza opzionali. Webhooks: configura gli endpoint webhook e visualizza i log di consegna. Fornitori: aggiungi e gestisci pagamenti e fornitori DNS. Fatturazione: visualizza il saldo del portafoglio, la cronologia delle ricariche e lo stato dell'abbonamento. Team: invita i membri del team con accesso basato sui ruoli (utente, amministratore).

La dashboard supporta sia temi chiari che scuri, con l'interruttore del tema nell'angolo in alto a destra. Tutte le pagine sono reattive e funzionano sui dispositivi mobili, sebbene l'esperienza desktop offra le visualizzazioni dati più complete.