Merge remote-tracking branch 'upstream/master'

.circleci/config.yml

@@ -7,7 +7,7 @@ aliases:
   - &environment
       docker:
         # specify the version you desire here
-        - image: circleci/node:12.16.1-browsers
+        - image: cimg/node:16.20-browsers
       resource_class: xlarge
         # Specify service dependencies here if necessary
         # CircleCI maintains a library of pre-built images

.eslintrc.js

@@ -42,6 +42,7 @@ module.exports = {
     sourceType: 'module',
     ecmaVersion: 2018,
   },
+  ignorePatterns: ['libraries/creative-renderer*'],
 
   rules: {
     'comma-dangle': 'off',

.github/workflows/release-drafter.yml

@@ -17,7 +17,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       # Drafts your next Release notes as Pull Requests are merged into "master"
-      - uses: release-drafter/release-drafter@v5
+      - uses: release-drafter/release-drafter@v6
         with:
          config-name: release-drafter.yml         
         env:

README.md

@@ -237,6 +237,12 @@ To lint the code:
 gulp lint
 ```
 
+To lint and only show errors
+
+```bash
+gulp lint --no-lint-warnings
+```
+
 To run the unit tests:
 
 ```bash
@@ -245,7 +251,7 @@ gulp test
 
 To run the unit tests for a particular file (example for pubmaticBidAdapter_spec.js):
 ```bash
-gulp test --file "test/spec/modules/pubmaticBidAdapter_spec.js"
+gulp test --file "test/spec/modules/pubmaticBidAdapter_spec.js" --nolint
 ```
 
 To generate and view the code coverage reports:
@@ -255,6 +261,12 @@ gulp test-coverage
 gulp view-coverage
 ```
 
+Local end-to-end testing can be done with:
+
+```bash
+gulp e2e-test --local
+```
+
 For Prebid.org members with access to BrowserStack, additional end-to-end testing can be done with:
 
 ```bash

RELEASE_SCHEDULE.md

@@ -9,7 +9,7 @@
 
 ## Release Schedule
 
-We aim to push a new release of Prebid.js every week on Tuesday.
+We aim to push a new release of Prebid.js each week barring any unforseen circumstances or in observance of holidays.
 
 While the releases will be available immediately for those using direct Git access,
 it will be about a week before the Prebid Org [Download Page](https://docs.prebid.org/download.html) will be updated.

allowedModules.js

@@ -1,22 +1,18 @@
 
-const sharedWhiteList = [
-];
-
 module.exports = {
   'modules': [
-    ...sharedWhiteList,
     'criteo-direct-rsa-validate',
     'crypto-js',
     'live-connect' // Maintained by LiveIntent : https://github.com/liveintent-berlin/live-connect/
   ],
   'src': [
-    ...sharedWhiteList,
     'fun-hooks/no-eval',
     'just-clone',
     'dlv',
     'dset'
   ],
   'libraries': [
-    ...sharedWhiteList // empty for now, but keep it to enable linting
+  ],
+  'creative': [
   ]
 };

creative/README.md

@@ -0,0 +1,44 @@
+## Dynamic creative renderers
+
+The contents of this directory are compiled separately from the rest of Prebid, and intended to be dynamically injected 
+into creative frames:
+
+- `crossDomain.js` (compiled into `build/creative/creative.js`, also exposed in `integrationExamples/gpt/x-domain/creative.html`)
+   is the logic that should be statically set up in the creative. 
+- At build time, each folder under 'renderers' is compiled into a source string made available from a corresponding
+`creative-renderer-*` library. These libraries are committed in source so that they are available to NPM consumers. 
+- At render time, Prebid passes the appropriate renderer's source string to the remote creative, which then runs it.
+
+The goal is to have a creative script that is as simple, lightweight, and unchanging as possible, but still allow the possibility
+of complex or frequently updated rendering logic. Compared to the approach taken by [PUC](https://github.com/prebid/prebid-universal-creative), this:
+
+- should perform marginally better: the creative only runs logic that is pertinent (for example, it sees native logic only on native bids);
+- avoids the problem of synchronizing deployments when the rendering logic is updated (see https://github.com/prebid/prebid-universal-creative/issues/187), since it's bundled together with the rest of Prebid;
+- is easier to embed directly in the creative (saving a network call), since the static "shell" is designed to change as infrequently as possible;
+- allows the same rendering logic to be used both in remote (cross-domain) and local (`pbjs.renderAd`) frames, since it's directly available to Prebid; 
+- requires Prebid.js - meaning it does not support AMP/App/Mobile (but it's still possible for something like PUC to run the same dynamic renderers
+  when it receives them from Prebid, and fall back to separate AMP/App/Mobile logic otherwise).
+
+### Renderer interface
+
+A creative renderer (not related to other types of renderers in the codebase) is a script that exposes a global `window.render` function:
+
+```javascript
+window.render = function(data, {mkFrame, sendMessage}, win) { ... }
+```
+
+where:
+
+ - `data` is rendering data about the winning bid, and varies depending on the bid type - see `getRenderingData` in `adRendering.js`;
+ - `mkFrame(document, attributes)` is a utility that creates a frame with the given attributes and convenient defaults (no border, margin, and scrolling);
+ - `sendMessage(messageType, payload)` is the mechanism by which the renderer/creative can communicate back with Prebid - see `creativeMessageHandler` in `adRendering.js`;
+ - `win` is the window to render into; note that this is not the same window that runs the renderer.
+
+The function may return a promise; if it does and the promise rejects, or if the function throws, an AD_RENDER_FAILED event is emitted in Prebid. Otherwise an AD_RENDER_SUCCEEDED is fired 
+when the promise resolves (or when `render` returns anything other than a promise).
+
+### Renderer development
+
+Since renderers are compiled into source, they use production settings even during development builds. You can toggle this with 
+the `--creative-dev` CLI option (e.g., `gulp serve-fast --creative-dev`), which disables the minifier and generates source maps; if you do, take care 
+to not commit the resulting `creative-renderer-*` libraries (or run a normal build before you do).

creative/constants.js

@@ -0,0 +1,9 @@
+// eslint-disable-next-line prebid/validate-imports
+import { AD_RENDER_FAILED_REASON, EVENTS, MESSAGES } from '../src/constants.js';
+
+export const MESSAGE_REQUEST = MESSAGES.REQUEST;
+export const MESSAGE_RESPONSE = MESSAGES.RESPONSE;
+export const MESSAGE_EVENT = MESSAGES.EVENT;
+export const EVENT_AD_RENDER_FAILED = EVENTS.AD_RENDER_FAILED;
+export const EVENT_AD_RENDER_SUCCEEDED = EVENTS.AD_RENDER_SUCCEEDED;
+export const ERROR_EXCEPTION = AD_RENDER_FAILED_REASON.EXCEPTION;

creative/crossDomain.js

@@ -0,0 +1,92 @@
+import {
+  ERROR_EXCEPTION,
+  EVENT_AD_RENDER_FAILED, EVENT_AD_RENDER_SUCCEEDED,
+  MESSAGE_EVENT,
+  MESSAGE_REQUEST,
+  MESSAGE_RESPONSE
+} from './constants.js';
+
+const mkFrame = (() => {
+  const DEFAULTS = {
+    frameBorder: 0,
+    scrolling: 'no',
+    marginHeight: 0,
+    marginWidth: 0,
+    topMargin: 0,
+    leftMargin: 0,
+    allowTransparency: 'true',
+  };
+  return (doc, attrs) => {
+    const frame = doc.createElement('iframe');
+    Object.entries(Object.assign({}, attrs, DEFAULTS))
+      .forEach(([k, v]) => frame.setAttribute(k, v));
+    return frame;
+  };
+})();
+
+export function renderer(win) {
+  return function ({adId, pubUrl, clickUrl}) {
+    const pubDomain = new URL(pubUrl, window.location).origin;
+
+    function sendMessage(type, payload, responseListener) {
+      const channel = new MessageChannel();
+      channel.port1.onmessage = guard(responseListener);
+      win.parent.postMessage(JSON.stringify(Object.assign({message: type, adId}, payload)), pubDomain, [channel.port2]);
+    }
+
+    function onError(e) {
+      sendMessage(MESSAGE_EVENT, {
+        event: EVENT_AD_RENDER_FAILED,
+        info: {
+          reason: e?.reason || ERROR_EXCEPTION,
+          message: e?.message
+        }
+      });
+      // eslint-disable-next-line no-console
+      e?.stack && console.error(e);
+    }
+
+    function guard(fn) {
+      return function () {
+        try {
+          return fn.apply(this, arguments);
+        } catch (e) {
+          onError(e);
+        }
+      };
+    }
+
+    function onMessage(ev) {
+      let data;
+      try {
+        data = JSON.parse(ev.data);
+      } catch (e) {
+        return;
+      }
+      if (data.message === MESSAGE_RESPONSE && data.adId === adId) {
+        const renderer = mkFrame(win.document, {
+          width: 0,
+          height: 0,
+          style: 'display: none',
+          srcdoc: `<script>${data.renderer}</script>`
+        });
+        renderer.onload = guard(function () {
+          const W = renderer.contentWindow;
+          // NOTE: on Firefox, `Promise.resolve(P)` or `new Promise((resolve) => resolve(P))`
+          // does not appear to work if P comes from another frame
+          W.Promise.resolve(W.render(data, {sendMessage, mkFrame}, win)).then(
+            () => sendMessage(MESSAGE_EVENT, {event: EVENT_AD_RENDER_SUCCEEDED}),
+            onError
+          )
+        });
+        win.document.body.appendChild(renderer);
+      }
+    }
+
+    sendMessage(MESSAGE_REQUEST, {
+      options: {clickUrl}
+    }, onMessage);
+  };
+}
+
+window.pbRender = renderer(window);

creative/renderers/display/constants.js

@@ -0,0 +1,4 @@
+// eslint-disable-next-line prebid/validate-imports
+import { AD_RENDER_FAILED_REASON } from '../../../src/constants.js';
+
+export const ERROR_NO_AD = AD_RENDER_FAILED_REASON.NO_AD;

creative/renderers/display/renderer.js

@@ -0,0 +1,21 @@
+import {ERROR_NO_AD} from './constants.js';
+
+export function render({ad, adUrl, width, height}, {mkFrame}, win) {
+  if (!ad && !adUrl) {
+    throw {
+      reason: ERROR_NO_AD,
+      message: 'Missing ad markup or URL'
+    };
+  } else {
+    const doc = win.document;
+    const attrs = {width, height};
+    if (adUrl && !ad) {
+      attrs.src = adUrl;
+    } else {
+      attrs.srcdoc = ad;
+    }
+    doc.body.appendChild(mkFrame(doc, attrs));
+  }
+}
+
+window.render = render;

creative/renderers/native/constants.js

@@ -0,0 +1,14 @@
+// eslint-disable-next-line prebid/validate-imports
+import { MESSAGES } from '../../../src/constants.js';
+
+export const MESSAGE_NATIVE = MESSAGES.NATIVE;
+export const ACTION_RESIZE = 'resizeNativeHeight';
+export const ACTION_CLICK = 'click';
+export const ACTION_IMP = 'fireNativeImpressionTrackers';
+
+export const ORTB_ASSETS = {
+  title: 'text',
+  data: 'value',
+  img: 'url',
+  video: 'vasttag'
+}

creative/renderers/native/renderer.js

@@ -0,0 +1,88 @@
+import {ACTION_CLICK, ACTION_IMP, ACTION_RESIZE, MESSAGE_NATIVE, ORTB_ASSETS} from './constants.js';
+
+export function getReplacer(adId, {assets = [], ortb, nativeKeys = {}}) {
+  const assetValues = Object.fromEntries((assets).map(({key, value}) => [key, value]));
+  let repl = Object.fromEntries(
+    Object.entries(nativeKeys).flatMap(([name, key]) => {
+      const value = assetValues.hasOwnProperty(name) ? assetValues[name] : undefined;
+      return [
+        [`##${key}##`, value],
+        [`${key}:${adId}`, value]
+      ];
+    })
+  );
+  if (ortb) {
+    Object.assign(repl,
+      {
+        '##hb_native_linkurl##': ortb.link?.url,
+        '##hb_native_privacy##': ortb.privacy
+      },
+      Object.fromEntries(
+        (ortb.assets || []).flatMap(asset => {
+          const type = Object.keys(ORTB_ASSETS).find(type => asset[type]);
+          return [
+            type && [`##hb_native_asset_id_${asset.id}##`, asset[type][ORTB_ASSETS[type]]],
+            asset.link?.url && [`##hb_native_asset_link_id_${asset.id}##`, asset.link.url]
+          ].filter(e => e);
+        })
+      )
+    );
+  }
+  repl = Object.entries(repl).concat([[/##hb_native_asset_(link_)?id_\d+##/g]]);
+
+  return function (template) {
+    return repl.reduce((text, [pattern, value]) => text.replaceAll(pattern, value || ''), template);
+  };
+}
+
+function loadScript(url, doc) {
+  return new Promise((resolve, reject) => {
+    const script = doc.createElement('script');
+    script.onload = resolve;
+    script.onerror = reject;
+    script.src = url;
+    doc.body.appendChild(script);
+  });
+}
+
+export function getAdMarkup(adId, nativeData, replacer, win, load = loadScript) {
+  const {rendererUrl, assets, ortb, adTemplate} = nativeData;
+  const doc = win.document;
+  if (rendererUrl) {
+    return load(rendererUrl, doc).then(() => {
+      if (typeof win.renderAd !== 'function') {
+        throw new Error(`Renderer from '${rendererUrl}' does not define renderAd()`);
+      }
+      const payload = assets || [];
+      payload.ortb = ortb;
+      return win.renderAd(payload);
+    });
+  } else {
+    return Promise.resolve(replacer(adTemplate ?? doc.body.innerHTML));
+  }
+}
+
+export function render({adId, native}, {sendMessage}, win, getMarkup = getAdMarkup) {
+  const {head, body} = win.document;
+  const resize = () => sendMessage(MESSAGE_NATIVE, {
+    action: ACTION_RESIZE,
+    height: body.offsetHeight,
+    width: body.offsetWidth
+  });
+  const replacer = getReplacer(adId, native);
+  head && (head.innerHTML = replacer(head.innerHTML));
+  return getMarkup(adId, native, replacer, win).then(markup => {
+    body.innerHTML = markup;
+    if (typeof win.postRenderAd === 'function') {
+      win.postRenderAd({adId, ...native});
+    }
+    win.document.querySelectorAll('.pb-click').forEach(el => {
+      const assetId = el.getAttribute('hb_native_asset_id');
+      el.addEventListener('click', () => sendMessage(MESSAGE_NATIVE, {action: ACTION_CLICK, assetId}));
+    });
+    sendMessage(MESSAGE_NATIVE, {action: ACTION_IMP});
+    win.document.readyState === 'complete' ? resize() : win.onload = resize;
+  });
+}
+
+window.render = render;