prebid.js 7.52.0 → 7.53.0

package/modules/uid2IdSystem.js

@@ -6,16 +6,19 @@
  * @requires module:modules/userId
  */
 
-import { logInfo } from '../src/utils.js';
+import { logInfo, logWarn } from '../src/utils.js';
 import {submodule} from '../src/hook.js';
 import {getStorageManager} from '../src/storageManager.js';
 import {MODULE_TYPE_UID} from '../src/activities/modules.js';
 
+// RE below lint exception: UID2 and EUID are separate modules, but the protocol is the same and shared code makes sense here.
+// eslint-disable-next-line prebid/validate-imports
+import { Uid2GetId, Uid2CodeVersion } from './uid2IdSystem_shared.js';
+
 const MODULE_NAME = 'uid2';
-const MODULE_REVISION = `1.0`;
+const MODULE_REVISION = Uid2CodeVersion;
 const PREBID_VERSION = '$prebid.version$';
 const UID2_CLIENT_ID = `PrebidJS-${PREBID_VERSION}-UID2Module-${MODULE_REVISION}`;
-const GVLID = 887;
 const LOG_PRE_FIX = 'UID2: ';
 const ADVERTISING_COOKIE = '__uid2_advertising_token';
 
@@ -24,131 +27,15 @@ const UID2_TEST_URL = 'https://operator-integ.uidapi.com';
 const UID2_PROD_URL = 'https://prod.uidapi.com';
 const UID2_BASE_URL = UID2_PROD_URL;
 
