AD, techniquement : comment ça marche et comment l'intégrer

Ce que c'est

Ce qu'est AD, et pour qui

AD est un serveur publicitaire direct : pas d'enchère, pas de boîte noire. Un éditeur vend l'espace publicitaire d'un site qu'il exploite déjà ; un annonceur choisit les zones exactes, règle le ciblage et lance. Un même compte peut jouer l'un ou l'autre rôle — ou les deux.

Accès

Comment entrer

Connectez-vous sur forhosting.com et choisissez « Gérer mon AD » dans le menu de votre compte. Le panneau s'ouvre avec une session courte — un identifiant qui expire en quelques minutes (jamais plus de 60) et ne laisse aucune clé permanente dans le navigateur. Quand elle expire, rouvrez-le depuis le même menu.

Pour vos intégrations, créez une clé d'API depuis le panneau (Profil) ou avec POST /tenants/:id/keys. Deux portées : tenant (accès complet à votre propre compte) et read (lecture seule, pour tableaux de bord et robots). La clé n'est affichée qu'une fois ; si elle est perdue, créez-en une autre et révoquez l'ancienne.

Notre équipe peut ouvrir votre panneau « en tant que client » pour vous aider : cette session dure au plus 15 minutes et porte le nom de la personne qui l'a ouverte. La maison n'opère jamais votre compte avec une clé permanente.

Annonceurs

Campagnes et ciblage

La campagne est le conteneur : nom, dates, budgets facultatifs et le ciblage partagé par ses créations. Elle naît en draft ; vous la passez active, paused, ou ended quand elle est terminée. Seules les créations actives d'une campagne active sont diffusées — mettre la campagne en pause arrête la diffusion aussitôt.

Entre les campagnes éligibles, le moteur ne tire pas au hasard : il fait tourner. Il en diffuse une, puis l'autre, et ce n'est qu'à égalité que le poids donné à chaque création départage — montrer dix fois de suite la même campagne au même visiteur ne vend rien. Les tours sont comptés par visiteur et par zone, dans le navigateur même du visiteur ; avec les cookies bloqués, il se rabat sur le tirage pondéré. Une création avec une limite de diffusion est aussi lissée (pacing) : toutes les 5 minutes son poids est réajusté pour que le budget s'étale sur les jours de la campagne au lieu de brûler dès le matin. Le pacing ne fait que freiner — il n'invente jamais de trafic.

Une création n'est diffusée que sur une zone où elle a une commande payée (voir « Acheter des emplacements »). Campagne, création, zone et commande sont visibles dans le panneau (Campagnes, Créations, Acheter des emplacements).

Annonceurs

Créations : six types, une balise

Chaque création a une URL de clic, une taille fixe facultative et un poids. Les limites de ce tableau sont celles que l'API applique à l'envoi — elles sont lues dans le code, pas écrites ici.

Le contrat HTML5

Votre index.html est chargé dans une iframe avec la destination du clic dans la query sous clickTag. Lisez-la et utilisez-la comme href de votre zone cliquable — cette URL est signée et compte le clic ; un lien écrit à la main ne compte pas.

// index.html — the click goes where the engine says
var clickTag = new URLSearchParams(location.search).get("clickTag");
document.getElementById("ad").href = clickTag;

Si votre création doit grandir, indiquez à la page sa hauteur réelle par postMessage. La balise indique aussi à la création la largeur de l'emplacement au chargement et à chaque redimensionnement, et envoie visible la première fois que l'emplacement entre dans la fenêtre — le bon moment pour lancer une animation. Les hauteurs jusqu'à 10000 px sont appliquées.

// creative → page: ask for the real height (applied up to 10000 px)
parent.postMessage({ fh: "resize", nh: document.documentElement.scrollHeight }, "*");

// page → creative: { fh: "size" | "visible" }
window.addEventListener("message", function (ev) {
  if (ev.data && ev.data.fh === "visible") { /* start your animation */ }
});

Une création minimale qui fait les deux, prête à envoyer telle quelle : téléchargez le ZIP d'exemple

Macros des créations script

Dans une création script, le moteur remplace ces marqueurs à la publication de la zone. Un modèle du panneau est la même chose avec des marqueurs supplémentaires que vous remplissez dans un formulaire.

Plusieurs destinations dans une même création

