Update Prebid.js support (#37)

- Update prebidUserDataFromCache API to return an object that can be
  directly sent to pbjs.setConfig(ortb2.user.data) by the caller. The
  returned user.data object now references Optable's requested segtax
  (seller defined audience/segment taxonomy) corresponding to "Optable
  Private Audiences" which is segtax=5001 as per our pending PR:
  InteractiveAdvertisingBureau/openrtb#81
- Document prebidUserDataFromCache in README
- Add a link to the prebid demo page from demos/index
- Delete old prebid-us-east-16 demo pages
- Silence webpack5 warnings when building lib/core/network.ts
- Complete replacing "sandbox" with "DCN" or "dcn" in demo pages
  and SDK codebase, but continue to support optable.instance.sandbox
  for backward compatibility
- Update broken privacy policy link in footer of demos/index pages
- Provide link to demos/index-nocookies.html as alternative
  integration example
- More succinct naming and labels and clarify documentation on
  Prebid.js integration in demos

Author: bmilekic

Dockerfile

@@ -46,23 +46,20 @@ WORKDIR /usr/share/nginx/html/
 COPY --from=build /build/demos/vanilla/targeting/gam360.html ./vanilla/targeting/gam360.html
 COPY --from=build /build/demos/vanilla/targeting/gam360-cached.html ./vanilla/targeting/gam360-cached.html
 COPY --from=build /build/demos/vanilla/targeting/prebid.html ./vanilla/targeting/prebid.html
-COPY --from=build /build/demos/vanilla/targeting/prebid-us-east-16.html ./vanilla/targeting/prebid-us-east-16.html
 COPY --from=build /build/demos/vanilla/targeting/prebid.js ./vanilla/targeting/prebid.js
-COPY --from=build /build/demos/vanilla/targeting/prebid-us-east-16.js ./vanilla/targeting/prebid-us-east-16.js
 COPY --from=build /build/demos/vanilla/identify.html ./vanilla/identify.html
 COPY --from=build /build/demos/vanilla/profile.html ./vanilla/profile.html
 COPY --from=build /build/demos/vanilla/witness.html ./vanilla/witness.html
 COPY --from=build /build/demos/vanilla/nocookies/targeting/gam360.html ./vanilla/nocookies/targeting/gam360.html
 COPY --from=build /build/demos/vanilla/nocookies/targeting/gam360-cached.html ./vanilla/nocookies/targeting/gam360-cached.html
 COPY --from=build /build/demos/vanilla/nocookies/targeting/prebid.html ./vanilla/nocookies/targeting/prebid.html
-COPY --from=build /build/demos/vanilla/nocookies/targeting/prebid-us-east-16.html ./vanilla/nocookies/targeting/prebid-us-east-16.html
 COPY --from=build /build/demos/vanilla/nocookies/targeting/prebid.js ./vanilla/nocookies/targeting/prebid.js
-COPY --from=build /build/demos/vanilla/nocookies/targeting/prebid-us-east-16.js ./vanilla/nocookies/targeting/prebid-us-east-16.js
 COPY --from=build /build/demos/vanilla/nocookies/identify.html ./vanilla/nocookies/identify.html
 COPY --from=build /build/demos/vanilla/nocookies/profile.html ./vanilla/nocookies/profile.html
 COPY --from=build /build/demos/vanilla/nocookies/witness.html ./vanilla/nocookies/witness.html
 COPY --from=build /build/demos/react/dist/ ./react/dist/
 COPY --from=build /build/demos/index.html ./index.html
+COPY --from=build /build/demos/index-nocookies.html ./index-nocookies.html
 COPY --from=build /build/demos/css/ ./css/
 COPY --from=build /build/demos/images/ ./images/
 

README.md

@@ -20,6 +20,9 @@ JavaScript SDK for integrating with an [Optable Data Connectivity Node (DCN)](ht
   - [Targeting key values](#targeting-key-values)
   - [Targeting key values from local cache](#targeting-key-values-from-local-cache)
   - [Witnessing ad events](#witnessing-ad-events)
+- [Integrating Prebid](#integrating-prebid)
+  - [Seller Defined Audiences](#seller-defined-audiences)
+  - [Custom key values](#custom-key-values)
 - [Identifying visitors arriving from Email newsletters](#identifying-visitors-arriving-from-email-newsletters)
   - [Insert oeid into your Email newsletter template](#insert-oeid-into-your-email-newsletter-template)
   - [Call tryIdentifyFromParams SDK API](#call-tryidentifyfromparams-sdk-api)
@@ -425,6 +428,161 @@ Note that you can call `installGPTEventListeners()` as many times as you like on
 
 A working example of both targeting and event witnessing is available in the demo pages.
 
+## Integrating Prebid
+
+The Optable Web SDK can fetch targeting data from a DCN and prepare an audience taxonomy object similar to the one described in [the prebid.js first party data documentation](https://docs.prebid.org/features/firstPartyData.html#segments-and-taxonomy). The `prebidUserDataFromCache()` function returns the object from the targeting data stored by `targeting()` API calls in `LocalStorage`.
+
+### Seller Defined Audiences
+
+The HTML code snippet below shows how `prebidUserDataFromCache()` can be used to retrieve targeting data from the `LocalStorage` administered by the Optable SDK, and write Seller Defined Audiences (SDA) into [prebid.js](https://prebid.org/product-suite/prebid-js/) which is also loaded into the page, using `pbjs.setConfig({ ortb2: { user: { data: [ { ... } ] } } })` as documented in [the prebid.js first party data documentation](https://docs.prebid.org/features/firstPartyData.html#segments-and-taxonomy). The `targeting()` API is also called in order to retrieve and locally store the latest matching activations from `dcn.customer.com/my-site`.
+
+Note that [prebid.js bidder adapters](https://docs.prebid.org/dev-docs/bidders.html) can subsequently retrieve the data from the [global config](https://docs.prebid.org/features/firstPartyData.html#supplying-global-data).
+
+An example of how to install the SDA data through `pbjs` is shown below. The `districtMDMX` bidder adapter is referenced, though the integration would look similar with any SDA compatible bidder adapters.
+
+For a working demo showing a `pbjs` and GAM integrated together, see the [demo pages section](#demo-pages) below.
+
+```html
+<!-- Optable SDK async load: -->
+<script async src="https://cdn.optable.co/web-sdk/v0/sdk.js"></script>
+
+<!-- Prebid.js lib async load: -->
+<script async src="prebid.js"></script>
+
+<!-- Initialize Optable SDK, and targeting call early when possible: -->
+<script>
+  window.optable = window.optable || { cmd: [] };
+
+  // Init Optable SDK via command:
+  optable.cmd.push(function () {
+    optable.instance = new optable.SDK({ host: "dcn.customer.com", site: "my-site" });
+  });
+
+  // Call Optable DCN for targeting data which will update the local cache on success.
+  optable.cmd.push(function () {
+    optable.instance.targeting().catch((err) => {
+      // Maybe log error
+    });
+  });
+</script>
+
+<!-- Placeholder DIV for adSlot -->
+<div id="div-gpt-ad-12345-0"></div>
+
+<!-- Initialize prebid.js -->
+<script>
+  window.pbjs = window.pbjs || { que: [] };
+
+  var PREBID_TIMEOUT = 3000;
+  var FAILSAFE_TIMEOUT = 5000;
+
+  var adUnits = [
+    {
+      code: "/22081946781/web-sdk-demo/box-ad",
+      mediaTypes: {
+        banner: {
+          sizes: [
+            [250, 250],
+            [300, 250],
+            [200, 200],
+          ],
+        },
+      },
+      bids: [
+        {
+          bidder: "districtmDMX",
+          params: {
+            dmxid: "/22081946781/web-sdk-demo/box-ad",
+            memberid: "102034",
+          },
+        },
+      ],
+    },
+  ];
+
+  function initAdserver() {
+    if (pbjs.initAdserverSet) return;
+    pbjs.initAdserverSet = true;
+    // ... etc ...
+  }
+
+  pbjs.que.push(function () {
+    optable.cmd.push(function () {
+      const pbdata = optable.instance.prebidUserDataFromCache();
+      if (pbdata.length > 0) {
+        pbjs.setConfig({
+          ortb2: {
+            user: {
+              data: pbdata,
+            },
+          },
+        });
+      }
+
+      // ... etc ...
+
+      pbjs.requestBids({
+        bidsBackHandler: initAdserver,
+        timeout: PREBID_TIMEOUT,
+      });
+    });
+  });
+
+  setTimeout(function () {
+    initAdserver();
+  }, FAILSAFE_TIMEOUT);
+</script>
+```
+
+### Custom key values
+
+For bidder adapters that do not support SDA, but that do support targeting private marketplace deals to key values, you can use a samilar approach to the [Google Ad Manager integration with key values from local cache](#targeting-key-values-from-local-cache). For example, for the IX bidder adapter and [IX bidder-specific FPD](https://docs.prebid.org/dev-docs/bidders/ix.html#ix-bidder-specific-fpd), you can encode the targeting key values as shown below:
+
+```html
+<script>
+  // ...
+  // prior to pbjs.requestBids():
+  pbjs.que.push(function () {
+    optable.cmd.push(function () {
+      const tdata = optable.instance.targetingFromCache();
+      var fpd = {};
+
+      /*
+       * Flatten targeting key=values from Optable SDK targeting cache
+       * into a custom key value object, such that a key K with values
+       * V1, V2, ... in the Optable SDK targeting cache is transformed
+       * to look like:
+       * {
+       *   K + V1: 1,
+       *   K + V2: 1,
+       *   ...
+       * }
+       *
+       * Note that + above indicates string concatenation.
+       *
+       * Optable DCNs have K configured to "optable" by default, so the
+       * above would result in a custom key value "optable_audienceKeyword=1"
+       * being set whenever the visitor is matched to the activated audience
+       * specified by audienceKeyword by the DCN.
+       */
+      for (const [key, values] of Object.entries(tdata || {})) {
+        for (const seg of values) {
+          fpd[key + seg] = "1";
+        }
+      }
+
+      pbjs.setConfig({
+        ix: {
+          firstPartyData: fpd,
+        },
+      });
+    });
+
+    pbjs.requestBids(...);
+  });
+</script>
+```
+
 ## Identifying visitors arriving from Email newsletters
 
 If you send Email newsletters that contain links to your website, then you may want to automatically _identify_ visitors that have clicked on any such links via their Email address.
@@ -460,3 +618,5 @@ On your website destination page, you can call a helper method provided by the S
 The demo pages are working examples of both `identify` and `targeting` APIs, as well as an integration with the [Google Ad Manager 360](https://admanager.google.com/home/) ad server, enabling the targeting of ads served by GAM360 to audiences activated in the [Optable](https://optable.co/) DCN.
 
 You can browse a recent (but not necessarily the latest) released version of the demo pages at [https://demo.optable.co/](https://demo.optable.co/). The source code to the demos can be found [here](https://github.com/Optable/optable-web-sdk/tree/master/demos). The demo pages will connect to the [Optable](https://optable.co/) demo DCN at `sandbox.optable.co` and reference the web site slug `web-sdk-demo`. The GAM360 targeting demo loads ads from a GAM360 account operated by [Optable](https://optable.co/).
+
+Note that the demo pages at [https://demo.optable.co/](https://demo.optable.co/) will by default rely on secure HTTP first-party cookies as described [here](https://github.com/Optable/optable-web-sdk#domains-and-cookies). To see an example based on [LocalStorage](https://github.com/Optable/optable-web-sdk#localstorage), see the [index-nocookies variant here](https://demo.optable.co/index-nocookies.html).

demos/Makefile

@@ -11,14 +11,12 @@ html:
 	envsubst < ./vanilla/targeting/gam360.html.tpl > ./vanilla/targeting/gam360.html && \
 	envsubst < ./vanilla/targeting/gam360-cached.html.tpl > ./vanilla/targeting/gam360-cached.html && \
 	envsubst < ./vanilla/targeting/prebid.html.tpl > ./vanilla/targeting/prebid.html && \
-	envsubst < ./vanilla/targeting/prebid-us-east-16.html.tpl > ./vanilla/targeting/prebid-us-east-16.html && \
 	envsubst < ./vanilla/nocookies/identify.html.tpl > ./vanilla/nocookies/identify.html && \
 	envsubst < ./vanilla/nocookies/witness.html.tpl > ./vanilla/nocookies/witness.html && \
 	envsubst < ./vanilla/nocookies/profile.html.tpl > ./vanilla/nocookies/profile.html && \
 	envsubst < ./vanilla/nocookies/targeting/gam360.html.tpl > ./vanilla/nocookies/targeting/gam360.html && \
 	envsubst < ./vanilla/nocookies/targeting/gam360-cached.html.tpl > ./vanilla/nocookies/targeting/gam360-cached.html && \
-	envsubst < ./vanilla/nocookies/targeting/prebid.html.tpl > ./vanilla/nocookies/targeting/prebid.html && \
-	envsubst < ./vanilla/nocookies/targeting/prebid-us-east-16.html.tpl > ./vanilla/nocookies/targeting/prebid-us-east-16.html
+	envsubst < ./vanilla/nocookies/targeting/prebid.html.tpl > ./vanilla/nocookies/targeting/prebid.html
 
 .PHONY: react
 react:

demos/index-nocookies.html

@@ -21,7 +21,7 @@
       </div>
       <div class="row">
         <div class="twelve column">
-          <h4>👋 demo.optable.co (cookies=false)</h4>
+          <h4>👋 demo.optable.co (LocalStorage)</h4>
           <p>
             To learn about optable-web-sdk integration on your web site or application, see the latest releases, or
             report an issue, please check out the
@@ -34,14 +34,14 @@ <h4>👋 demo.optable.co (cookies=false)</h4>
           </p>
           <p>
             <strong
-              >Note that the examples below initialize the OptableSDK with cookies=false, so all ID transport is done
+              >Note that the examples below initialize the OptableSDK with cookies=false, so all ID storage is done
               using browser LocalStorage.</strong
             >
             Generally, it is preferable to use secure first party HTTP-only cookies for transporting IDs from
             OptableSDK. However, when the integrating website does not share the same top-level domain name with the
-            Optable Sandbox, then first party cookies are not reliable, and the LocalStorage method is suggested. To
-            enable it, simply initialize the OptableSDK object with the <code>cookies</code> option set to
-            <code>false</code>, and the SDK will do the rest.
+            Optable DCN, then first party cookies are not reliable, and the LocalStorage method is suggested. To enable
+            it, simply initialize the OptableSDK object with the <code>cookies</code> option set to <code>false</code>,
+            and the SDK will do the rest.
           </p>
         </div>
       </div>
@@ -51,28 +51,28 @@ <h5>Examples</h5>
           <table class="u-full-width">
             <thead>
               <tr>
-                <th>Link</th>
+                <th>API</th>
                 <th>Description</th>
               </tr>
             </thead>
             <tbody>
               <tr>
-                <td><a href="/vanilla/nocookies/identify.html">identify API</a></td>
+                <td><a href="/vanilla/nocookies/identify.html">identify</a></td>
                 <td>
                   Simple <code>script</code> tag integration showing how to send a hashed Email address and optional
-                  publisher user ID to your sandbox.
+                  publisher user ID to your DCN.
                 </td>
               </tr>
               <tr>
-                <td><a href="/vanilla/nocookies/witness.html">witness API</a></td>
-                <td>Shows how to log events with optional properties to your sandbox.</td>
+                <td><a href="/vanilla/nocookies/witness.html">witness</a></td>
+                <td>Shows how to log events with optional properties to your DCN.</td>
               </tr>
               <tr>
-                <td><a href="/vanilla/nocookies/profile.html">profile API</a></td>
-                <td>Shows how to set visitor traits (e.g., <code>age=45</code>) and sync them to your sandbox.</td>
+                <td><a href="/vanilla/nocookies/profile.html">profile</a></td>
+                <td>Shows how to set visitor traits (e.g., <code>age=45</code>) and sync them to your DCN.</td>
               </tr>
               <tr>
-                <td><a href="/vanilla/nocookies/targeting/gam360.html">targeting &amp; GAM360 activation</a></td>
+                <td><a href="/vanilla/nocookies/targeting/gam360.html">targeting: GAM360</a></td>
                 <td>
                   Shows how to load active cohorts for a visitor and pass them to
                   <a href="https://admanager.google.com/home/">Google Ad Manager</a> (GAM) via the
@@ -82,7 +82,7 @@ <h5>Examples</h5>
               </tr>
               <tr>
                 <td>
-                  <a href="/vanilla/nocookies/targeting/gam360-cached.html">cached targeting &amp; GAM360 activation</a>
+                  <a href="/vanilla/nocookies/targeting/gam360-cached.html">targeting: GAM360 (cached data)</a>
                 </td>
                 <td>
                   Shows how to load and cache active cohorts in a visitor's browser. Separately, cached cohorts are
@@ -91,15 +91,26 @@ <h5>Examples</h5>
                   ad targeting.
                 </td>
               </tr>
+              <tr>
+                <td><a href="/vanilla/nocookies/targeting/prebid.html">targeting: Prebid.js</a></td>
+                <td>
+                  Shows how to load and cache active cohorts in a visitor's browser. Separately, cached cohorts are
+                  passed to <a href="https://prebid.org/">Prebid.js</a> bidder adapters via the
+                  <a href="https://docs.prebid.org/features/firstPartyData.html#segments-and-taxonomy"
+                    >first-party data segments and taxonomy mechanism</a
+                  >.
+                </td>
+              </tr>
             </tbody>
           </table>
         </div>
       </div>
       <div class="row">
-        <div class="twelve column" style="font-size: 0.8rem; padding: 10px;">
+        <div class="twelve column" style="padding: 10px;">
           <center>
             <a href="https://www.optable.co/">Home</a> | <a href="https://www.optable.co/company/contact">Contact</a> |
-            <a href="https://optable.co/privacy">Privacy</a> |
+	    <a href="https://docs.optable.co/">Documentation</a> |
+            <a href="https://www.optable.co/privacy/products-and-services-privacy-policy">Privacy</a> |
             <a href="https://www.linkedin.com/company/optableco/">LinkedIn</a> |
             <a href="https://twitter.com/optable_co">Twitter</a>
           </center>