AD, tecnicamente: come funziona e come si integra

Cos'è

Cos'è AD e per chi è

AD è un ad server diretto: nessuna asta e nessuna scatola nera. Un publisher vende lo spazio pubblicitario di un sito che già gestisce; un inserzionista sceglie le zone esatte, imposta il targeting e lancia. Uno stesso account può avere uno dei due ruoli — o entrambi.

Accesso

Come entrare

Accedi su forhosting.com e scegli “Gestisci il mio AD” nel menu del tuo account. Il pannello si apre con una sessione breve — una credenziale che scade in pochi minuti (mai più di 60) e non lascia nessuna chiave permanente nel browser. Quando scade, riaprilo dallo stesso menu.

Per le integrazioni, crea una chiave API dal pannello (Profilo) o con POST /tenants/:id/keys. Due ambiti: tenant (accesso completo al tuo account) e read (sola lettura, per dashboard e bot). La chiave viene mostrata una sola volta; se la perdi, creane un'altra e revoca la vecchia.

Il nostro staff può aprire il tuo pannello “come cliente” per aiutarti: quella sessione dura al massimo 15 minuti e porta il nome della persona che l'ha aperta. La casa non opera mai il tuo account con una chiave permanente.

Inserzionisti

Campagne e targeting

La campagna è il contenitore: nome, date, budget facoltativi e il targeting condiviso dalle sue creatività. Nasce come draft; tu la metti active, paused, oppure ended quando è finita. Vengono erogate solo le creatività attive di una campagna attiva — mettere in pausa la campagna ferma subito l'erogazione.

Tra le campagne eleggibili il motore non sceglie a caso: fa a turni. Eroga l'una, poi l'altra, e solo quando sono pari il peso che hai dato a ciascuna creatività rompe la parità — mostrare allo stesso visitatore la stessa campagna dieci volte di fila non vende nulla. I turni si contano per visitatore e per zona, nel browser del visitatore stesso; con i cookie bloccati degrada al sorteggio ponderato. Una creatività con un limite di erogazione ha anche il pacing: ogni 5 minuti il suo peso viene ricalibrato così che il budget si distribuisca sui giorni della campagna invece di bruciarsi al mattino. Il pacing frena soltanto — non inventa mai traffico.

Una creatività viene erogata solo in una zona dove ha un ordine pagato (vedi «Comprare spazi»). Campagna, creatività, zona e ordine sono visibili nel pannello (Campagne, Creatività, Compra spazi).

Inserzionisti

Creatività: sei tipi, un tag

Ogni creatività ha una URL di clic, una dimensione fissa facoltativa e un peso. I limiti di questa tabella sono quelli che l'API applica al caricamento — si leggono dal codice, non si scrivono qui.

Il contratto HTML5

Il tuo index.html viene caricato in un iframe con la destinazione del clic nella query come clickTag. Leggila e usala come href della tua area cliccabile — quella URL è firmata e conta il clic; un link scritto a mano non lo conta.

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

Se la creatività deve crescere, comunica alla pagina la sua altezza reale con postMessage. Il tag comunica anche alla creatività la larghezza dello spazio al caricamento e a ogni ridimensionamento, e invia visible la prima volta che lo spazio entra nel viewport — il momento giusto per avviare un'animazione. Si applicano altezze fino a 10000 px.

// 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 */ }
});

Una creatività minima che fa entrambe le cose, pronta da caricare così com'è: scarica lo ZIP di esempio

Macro delle creatività script

In una creatività script il motore sostituisce questi segnaposto alla pubblicazione della zona. Un template del pannello è la stessa cosa con segnaposto aggiuntivi che compili in un modulo.

Più destinazioni in una stessa creatività

Una creatività può portare fino a 8 destinazioni con nome oltre alla sua URL di clic principale — un pulsante App Store e un pulsante Google Play nello stesso pezzo, per esempio. Ognuna ha un id di massimo 20 caratteri minuscoli; main è riservato alla URL principale.

