universal-ad-loader 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# 0.1.0
+
+Prima versione.
+
+**Novità**
+- Loader da servire con un tag `<script>` (`dist/ual.min.js`): slot, configurazione JSON centralizzata,
+  lazy load, waterfall tra provider, consenso IAB TCF, render in iframe isolato, viewability ed eventi.
+- Adapter: `json`, `iframe`, `revive`, `revive-async`, `gpt`, `adsense`, `house`.
+- Nucleo come libreria (ESM e CJS), sicuro da importare sul server: `createUal`, `getUal`, `defineConfig`.
+- Componenti per React, Next.js, Vue e Astro, che avviano UAL dopo l'idratazione e gestiscono il cambio pagina.
+- Tipi TypeScript e JSON Schema della configurazione.
+
+**Da sapere**
+- `adsense`, `revive-async` e `gpt` sono scritti sulle API pubbliche ma non provati su account reali.
+- Nuxt, Remix e React Router non sono stati provati.
+- Con una CSP rigida i banner compaiono ma `UALExt` e il click tracciato non funzionano senza `'unsafe-inline'`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ArdensLab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,209 @@
-# Temporary Holding Version
+# UAL — Universal Ad Loader
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Un solo tag per sito. Gestisce slot, configurazione centralizzata, consenso TCF, lazy load, waterfall tra provider (adapter), render in sandbox, viewability ed eventi. ~10 KB gzip.
+
+## Installazione su un sito
+
+```html
+<script async src="https://adcdn.tuodominio.net/ual.min.js"
+        data-config="https://adcdn.tuodominio.net/config/site_123.json"></script>
+
+<div data-ad-slot="top"></div>
+<div data-ad-slot="sidebar" data-ad-params='{"zone":7}'></div>
+```
+
+- `data-ad-slot` è il nome dello slot in configurazione. Lo stesso nome può comparire più volte (es. in-feed).
+- `data-ad-params` (opzionale) sovrascrive i `params` del provider per quell'istanza.
+- I div aggiunti dopo (SPA, infinite scroll) vengono rilevati da soli. Al cambio di route chiama `ual.pageView()`.
+
+> **Cosa caricare sulla CDN:** il loader (`dist/ual.min.js`) e un JSON di configurazione per sito, con gli header giusti: vedi `docs/cdn.md`.
+
+## Configurazione (JSON servito da CDN)
+
+Vedi `examples/site_demo.json`. Campi principali:
+
+| Campo | Descrizione |
+|---|---|
+| `site` | ID del sito, inviato agli adapter |
+| `consent` | `{ mode:'tcf'\|'none', timeoutMs, requiredPurposes:[1], vendorId }` |
+| `lazy` | `{ enabled, fetchMargin:'200px' }`. Lo slot viene richiesto quando arriva a quella distanza dal viewport |
+| `viewability` | `{ threshold:0.5, durationMs:1000 }` (standard MRC) |
+| `collapseEmpty` | nasconde lo slot se nessun provider lo riempie |
+| `providerTimeoutMs` | timeout di default per provider |
+| `targeting` | key-value di pagina inviati a tutti gli adapter |
+| `providers` | `{ id: { adapter:'json'\|'iframe'\|'revive'\|'revive-async'\|'gpt'\|'adsense'\|'house', consent:'optional'\|'required'\|'contextual', timeoutMs, ...opzioni adapter } }` |
+| `slots` | `{ nome: { sizes \| sizeMapping, providers:[...waterfall], label, minHeight, lazy, collapseEmpty, refreshSec, maxRefresh, enabled } }` |
+| `pageRules` | `[{ match:'^/on-air', disable:[...], enable:[...], targeting:{}, slots:{ override } }]` |
+
+**Waterfall**: `providers` di uno slot è una lista ordinata (`"house"` oppure `{ "id":"main", "params":{...} }`). Se il primo non riempie, si passa al successivo. Per ogni livello, gli slot pronti insieme vengono raggruppati in **una sola richiesta per provider**.
+
+**Consenso per provider** (`providers.X.consent`):
+
+| Valore | Comportamento |
+|---|---|
+| `optional` (default) | Aspetta la risposta della CMP (max `consent.timeoutMs`) e riceve il consenso così com'è |
+| `required` | Come `optional`, ma se il consenso non c'è il provider viene **saltato** e si passa al livello successivo (es. un fallback house contestuale) |
+| `contextual` | **Non aspetta la CMP**: parte subito e riceve il consenso noto in quel momento (spesso `granted:false`). Per richieste contestuali senza cookie né ID |
+
+Il consenso viene seguito per tutta la vita della pagina: se la CMP compare in ritardo (fino a `consent.lateWatchMs`, default 30 s) o l'utente cambia scelta, UAL emette l'evento `consent` e, quando si passa a `granted:true`, ricarica gli slot che avevano saltato un provider `required`.
+
+## Adapter inclusi
+
+| Adapter | Uso | Rileva il vuoto? |
+|---|---|---|
+| `json` | Il tuo ad server: POST batch su `endpoint` (contratto sotto) | Sì |
+| `iframe` | Qualsiasi URL che restituisce il banner (`work.php?n=..&size=..`) con template `{params.x}`, `{width}`, `{cb}`… | No (considerato pieno) |
+| `revive` | Revive Adserver via `afr.php` (iframe) | No |
+| `revive-async` | Revive via `asyncjs.php` + `<ins>` | Sì (osserva il DOM) |
+| `gpt` | Google Ad Manager, SRA con `disableInitialLoad` + `refresh` | Sì (`slotRenderEnded`) |
+| `adsense` | AdSense come backfill | Sì (`data-ad-status`) |
+| `house` | Creatività in config, scelta pesata per slot/dispositivo/date | Sì |
+
+### Contratto dell'adapter `json`
+
+Richiesta `POST {endpoint}`:
+```json
+{
+  "site": "site_123",
+  "page": { "url": "...", "path": "/", "ref": "...", "title": "..." },
+  "device": "desktop", "viewport": { "w": 1280, "h": 900 },
+  "targeting": { "section": "onair" },
+  "consent": { "gdprApplies": true, "tcString": "...", "granted": true },
+  "slots": [ { "id": "top#1", "name": "top", "sizes": [[728,90]], "params": { "zone": 1 } } ]
+}
+```
+Risposta (200 oppure 204 se vuota):
+```json
+{ "ads": [ {
+  "slotId": "top#1", "type": "image", "src": "https://cdn/.../b.webp",
+  "width": 728, "height": 90, "clickUrl": "https://ads/c?t=SIGNED",
+  "trackers": { "impression": ["https://ads/i?t=..."], "viewable": ["https://ads/v?t=..."], "click": [] }
+} ] }
+```
+`type`: `image` (src + clickUrl), `html` (markup, `clickTag` disponibile), `url` (iframe esterno). Gli slot senza voce passano al provider successivo.
+
+## Render e API per le creatività
+
+Le creatività `image`/`html` girano in un iframe `srcdoc` con sandbox **senza** `allow-same-origin` (origine opaca): non possono leggere la pagina, i cookie o il DOM del sito. Dentro l'iframe sono disponibili:
+
+```js
+clickTag                   // = clickUrl
+UALExt.click()             // traccia il click e apre clickTag
+UALExt.expand(728, 300)    // ridimensiona (max 2000px)
+UALExt.collapse()          // torna alla dimensione originale
+UALExt.close()             // chiude e nasconde lo slot
+```
+I messaggi vengono accettati solo dall'iframe dello slot (controllo su `event.source`).
+
+**Validazione delle creatività.** Ogni annuncio ricevuto da un adapter passa da un controllo prima del render; se non è valido viene scartato (log + evento `error`) e si passa al provider successivo:
+
+- `width` e `height` obbligatori, interi tra 1 e 2000.
+- `src` (image), `url` (url), `clickUrl` e tutti i `trackers`: solo `http:`/`https:` (per `src` anche `data:image/`). Niente `javascript:`.
+- Sandbox: mai `allow-same-origin` per `image`/`html`; mai `allow-top-navigation` (la creatività non può reindirizzare la pagina; i link `target=_blank` aprono un popup). Per `type:'url'` `allow-same-origin` resta (serve ai server legacy) **solo se l'URL è di un'altra origine** della pagina; se è della stessa origine viene tolto. L'override `sandbox` di una creatività è filtrato con le stesse regole.
+
+## API JavaScript
+
+```js
+window.ual = window.ual || { cmd: [] };
+ual.cmd.push(function (u) {
+  u.on('slotRendered', (e) => console.log(e.slot, e.provider, e.width, e.height));
+  u.on('slotEmpty', (e) => {});
+  u.on('slotViewable', (e) => {});
+  u.on('slotClick', (e) => {});
+  u.on('error', (e) => {});
+  u.setTargeting({ author: 'mario' });
+});
+// Senza data-config: ual.cmd.push(u => u.init({ ...config }))  oppure  u.init('https://.../site.json')
+ual.refresh(['top']);   // ricarica slot (tutti se senza argomenti)
+ual.pageView();         // SPA: nuova pagina
+ual.getSlots(); ual.getConsent();
+ual.isInitialized();    // true se init è già stato avviato (anche se non ancora finito)
+ual.whenReady();        // la promessa dell'init, o null se mai avviato
+```
+`setTargeting` funziona anche prima dell'init (dentro `ual.cmd.push`), resta valido dopo `pageView()` e un valore `null` rimuove la chiave. Il targeting delle `pageRules` viene ricalcolato a ogni pagina. L'adapter `gpt` lo riapplica a ogni richiesta e toglie le chiavi non più presenti.
+
+L'attributo sullo script può chiamarsi `data-config` o `data-ual-config` (è equivalente; il secondo si legge anche se lo script è stato inserito dinamicamente da un framework).
+
+Debug: `?ual_debug=1` nell'URL, oppure `localStorage.ual_debug = '1'`.
+
+## Con Astro, Next.js, React, Vue e Node
+
+UAL è uno script del browser (non gira in Node). Per i siti con una build c'è anche il **pacchetto**: import sicuro sul server, componenti per React, Next.js, Vue e Astro, tipi TypeScript (`defineConfig`). Vedi `docs/libreria.md`. **Il pacchetto `universal-ad-loader` non è ancora pubblicato su npm** (vedi `docs/pubblicazione-npm.md`): per ora si installa dal tarball di `npm pack`.
+
+```tsx
+import { UalProvider, AdSlot } from 'universal-ad-loader/next';   // o /react, /vue; per Astro i file in astro/
+
+<UalProvider config={config}>   {/* parte dopo l'idratazione, gestisce il cambio pagina */}
+  <AdSlot name="top" minHeight={90} />
+</UalProvider>
+```
+
+Se usi invece il tag con un framework, cose verificate con un'app React server-rendered:
+
+- **Carica il loader dopo l'idratazione** (`next/script` con `strategy="afterInteractive"`, o un `useEffect`). Se parte prima, UAL inserisce il banner nel `div` prima che React si attacchi: errore *Hydration failed* (anche con `suppressHydrationWarning`) e banner richiesto due volte. I componenti lo evitano da soli.
+- **Cambio pagina lato client:** gli slot nuovi si registrano da soli, ma `pageRules` e targeting si ricalcolano solo con `ual.pageView()`.
+- **Non importare `dist/ual.js` in codice server:** usa `window` al caricamento (`ReferenceError` in Node). Il nucleo del pacchetto (`dist/index.*`) invece è sicuro.
+- **CSP rigida:** le creatività ereditano la CSP della pagina. Provato: senza `'unsafe-inline'` per script e stili il banner compare ma `UALExt` e il click tracciato non funzionano; con nonce e `'strict-dynamic'` nemmeno.
+
+Guida con esempi e tabella CSP: configuratore, pagina `/docs/`.
+
+## Altri documenti
+
+- `docs/esempio.md`: sito cliente completo (config, flusso, endpoint `decide` minimo).
+- `docs/pubblicazione-npm.md`: come pubblicare il pacchetto su npm (CI GitLab con il branch `deploy-npm`, token, mirror GitHub, rilasci).
+- `docs/cdn.md`: **quali file mettere sulla CDN** (loader e configurazione), header, struttura, cosa non serve e come aggiornare.
+- `docs/libreria.md`: UAL come pacchetto (componenti React/Next/Vue/Astro, tipi, nucleo sicuro sul server, come è verificato).
+- `docs/ad-server-esistenti.md`: come collegare AdManager, Banner Exchange Pro, Banner Exchange e i PHP legacy con l'adapter `iframe`, con limiti e verifiche.
+- `schema/ual-config.schema.json`: JSON Schema della configurazione.
+- Il configuratore web (`../ual-configurator`) ha una guida HTML con esempi apribili nell'editor.
+
+## Adapter custom
+
+```js
+ual.cmd.push(u => u.registerAdapter('mioserver', {
+  init(providerCfg, ctx) {},                       // opzionale, una volta per provider
+  // A) l'adapter restituisce gli annunci e UAL li rende in sandbox:
+  async request(slots, providerCfg, ctx) {         // slots: [{id,name,sizes,params,el}]
+    return { [slots[0].id]: { type:'image', src:'...', width:300, height:250, clickUrl:'...' } };
+  },
+  // B) oppure l'adapter rende da solo dentro slot.el:
+  // async fill(slots, providerCfg, ctx) { return { [id]: { filled:true, width, height } } },
+  destroy(slot, providerCfg) {},                   // opzionale
+}));
+```
+`ctx` contiene `site, page, device, viewport, targeting, consent`. Per registrare un adapter custom prima dell'init automatico, metti `ual.cmd.push(...)` **prima** del tag del loader.
+
+## Build e test
+
+```bash
+npm ci                          # dipendenze di base (~120 MB)
+npm ci --prefix test/heavy      # solo per i test dei framework: Next.js e Astro (~620 MB)
+npx playwright install chromium # una tantum, per i test in browser
+npm test                        # build + tutte le suite, circa 2 minuti
+```
+
+Per lavorare per parti (è lo stesso che fa la CI, in job paralleli):
+
+| Comando | Cosa esegue | Serve |
+|---|---|---|
+| `npm run lint` | oxlint sui sorgenti | solo le dipendenze di base |
+| `npm run test:node` | `test/package.mjs` | solo le dipendenze di base (nessun browser) |
+| `npm run test:browser` | `test/run.mjs` e `test/regression.mjs` | + Chromium |
+| `npm run test:frameworks` | `test/wrappers.mjs` | + `test/heavy` e Chromium |
+
+Ogni suite scrive anche un report JUnit in `test-results/` (la CI lo mostra nella scheda Tests).
+
+| Suite | Cosa verifica |
+|---|---|
+| `test/run.mjs` | e2e del loader con ad server finto e CMP finta: batch per provider, waterfall verso house, lazy load, `sizeMapping`, consenso, `pageRules`, tracker, expand, sandbox |
+| `test/regression.mjs` | sicurezza del render, `setTargeting`, CMP in ritardo, provider `contextual`, slot spostati/chiusi nel DOM, refresh, `pageView`, adapter `gpt` (con uno stub di `googletag`), adapter `iframe` con i sistemi esistenti |
+| `test/package.mjs` | il pacchetto: import in Node (ESM e CJS) senza `window`, rendering sul server di React e Vue, mappa `exports`, contenuto del tarball (`npm pack`), tipi (usi corretti compilano, quelli errati danno errore) |
+| `test/wrappers.mjs` | i componenti in un browser vero, con rendering sul server e idratazione ritardata: React (nel bundle, da CDN, versione Next), Vue, **Next.js 16** (App Router, build di produzione) e **Astro 7** (View Transitions); più un controllo che dimostra il problema che i componenti evitano |
+
+Gli adapter `adsense` e `revive-async` sono scritti sulle API pubbliche ma non sono testati: vanno provati sui tuoi account e server. Anche `gpt` va provato con Google Ad Manager reale: lo stub verifica la logica di UAL, non il comportamento di GPT. Non sono stati eseguiti Nuxt, Remix e React Router.
+
+## Note
+
+- **Consenso**: su siti di clienti il tuo ad server è un fornitore terzo. Senza consenso, invia solo richieste contestuali (niente cookie né ID). `vendorId` serve se il tuo server è registrato nella GVL IAB. Fai verificare l'impostazione privacy a un legale.
+- **Refresh automatico** (`refreshSec`): solo se lo slot è a schermo e la tab è visibile. GPT e AdSense hanno policy proprie sul refresh.
+- **CLS**: usa `minHeight` sugli slot sopra la piega.

