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, la metti in pausa o la chiudi. Vengono erogate solo le creatività attive di una campagna attiva — mettere in pausa la campagna ferma subito l'erogazione.

Tra le creatività eleggibili il motore sceglie a caso, ponderando con il peso che dai a ciascuna. Una creatività con un limite di erogazione ha 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.

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 una persona lo verifica prima che le sue zone possano vendere — un dominio non verificato non può incassare la quota. Ritirare un sito avvia un raffreddamento di 90 giorni sul dominio: nel frattempo nessun altro può registrarlo ed ereditarne la storia.

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). Una zona interstitial dichiara anche quali link attivano l'overlay — di default p a, nav a, h2 a — e i secondi prima di poterlo chiudere.

Il tag

Incollalo dove deve apparire l'annuncio. L'id della zona è nel pannello (Siti e zone). Lo stesso tag eroga tutti i formati che la zona accetta; una zona interstitial usa anch'essa 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 undefined minuti e nessuno modifica un template (oggi serve v6, 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.

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 per creatività, zona, campagna, sito o host del referrer. Si conserva solo l'host del referrer, mai la URL.

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