Une création peut porter jusqu'à 8 destinations nommées en plus de son URL de clic principale — un bouton App Store et un bouton Google Play dans la même pièce, par exemple. Chacune a un identifiant d'au plus 20 caractères minuscules ; main est réservé à l'URL principale.

Dans une création HTML5, elles arrivent dans la query sous clickTag_<id>, à côté du clickTag habituel ; dans une création script, vous écrivez [CLICKTAG:<id>]. Chacune passe par le traqueur de clics : elles s'ajoutent donc au total et se détaillent bouton par bouton dans les rapports.

Suivi tiers et consentement

Toute création peut porter un code de suivi (un pixel ou un script d'un fournisseur de mesure). Il est émis après l'annonce avec chaque src transformé en data-src, de sorte que rien ne charge tant que la balise ne l'autorise pas.

Si vous indiquez l'identifiant IAB TCF v2 du fournisseur, le code ne charge qu'après le consentement du visiteur pour ce fournisseur, avec ${GDPR} et ${GDPR_CONSENT_n} renseignés. La balise attend jusqu'à 10 secondes le gestionnaire de consentement du site ; sans identifiant de fournisseur, le code charge comme un élément ordinaire.

Revue manuelle

Toute création naît en_revision et est revue par une personne avant de pouvoir diffuser. Approuvée, vous la passez active ou paused ; refusée, vous voyez le motif et pouvez la corriger et la soumettre de nouveau. Rien d'une création non revue — ni le balisage, ni le script, ni le code de suivi — n'atteint jamais un visiteur.

Changer l'URL de clic, le contenu ou le fichier d'une création approuvée la renvoie en revue : ce qui a été approuvé est ce qui est diffusé, jamais autre chose.

Annonceurs

Acheter des emplacements

La vitrine liste chaque zone en vente : site, taille, formats acceptés, modèle de vente et le prix fixé par l'éditeur. Vous choisissez une zone, une création d'un format que la zone accepte, un budget et une date de début. Le devis et le débit utilisent la même formule :

La commande minimale est de $5 ; le devis refuse tout montant inférieur. Une commande est un achat prépayé de volume — l'argent ne bouge qu'une fois, à l'achat. Envoyez une idempotencyKey et une requête réessayée renvoie la même commande au lieu d'en créer une seconde.

Comment vous payez

Quand une commande est marquée payée, 80% de son prix final est crédité à l'éditeur de la zone — sur la commande entière, sans prorata de diffusion. La zone est republiée immédiatement et votre création commence à diffuser dans la minute.

Éditeurs

Sites, zones, balise et versements

Sites

Déclarez un site par son domaine (Devenir éditeur). Il naît en attente et se vérifie tout seul : publiez le jeton que nous vous donnons sur /.well-known/fh-ad-site-verification.txt ou dans la page d'accueil, demandez la vérification, et le site s'active de lui-même — sans file d'attente et sans que personne ici ait à le regarder d'abord. Un domaine non vérifié ne peut pas toucher de part. Retirer un site déclenche un délai de 90 jours sur le domaine : personne d'autre ne peut l'enregistrer entre-temps et hériter de son historique.

Zones

La zone est l'emplacement vendable : un nom, une taille en pixels (ou -1 pour une largeur adaptative), les formats qu'elle accepte, un modèle de vente avec son prix, et si elle est en vente dans la vitrine. Vous pouvez fixer une création de repli à vous qui diffuse quand rien d'autre n'est éligible — elle ignore ciblage et plafonds.

Deux comportements facultatifs s'exécutent dans le navigateur du visiteur : le rafraîchissement automatique (une nouvelle requête toutes les N secondes, minimum 5 ; un onglet masqué ne rafraîchit jamais, et un emplacement qui revient vide garde l'annonce précédente) et le report des paramètres (la query de la page voyage avec le clic jusqu'à la destination de l'annonceur).

Comment l'interstitiel se déclenche

L'overlay est une propriété de la zone, pas du site : rien n'a besoin d'être collé pour lui — la balise construit ce qu'il lui faut — et le rythme se change depuis le panneau où l'on achète. Quatre modes :

Un rythme fixe fatigue le visiteur autant au 30e jour qu'au 1er — c'est à cela que sert le calendrier échelonné : il encaisse la première impression tôt, puis s'efface. Le compte vit dans le navigateur même du visiteur ; si le stockage est bloqué, il se rabat sur un comptage en mémoire au lieu de casser.

