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, la mettez en pause ou la terminez. Seules les créations actives d'une campagne active sont diffusées — mettre la campagne en pause arrête la diffusion aussitôt.

Parmi les créations éligibles, le moteur tire au hasard, pondéré par le poids que vous donnez à chacune. Une création avec une limite de diffusion est 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.

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 une personne le vérifie avant que ses zones puissent vendre — un domaine non vérifié ne peut pas toucher de part. Retirer un site lance un refroidissement de 90 jours sur le domaine : personne d'autre ne peut le déclarer 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). Une zone interstitielle déclare aussi quels liens déclenchent la surimpression — par défaut p a, nav a, h2 a — et les secondes avant de pouvoir la fermer.

La balise

Collez-la là où l'annonce doit apparaître. L'identifiant de zone vient du panneau (Sites et zones). La même balise diffuse 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 undefined minutes et personne ne modifie de gabarit (elle sert v6 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.

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 par création, zone, campagne, site ou hôte du referrer. Seul l'hôte du referrer est conservé, jamais l'URL.

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