universal-ad-loader 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,3 +1,27 @@
+# 0.2.0
+
+**What's new**
+- `native` creatives: the ad server sends assets (title, body, image, icon, sponsored-by, call to action, rating, price) and UAL draws
+  them in the page inside a Shadow DOM, inheriting the site's font and colour. A "Sponsored" label is always shown. Assets are text,
+  never HTML; images and links must be http(s). Layouts: `card`, `list`, `compact`; style with the `--ual-native-*` CSS variables.
+- `video` creatives (out-stream): a muted `<video>` that starts when at least half of it is visible and pauses when it leaves the
+  screen, with a sound button. No audio autoplay. New trackers: `trackers.start` and `trackers.quartile.{firstQuartile,midpoint,thirdQuartile,complete}`,
+  each fired once, and a `videoEvent` event. Video viewability waits 2 seconds instead of 1 (unless the slot sets `viewability.durationMs`).
+- `UALExt.track(name)`: HTML creatives can fire the named trackers declared in `trackers.custom`. Undeclared names are ignored.
+- `slots.X.sticky`: a small banner anchored to the top or bottom edge with a close button. Only when the ad takes at most 30% of
+  the screen height (Better Ads); otherwise it stays in the page flow.
+- `width`/`height` are optional for `native` ads.
+
+**Good to know**
+- The old tags and configurations keep working unchanged.
+- Video quartiles use the player's `timeupdate`; the file must have a duration (a live recording without one gives no quartiles).
+- The 2-second video viewability rule is the one commonly used for video; check it against the MRC guideline before relying on it for billing.
+
+# 0.1.2
+
+**Changes**
+- README: example of inline configuration (`ual.cmd.push` + `init({...})`) as an alternative to `data-config`.
+
 # 0.1.1
 
 **Changes**

package/README.md

@@ -1,11 +1,11 @@
-# UAL — Universal Ad Loader
+# UAL — Universal Ad Loader [![NPM version](https://img.shields.io/npm/v/universal-ad-loader)](https://www.npmjs.com/package/universal-ad-loader) [![Downloads](https://img.shields.io/npm/dm/universal-ad-loader)](https://www.npmjs.com/package/universal-ad-loader) [![Node version](https://img.shields.io/node/v/universal-ad-loader)](https://www.npmjs.com/package/universal-ad-loader) [![Bundle size](https://img.shields.io/bundlephobia/minzip/universal-ad-loader)](https://bundlephobia.com/package/universal-ad-loader) [![License](https://img.shields.io/npm/l/universal-ad-loader)](LICENSE)
 
 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"
+<script async src="https://cdn.jsdelivr.net/npm/universal-ad-loader@0.1.2/dist/ual.min.js"
         data-config="https://adcdn.yourdomain.net/config/site_123.json"></script>
 
 <div data-ad-slot="top"></div>
@@ -16,7 +16,30 @@ One tag per site. It handles slots, centralized configuration, TCF consent, lazy
 - `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`.