Quand les annonces sont demandées — votre site d'abord

Les annonces ne doivent pas ralentir votre site, et le réglage vit ici, pas dans votre HTML. Chaque site choisit quand la balise demande sa première annonce :

Et pendant que l'annonce est en route, l'emplacement n'est pas vide : la balise y peint un gabarit d'attente, et elle apprend la hauteur — la première visite réserve une taille prudente, et dès la deuxième l'emplacement réservé est le bon, de sorte que la page ne saute pas quand l'annonce arrive. Ce saut est ce que Google mesure comme décalage de mise en page, et c'est la raison habituelle pour laquelle une régie publicitaire coûte son score à un site.

La balise

Collez-la là où la publicité doit apparaître — ou laissez la zone dire où elle va et sautez cette étape entièrement (voir « Où sort la publicité », plus bas). L'id de zone vient du panneau (Sites et zones). La même balise sert tous les formats que la zone accepte ; une zone interstitielle utilise aussi la balise standard.

Standard (un div et un script, asynchrone) :

<div data-fh-ad="zon_XXXXXXXXXXXXXXXXXXXXXXXX"></div>
<script src="https://api.ad.forhosting.com/ad-tag.js" async></script>

Legacy, pour les CMS qui n'exécutent pas de scripts asynchrones :

<script src="https://api.ad.forhosting.com/ad-serve?zone=zon_XXXXXXXXXXXXXXXXXXXXXXXX&mode=js"></script>

Lien texte : une URL qui compte l'impression et redirige vers l'annonceur :

https://api.ad.forhosting.com/ad-serve?zone=zon_XXXXXXXXXXXXXXXXXXXXXXXX&mode=link

La balise se met à jour toute seule : son URL ne porte pas de version et ne change jamais, donc une amélioration de notre côté atteint tous les sites en environ 60 minutes et personne ne modifie de gabarit (elle sert v11 aujourd'hui, dans l'en-tête x-tag-version). Elle attend que votre page finisse de charger avant de demander quoi que ce soit : les annonces ne concurrencent jamais votre contenu. Ses seules marques dans votre page sont l'attribut data-fh-ad et l'id de l'overlay — vérifiés contre les listes de blocage courantes, sans aucune correspondance. Les plafonds de fréquence utilisent un cookie propriétaire.

Si le même emplacement se répète le long d'une page — « tous les N messages » sur un forum, par exemple — la balise demande toutes ses copies en une seule requête (jusqu'à 10), et le plafond de fréquence avance à l'intérieur de ce lot : une même création ne peut donc pas remplir tous les emplacements de la page. Si notre côté ne comprend pas le lot, la balise se rabat sur un emplacement à la fois plutôt que de laisser la page vide. Répéter une zone se déclare chez nous : en règle générale, une zone par emplacement, parce que la zone est ce qu'un rapport regroupe.

Où sort la publicité — sans toucher à votre thème

