33Across user id sub-module: initial release (prebid#8335)

* wip * Rename lexicon param url to apiUrl and remove envelope param * Rename gvlid spec title - lexicon id system * add missing semicolon * apply code review feedback lexicon id system * Unit test coverage for the callback execution - lexicon id system * Add lexicon to user id integration example * Add lexicon is system markdown documentation * Update modules/lexiconIdSystem.js add colon to error message Co-authored-by: macinjosh32 <macinjosh32@users.noreply.github.com> * Send privacy strings in the lexicon id system request * apply code review feedback markdown lexicon documentation * Rename files with references to lexicon * rename 33across ID from lexicon to 33acrossId * fix failing unit tests incorrect URL and error message * Add 33acrossId reference in submodules & documentation Co-authored-by: macinjosh32 <macinjosh32@users.noreply.github.com>
tpmn-admin · May 9, 2022 · 3a73b00 · 3a73b00
1 parent f0d09dc
commit 3a73b00
Show file tree

Hide file tree

Showing 9 changed files with 650 additions and 2 deletions.
diff --git a/integrationExamples/gpt/userId_example.html b/integrationExamples/gpt/userId_example.html
@@ -77,6 +77,7 @@
                   "301": true,    // zeotapIdPlus
                   "91": true,     // criteo
                   "737": true,    // amxId
+                  "58": true,     // 33acrossId
                 }
               }
             }
@@ -128,6 +129,17 @@
                 "expires": 30
               }
             },