-function getStorage() {
-  return getStorageManager({moduleType: MODULE_TYPE_UID, moduleName: MODULE_NAME});
-}
-
-function createLogInfo(prefix) {
+function createLogger(logger, prefix) {
   return function (...strings) {
-    logInfo(prefix + ' ', ...strings);
-  }
-}
-export const storage = getStorage();
-const _logInfo = createLogInfo(LOG_PRE_FIX);
-
-function readFromLocalStorage() {
-  return storage.localStorageIsEnabled() ? storage.getDataFromLocalStorage(ADVERTISING_COOKIE) : null;
-}
-
-function readModuleCookie() {
-  const cookie = readCookie(ADVERTISING_COOKIE);
-  if (cookie && cookie.includes('{')) {
-    return JSON.parse(cookie);
+    logger(prefix + ' ', ...strings);
   }
-  return cookie;
-}
-
-function readJsonCookie(cookieName) {
-  return JSON.parse(readCookie(cookieName));
-}
-
-function readCookie(cookieName) {
-  const cookie = storage.cookiesAreEnabled() ? storage.getCookie(cookieName) : null;
-  if (!cookie) {
-    _logInfo(`Attempted to read UID2 from cookie '${cookieName}' but it was empty`);
-    return null;
-  };
-  _logInfo(`Read UID2 from cookie '${cookieName}'`);
-  return cookie;
 }
+const _logInfo = createLogger(logInfo, LOG_PRE_FIX);
+const _logWarn = createLogger(logWarn, LOG_PRE_FIX);
 
-function storeValue(value) {
-  if (storage.cookiesAreEnabled()) {
-    storage.setCookie(ADVERTISING_COOKIE, JSON.stringify(value), Date.now() + 60 * 60 * 24 * 1000);
-  } else if (storage.localStorageIsEnabled()) {
-    storage.setLocalStorage(ADVERTISING_COOKIE, value);
-  }
-}
-
-function isValidIdentity(identity) {
-  return !!(typeof identity === 'object' && identity !== null && identity.advertising_token && identity.identity_expires && identity.refresh_from && identity.refresh_token && identity.refresh_expires);
-}
-
-// This is extracted from an in-progress API client. Once it's available via NPM, this class should be replaced with the NPM package.
-class Uid2ApiClient {
-  constructor(opts) {
-    this._baseUrl = opts.baseUrl ? opts.baseUrl : UID2_BASE_URL;
-    this._clientVersion = UID2_CLIENT_ID;
-  }
-  createArrayBuffer(text) {
-    const arrayBuffer = new Uint8Array(text.length);
-    for (let i = 0; i < text.length; i++) {
-      arrayBuffer[i] = text.charCodeAt(i);
-    }
-    return arrayBuffer;
-  }
-  hasStatusResponse(response) {
-    return typeof (response) === 'object' && response && response.status;
-  }
-  isValidRefreshResponse(response) {
-    return this.hasStatusResponse(response) && (
-      response.status === 'optout' || response.status === 'expired_token' || (response.status === 'success' && response.body && isValidIdentity(response.body))
-    );
-  }
-  ResponseToRefreshResult(response) {
-    if (this.isValidRefreshResponse(response)) {
-      if (response.status === 'success') { return { status: response.status, identity: response.body }; }
-      return response;
-    } else { return "Response didn't contain a valid status"; }
-  }
-  callRefreshApi(refreshDetails) {
-    const url = this._baseUrl + '/v2/token/refresh';
-    const req = new XMLHttpRequest();
-    req.overrideMimeType('text/plain');
-    req.open('POST', url, true);
-    req.setRequestHeader('X-UID2-Client-Version', this._clientVersion);
-    let resolvePromise;
-    let rejectPromise;
-    const promise = new Promise((resolve, reject) => {
-      resolvePromise = resolve;
-      rejectPromise = reject;
-    });
-    req.onreadystatechange = () => {
-      if (req.readyState !== req.DONE) { return; }
-      try {
-        if (!refreshDetails.refresh_response_key || req.status !== 200) {
-          _logInfo('Error status OR no response decryption key available, assuming unencrypted JSON');
-          const response = JSON.parse(req.responseText);
-          const result = this.ResponseToRefreshResult(response);
-          if (typeof result === 'string') { rejectPromise(result); } else { resolvePromise(result); }
-        } else {
-          _logInfo('Decrypting refresh API response');
-          const encodeResp = this.createArrayBuffer(atob(req.responseText));
-          window.crypto.subtle.importKey('raw', this.createArrayBuffer(atob(refreshDetails.refresh_response_key)), { name: 'AES-GCM' }, false, ['decrypt']).then((key) => {
-            _logInfo('Imported decryption key')
-            // returns the symmetric key
-            window.crypto.subtle.decrypt({
-              name: 'AES-GCM',
-              iv: encodeResp.slice(0, 12),
-              tagLength: 128, // The tagLength you used to encrypt (if any)
-            }, key, encodeResp.slice(12)).then((decrypted) => {
-              const decryptedResponse = String.fromCharCode(...new Uint8Array(decrypted));
-              _logInfo('Decrypted to:', decryptedResponse);
-              const response = JSON.parse(decryptedResponse);
-              const result = this.ResponseToRefreshResult(response);
-              if (typeof result === 'string') { rejectPromise(result); } else { resolvePromise(result); }
-            }, (reason) => console.warn(`Call to UID2 API failed`, reason));
-          }, (reason) => console.warn(`Call to UID2 API failed`, reason));
-        }
-      } catch (err) {
-        rejectPromise(err);
-      }
-    };
-    _logInfo('Sending refresh request', req);
-    req.send(refreshDetails.refresh_token);
-    return promise;
-  }
-}
+export const storage = getStorageManager({moduleType: MODULE_TYPE_UID, moduleName: MODULE_NAME});
 
 /** @type {Submodule} */
 export const uid2IdSubmodule = {
@@ -158,11 +45,6 @@ export const uid2IdSubmodule = {
    */
   name: MODULE_NAME,
 
-  /**
-   * Vendor id of Prebid
-   * @type {Number}
-   */
-  gvlid: GVLID,
   /**
    * decode the stored id value for passing to bid requests
    * @function
@@ -183,29 +65,29 @@ export const uid2IdSubmodule = {
    * @returns {uid2Id}
    */
   getId(config, consentData) {
-    const result = getIdImpl(config, consentData);
+    if (consentData?.gdprApplies === true) {
+      _logWarn('UID2 is not intended for use where GDPR applies. The UID2 module will not run.');
+      return;
+    }
+
+    const mappedConfig = {
+      apiBaseUrl: config?.params?.uid2ApiBase ?? UID2_BASE_URL,
+      paramToken: config?.params?.uid2Token,
+      serverCookieName: config?.params?.uid2Cookie ?? config?.params?.uid2ServerCookie,
+      storage: config?.params?.storage ?? 'localStorage',
+      clientId: UID2_CLIENT_ID,
+      internalStorage: ADVERTISING_COOKIE
+    }
+    _logInfo(`UID2 configuration loaded and mapped.`, mappedConfig);
+    const result = Uid2GetId(mappedConfig, storage, _logInfo, _logWarn);
     _logInfo(`UID2 getId returned`, result);
     return result;
   },
 };
 
-function refreshTokenAndStore(baseUrl, token) {
-  _logInfo('UID2 base url provided: ', baseUrl);
-  const client = new Uid2ApiClient({baseUrl});
-  return client.callRefreshApi(token).then((response) => {
-    _logInfo('Refresh endpoint responded with:', response);
-    const tokens = {
-      originalToken: token,
-      latestToken: response.identity,
-    };
-    storeValue(tokens);
-    return tokens;
-  });
-}
-
 function decodeImpl(value) {
   if (typeof value === 'string') {
-    _logInfo('Found an old-style ID from an earlier version of the module. Refresh is unavailable for this token.');
+    _logInfo('Found server-only token. Refresh is unavailable for this token.');
     const result = { uid2: { id: value } };
     return result;
   }
@@ -215,70 +97,5 @@ function decodeImpl(value) {
   return null;
 }
 
-function getIdImpl(config, consentData) {
-  let suppliedToken = null;
-  const uid2BaseUrl = config?.params?.uid2ApiBase ?? UID2_BASE_URL;
-  if (config && config.params) {
-    if (config.params.uid2Token) {
-      suppliedToken = config.params.uid2Token;
-      _logInfo('Read token from params', suppliedToken);
-    } else if (config.params.uid2ServerCookie) {
-      suppliedToken = readJsonCookie(config.params.uid2ServerCookie);
-      _logInfo('Read token from server-supplied cookie', suppliedToken);
-    }
-  }
-  let storedTokens = readModuleCookie() || readFromLocalStorage();
-  _logInfo('Loaded module-stored tokens:', storedTokens);
-
-  if (storedTokens && typeof storedTokens === 'string') {
-    // Legacy value stored, this must be from an old integration. If no token supplied, just use the legacy value.
-
-    if (!suppliedToken) {
-      _logInfo('Returning legacy cookie value.');
-      return { id: storedTokens };
-    }
-    // Otherwise, ignore the legacy value - it should get over-written later anyway.
-    _logInfo('Discarding superseded legacy cookie.');
-    storedTokens = null;
-  }
-
-  if (suppliedToken && storedTokens) {
-    if (storedTokens.originalToken?.advertising_token !== suppliedToken.advertising_token) {
-      _logInfo('Server supplied new token - ignoring stored value.', storedTokens.originalToken?.advertising_token, suppliedToken.advertising_token);
-      // Stored token wasn't originally sourced from the provided token - ignore the stored value. A new user has logged in?
-      storedTokens = null;
-    }
-  }
-  // At this point, any legacy values or superseded stored tokens have been nulled out.
-  const useSuppliedToken = !(storedTokens?.latestToken) || (suppliedToken && suppliedToken.identity_expires > storedTokens.latestToken.identity_expires);
-  const newestAvailableToken = useSuppliedToken ? suppliedToken : storedTokens.latestToken;
-  _logInfo('UID2 module selected latest token', useSuppliedToken, newestAvailableToken);
-  if (!newestAvailableToken || Date.now() > newestAvailableToken.refresh_expires) {
-    _logInfo('Newest available token is expired and not refreshable.');
-    return { id: null };
-  }
-  if (Date.now() > newestAvailableToken.identity_expires) {
-    const promise = refreshTokenAndStore(uid2BaseUrl, newestAvailableToken);
-    _logInfo('Token is expired but can be refreshed, attempting refresh.');
-    return { callback: (cb) => {
-      promise.then((result) => {
-        _logInfo('Refresh reponded, passing the updated token on.', result);
-        cb(result);
-      });
-    } };
-  }
-  // If should refresh (but don't need to), refresh in the background.
-  if (Date.now() > newestAvailableToken.refresh_from) {
-    _logInfo(`Refreshing token in background with low priority.`);
-    refreshTokenAndStore(uid2BaseUrl, newestAvailableToken);
-  }
-  const tokens = {
-    originalToken: suppliedToken ?? storedTokens?.originalToken,
-    latestToken: newestAvailableToken,
-  };
-  storeValue(tokens);
-  return { id: tokens };
-}
-
 // Register submodule for userId
 submodule('userId', uid2IdSubmodule);

package/modules/uid2IdSystem.md

@@ -1,25 +1,56 @@
-## UID 2.0 User ID Submodule
+## UID2 User ID Submodule
 
-UID 2.0 ID Module.
+UID2 requires initial tokens to be generated server-side. The UID2 module handles storing, providing, and optionally refreshing them. The module can operate in one of two different modes: *Client Refresh* mode or *Server Only* mode.
 
-### Prebid Params
+*Server Only* mode was originally referred to as *legacy mode*, but it is a popular mode for new integrations where publishers prefer to handle token refresh server-side.
 
-Individual params may be set for the UID 2.0 Submodule. At least one identifier must be set in the params.
+**Important information:** UID2 is not designed to be used where GDPR applies. The module checks the passed-in consent data and will not operate if the `gdprApplies` flag is true.
 
-The module will handle refreshing the token periodically and storing the updated token using the Prebid.js storage manager. If you provide an expired identity and the module has a valid identity which was refreshed from the identity you provide, it will use the refreshed identity. The module stores the original token used for refreshing the token, and it will use the refreshed tokens as long as the original token matches the one supplied.
+## Client Refresh mode
 
+This is the recommended mode for most scenarios. In this mode, the full response body from the UID2 Token Generate or Token Refresh endpoint must be provided to the module. As long as the refresh token remains valid, the module will refresh the advertising token as needed.
+
+To configure the module to use this mode, you must **either**:
+1. Set `params.uid2Cookie` to the name of the cookie which contains the response body as a JSON string, **or**
+2. Set `params.uid2Token` to the response body as a JavaScript object.
+
+The `uid2Cookie` param was originally `uid2ServerCookie`. The old name can still be used, however the inclusion of the word 'server' was causing some confusion. If both values are provided, `uid2ServerCookie` will be ignored.
+
+### Client refresh cookie example
+
+In this example, the cookie is called `uid2_pub_cookie`.
+
+Cookie:
+```
+uid2_pub_cookie={"advertising_token":"...advertising token...","refresh_token":"...refresh token...","identity_expires":1684741472161,"refresh_from":1684741425653,"refresh_expires":1684784643668,"refresh_response_key":"...response key..."}
+```
+
+Configuration:
+```
+pbjs.setConfig({
+    userSync: {
+        userIds: [{
+            name: 'uid2',
+            params: {
+                uid2Cookie: 'uid2_pub_cookie'
+            }
+        }]
+    }
+});
+```
+
+### Client refresh uid2Token example
+
+Configuration:
 ```
 pbjs.setConfig({
     userSync: {
         userIds: [{
             name: 'uid2',
             params: {
-                // Either:
-                uid2ServerCookie: 'your_UID2_server_set_cookie_name'
-                // Or:
                 uid2Token: {
-                    'advertising_token': '...',
-                    'refresh_token': '...',
+                    'advertising_token': '...advertising token...',
+                    'refresh_token': '...refresh token...',
                     // etc. - see the Sample Token below for contents of this object
                 }
             }
@@ -27,28 +58,78 @@ pbjs.setConfig({
     }
 });
 ```
-## Parameter Descriptions for the `usersync` Configuration Section
-The below parameters apply only to the UID 2.0 User ID Module integration.
 
-You should supply either `uid2Token` or `uid2ServerCookie`.
+## Server-Only Mode
 
-If you provide `uid2Token`, the value should be a JavaScript/JSON object with the decrypted `body` payload response from a call to either `/token/generate` or `/token/refresh`.
+In this mode, only the advertising token is provided to the module. The module will not be able to refresh the token. The publisher is responsible for implementing some other way to refresh the token.
 
-If you provide `uid2ServerCookie`, the module will expect that same JSON object to be stored in the cookie - i.e. it will pass the cookie value to `JSON.parse` and expect to receive an object containing similar to what you see in the `Sample token` section below.
+To configure the module to use this mode, you must **either**:
+1. Set a cookie named `__uid2_advertising_token` to the advertising token, **or**
+2. Set `value` to an ID block containing the advertising token (see "Server only value" example below).
 
-The module will make calls to the `/token/refresh` endpoint to update the token it stores internally, so bids may contain an updated token.
+### Server only cookie example
 
-If neither of `uid2Token` or `uid2ServerCookie` are supplied, and the module has stored a token using the Prebid.js storage system (typically in a cookie named `__uid2_advertising_token`), it will use that token. This cookie is internal to the module and should not be set directly.
+Cookie:
+```
+__uid2_advertising_token=...advertising token...
+```
 
-If a new token is supplied which does not match the original token used to generate any refreshed tokens, all stored tokens will be discarded and the new token used instead (refreshed if necessary).
+Configuration:
+```
+pbjs.setConfig({
+    userSync: {
+        userIds: [{
+            name: 'uid2'
+        }]
+    }
+});
+```
+
+### Server only value example
+
+Configuration:
+```
+pbjs.setConfig({
+    userSync: {
+        userIds: [{
+            name: 'uid2'
+            value: {
+                'uid2': {
+                    'id': '...advertising token...'
+                }
+            }
+        }]
+    }
+});
+```
+
+## Storage
 
-### Sample token
+The module stores a number of internal values. By default, all values are stored in HTML5 local storage. You can switch to cookie storage by setting `params.storage` to `cookie`. The cookie size can be significant and this is not recommended, but is provided as an option if local storage is not an option.
+
+## Sample token
 
 `{`<br />&nbsp;&nbsp;`"advertising_token": "...",`<br />&nbsp;&nbsp;`"refresh_token": "...",`<br />&nbsp;&nbsp;`"identity_expires": 1633643601000,`<br />&nbsp;&nbsp;`"refresh_from": 1633643001000,`<br />&nbsp;&nbsp;`"refresh_expires": 1636322000000,`<br />&nbsp;&nbsp;`"refresh_response_key": "wR5t6HKMfJ2r4J7fEGX9Gw=="`<br />`}`
 
+### Notes
+
+If you are trying to limit the size of cookies, provide the token in configuration and use the default option of local storage.
+
+If you provide an expired identity and the module has a valid identity which was refreshed from the identity you provide, it will use the refreshed identity. The module stores the original token used for refreshing the token, and it will use the refreshed tokens as long as the original token matches the one supplied.
+
+If a new token is supplied which does not match the original token used to generate any refreshed tokens, all stored tokens will be discarded and the new token used instead (refreshed if necessary).
+
+You can set `params.uid2ApiBase` to `"https://operator-integ.uidapi.com"` during integration testing. Be aware that you must use the same environment (production or integration) here as you use for generating tokens.
+
+## Parameter Descriptions for the `usersync` Configuration Section
+
+The below parameters apply only to the UID2 User ID Module integration.
+
 | Param under userSync.userIds[] | Scope | Type | Description | Example |
 | --- | --- | --- | --- | --- |
-| name | Required | String | ID value for the UID20 module - `"uid2"` | `"uid2"` |
-| params.uid2Token | Optional | Object | The initial UID2 token. This should be `body` element of the decrypted response from a call to the `/token/generate` or `/token/refresh` endpoint. | See the sample token above. |
-| params.uid2ServerCookie | Optional | String | The name of a cookie which holds the initial UID2 token, set by the server. The cookie should contain JSON in the same format as the alternative uid2Token param. **If uid2Token is supplied, this param is ignored.** | See the sample token above. |
-| params.uid2ApiBase | Optional | String | Overrides the default UID2 API endpoint. | `https://prod.uidapi.com` _(default)_ |
+| name | Required | String | ID value for the UID2 module - `"uid2"` | `"uid2"` |
+| value | Optional, Server only | Object | An object containing the value for the advertising token. | See the example above. |
+| params.uid2Token | Optional, Client refresh | Object | The initial UID2 token. This should be `body` element of the decrypted response from a call to the `/token/generate` or `/token/refresh` endpoint. | See the sample token above. |
+| params.uid2Cookie | Optional, Client refresh | String | The name of a cookie which holds the initial UID2 token, set by the server. The cookie should contain JSON in the same format as the uid2Token param. **If uid2Token is supplied, this param is ignored.** | See the sample token above. |
+| params.uid2ApiBase | Optional, Client refresh | String | Overrides the default UID2 API endpoint. | `"https://prod.uidapi.com"` _(default)_|
+| params.storage | Optional, Client refresh | String | Specify whether to use `cookie` or `localStorage` for module-internal storage. It is recommended to not provide this and allow the module to use the default. | `localStorage` _(default)_ |