Une zone peut déclarer où elle va : un sélecteur CSS (jusqu'à 300 caractères) et une position par rapport à ce que ce sélecteur trouve. C'est la balise qui crée l'emplacement, donc déplacer une publicité coûte un changement dans le panneau et non une modification de votre thème.

Deux nombres facultatifs gouvernent la répétition : l'un place l'emplacement toutes les N occurrences (jusqu'à 50) et un plafond limite le nombre d'emplacements créés — 4 par défaut quand on répète, 20 au maximum. Il y a toujours un plafond : un sélecteur lâche comme p correspond des centaines de fois dans un long article, et cette limite ne peut pas dépendre de la mémoire de celui qui configure.

Deux choses à savoir. Un div data-fh-ad que vous placez vous-même dans le thème l'emporte : la balise n'ajoutera pas un second emplacement pour cette zone, vous pouvez donc passer d'une méthode à l'autre sans payer deux impressions pour une. Et un sélecteur qui ne correspond à rien ne lève aucune erreur — votre page s'affiche très bien sans la publicité et le panneau reste au vert. Vérifiez l'emplacement dans un navigateur, en bureau et en mobile : un sélecteur peut exister sur l'article et pas sur l'accueil, ou mesurer 1360 px en bureau et 0 sur un téléphone.

WordPress : rien à coller

Si votre site tourne sous WordPress, il y a une extension, forhosting-ad. Installez-la et elle se présente toute seule : elle publie un défi sur votre propre domaine, nous le lisons, et l'identifiant est délivré une seule fois. Vous ne tapez aucune clé, aucun id, aucun jeton — et prouver que vous contrôlez le domaine n'est pas la même chose qu'être invité : rien n'est délivré tant que le site n'est pas approuvé.

À partir de là les zones se gèrent depuis le panneau, emplacement compris. L'extension demande en plus au cache de pages que votre site utilise de purger les pages dont le balisage a changé — elle reconnaît les plus courants et s'adresse à chacun à sa manière. Une page en cache est la raison la plus fréquente pour laquelle la balise est dans votre HTML et la publicité toujours pas à l'écran, et cela ne se voit pas en ligne de commande : la copie périmée n'est servie qu'à un vrai navigateur.

Il existe une seconde extension, forhosting-ad-updater, qui reçoit un paquet et l'installe. C'est par conception un canal d'exécution à distance, nous ne l'installons donc que sur nos propres sites ; chez vous, les mises à jour arrivent par le canal natif de WordPress et vous décidez quand les appliquer.

Versements

Votre part de 80% sur chaque commande payée s'accumule dans le panneau (Versements). Quand le cumul atteint $10, demandez le versement avec la méthode de votre profil (paypal, bank, other) ; notre équipe paie hors du panneau et enregistre la référence.

États : accrued → requested → processing → paid ; un versement échoué vous revient avec le motif pour que vous le redemandiez avec des coordonnées corrigées.

Pour tous

Rapports

Impressions, clics et début/fin de vidéo sont comptés en bordure, à chaque requête. Avant de compter, le trafic est filtré : robots connus par leur user agent, réseaux de centres de données, requêtes avec un score de bot très bas, et toute IP répétant la même requête en moins de 2 secondes. Une requête filtrée reçoit quand même son annonce ou sa redirection — seul le compteur est protégé.

Toutes les 5 minutes, les comptages sont consolidés en lignes journalières par création, zone et hôte du referrer. Le jour en cours peut avoir jusqu'à ce retard ; les jours clos ne changent jamais.

Le panneau (Rapports) montre les totaux et une série journalière, le CTR (clics ÷ impressions × 100) et l'eCPM (valeur délivrée × 1000 ÷ impressions), côté annonceur ou côté éditeur, et un classement regroupé selon l'une des six dimensions :

Chacune de ces vues peut aussi être filtrée par campagne, création, zone, hôte du referrer ou destination, et les mêmes chiffres sont disponibles par l'API.

Avant tout comptage, le trafic passe par le filtre anti-robots, que la maison exploite dans l'un de trois modes : block (par défaut : les requêtes filtrées reçoivent quand même leur annonce, elles ne comptent simplement pas), log (elles comptent et sont enregistrées à part, pour mesurer avant de décider) et off.

Intégrer

Référence de l'API

URL de base https://api.ad.forhosting.com. Envoyez votre clé en jeton Bearer ; corps et réponses sont en JSON. Chaque réponse a la forme {"success":true,"data":…} ou {"success":false,"error":{"code","message"}} avec le statut HTTP correspondant.

curl https://api.ad.forhosting.com/me \
  -H "Authorization: Bearer ads_ten_…"

Portées des identifiants

Un identifiant tenant, read ou session opère toujours son propre compte — un tenantId envoyé par le client est ignoré. Un identifiant qui appartient à quelqu'un d'autre renvoie 404, pas 403 : l'API ne confirme jamais qu'il existe.

Routes

Toutes les routes que le service annonce, avec la portée que le routeur exige — dérivée du routeur lui-même à chaque build.

publique: sans identifiant — le chemin de diffusion · n'importe laquelle: tout identifiant valide, sur son propre compte · lecture: tenant, session ou read · écriture: tenant ou session (read est refusé) · system: la maison seulement

Erreurs à connaître : 401 unauthorized (identifiant absent ou expiré), 403 forbidden (la portée ne peut pas faire cela), 404 not_found, 400 bad_request avec le motif dans le message, 409 conflict (une transition d'état non permise), 402 insufficient_balance au paiement d'une commande, et 503 payments_disabled si les ventes sont en pause.

FAQ

Questions techniques