package/astro/AdSlot.astro

@@ -0,0 +1,23 @@
+---
+// Una posizione pubblicitaria: un div vuoto che UAL riempie.
+// <AdSlot name="top" minHeight={90} params={{ zona: 7 }} />
+interface Props {
+  /** Nome dello slot in configurazione (data-ad-slot). */
+  name: string;
+  /** Sovrascrive i `params` del provider per questa istanza. */
+  params?: Record<string, unknown>;
+  /** Riserva lo spazio già nell'HTML (evita salti di layout). */
+  minHeight?: number;
+  class?: string;
+  id?: string;
+}
+const { name, params, minHeight, class: className, id } = Astro.props;
+---
+
+<div
+  data-ad-slot={name}
+  data-ad-params={params ? JSON.stringify(params) : undefined}
+  id={id}
+  class={className}
+  style={minHeight ? `min-height:${minHeight}px` : undefined}
+></div>

package/astro/UalBundled.astro

@@ -0,0 +1,34 @@
+---
+// Carica UAL incluso nel bundle del sito (nessuna CDN per il loader), con la configurazione nella pagina.
+//   <UalBundled config={{ site: '…', providers: {…}, slots: {…} }} />
+//   <UalBundled config="/config/sito.json" />
+// Per caricare il loader da una CDN usa invece UalLoader.
+// La configurazione sta in un blocco JSON (non eseguito, quindi compatibile con una CSP rigida).
+import type { UalConfig } from '../dist/index';
+
+interface Props {
+  /** La configurazione, oppure l'URL del JSON. */
+  config: UalConfig | string;
+}
+const { config } = Astro.props;
+const data = JSON.stringify(config).replace(/</g, '\\u003c');
+---
+
+<script type="application/json" data-ual-config set:html={data}></script>
+<script>
+  import { getUal } from '../dist/index.mjs';
+
+  const el = document.querySelector('script[data-ual-config]');
+  if (el && el.textContent) {
+    const ual = getUal();
+    if (!ual.isInitialized()) {
+      ual.init(JSON.parse(el.textContent)).catch((e) => console.warn('[UAL]', e && e.message ? e.message : e));
+    }
+    // View Transitions: il primo astro:page-load è il caricamento iniziale, gli altri sono navigazioni
+    let first = true;
+    document.addEventListener('astro:page-load', () => {
+      if (first) { first = false; return; }
+      ual.pageView();
+    });
+  }
+</script>