In una creatività HTML5 arrivano nella query come clickTag_<id>, accanto al solito clickTag; in una creatività script scrivi [CLICKTAG:<id>]. Ognuna di esse passa dal tracker dei clic, quindi sommano al totale e si scompongono per pulsante nei report.

Tracking di terzi e consenso

Qualsiasi creatività può portare un codice di tracking (un pixel o uno script di un fornitore di misurazione). Viene emesso dopo l'annuncio con ogni src trasformato in data-src, così niente si carica finché il tag non lo consente.

Se indichi l'id IAB TCF v2 del fornitore, il codice si carica solo dopo il consenso del visitatore per quel fornitore, con ${GDPR} e ${GDPR_CONSENT_n} compilati. Il tag aspetta fino a 10 secondi il gestore del consenso del sito; senza id del fornitore il codice si carica come un elemento normale.

Revisione manuale

Ogni creatività nasce en_revision e viene revisionata da una persona prima di poter essere erogata. Approvata, la metti active o paused; respinta, vedi il motivo e puoi correggerla e reinviarla. Niente di una creatività non revisionata — né il markup, né lo script, né il codice di tracking — raggiunge mai un visitatore.

Cambiare la URL di clic, il contenuto o il file di una creatività approvata la rimanda in revisione: ciò che è stato approvato è ciò che viene erogato, mai altro.

Inserzionisti

Comprare spazi

La vetrina elenca ogni zona in vendita: sito, dimensione, formati accettati, modello di vendita e il prezzo fissato dal publisher. Scegli una zona, una creatività di un formato che la zona accetta, un budget e una data di inizio. Il preventivo e l'addebito usano la stessa formula:

L'ordine minimo è $5; il preventivo rifiuta qualsiasi importo inferiore. Un ordine è un acquisto prepagato di volume — il denaro si muove una volta, all'acquisto. Invia una idempotencyKey e una richiesta ripetuta restituisce lo stesso ordine invece di crearne un secondo.

Come paghi

Quando un ordine viene segnato come pagato, il 80% del suo prezzo finale viene accreditato al publisher della zona — sull'ordine intero, non proporzionato all'erogazione. La zona viene ripubblicata subito e la tua creatività inizia a essere erogata entro un minuto.

Publisher

Siti, zone, tag e pagamenti

Siti

Registra un sito per dominio (Diventa publisher). Nasce in sospeso e si verifica da solo: pubblica il token che ti diamo su /.well-known/fh-ad-site-verification.txt o nella home, chiedi la verifica, e il sito si attiva da sé — senza coda e senza che nessuno qui debba guardarlo prima. Un dominio non verificato non può incassare la quota. Ritirare un sito avvia un raffreddamento di 90 giorni sul dominio: nessun altro può registrarlo nel frattempo ed ereditarne lo storico.

Zone

La zona è lo spazio vendibile: un nome, una dimensione in pixel (o -1 per larghezza adattiva), i formati che accetta, un modello di vendita con il suo prezzo e se è in vendita nella vetrina. Puoi impostare una tua creatività di riserva che viene erogata quando nient'altro è eleggibile — salta targeting e tetti.

Due comportamenti facoltativi girano nel browser del visitatore: l'aggiornamento automatico (una nuova richiesta ogni N secondi, minimo 5; una scheda nascosta non aggiorna mai, e uno spazio che torna vuoto mantiene l'annuncio precedente) e l'inoltro dei parametri (la query della pagina viaggia con il clic fino alla destinazione dell'inserzionista).

Come si attiva l'interstitial

L'overlay è una proprietà della zona, non del sito: non serve incollare nulla per lui — il tag costruisce ciò che gli serve — e il ritmo lo cambi dal pannello dove compri. Quattro modalità:

Un ritmo fisso stanca il visitatore il giorno 30 quanto il giorno 1 — a questo serve il calendario scaglionato: incassa presto la prima impression e poi si fa da parte. Il conteggio vive nel browser del visitatore stesso; se lo storage è bloccato, degrada a contare in memoria invece di rompersi.