+            {
+              "name": "33acrossId",
+              "params": {
+                "pid": '0'
+              },
+              "storage": {
+                "type": 'html5',
+                "name": '33acrossId',
+                "expires": 90
+              }
+            },
             {
               "name": "intentIqId",
               "params": {

diff --git a/modules/.submodules.json b/modules/.submodules.json
@@ -1,5 +1,6 @@
 {
   "userId": [
+    "33acrossIdSystem",
     "admixerIdSystem",
     "adtelligentIdSystem",
     "akamaiDAPIdSystem",

diff --git a/modules/33acrossIdSystem.js b/modules/33acrossIdSystem.js
@@ -0,0 +1,115 @@
+/**
+ * This module adds 33acrossId to the User ID module
+ * The {@link module:modules/userId} module is required
+ * @module modules/33acrossIdSystem
+ * @requires module:modules/userId
+ */
+
+import { logMessage, logError } from '../src/utils.js';
+import { ajaxBuilder } from '../src/ajax.js';
+import { submodule } from '../src/hook.js';
+import { uspDataHandler } from '../src/adapterManager.js';
+
+const MODULE_NAME = '33acrossId';
+const API_URL = 'https://lexicon.33across.com/v1/envelope';
+const AJAX_TIMEOUT = 10000;
+
+function getEnvelope(response) {
+  if (!response.succeeded) {
+    logError(`${MODULE_NAME}: Unsuccessful response`);
+
+    return;
+  }
+
+  if (!response.data.envelope) {
+    logMessage(`${MODULE_NAME}: No envelope was received`);
+
+    return;
+  }
+
+  return response.data.envelope;
+}
+
+function calculateQueryStringParams(pid, gdprConsentData) {
+  const uspString = uspDataHandler.getConsentData();
+  const gdprApplies = Boolean(gdprConsentData?.gdprApplies);
+  const params = {
+    pid,
+    gdpr: Number(gdprApplies),
+  };
+
+  if (uspString) {
+    params.us_privacy = uspString;
+  }
+
+  if (gdprApplies) {
+    params.gdpr_consent = gdprConsentData.consentString || '';
+  }
+
+  return params;
+}
+
+/** @type {Submodule} */
+export const thirthyThreeAcrossIdSubmodule = {
+  /**
+   * used to link submodule with config
+   * @type {string}
+   */
+  name: MODULE_NAME,
+
+  gvlid: 58,
+
+  /**
+   * decode the stored id value for passing to bid requests
+   * @function
+   * @param {string} id
+   * @returns {{'33acrossId':{ envelope: string}}}
+   */
+  decode(id) {
+    return {
+      [MODULE_NAME]: {
+        envelope: id
+      }
+    };
+  },
+
+  /**
+   * performs action to obtain id and return a value in the callback's response argument
+   * @function
+   * @param {SubmoduleConfig} [config]
+   * @returns {IdResponse|undefined}
+   */
+  getId({ params = { } }, gdprConsentData) {
+    if (typeof params.pid !== 'string') {
+      logError(`${MODULE_NAME}: Submodule requires a partner ID to be defined`);
+
+      return;
+    }
+
+    const { pid, apiUrl = API_URL } = params;
+
+    return {
+      callback(cb) {
+        ajaxBuilder(AJAX_TIMEOUT)(apiUrl, {
+          success(response) {
+            let envelope;
+
+            try {
+              envelope = getEnvelope(JSON.parse(response))
+            } catch (err) {
+              logError(`${MODULE_NAME}: ID reading error:`, err);
+            }
+            cb(envelope);
+          },
+          error(err) {
+            logError(`${MODULE_NAME}: ID error response`, err);
+
+            cb();
+          }
+        }, calculateQueryStringParams(pid, gdprConsentData), { method: 'GET', withCredentials: true });
+      }
+    };
+  }
+};
+
+submodule('userId', thirthyThreeAcrossIdSubmodule);
diff --git a/modules/33acrossIdSystem.md b/modules/33acrossIdSystem.md
@@ -0,0 +1,53 @@
+# 33ACROSS ID
+
+For help adding this submodule, please contact [PrebidUIM@33across.com](PrebidUIM@33across.com).
+
+### Prebid Configuration
+
+You can configure this submodule in your `userSync.userIds[]` configuration:
+
+```javascript
+pbjs.setConfig({
+  userSync: {
+    userIds: [
+      {
+        name: "33acrossId",
+        storage: {
+          name: "33acrossId",
+          type: "html5",
+          expires: 90,
+          refreshInSeconds: 8*3600
+        },
+        params: {
+          pid: "0010b00002GYU4eBAH",
+        },
+      },
+    ],
+  },
+});
+```
+
+| Parameters under `userSync.userIds[]` | Scope    | Type   | Description                 | Example                                   |
+| ---| --- | --- | --- | --- |
+| name | Required | String | Name for the 33Across ID submodule | `"33acrossId"` |                                 |
+| storage                          | Required | Object | Configures how to cache User IDs locally in the browser | See [storage settings](#storage-settings) |
+| params                           | Required | Object | Parameters for 33Across ID submodule | See [params](#params)                     |
+
+### Storage Settings
+
+The following settings are available for the `storage` property in the `userSync.userIds[]` object:
+
+| Param name | Scope | Type | Description | Example   |
+| --- | --- | --- | --- | --- |
+| name | Required | String| Name of the cookie or HTML5 local storage where the user ID will be stored | `"33acrossId"` |
+| type | Required | String | `"html5"` (preferred)  or `"cookie"` | `"html5"` |
+| expires | Strongly Recommended | Number | How long (in days) the user ID information will be stored. 33Across recommends `90`. | `90` |
+| refreshInSeconds | Strongly Recommended | Number | The interval (in seconds) for refreshing the user ID. 33Across recommends no more than 8 hours between refreshes. | `8*3600` |
+
+### Params
+
+The following settings are available in the `params` property in `userSync.userIds[]` object:
+
+| Param name | Scope | Type | Description | Example |
+| --- | --- | --- | --- | --- |
+| pid | Required | String | Partner ID provided by 33Across | `"0010b00002GYU4eBAH"` |
diff --git a/modules/userId/eids.js b/modules/userId/eids.js
@@ -305,6 +305,15 @@ export const USER_IDS_CONFIG = {
     source: 'impact-ad.jp',
     atype: 1
   },
+
+  // 33across ID
+  '33acrossId': {
+    source: '33across.com',
+    atype: 1,
+    getValue: function(data) {
+      return data.envelope;
+    }
+  },
 };
 
 // this function will create an eid object for the given UserId sub-module

diff --git a/modules/userId/eids.md b/modules/userId/eids.md
@@ -2,6 +2,13 @@
 
 ```
 userIdAsEids = [
+    {
+        source: '33across.com',
+        uids: [{
+            id: 'some-random-id-value',
+            atype: 1
+        }]
+    },
     {
         source: 'trustpid.com',
         uids: [{

diff --git a/modules/userId/userId.md b/modules/userId/userId.md
@@ -6,6 +6,17 @@ Example showing `cookie` storage for user id data for each of the submodules
 pbjs.setConfig({
     userSync: {
         userIds: [{
+            name: "33acrossId",
+            storage: {
+                type: "cookie",
+                name: "33acrossId",
+                expires: 90,
+                refreshInSeconds: 8*3600
+            },
+            params: {
+                pid: "0010b00002GYU4eBAH" // Example ID
+            }
+        }, {
             name: "pubCommonId",
             storage: {
                 type: "cookie",
@@ -166,8 +177,18 @@ Example showing `localStorage` for user id data for some submodules
 ```
 pbjs.setConfig({
     userSync: {
-        userIds: [
-            {
+        userIds: [{
+            name: "33acrossId",
+            storage: {
+                type: "html5",
+                name: "33acrossId",
+                expires: 90,
+                refreshInSeconds: 8*3600
+            },
+            params: {
+                pid: "0010b00002GYU4eBAH" // Example ID
+            }
+        }, {
             name: 'trustpid',
             params: {
               maxDelayTime: 2500