universal-ad-loader 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# 0.1.1
+
+**Changes**
+- Documentation (README, guides, changelog) translated to English.
+- `engines`: Node 22 or later.
+- `browser`, `jsdelivr` and `unpkg` fields point to `dist/ual.min.js`, so the CDN default file is the loader.
+- The internal publishing guide (`docs/pubblicazione-npm.md`) is no longer included in the package.
+
+# 0.1.0
+
+First release.
+
+**What's new**
+- Loader served with a `<script>` tag (`dist/ual.min.js`): slots, centralized JSON configuration,
+  lazy load, waterfall across providers, IAB TCF consent, isolated iframe rendering, viewability and events.
+- Adapters: `json`, `iframe`, `revive`, `revive-async`, `gpt`, `adsense`, `house`.
+- Core as a library (ESM and CJS), safe to import on the server: `createUal`, `getUal`, `defineConfig`.
+- Components for React, Next.js, Vue and Astro, which start UAL after hydration and handle page changes.
+- TypeScript types and a JSON Schema of the configuration.
+
+**Good to know**
+- `adsense`, `revive-async` and `gpt` are written against the public APIs but have not been tried on real accounts.
+- Nuxt, Remix and React Router have not been tried.
+- With a strict CSP banners show up, but `UALExt` and the tracked click do not work without `'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,208 @@
-# 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.
+One tag per site. It handles slots, centralized configuration, TCF consent, lazy loading, waterfalls across providers (adapters), sandboxed rendering, viewability and events. ~10 KB gzip.
+
+## Installing on a site
+
+```html
+<script async src="https://adcdn.yourdomain.net/ual.min.js"
+        data-config="https://adcdn.yourdomain.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` is the slot name in the configuration. The same name can appear more than once (e.g. in-feed).
+- `data-ad-params` (optional) overrides the provider's `params` for that instance.
+- Divs added later (SPA, infinite scroll) are detected automatically. On a route change, call `ual.pageView()`.
+
+> **What to upload to the CDN:** the loader (`dist/ual.min.js`) and one configuration JSON per site, with the right headers: see `docs/cdn.md`.
+
+## Configuration (JSON served from the CDN)
+
+See `examples/site_demo.json`. Main fields:
+
+| Field | Description |
+|---|---|
+| `site` | Site ID, sent to the adapters |
+| `consent` | `{ mode:'tcf'\|'none', timeoutMs, requiredPurposes:[1], vendorId }` |
+| `lazy` | `{ enabled, fetchMargin:'200px' }`. The slot is requested when it comes within that distance of the viewport |
+| `viewability` | `{ threshold:0.5, durationMs:1000 }` (MRC standard) |
+| `collapseEmpty` | hides the slot if no provider fills it |
+| `providerTimeoutMs` | default timeout per provider |
+| `targeting` | page-level key-values sent to all adapters |
+| `providers` | `{ id: { adapter:'json'\|'iframe'\|'revive'\|'revive-async'\|'gpt'\|'adsense'\|'house', consent:'optional'\|'required'\|'contextual', timeoutMs, ...adapter options } }` |
+| `slots` | `{ name: { sizes \| sizeMapping, providers:[...waterfall], label, minHeight, lazy, collapseEmpty, refreshSec, maxRefresh, enabled } }` |
+| `pageRules` | `[{ match:'^/on-air', disable:[...], enable:[...], targeting:{}, slots:{ override } }]` |
+
+**Waterfall**: a slot's `providers` is an ordered list (`"house"` or `{ "id":"main", "params":{...} }`). If the first one does not fill the slot, the next one is tried. At each level, the slots that become ready together are grouped into **a single request per provider**.
+
+**Consent per provider** (`providers.X.consent`):
+
+| Value | Behavior |
+|---|---|
+| `optional` (default) | Waits for the CMP response (up to `consent.timeoutMs`) and receives the consent as it is |
+| `required` | Like `optional`, but if consent is missing the provider is **skipped** and the next level is tried (e.g. a contextual house fallback) |
+| `contextual` | **Does not wait for the CMP**: starts immediately and receives the consent known at that moment (often `granted:false`). For contextual requests with no cookies or IDs |
+
+Consent is followed for the whole life of the page: if the CMP shows up late (up to `consent.lateWatchMs`, default 30 s) or the user changes their choice, UAL emits the `consent` event and, when it switches to `granted:true`, reloads the slots that had skipped a `required` provider.
+
+## Included adapters
+
+| Adapter | Use | Detects empty? |
+|---|---|---|
+| `json` | Your ad server: batch POST to `endpoint` (contract below) | Yes |
+| `iframe` | Any URL that returns the banner (`work.php?n=..&size=..`) with `{params.x}`, `{width}`, `{cb}`… templates | No (treated as filled) |
+| `revive` | Revive Adserver via `afr.php` (iframe) | No |
+| `revive-async` | Revive via `asyncjs.php` + `<ins>` | Yes (observes the DOM) |
+| `gpt` | Google Ad Manager, SRA with `disableInitialLoad` + `refresh` | Yes (`slotRenderEnded`) |
+| `adsense` | AdSense as backfill | Yes (`data-ad-status`) |
+| `house` | Creatives in the config, weighted pick by slot/device/date | Yes |
+
+### The `json` adapter contract
+
+Request `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 } } ]
+}
+```
+Response (200, or 204 if empty):
+```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` available), `url` (external iframe). Slots with no entry fall through to the next provider.
+
+## Rendering and creative API
+
+`image`/`html` creatives run in a `srcdoc` iframe with a sandbox **without** `allow-same-origin` (opaque origin): they cannot read the page, its cookies or its DOM. Inside the iframe the following are available:
+
+```js
+clickTag                   // = clickUrl
+UALExt.click()             // tracks the click and opens clickTag
+UALExt.expand(728, 300)    // resizes (max 2000px)
+UALExt.collapse()          // back to the original size
+UALExt.close()             // closes and hides the slot
+```
+Messages are accepted only from the slot's own iframe (checked on `event.source`).
+
+**Creative validation.** Every ad received from an adapter goes through a check before rendering; if it is not valid it is discarded (log + `error` event) and the next provider is tried:
+
+- `width` and `height` are required, integers between 1 and 2000.
+- `src` (image), `url` (url), `clickUrl` and all `trackers`: only `http:`/`https:` (and `data:image/` for `src`). No `javascript:`.
+- Sandbox: never `allow-same-origin` for `image`/`html`; never `allow-top-navigation` (a creative cannot redirect the page; `target=_blank` links open a popup). For `type:'url'`, `allow-same-origin` is kept (legacy servers need it) **only if the URL has a different origin from the page**; if it is the same origin it is removed. A creative's `sandbox` override is filtered with the same rules.
+
+## JavaScript API
+
+```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' });
+});
+// Without data-config: ual.cmd.push(u => u.init({ ...config }))  or  u.init('https://.../site.json')
+ual.refresh(['top']);   // reloads slots (all of them if called without arguments)
+ual.pageView();         // SPA: new page
+ual.getSlots(); ual.getConsent();
+ual.isInitialized();    // true if init has already been started (even if not finished yet)
+ual.whenReady();        // the init promise, or null if never started
+```
+`setTargeting` also works before init (inside `ual.cmd.push`), stays valid after `pageView()`, and a `null` value removes the key. The `pageRules` targeting is recomputed on every page. The `gpt` adapter reapplies it on every request and removes keys that are no longer present.
+
+The script attribute can be named `data-config` or `data-ual-config` (equivalent; the second is also read when the script was inserted dynamically by a framework).
+
+Debug: `?ual_debug=1` in the URL, or `localStorage.ual_debug = '1'`.
+
+## With Astro, Next.js, React, Vue and Node
+
+UAL is a browser script (it does not run in Node). For sites with a build step there is also the **package**: server-safe import, components for React, Next.js, Vue and Astro, TypeScript types (`defineConfig`). See `docs/libreria.md`. **The `universal-ad-loader` package is published on npm** (`npm i universal-ad-loader`).
+
+```tsx
+import { UalProvider, AdSlot } from 'universal-ad-loader/next';   // or /react, /vue; for Astro use the files in astro/
+
+<UalProvider config={config}>   {/* starts after hydration, handles page changes */}
+  <AdSlot name="top" minHeight={90} />
+</UalProvider>
+```
+
+If you use the tag with a framework instead, things verified with a server-rendered React app:
+
+- **Load the loader after hydration** (`next/script` with `strategy="afterInteractive"`, or a `useEffect`). If it starts earlier, UAL inserts the banner into the `div` before React attaches: *Hydration failed* error (even with `suppressHydrationWarning`) and the banner is requested twice. The components avoid this on their own.
+- **Client-side page change:** new slots register themselves, but `pageRules` and targeting are only recomputed with `ual.pageView()`.
+- **Do not import `dist/ual.js` in server code:** it uses `window` at load time (`ReferenceError` in Node). The package core (`dist/index.*`) is safe, though.
+- **Strict CSP:** creatives inherit the page's CSP. Tested: without `'unsafe-inline'` for scripts and styles the banner shows up but `UALExt` and the tracked click do not work; the same goes for nonces with `'strict-dynamic'`.
+
+Guide with examples and a CSP table: configurator, `/docs/` page.
+
+## Other documents
+
+- `docs/esempio.md`: complete client site (config, flow, minimal `decide` endpoint).
+- `docs/cdn.md`: **which files to put on the CDN** (loader and configuration), headers, structure, what is not needed and how to update.
+- `docs/libreria.md`: UAL as a package (React/Next/Vue/Astro components, types, server-safe core, how it is verified).
+- `docs/ad-server-esistenti.md`: how to connect AdManager, Banner Exchange Pro, Banner Exchange and the legacy PHP systems with the `iframe` adapter, with limits and checks.
+- `schema/ual-config.schema.json`: JSON Schema of the configuration.
+- The web configurator (`../ual-configurator`) has an HTML guide with examples that open in the editor.
+
+## Custom adapters
+
+```js
+ual.cmd.push(u => u.registerAdapter('myserver', {
+  init(providerCfg, ctx) {},                       // optional, once per provider
+  // A) the adapter returns the ads and UAL renders them in the 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) or the adapter renders by itself inside slot.el:
+  // async fill(slots, providerCfg, ctx) { return { [id]: { filled:true, width, height } } },
+  destroy(slot, providerCfg) {},                   // optional
+}));
+```
+`ctx` contains `site, page, device, viewport, targeting, consent`. To register a custom adapter before the automatic init, put `ual.cmd.push(...)` **before** the loader tag.
+
+## Build and tests
+
+```bash
+npm ci                          # base dependencies (~120 MB)
+npm ci --prefix test/heavy      # only for the framework tests: Next.js and Astro (~620 MB)
+npx playwright install chromium # once, for the browser tests
+npm test                        # build + all suites, about 2 minutes
+```
+
+To work on one part at a time (this is what CI does, in parallel jobs):
+
+| Command | What it runs | Needs |
+|---|---|---|
+| `npm run lint` | oxlint on the sources | base dependencies only |
+| `npm run test:node` | `test/package.mjs` | base dependencies only (no browser) |
+| `npm run test:browser` | `test/run.mjs` and `test/regression.mjs` | + Chromium |
+| `npm run test:frameworks` | `test/wrappers.mjs` | + `test/heavy` and Chromium |
+
+Every suite also writes a JUnit report to `test-results/` (CI shows it in the Tests tab).
+
+| Suite | What it verifies |
+|---|---|
+| `test/run.mjs` | loader e2e with a fake ad server and a fake CMP: batching per provider, waterfall to house, lazy load, `sizeMapping`, consent, `pageRules`, trackers, expand, sandbox |
+| `test/regression.mjs` | render security, `setTargeting`, late CMP, `contextual` providers, slots moved/closed in the DOM, refresh, `pageView`, the `gpt` adapter (with a `googletag` stub), the `iframe` adapter with the existing systems |
+| `test/package.mjs` | the package: import in Node (ESM and CJS) without `window`, server rendering of React and Vue, `exports` map, tarball contents (`npm pack`), types (correct usages compile, wrong ones fail) |
+| `test/wrappers.mjs` | the components in a real browser, with server rendering and delayed hydration: React (in the bundle, from CDN, Next version), Vue, **Next.js 16** (App Router, production build) and **Astro 7** (View Transitions); plus a check that demonstrates the problem the components avoid |
+
+The `adsense` and `revive-async` adapters are written against the public APIs but are not tested: they need to be tried on your own accounts and servers. `gpt` too must be tried with a real Google Ad Manager: the stub verifies UAL's logic, not GPT's behavior. Nuxt, Remix and React Router have not been run.
+
+## Notes
+
+- **Consent**: on client sites your ad server is a third-party vendor. Without consent, send only contextual requests (no cookies or IDs). `vendorId` is needed if your server is registered in the IAB GVL. Have the privacy setup reviewed by a lawyer.
+- **Automatic refresh** (`refreshSec`): only if the slot is on screen and the tab is visible. GPT and AdSense have their own refresh policies.
+- **CLS**: use `minHeight` on above-the-fold slots.

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 {};