Merge branch 'prebid:master' into 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

@@ -11,12 +11,25 @@ module.exports = {
       node: {
         moduleDirectory: ['node_modules', './']
       }
+    },
+    'jsdoc': {
+      mode: 'typescript',
+      tagNamePreference: {
+        'tag constructor': 'constructor',
+        extends: 'extends',
+        method: 'method',
+        return: 'return',
+      }
     }
   },
-  extends: 'standard',
+  extends: [
+    'standard',
+    'plugin:jsdoc/recommended'
+  ],
   plugins: [
     'prebid',
-    'import'
+    'import',
+    'jsdoc'
   ],
   globals: {
     'BROWSERSTACK_USERNAME': false,
@@ -29,6 +42,7 @@ module.exports = {
     sourceType: 'module',
     ecmaVersion: 2018,
   },
+  ignorePatterns: ['libraries/creative-renderer*'],
 
   rules: {
     'comma-dangle': 'off',
@@ -46,6 +60,24 @@ module.exports = {
     'no-undef': 2,
     'no-useless-escape': 'off',
     'no-console': 'error',
+    'jsdoc/check-types': 'off',
+    'jsdoc/newline-after-description': 'off',
+    'jsdoc/require-jsdoc': 'off',
+    'jsdoc/require-param': 'off',
+    'jsdoc/require-param-description': 'off',
+    'jsdoc/require-param-name': 'off',
+    'jsdoc/require-param-type': 'off',
+    'jsdoc/require-property': 'off',
+    'jsdoc/require-property-description': 'off',
+    'jsdoc/require-property-name': 'off',
+    'jsdoc/require-property-type': 'off',
+    'jsdoc/require-returns': 'off',
+    'jsdoc/require-returns-check': 'off',
+    'jsdoc/require-returns-description': 'off',
+    'jsdoc/require-returns-type': 'off',
+    'jsdoc/require-yields': 'off',
+    'jsdoc/require-yields-check': 'off',
+    'jsdoc/tag-lines': 'off'
   },
   overrides: Object.keys(allowedModules).map((key) => ({
     files: key + '/**/*.js',

.github/workflows/codeql-analysis.yml

@@ -42,7 +42,7 @@ jobs:
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@v2
+      uses: github/codeql-action/init@v3
       with:
         languages: ${{ matrix.language }}
         config-file: ./.github/codeql/codeql-config.yml
@@ -57,7 +57,7 @@ jobs:
     # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
     # If this step fails, then you should remove it and run the build manually (see below)
     - name: Autobuild
-      uses: github/codeql-action/autobuild@v2
+      uses: github/codeql-action/autobuild@v3
 
     # ℹ️ Command-line programs to run using the OS shell.
     # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
@@ -70,4 +70,4 @@ jobs:
     #   ./location_of_script_within_repo/buildscript.sh
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v2
+      uses: github/codeql-action/analyze@v3

.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:

PR_REVIEW.md

@@ -55,7 +55,6 @@ Follow steps above for general review process. In addition, please verify the fo
     - Adapters that accept a floor parameter must also support the [floors module](https://docs.prebid.org/dev-docs/modules/floors.html) -- look for a call to the `getFloor()` function.
     - Adapters cannot accept an schain parameter. Rather, they must look for the schain parameter at bidRequest.schain.
     - The bidderRequest.refererInfo.referer must be checked in addition to any bidder-specific parameter.
-    - If they're getting the COPPA flag, it must come from config.getConfig('coppa');
     - Page position must come from bidrequest.mediaTypes.banner.pos or bidrequest.mediaTypes.video.pos
     - Global OpenRTB fields should come from [getConfig('ortb2');](https://docs.prebid.org/dev-docs/publisher-api-reference/setConfig.html#setConfig-fpd):
         - bcat, battr, badv

README.md

@@ -255,6 +255,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 CONSTANTS from '../src/constants.json';
+
+export const MESSAGE_REQUEST = CONSTANTS.MESSAGES.REQUEST;
+export const MESSAGE_RESPONSE = CONSTANTS.MESSAGES.RESPONSE;
+export const MESSAGE_EVENT = CONSTANTS.MESSAGES.EVENT;
+export const EVENT_AD_RENDER_FAILED = CONSTANTS.EVENTS.AD_RENDER_FAILED;
+export const EVENT_AD_RENDER_SUCCEEDED = CONSTANTS.EVENTS.AD_RENDER_SUCCEEDED;
+export const ERROR_EXCEPTION = CONSTANTS.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 CONSTANTS from '../../../src/constants.json';
+
+export const ERROR_NO_AD = CONSTANTS.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 CONSTANTS from '../../../src/constants.json';
+
+export const MESSAGE_NATIVE = CONSTANTS.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'
+}