Documentazione

Manuale operativo

Versione plugin: 3.0.3 (Responsive Update) · Aggiornato: Gennaio 2026

Scarica il plugin Avvio rapido →

⚡ Avvio rapido (15 minuti)

Obiettivo: andare live con uno o più spazi banner, con rotazione e statistiche attive, senza impatti negativi su cache e mobile.

  1. Installa e attiva il plugin: Plugin → Aggiungi nuovo → Carica.
  2. Vai in HubBanner → Impostazioni → Dimensioni Banner e abilita solo le dimensioni realmente usate.
  3. Vai in HubBanner → Siti e crea il sito (nome + URL) impostando il pattern categoria (es. /category/{parent}/{slug}/).
  4. Nel sito appena creato, importa o sincronizza le categorie WordPress.
  5. Vai in HubBanner → Spazi → Aggiungi spazio: scegli sito, dimensione e descrizione.
  6. Apri lo spazio e copia il codice JavaScript (modalità consigliata). Incollalo nel tema.
  7. Vai in HubBanner → Banner → Aggiungi banner: carica immagine, URL, dimensione, attiva e assegna allo spazio.
  8. Apri una pagina del sito e verifica che il banner compaia. Controlla poi le statistiche.
Se usi cache o CDN: assicurati che gli endpoint REST del plugin non vengano cachati e che JavaScript sia servito correttamente. Vedi sezione Integrazione.

1. Panoramica

A cosa serve

HubBanner è un plugin WordPress per gestire spazi pubblicitari e banner con rotazione, targeting contestuale e tracciamento (impressioni, click, CTR). L'obiettivo è ridurre l'operatività manuale e aumentare la qualità del delivery con posizionamento coerente con il contesto e KPI misurabili.

Casi d'uso tipici

  • Vendita diretta di spazi (header, sidebar, in-article) con rotazione di più creatività.
  • Campagne per categorie specifiche (es. solo "Sport" o "Motori") con priorità rispetto ai banner globali.
  • Campagne per tag o per URL/pattern (es. landing page).
  • Gestione multi-sito logica: più proprietà editoriali da un unico WordPress.
  • Delivery compatibile con cache e CDN tramite REST API + JavaScript.

Architettura in breve

HubBanner introduce due entità principali: Spazio pubblicitario (contenitore posizionale) e Banner (creatività assegnata a uno o più spazi). Il targeting è gestito a livello banner, con logica di priorità: prima i banner mirati, poi il fallback "sito intero".

2. Concetti chiave

Siti (multi-sito logico)

Il plugin consente di gestire più "siti" come contenitori logici: ciascun sito ha un nome, un URL e un pattern per estrarre la categoria dall'URL. Non richiede WordPress Multisite: è un livello organizzativo interno al plugin.

Categorie per sito

Le categorie HubBanner possono essere importate dalle categorie WordPress. Servono per il targeting e per mantenere consistenza anche con categorie gerarchiche.

Dimensioni

Le dimensioni disponibili sono gestite da una lista (IAB standard + custom). Abilitare solo quelle necessarie riduce errori operativi e aumenta la governabilità.

Targeting

Ogni banner può essere configurato in una delle modalità:

  • All: il banner può apparire ovunque (fallback).
  • Specific: solo nelle categorie selezionate (inclusi i figli).
  • Tags: solo quando sulla pagina sono presenti tag corrispondenti.
  • URLs: solo su URL che contengono uno dei pattern inseriti.
Logica di priorità: se in uno spazio esistono banner mirati che matchano la pagina corrente, questi hanno priorità e vengono mostrati a rotazione. In assenza di match, vengono mostrati i banner "All".

3. Requisiti e compatibilità

  • WordPress: versione recente (consigliato sempre aggiornato).
  • PHP: versione recente supportata da WordPress.
  • Permessi: ruolo Amministratore per configurazione; Editor/Marketing per gestione banner.
  • REST API WordPress attiva e raggiungibile.
  • Compatibile con cache e CDN (es. Cloudflare) con esclusione degli endpoint dinamici.
  • Ambienti consigliati: staging per test prima del go-live; backup prima degli aggiornamenti major.