+**Inline configuration (no JSON file).** Instead of `data-config`, the configuration can be passed as an object in the page. The `cmd.push` block can go before or after the loader tag:
+
+```html
+<script>
+  window.ual = window.ual || { cmd: [] };
+  ual.cmd.push(function (u) {
+    u.init({
+      site: 'site_123',
+      providers: { main: { adapter: 'json', endpoint: 'https://ads.yourdomain.net/v1/decide' } },
+      slots: { top: { sizes: [[728, 90]], providers: ['main'] } }
+    });
+  });
+</script>
+<script async src="https://cdn.jsdelivr.net/npm/universal-ad-loader@0.1.2/dist/ual.min.js"></script>
+
+<div data-ad-slot="top"></div>
+```
+
+- Use either `data-config` or `init(...)`, not both: a second `init` is ignored with a warning.
+- The configuration lives in the page HTML, so changing it means redeploying the page (with a JSON on the CDN you just replace the file). `u.init('https://.../site_123.json')` also works if you want to choose the URL at runtime.
+- An inline script needs `'unsafe-inline'` or a nonce in the page's CSP; with a strict CSP prefer the external JSON.
+- **Components (React, Next.js, Vue, Astro):** the same applies, and inline is already the default. The `config` prop takes an object (inline) or the URL of a JSON; Astro's `UalBundled` writes the object into an `application/json` block, which works even with a strict CSP. See `docs/libreria.md`.
+
+> **Where the files live:** the loader is served for free by [jsDelivr](https://www.jsdelivr.com/) straight from the npm package (nothing to upload; pin the version in the URL, as above). Only the configuration JSON, one per site, goes on your own CDN with the right headers: see `docs/cdn.md`.
 
 ## Configuration (JSON served from the CDN)
 
@@ -101,6 +124,36 @@ Messages are accepted only from the slot's own iframe (checked on `event.source`
 - `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.
 
+## Native, video and sticky
+
+Besides `image`, `html` and `url`, an ad can be `native` or `video`.
+
+```json
+{ "slotId": "feed#1", "type": "native", "clickUrl": "https://ads/c?t=SIGNED",
+  "native": { "title": "A headline", "body": "Two lines of text", "sponsoredBy": "ACME",
+              "cta": "Learn more", "image": { "src": "https://cdn/.../main.jpg", "width": 1200, "height": 628 },
+              "icon": "https://cdn/.../icon.png", "layout": "card" },
+  "trackers": { "impression": ["https://ads/i?t=..."], "viewable": ["https://ads/v?t=..."] } }
+```
+
+The assets are plain data (never HTML). UAL draws them in the page inside a Shadow DOM, so the card inherits the site's font and colour;
+a "Sponsored" label is always shown. Style it with CSS variables on the slot: `--ual-native-bg`, `--ual-native-border`,
+`--ual-native-radius`, `--ual-native-accent`, `--ual-native-accent-text`. Title is limited to 150 characters, body to 300 (longer text is cut).
+
+```json
+{ "slotId": "article#1", "type": "video", "src": "https://cdn/.../ad.mp4", "mime": "video/mp4", "poster": "https://cdn/.../p.jpg",
+  "width": 640, "height": 360, "clickUrl": "https://ads/c?t=SIGNED",
+  "trackers": { "impression": ["..."], "viewable": ["..."], "start": ["..."],
+                "quartile": { "firstQuartile": ["..."], "midpoint": ["..."], "thirdQuartile": ["..."], "complete": ["..."] } } }
+```
+
+The video starts **muted** when at least half of it is visible and pauses when it is not; the visitor can turn the sound on. Each tracker fires once.
+The `videoEvent` event reports `start`, `firstQuartile`, `midpoint`, `thirdQuartile` and `complete`. Video is counted as viewable after 2 s in view (set `viewability.durationMs` on the slot to change it).
+
+`UALExt.track(name)` lets an HTML creative fire a named tracker declared in `trackers.custom` (`{ "engaged": ["https://ads/e?t=..."] }`); names that were not declared are ignored.
+
+`slots.X.sticky` (`true`, `"top"`, `"bottom"` or `{ "position": "bottom" }`) anchors a small banner to the screen edge with a close button. It only applies if the ad is at most 30% of the screen height; larger ads stay in the page.
+
 ## JavaScript API
 
 ```js
@@ -187,7 +240,7 @@ To work on one part at a time (this is what CI does, in parallel jobs):
 |---|---|---|
 | `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:browser` | `test/run.mjs`, `test/regression.mjs` and `test/formats.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).
@@ -196,6 +249,7 @@ Every suite also writes a JUnit report to `test-results/` (CI shows it in the Te
 |---|---|
 | `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/formats.mjs` | `native`, `video` (muted autoplay when visible, pause, quartiles once each, sound button), `UALExt.track` and `sticky`, in Chromium with a real video file; plus the validation rules |
 | `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 |