package/astro/UalLoader.astro

@@ -0,0 +1,40 @@
+---
+// Carica UAL in una pagina Astro con il loader servito da una CDN (aggiornabile senza rideploy del sito).
+//   <UalLoader src="https://cdn.tuodominio.net/ual.min.js" config="https://cdn.tuodominio.net/config/sito.json" />
+//   <UalLoader src="…/ual.min.js" config={{ site: '…', providers: {…}, slots: {…} }} />
+// Per includere UAL nel bundle del sito usa invece UalBundled.
+// Con le View Transitions (ClientRouter) ricalcola le regole per pagina a ogni navigazione.
+import type { UalConfig } from '../dist/index';
+
+interface Props {
+  /** URL del loader (ual.min.js). */
+  src: string;
+  /** URL del JSON di configurazione, oppure la configurazione stessa. */
+  config: UalConfig | string;
+}
+const { src, config } = Astro.props;
+const isUrl = typeof config === 'string';
+// "<" escapato: i dati non possono chiudere lo script
+const data = JSON.stringify(config).replace(/</g, '\\u003c');
+const init = `window.ual=window.ual||{cmd:[]};window.ual.cmd.push(function(u){u.init(${data})});`;
+---
+
+{isUrl
+  ? <script is:inline async src={src} data-ual-config={config as string}></script>
+  : (
+    <Fragment>
+      <script is:inline set:html={init}></script>
+      <script is:inline async src={src}></script>
+    </Fragment>
+  )}
+<script is:inline>
+  (function () {
+    // Il primo astro:page-load coincide con il caricamento iniziale: lì UAL parte da solo
+    var first = true;
+    document.addEventListener('astro:page-load', function () {
+      if (first) { first = false; return; }
+      var ual = window.ual;
+      if (ual && ual.cmd && typeof ual.cmd.push === 'function') ual.cmd.push(function (u) { u.pageView(); });
+    });
+  })();
+</script>

package/dist/global.d.ts

@@ -0,0 +1,13 @@
+// Tipi opzionali per chi usa il tag <script> (window.ual): import 'universal-ad-loader/global';
+// Sono in un file a parte perché dichiarano una proprietà globale di Window, che potrebbe
+// confliggere con una dichiarazione già presente nel progetto.
+import type { Ual } from './index';
+
+declare global {
+  interface Window {
+    /** Prima del caricamento del loader è solo la coda dei comandi; dopo è l'API completa. */
+    ual?: (Partial<Ual> & { cmd: { push(fn: (u: Ual) => void): void } | Array<(u: Ual) => void> });
+  }
+}
+
+export {};