4. Installazione

  1. Scarica il file ZIP del plugin.
  2. In WordPress: Plugin → Aggiungi nuovo → Carica plugin → Seleziona ZIP → Installa ora.
  3. Attiva il plugin.
  4. Verifica che compaia il menu HubBanner in Bacheca.
  5. Apri HubBanner → Impostazioni → Info per verificare la versione installata.
Se la UI non appare correttamente, svuota la cache del browser e la cache del sito (plugin cache/CDN).

5. Configurazione iniziale

Impostazioni generali

Percorso: HubBanner → Impostazioni → Generali

  • Abilita statistiche: attiva/disattiva il tracciamento impressioni e click.
  • Conservazione dati: definisce la retention dei dati statistici (es. 90 giorni).

Dimensioni banner

Percorso: HubBanner → Impostazioni → Dimensioni Banner

Seleziona le dimensioni IAB supportate (es. 728x90, 300x250, 160x600) e aggiungi dimensioni custom se necessario. Best practice: standardizza i formati venduti.

Siti e pattern URL

Percorso: HubBanner → Siti → Aggiungi sito

Definisci nome, URL del sito e pattern categorie. Il pattern deve riflettere la struttura permalink reale:

/category/{parent}/{slug}/   → gerarchico (consigliato)
/category/{slug}/            → senza sottocategorie
/{slug}/                     → routing personalizzato
Se il pattern è errato, il targeting per categorie non matcha correttamente.

Categorie del sito

All'interno della scheda del sito puoi importare o sincronizzare le categorie WordPress. Usa "Sincronizza" se le categorie cambiano nel tempo.

6. Gestione degli spazi pubblicitari

Creazione di uno spazio

Percorso: HubBanner → Spazi → Aggiungi spazio

Definisci titolo, sito di appartenenza, dimensione e descrizione. Gli spazi sono contenitori posizionali: la logica di selezione dipende dai banner assegnati e dal loro targeting.

Codice di integrazione

Nella meta box "Codice integrazione" lo spazio fornisce 3 modalità:

  • JavaScript (raccomandato): compatibile con cache/CDN. Rotazione lato client.
  • PHP: utile per inserimento diretto nel tema o template (server-side).
  • IFrame: non raccomandato (problemi SEO e responsive).

8. Integrazione sul sito

Inserimento nel tema WordPress

Canali tipici: widget/blocco HTML, area "Ads" del tema, o direttamente nei file template (preferibile con child theme).

Modalità data-attributes

Per inserire più spazi con un unico include JavaScript:

<div id="hubbanner-space-123"
     data-hubbanner-space="123"
     data-hubbanner-pattern="/category/{parent}/{slug}/"
     data-hubbanner-api="https://www.tuodominio.com/wp-json/hubbanner/v1">
</div>

<script src=".../hubbanner/assets/js/hubbanner-public.js"></script>

