Merge branch 'master' of https://github.com/wishabi/Prebid.js

.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/PULL_REQUEST_TEMPLATE.md

@@ -16,7 +16,8 @@ For any user facing change, submit a link to a PR on the docs repo at https://gi
 <!-- Remove items that don't apply and/or select an item by changing [ ] to [x] -->
 - [ ] Bugfix
 - [ ] Feature
-- [ ] New bidder adapter  <!--  IMPORTANT: if checking here, also submit your bidder params documentation here https://github.com/prebid/prebid.github.io/tree/master/dev-docs/bidders --> 
+- [ ] New bidder adapter  <!--  IMPORTANT: also submit your bidder parameter documentation as noted in https://docs.prebid.org/dev-docs/bidder-adaptor.html#submitting-your-adapter -->
+- [ ] Updated bidder adapter  <!--  IMPORTANT: (1) consider whether you need to upgrade your bidder parameter documentation in https://github.com/prebid/prebid.github.io/tree/master/dev-docs/bidders and (2) if you have a Prebid Server adapter, please consider whether that should be updated as well. --> 
 - [ ] Code style update (formatting, local variables)
 - [ ] Refactoring (no functional changes, no api changes)
 - [ ] Build related changes

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

README.md

@@ -229,6 +229,16 @@ Or, if you are consuming Prebid through npm, with the `disableFeatures` option i
 
 **Note**: this is still a work in progress - at the moment, `NATIVE` is the only feature that can be disabled this way, resulting in a minimal decrease in size (but you can expect that to improve over time).
 
+## Unminified code
+
+You can get a version of the code that's unminified for debugging with `build-bundle-dev`:
+
+```bash
+gulp build-bundle-dev --modules=bidderA,module1,...
+```
+
+The results will be in build/dev/prebid.js.
+
 ## Test locally
 
 To lint the code:
@@ -237,6 +247,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 +261,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 +271,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',
+    'klona',
     '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'
+}