Quando vengono richiesti gli annunci — il tuo sito viene prima

Gli annunci non devono rallentare il tuo sito, e l'impostazione vive qui, non nel tuo HTML. Ogni sito sceglie quando il tag chiede il suo primo annuncio:

E mentre l'annuncio è in arrivo lo spazio non resta bianco: il tag disegna un segnaposto, e impara l'altezza — la prima visita riserva una misura prudente, e dalla seconda lo spazio riservato è quello esatto, così la pagina non salta quando l'annuncio atterra. Quel salto è ciò che Google misura come layout shift, ed è il motivo abituale per cui una rete pubblicitaria costa a un sito il suo punteggio.

Il tag

Incollalo dove deve apparire l'annuncio — oppure lascia che sia la zona a dire dove va e salta del tutto questo passaggio (vedi «Dove esce l'annuncio», più sotto). L'id della zona viene dal pannello (Siti e zone). Lo stesso tag serve tutti i formati che la zona accetta; una zona interstiziale usa anche il tag standard.

Standard (un div e uno script, asincrono):

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

Legacy, per i CMS che non eseguono script asincroni:

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

Link testuale: una URL che conta l'impression e reindirizza all'inserzionista:

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

Il tag si aggiorna da solo: la sua URL non porta versione e non cambia mai, quindi un miglioramento nostro arriva a tutti i siti in circa 60 minuti e nessuno modifica un template (oggi serve v11, nell'header x-tag-version). Aspetta che la tua pagina finisca di caricare prima di chiedere qualsiasi cosa, così gli annunci non competono mai con i tuoi contenuti. Le sue uniche tracce nella tua pagina sono l'attributo data-fh-ad e l'id dell'overlay — verificati contro le liste di blocco più diffuse, con zero corrispondenze. I limiti di frequenza usano un cookie proprietario.

Se la stessa posizione si ripete lungo una pagina — “ogni N messaggi” in un forum, per esempio — il tag chiede tutte le sue copie in una sola richiesta (fino a 10), e il tetto di frequenza avanza dentro quel lotto, così una creatività non può riempire tutti gli spazi della pagina. Se il nostro lato non capisce il lotto, il tag ripiega su uno spazio alla volta invece di lasciare la pagina vuota. Ripetere una zona si dichiara con noi: di regola, una zona per posizione, perché la zona è ciò per cui un report raggruppa.

Dove esce l'annuncio — senza toccare il tuo tema

Una zona può dichiarare dove va: un selettore CSS (fino a 300 caratteri) e una posizione rispetto a ciò che quel selettore trova. Lo spazio lo crea il tag, quindi spostare un annuncio costa una modifica nel pannello e non una modifica del tuo tema.

Due numeri facoltativi governano la ripetizione: uno colloca lo spazio ogni N corrispondenze (fino a 50) e un tetto limita quanti spazi si creano — 4 per impostazione predefinita quando si ripete, 20 al massimo. C'è sempre un tetto: un selettore sciolto come p corrisponde centinaia di volte in un articolo lungo, e quel limite non può dipendere dal fatto che chi configura si ricordi di metterlo.

Due cose da sapere. Un div data-fh-ad che metti tu stesso nel tema comanda: il tag non aggiungerà un secondo spazio per quella zona, così puoi passare da un metodo all'altro senza pagare due impression per una. E un selettore che non corrisponde a nulla non dà errore — la pagina si vede benissimo senza l'annuncio e il pannello resta verde. Controlla la collocazione in un browser, su desktop e su telefono: un selettore può esistere nell'articolo e non in home, o misurare 1360 px su desktop e 0 su telefono.

WordPress: niente da incollare

Se il tuo sito è WordPress c'è un plugin, forhosting-ad. Lo installi e si presenta da solo: pubblica una sfida sul tuo stesso dominio, noi la leggiamo, e la credenziale viene consegnata una volta sola. Non digiti nessuna chiave, nessun id e nessun token — e dimostrare che controlli il dominio non è la stessa cosa che essere invitato: non si emette nulla finché il sito non viene approvato.

Da lì in poi le zone si gestiscono dal pannello, collocazione compresa. Il plugin chiede inoltre alla cache di pagina che il tuo sito usa di svuotare le pagine il cui markup è cambiato — riconosce quelle abituali e lo chiede a ciascuna a modo suo. Una pagina in cache è il motivo più comune per cui il tag è nel tuo HTML e l'annuncio ancora non è sullo schermo, e da riga di comando non si vede: la copia vecchia viene servita solo a un browser vero.

C'è un secondo plugin, forhosting-ad-updater, che riceve un pacchetto e lo installa. È per progetto un canale di esecuzione remota, quindi lo installiamo solo su siti nostri; sul tuo, gli aggiornamenti arrivano dal canale nativo di WordPress e decidi tu quando applicarli.

Pagamenti

La tua quota del 80% su ogni ordine pagato si accumula nel pannello (Pagamenti). Quando l'accumulato raggiunge $10, richiedi il pagamento con il metodo del tuo profilo (paypal, bank, other); il nostro staff paga fuori dal pannello e registra il riferimento.

Stati: accrued → requested → processing → paid; un versamento fallito torna a te con il motivo, così puoi richiederlo di nuovo con i dati corretti.

Per tutti

Report

Impression, clic e inizio/fine video vengono contati al bordo, a ogni richiesta. Prima di contare, il traffico viene filtrato: crawler noti dallo user agent, reti di data center, richieste con un punteggio bot molto basso e qualsiasi IP che ripeta la stessa richiesta entro 2 secondi. Una richiesta filtrata riceve comunque il suo annuncio o il suo redirect — si protegge solo il contatore.

Ogni 5 minuti i conteggi vengono consolidati in righe giornaliere per creatività, zona e host del referrer. Il giorno in corso può avere fino a quel ritardo; i giorni chiusi non cambiano mai.

Il pannello (Report) mostra totali e una serie giornaliera, il CTR (clic ÷ impression × 100) e l'eCPM (valore erogato × 1000 ÷ impression), per il lato inserzionista o il lato publisher, e una classifica raggruppata per una qualsiasi di sei dimensioni:

Ognuna di queste viste si può anche filtrare per campagna, creatività, zona, host del referrer o destinazione, e gli stessi numeri sono disponibili tramite l'API.

Prima di contare qualsiasi cosa, il traffico passa dal filtro anti-bot, che la casa fa girare in una di tre modalità: block (quella predefinita: le richieste filtrate ricevono comunque il loro annuncio, semplicemente non contano), log (contano e vengono registrate a parte, per misurare prima di decidere) e off.

Integrare

Riferimento dell'API

URL base https://api.ad.forhosting.com. Invia la tua chiave come token Bearer; corpi e risposte sono JSON. Ogni risposta ha la forma {"success":true,"data":…} oppure {"success":false,"error":{"code","message"}} con lo stato HTTP corrispondente.

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

Ambiti delle credenziali

Una credenziale tenant, read o session opera sempre sul proprio account — un tenantId inviato dal client viene ignorato. Un id che appartiene a qualcun altro restituisce 404, non 403: l'API non conferma mai che esista.

Rotte

Tutte le rotte che il servizio annuncia, con l'ambito che il router richiede — derivato dal router stesso a ogni build.

pubblica: senza credenziale — il percorso di erogazione · qualsiasi: qualsiasi credenziale valida, sul proprio account · lettura: tenant, session o read · scrittura: tenant o session (read viene rifiutato) · system: solo la casa

Errori da conoscere: 401 unauthorized (credenziale assente o scaduta), 403 forbidden (l'ambito non può farlo), 404 not_found, 400 bad_request con il motivo nel messaggio, 409 conflict (una transizione di stato non permessa), 402 insufficient_balance nel pagare un ordine, e 503 payments_disabled se le vendite sono in pausa.

FAQ

Domande tecniche