Documentation

Magicgate sépare le trafic des robots des utilisateurs réels en évaluant chaque visiteur par rapport à un ensemble de filtres configurables. La plateforme renvoie un verdict – soit « blanc » (bot/crawler/unwanted) ou « offre » (utilisateur réel) – en moins de 10 millisecondes.

Il existe deux modes d'intégration. API Mode vous permet d'envoyer des attributs de visiteur via un point de terminaison REST et de recevoir un verdict JSON sur lequel votre application agit. Direct Mode gère tout automatiquement : pointez votre domaine sur Magicgate et les visiteurs sont filtrés et redirigés sans aucune modification de code de votre part.

Ce démarrage rapide se concentre sur API Mode car il vous donne le plus de contrôle et la boucle de rétroaction la plus rapide pendant le développement. Une fois que vous êtes à l'aise, vous pouvez passer à Direct Mode pour les déploiements de production où l'intégration sans code est préférée.

Magicgate évalue chaque visiteur entrant par rapport à un pipeline de détection multicouche. Chaque filtre fonctionne indépendamment et contribue au verdict final. L’ensemble de l’évaluation se termine en moins de 10 millisecondes, garantissant une latence nulle perceptible pour les utilisateurs réels.

Le pipeline de détection est divisé en plusieurs catégories : vérifications au niveau du réseau (réputation IP, détection GeoIP, VPN/proxy/Tor, identification du centre de données), vérifications au niveau du navigateur (analyse de l'agent utilisateur, empreintes digitales JavaScript, cohérence des en-têtes), vérifications comportementales (modèles de clic, vitesse de session, validation du référent) et vérifications basées sur des listes (listes de blocage, listes autorisées, filtrage ISP).

Chaque filtre peut être activé ou désactivé individuellement par flux. Ce contrôle granulaire vous permet d'affiner la détection pour différentes sources de trafic. Par exemple, une campagne ciblant les utilisateurs mobiles aux États-Unis peut activer la détection GeoIP (États-Unis uniquement), VPN/proxy et la vérification des appareils mobiles, tout en désactivant le filtrage ISP.

Le filtrage GeoIP utilise des bases de données MaxMind hébergées localement et mises à jour chaque semaine pour des recherches sans latence. Vous pouvez cibler ou exclure le trafic par pays, région ou ville. La base de données couvre les adresses IPv4 et IPv6 avec une précision de 99,8 % au niveau national.

La détection VPN, proxy et Tor combine plusieurs bases de données commerciales et open source. Magicgate maintient une liste continuellement mise à jour des nœuds de sortie VPN connus, des serveurs proxy publics et privés, des relais de sortie Tor et des réseaux proxy résidentiels. La détection couvre les plages IPv4 et IPv6.

La détection des centres de données identifie le trafic provenant des fournisseurs de cloud (AWS, GCP, Azure, DigitalOcean, OVH, Hetzner et plus de 200 autres). Ceci est particulièrement efficace pour détecter les scripts automatisés et les navigateurs sans tête exécutés sur des machines virtuelles.

L'analyse de l'agent utilisateur analyse la chaîne de l'agent utilisateur du visiteur par rapport à une base de données de robots d'exploration, de robots et d'outils automatisés connus. Il détecte également les incohérences : par exemple, un agent utilisateur prétendant être Chrome sous Windows mais envoyant des en-têtes spécifiques à Linux.

Le filtre de liste de blocage vous permet de conserver des listes personnalisées d'adresses IP, de plages IP (notation CIDR) et de modèles d'agent utilisateur qui doivent toujours être classés comme robots. À l’inverse, le filtre de liste autorisée vous permet de mettre sur liste blanche les adresses IP de confiance (telles que votre propre infrastructure de test) qui doivent toujours passer.

La validation du référent vérifie l'en-tête HTTP Referer par rapport aux modèles attendus. Vous pouvez exiger que le trafic provienne de domaines spécifiques (par exemple, Google, Facebook) ou bloquer le trafic avec des référents vides, manquants ou suspects.

À la base, Magicgate est un routeur de trafic. Chaque visiteur est évalué par rapport à vos filtres configurés et se voit attribuer un verdict : « offre » (utilisateur légitime) ou « blanc » (bot, robot d'exploration ou trafic indésirable). Le verdict détermine où le visiteur est redirigé.

La page d'offre est votre véritable page de destination, page d'offre ou entonnoir de conversion : la page que vous souhaitez que les vrais visiteurs humains voient. La page blanche est une page leurre ou inoffensive présentée aux robots, aux robots d'exploration et aux réviseurs de réseaux publicitaires. Les pages blanches courantes incluent de simples articles de blog, des articles de presse ou du contenu informatif générique.

Cette séparation est essentielle pour la protection de la campagne. Les examinateurs de la conformité des réseaux publicitaires, les robots frauduleux aux clics et les concurrents voient la page blanche, tandis que les véritables utilisateurs de votre public cible accèdent à la page de l'offre. Le routage s'effectue de manière transparente et à la vitesse du fil.

En Direct Mode, le routage est entièrement automatique. Vous pointez le DNS de votre domaine vers Magicgate, et la plateforme gère l'intégralité du cycle de vie de la requête : recevez le visiteur, évaluez les filtres et émettez une redirection HTTP (302 par défaut) vers la destination appropriée. Le visiteur ne voit jamais de page intermédiaire.

Dans API Mode, votre application appelle le point de terminaison /api/v1/check avec les attributs du visiteur et reçoit une réponse JSON contenant le verdict et l'URL de redirection recommandée. Votre application gère ensuite elle-même la redirection. Cela vous donne un contrôle total sur l'expérience utilisateur : vous pouvez ajouter une logique personnalisée, une journalisation ou des tests A/B avant la redirection.

Magicgate prend en charge trois modes d'affichage pour acheminer les visiteurs. « Redirection » (par défaut) émet une redirection HTTP vers l'URL de destination. « Proxy » diffuse le contenu de la page de destination à l'URL d'origine sans modifier la barre d'adresse du navigateur. 'Iframe' charge la page de destination dans une iframe sur l'URL d'origine. Le mode d'affichage est configurable par flux.

Les verdicts sont traités de manière synchrone et mis en cache brièvement pour gérer les demandes successives rapides du même visiteur (par exemple, le chargement des ressources de la page après la redirection initiale). La durée de vie du cache est configurable par flux, avec une valeur par défaut de 30 secondes.

Magicgate propose deux modes d'intégration distincts, chacun conçu pour différents cas d'utilisation et exigences techniques. Choisir le bon mode affecte la complexité de votre déploiement, le contrôle de l'expérience utilisateur et les frais opérationnels.

API Mode est une intégration programmatique. Votre application envoie une requête POST au point de terminaison /api/v1/check avec les attributs du visiteur (adresse IP, user-agent, référent, etc.) et reçoit une réponse JSON contenant le verdict. Votre code gère ensuite le routage – redirigeant les robots vers la page blanche et permettant aux vrais utilisateurs de passer. Ce mode vous oblige à écrire du code d'intégration mais vous donne un contrôle total sur le flux des requêtes.

Direct Mode est une intégration de niveau DNS. Vous configurez les enregistrements DNS de votre domaine (CNAME à proxy.magicgate.io, ou ALIAS/ANAME pour les domaines racine) pour pointer vers Magicgate. Lorsqu'un visiteur arrive, Magicgate intercepte la demande de manière transparente, évalue le visiteur et émet une redirection HTTP vers la page d'offre ou la page blanche. Aucune modification de code n'est nécessaire sur votre application : l'ensemble de la couche de filtrage et de routage se trouve devant votre serveur d'origine.

Avantages API Mode : Contrôle total sur la logique de routage. Vous pouvez ajouter un traitement personnalisé entre la réception du verdict et la redirection de l'utilisateur : journalisation, attribution de tests A/B, paramètres de cookies, événements d'analyse ou logique conditionnelle basée sur les métadonnées du verdict. API Mode fonctionne avec n'importe quelle pile backend et ne nécessite pas de modifications DNS. Il est également idéal pour les applications monopage (SPA) dans lesquelles JavaScript côté client effectue l'appel de vérification.

Inconvénients de API Mode : Nécessite des modifications de code dans votre application. Vous devez gérer l'appel API, les cas d'erreur (délais d'attente, limites de débit) et la logique de redirection. L'appel API ajoute un aller-retour réseau au temps de chargement de votre page (généralement 10 à 50 ms en fonction de la proximité géographique avec le bord de Magicgate).

Avantages Direct Mode : Zéro changement de code. Pointez votre DNS et configurez votre flux : les visiteurs sont filtrés et redirigés automatiquement. Direct Mode est plus rapide pour l'utilisateur final car il n'y a pas d'aller-retour API supplémentaire ; le filtrage s'effectue en périphérie dans le cadre de la résolution DNS et de la requête initiale HTTP. Il gère également tous les cas extrêmes (délais d’attente, tentatives) de manière transparente.

Inconvénients de Direct Mode : Moins de contrôle sur le processus de routage. Vous ne pouvez pas injecter de logique personnalisée entre le verdict et la redirection. Les modifications DNS se propagent lentement (de quelques minutes à quelques heures), ce qui ralentit les tests et la restauration. Direct Mode nécessite que votre page blanche et votre page d'offre soient accessibles via des URL publiques.

Une approche hybride est également possible. Utilisez Direct Mode pour vos pages de destination principales (où l'intégration sans code est une priorité) et API Mode pour les points de terminaison spécifiques qui nécessitent une gestion de verdict personnalisée (par exemple, les soumissions de formulaires, les points de terminaison d'API ou les flux de paiement).

Chaque compte Magicgate a accès à un domaine partagé (go.magicgate.io) pour une utilisation immédiate. Les plans Starter et supérieurs peuvent ajouter des domaines personnalisés pour les URL de marque et des signaux de confiance améliorés avec les réseaux publicitaires.

Les domaines personnalisés vous permettent d'utiliser votre propre URL (par exemple, track.yourbrand.com) au lieu du domaine partagé. Ceci est important pour la conformité des publicités : de nombreux réseaux publicitaires sont plus indulgents avec le trafic provenant de domaines de marque plutôt que de domaines de suivi partagés.

Magicgate prend en charge à la fois les sous-domaines (track.yourbrand.com) et les domaines racine (yourbrand.com). Les sous-domaines sont recommandés car ils n'interfèrent pas avec la configuration DNS de votre site Web principal et sont plus faciles à gérer.

La vérification du domaine utilise des enregistrements CNAME pointant vers proxy.magicgate.io. Lorsque vous ajoutez un domaine, vous configurez un enregistrement CNAME de votre domaine sur proxy.magicgate.io. Pour les domaines racine qui ne prennent pas en charge les enregistrements CNAME, utilisez plutôt un enregistrement ALIAS ou ANAME pointant vers proxy.magicgate.io. Magicgate vérifie la propriété en vérifiant que l'enregistrement DNS est correctement résolu en point de terminaison proxy.

Les certificats SSL sont fournis automatiquement via Let's Encrypt une fois la propagation DNS terminée. Magicgate gère la délivrance, le renouvellement et l'installation des certificats. Votre domaine personnalisé diffusera le trafic via HTTPS avec un certificat valide quelques minutes après la configuration DNS.

Pour les utilisateurs Cloudflare, assurez-vous que le proxy (nuage orange) est désactivé pour l'enregistrement CNAME pointant vers Magicgate. Le proxy de Cloudflare intercepte le trafic avant qu'il n'atteigne Magicgate, ce qui peut interférer avec l'évaluation des visiteurs. Réglez l'enregistrement en mode « DNS uniquement » (nuage gris).

Vous pouvez également acheter des domaines directement via le marché de Magicgate. Ces domaines sont préconfigurés et prêts à être utilisés immédiatement : aucune configuration ou vérification DNS n'est requise. La place de marché propose une sélection de domaines propres adaptés aux campagnes de trafic.

Webhooks vous permet de recevoir des notifications HTTP POST en temps réel lorsque des événements importants se produisent dans votre compte Magicgate, tels que des modifications de flux, une vérification de domaine ou des mises à jour de paiement.

Magicgate prend en charge les événements de webhook dans plusieurs catégories : événements de flux (flow.created, flow.updated, flow.deleted), événements de domaine (domain.added, domain.verified, domain.deleted, domain.registration_failed), événements de page blanche (white_page.ready, white_page.failed, white_page.deleted), événements de liste noire (blacklist.created, blacklist.updated, blacklist.deleted), événements API key (apikey.created, apikey.deleted, apikey.activated, apikey.deactivated), événements de portefeuille (wallet.credited, wallet.debited), les événements d'abonnement (subscription.changed, subscription.canceled, souscription.plan_changed, et plus), les événements de facturation (payment.completed, payment.failed) et les événements de support (ticket.created, ticket.replied, ticket.resolved, ticket.closed).

Chaque livraison de webhook comprend trois en-têtes de sécurité : X-Webhook-Signature (résumé hexadécimal HMAC-SHA256), X-Webhook-Timestamp (horodatage Unix) et X-Webhook-ID (identifiant de point de terminaison). La signature couvre l'horodatage et le corps ensemble - calculé comme HMAC-SHA256 (secret, horodatage + '.' + corps) - ce qui empêche à la fois les attaques de falsification et de relecture. Vous devez vérifier la signature et rejeter les demandes dont l'horodatage date de plus de 5 minutes. Le secret de signature est généré lorsque vous créez le point de terminaison du webhook et est affiché une fois : stockez-le en toute sécurité.

Magicgate réessaye les livraisons de webhooks ayant échoué. Si votre point de terminaison renvoie un code d'état autre que 2xx ou ne répond pas dans les 10 secondes, la livraison est retentée. Une fois toutes les tentatives épuisées, l'événement est marqué comme ayant échoué et le nombre d'échecs du point de terminaison est incrémenté.

Les charges utiles Webhook sont codées en JSON avec la structure : { id, event, timestamp, data }. Le champ 'event' contient la chaîne du type d'événement (par exemple, 'domain.verified'), 'id' est un identifiant de livraison unique pour l'idempotence, 'timestamp' est une date/heure ISO 8601 et 'data' contient des détails spécifiques à l'événement.

Vous pouvez configurer plusieurs points de terminaison de webhook par compte, chacun étant abonné à différents types d'événements. Cela vous permet d'acheminer les événements de domaine vers votre pipeline de déploiement et les événements de facturation vers votre système de comptabilité, par exemple.

Magicgate utilise un modèle de facturation basé sur un portefeuille. Vous ajoutez des fonds à votre portefeuille via des dépôts cryptographiques et votre abonnement se renouvelle automatiquement à partir du solde du portefeuille à chaque cycle de facturation. Cela élimine le besoin de frais de carte récurrents et offre un contrôle total sur vos dépenses.

Trois fournisseurs de paiement sont pris en charge : CCPayment, NowPayments et TransVoucher. Chaque fournisseur prend en charge Bitcoin, Ethereum, USDT, USDC et plus de 50 crypto-monnaies supplémentaires. Lorsque vous effectuez un dépôt, une adresse de paiement et un montant sont générés. Une fois que la blockchain confirme la transaction, le solde de votre portefeuille est automatiquement mis à jour.

Les forfaits déterminent vos limites de fonctionnalités : contrôles par mois, nombre de flux, règles par flux, accès API, domaines personnalisés, etc. Vous pouvez afficher les forfaits disponibles sans authentification. La mise à niveau ou la rétrogradation prend effet immédiatement : le solde inutilisé de la période en cours est calculé au prorata et recrédité sur votre portefeuille.

Les abonnements peuvent être mensuels ou annuels. Les abonnements annuels offrent une réduction. Vous pouvez annuler à tout moment : l'abonnement reste actif jusqu'à la fin de la période de facturation en cours. La reprise d'un abonnement annulé le restaure sans en créer un nouveau.

Le portefeuille suit toutes les transactions : dépôts, frais d'abonnement, remboursements et crédits au prorata. Chaque transaction comprend un type de référence et un identifiant la liant à l'événement d'origine (dépôt, renouvellement d'abonnement, changement de forfait, etc.).

Le tableau de bord Magicgate est votre panneau de contrôle central pour gérer les flux de trafic, surveiller les analyses et configurer les paramètres du compte. Une fois connecté, vous arrivez sur la page Présentation qui affiche un résumé des indicateurs clés de votre compte.

La page Présentation affiche le nombre total de chèques traités, la distribution des verdicts (offre vs blanc), les flux actifs et l'activité récente. Un graphique de séries chronologiques montre le volume de trafic au cours des dernières 24 heures, 7 ou 30 jours. Cela vous donne une idée immédiate de l’état de votre trafic et de l’efficacité du filtrage.

La section Flux est l'endroit où vous créez et gérez les flux de trafic. Chaque flux représente une configuration de filtrage distincte : un ensemble de filtres, une URL de page d'offre, une URL de page blanche et des paramètres d'intégration (API Mode ou Direct Mode). Vous pouvez avoir plusieurs flux pour différentes campagnes, pages de destination ou sources de trafic.

Dans la vue détaillée de chaque flux, vous pouvez voir des analyses par flux : contrôles totaux, répartition des verdicts, taux de réussite des filtres, répartition géographique et principaux référents. Ces données granulaires vous aident à optimiser les paramètres de filtrage pour chaque campagne spécifique.

La section Analytics fournit une vue complète de tous les flux. Les graphiques incluent les tendances des verdicts au fil du temps, l'efficacité des filtres (les filtres se déclenchent le plus souvent), des cartes thermiques géographiques montrant l'origine du trafic, les pannes des appareils et des navigateurs et les modèles de trafic horaire. Tous les graphiques prennent en charge le filtrage par plage de dates et le filtrage spécifique au flux.

La section Domaines répertorie tous les domaines configurés (partagés et personnalisés). Pour chaque domaine, vous pouvez voir son statut (actif, en attente de vérification, erreur DNS), le statut du certificat SSL et les flux associés. Les vérifications de l'état du domaine s'exécutent automatiquement et vous alertent si des problèmes DNS ou SSL sont détectés.

La section Paramètres contient la configuration à l'échelle du compte. Clés API : générez et gérez des API key avec des dates d'expiration facultatives. Webhooks : configurez les points de terminaison du webhook et affichez les journaux de livraison. Fournisseurs : ajoutez et gérez les fournisseurs de paiement et DNS. Facturation : consultez le solde du portefeuille, l'historique des recharges et l'état de l'abonnement. Équipe : invitez les membres de l'équipe avec un accès basé sur les rôles (utilisateur, administrateur).

Le tableau de bord prend en charge les thèmes clairs et sombres, avec la bascule de thème dans le coin supérieur droit. Toutes les pages sont réactives et fonctionnent sur les appareils mobiles, bien que l'expérience de bureau offre les vues de données les plus complètes.