Cache, CDN e performance

  • Escludi dal caching gli endpoint: /wp-json/hubbanner/v1/*
  • Whitelista le route REST HubBanner nei plugin di sicurezza.
  • Controlla in console browser che le chiamate API ritornino 200 e JSON valido.
Il plugin imposta header no-cache sulle risposte API, ma alcuni layer di cache possono ignorarli. Valida sempre in produzione con modalità di navigazione anonima.

9. Statistiche e KPI

Metriche disponibili

  • Impressioni: numero di visualizzazioni registrate.
  • Click: numero di click registrati (tracking client-side).
  • CTR: Click / Impressioni (percentuale).

Dove si consultano

HubBanner → Statistiche: dashboard per periodo (7/30/90/365 giorni). Meta box "Statistiche" nella pagina del singolo banner per lettura rapida.

Data retention e pulizia

Imposta una retention coerente (es. 90 giorni) ed esegui periodicamente la pulizia dal tab Manutenzione DB. Definisci una routine mensile di "data hygiene".

10. Governance, sicurezza e privacy

Ruoli e processo

  • Amministratore: setup, siti, dimensioni, integrazione, policy cache/CDN.
  • Marketing/Trafficking: creazione banner, targeting, pianificazione, analisi KPI.
  • IT/DevOps: monitoraggio performance REST, log, sicurezza, backup.

Dati raccolti e GDPR

Con statistiche attive, il plugin registra eventi di impression e click e può memorizzare informazioni tecniche (IP, user-agent, referrer). Questi dati rientrano nel perimetro GDPR.

  • Aggiorna informativa privacy/cookie includendo la finalità pubblicitaria.
  • Riduci la retention se non necessaria.
  • Valuta la disattivazione del tracciamento per siti con policy restrittive.
Per configurazioni avanzate (anonimizzazione IP, consent mode) è opportuno un confronto con il DPO/consulente privacy.

11. Troubleshooting operativo

Banner non si vede

  • Verifica che lo spazio sia pubblicato e abbia banner assegnati.
  • Verifica che almeno un banner sia attivo e le date siano valide.
  • Controlla console browser: errori JavaScript o richieste REST fallite.
  • Verifica che il pattern categorie del sito sia coerente con i permalink.
  • Se c'è targeting "Specific", controlla che la pagina abbia una categoria riconosciuta.

Rotazione non funziona

  • Verifica che ci siano più banner validi nello stesso spazio.
  • Controlla che non ci sia caching del JSON della REST API.
  • Escludi /wp-json/hubbanner/v1/banner/* dal caching.

Statistiche a zero

  • Abilita statistiche in Impostazioni → Generali.
  • Verifica che il browser non blocchi le chiamate di tracking (ad blocker).
  • Controlla che l'endpoint track/impression ritorni GIF 1x1.
  • Verifica che il database non sia in sola lettura.

Responsive problematico

  • Verifica che public.css sia caricato e non sovrascritto dal tema.
  • Svuota cache completa (WP, CDN, browser).
  • Se il contenitore impone larghezze fisse, valuta un wrapper fluid.

12. Note di versione

v3.0.3
Gennaio 2026

Responsive Update

Introduzione del sistema CSS responsive con classi automatiche (hubbanner-large, hubbanner-medium, hubbanner-small) in base alle dimensioni del banner. I formati grandi (es. 728x90) non causano più overflow su dispositivi mobili. Le immagini si adattano con max-width: 100%; height: auto e vengono centrate automaticamente. CSS dedicato in assets/css/public.css.

v3.0.0
2025

Migrazione targeting e meta keys

La linea 3.x adotta meta keys _hubbanner_* e un targeting più strutturato a livello banner, con priorità "mirati" vs "all". Per migrazioni da 2.x è disponibile uno script SQL di conversione meta (da eseguire dopo backup completo di file e database).

Appendice A — Endpoint REST

Gli endpoint principali usati dal frontend:

GET  /wp-json/hubbanner/v1/banner/{space_id}
     → parametri: category, parent, tags, url

GET/POST /wp-json/hubbanner/v1/track/impression
     → banner_id, space_id, category

GET/POST /wp-json/hubbanner/v1/track/click
     → banner_id, space_id
Gli endpoint sono pubblici per consentire il delivery lato client. In ambienti con hardening REST, vanno esplicitamente whitelistati.

Appendice B — Checklist go-live

  • ☐ Dimensioni abilitate coerenti con il listino commerciale.
  • ☐ Sito configurato con URL e pattern corretti; categorie importate/sincronizzate.
  • ☐ Spazi inseriti nei punti corretti del tema; naming standard adottato.
  • ☐ Banner ottimizzati (peso, alt text, URL) e con targeting validato.
  • ☐ Cache/CDN configurata per bypass API HubBanner; test in modalità anonima.
  • ☐ Verifica KPI iniziali (impression/click) e retention definita.
  • ☐ Allineamento privacy: informativa e base giuridica aggiornate.

Pronto ad iniziare?

Scarica HubBanner e segui la guida rapida per essere live in 15 minuti.

Scarica HubBanner Hai bisogno di aiuto?