Mediawallah ID System: add openlink userId submodule (prebid#5921)

* My first commit

* Removed unnecessary await operation

* Bug fixes and compliance fixes

* Fixing some formatting and naming

* Updating code based on automated feedback.

* Parking refactoring change for team review

* update mwOpenLink module

* remove .git 2 folder

* Trying to force a change

* update the PR comments

* applying the changes

* update submodules.json and userId.md

* fix typo of module names

* update module decode function and test code

* update test codes

* apply the suggestions from Prebid

* fix count of modules.

Co-authored-by: Eric Brown <eric@mediawallah.com>
Co-authored-by: hanna <hanna.panova190119@gmail.com>
Co-authored-by: hannapanova190119 <71532550+hannapanova190119@users.noreply.github.com>

modules/.submodules.json

@@ -20,6 +20,7 @@
     "fabrickIdSystem",
     "verizonMediaIdSystem",
     "pubProvidedIdSystem",
+    "mwOpenLinkIdSystem",
     "tapadIdSystem",
     "novatiqIdSystem"
   ],

modules/mwOpenLinkIdSystem.js

@@ -0,0 +1,142 @@
+/**
+ * This module adds MediaWallah OpenLink to the User ID module
+ * The {@link module:modules/userId} module is required
+ * @module modules/mwOpenLinkIdSystem
+ * @requires module:modules/userId
+ */
+
+import * as utils from '../src/utils.js';
+import { ajax } from '../src/ajax.js';
+import { submodule } from '../src/hook.js';
+import { getStorageManager } from '../src/storageManager.js';
+
+const openLinkID = {
+  name: 'mwol',
+  cookie_expiration: (86400 * 1000 * 365 * 1) // 1 year
+}
+
+const storage = getStorageManager();
+
+function getExpirationDate() {
+  return (new Date(utils.timestamp() + openLinkID.cookie_expiration)).toGMTString();
+}
+
+function isValidConfig(configParams) {
+  if (!configParams) {
+    utils.logError('User ID - mwOlId submodule requires configParams');
+    return false;
+  }
+  if (!configParams.accountId) {
+    utils.logError('User ID - mwOlId submodule requires accountId to be defined');
+    return false;
+  }
+  if (!configParams.partnerId) {
+    utils.logError('User ID - mwOlId submodule requires partnerId to be defined');
+    return false;
+  }
+  return true;
+}
+
+function deserializeMwOlId(mwOlIdStr) {
+  const mwOlId = {};
+  const mwOlIdArr = mwOlIdStr.split(',');
+
+  mwOlIdArr.forEach(function(value) {
+    const pair = value.split(':');
+    // unpack a value of 1 as true
+    mwOlId[pair[0]] = +pair[1] === 1 ? true : pair[1];
+  });
+
+  return mwOlId;
+}
+
+function serializeMwOlId(mwOlId) {
+  let components = [];
+
+  if (mwOlId.eid) {
+    components.push('eid:' + mwOlId.eid);
+  }
+  if (mwOlId.ibaOptout) {
+    components.push('ibaOptout:1');
+  }
+  if (mwOlId.ccpaOptout) {
+    components.push('ccpaOptout:1');
+  }
+
+  return components.join(',');
+}
+
+function readCookie(name) {
+  if (!name) name = openLinkID.name;
+  const mwOlIdStr = storage.getCookie(name);
+  if (mwOlIdStr) {
+    return deserializeMwOlId(decodeURIComponent(mwOlIdStr));
+  }
+  return null;
+}
+
+function writeCookie(mwOlId) {
+  if (mwOlId) {
+    const mwOlIdStr = encodeURIComponent(serializeMwOlId(mwOlId));
+    storage.setCookie(openLinkID.name, mwOlIdStr, getExpirationDate(), 'lax');
+  }
+}
+
+function register(configParams, olid) {
+  const { accountId, partnerId, uid } = configParams;
+  const url = 'https://ol.mediawallahscript.com/?account_id=' + accountId +
+            '&partner_id=' + partnerId +
+            '&uid=' + uid +
+            '&olid=' + olid +
+            '&cb=' + Math.random()
+            ;
+  ajax(url);
+}
+
+function setID(configParams) {
+  if (!isValidConfig(configParams)) return undefined;
+  const mwOlId = readCookie();
+  const newMwOlId = mwOlId ? utils.deepClone(mwOlId) : {eid: utils.generateUUID()};
+  writeCookie(newMwOlId);
+  register(configParams, newMwOlId.eid);
+  return {
+    id: newMwOlId
+  };
+};
+
+/* End MW */
+
+export { writeCookie };
+
+/** @type {Submodule} */
+export const mwOpenLinkIdSubModule = {
+  /**
+     * used to link submodule with config
+     * @type {string}
+     */
+  name: 'mwOpenLinkId',
+  /**
+     * decode the stored id value for passing to bid requests
+     * @function
+     * @param {MwOlId} mwOlId
+     * @return {(Object|undefined}
+     */
+  decode(mwOlId) {
+    const id = mwOlId && utils.isPlainObject(mwOlId) ? mwOlId.eid : undefined;
+    return id ? { 'mwOpenLinkId': id } : undefined;
+  },
+
+  /**
+     * performs action to obtain id and return a value in the callback's response argument
+     * @function
+     * @param {SubmoduleParams} [submoduleParams]
+     * @returns {id:MwOlId | undefined}
+     */
+  getId(submoduleConfig) {
+    const submoduleConfigParams = (submoduleConfig && submoduleConfig.params) || {};
+    if (!isValidConfig(submoduleConfigParams)) return undefined;
+    return setID(submoduleConfigParams);
+  }
+};
+
+submodule('userId', mwOpenLinkIdSubModule);

modules/mwOpenLinkIdSystem.md

@@ -0,0 +1,43 @@
+## MediaWallah openLink User ID Submodule
+
+OpenLink ID User ID Module generates a UUID that can be utilized to improve user matching. This module enables timely synchronization which handles MediaWallah optout. You must have a pre-existing relationship with MediaWallah prior to integrating.  
+
+### Building Prebid with openLink Id Support
+Your Prebid build must include the modules for both **userId** and **mwOpenLinkId** submodule. Follow the build instructions for Prebid as
+explained in the top level README.md file of the Prebid source tree.
+
+ex: $ gulp build --modules=userId,mwOpenLinkIdSystem
+
+##$ MediaWallah openLink ID Example Configuration
+
+When the module is included, it's automatically enabled and saves an id to both cookie with an expiration time of 1 year.  
+
+### Prebid Params
+
+Individual params may be set for the MediaWallah openLink User ID Submodule. At least accountId and partnerId must be set in the params.
+
+```javascript
+pbjs.setConfig({
+    userSync: {
+        userIds: [{
+            name: 'mwOpenLinkId',
+            params: {
+                accountId: '1000',
+                partnerId: '1001',
+                uid: 'u-123xyz'
+            }
+        }]
+    }
+});
+```
+
+### Parameter Descriptions for the `usersync` Configuration Section
+The below parameters apply only to the MediaWallah OpenLink ID User ID Module integration.
+
+| Params under usersync.userIds[]| Scope | Type | Description | Example |
+| --- | --- | --- | --- | --- |
+| name | Required | String | The name of this module. | `'mwOpenLinkId'` |
+| params | Required | Object | Details for mwOLID syncing. | |
+| params.accountId | Required | String | The MediaWallah assigned Account Id | `1000` |
+| params.partnerId | Required | String | The MediaWallah assign Partner Id | `1001` |
+| params.uid | Optional | String | Your unique Id for the user or browser. Used for matching | `u-123xyz` |

modules/userId/eids.js

@@ -169,11 +169,15 @@ const USER_IDS_CONFIG = {
     source: 'neustar.biz',
     atype: 1
   },
+  // MediaWallah OpenLink
+  'mwOpenLinkId': {
+    source: 'mediawallahscript.com',
+    atype: 1
+  },
   'tapadId': {
     source: 'tapad.com',
     atype: 1
   },
-
   // Novatiq Snowflake
   'novatiq': {
     getValue: function(data) {

modules/userId/eids.md

@@ -142,6 +142,13 @@ userIdAsEids = [
             atype: 1
         }]
     },
+    {
+        source: 'mediawallahscript.com',
+        uids: [{
+            id: 'some-random-id-value',
+            atype: 1
+        }]
+    },
     {
         source: 'tapad.com',
         uids: [{

modules/userId/userId.md

@@ -77,6 +77,13 @@ pbjs.setConfig({
                  name: '_criteoId',
                  expires: 1
               }
+        }, {
+            name: 'mwOpenLinkId',
+            params: {
+                accountId: 0000,
+                partnerId: 0000,
+                uid: '12345xyz'
+            }
         }],
         syncDelay: 5000,
         auctionDelay: 1000

test/spec/modules/mwOpenLinkIdSystem_spec.js

@@ -0,0 +1,20 @@
+import { writeCookie, mwOpenLinkIdSubModule } from 'modules/mwOpenLinkIdSystem.js';
+
+const P_CONFIG_MOCK = {
+  params: {
+    accountId: '123',
+    partnerId: '123'
+  }
+};
+
+describe('mwOpenLinkId module', function () {
+  beforeEach(function() {
+    writeCookie('');
+  });
+
+  it('getId() should return a MediaWallah openLink Id when the MediaWallah openLink first party cookie exists', function () {
+    writeCookie({eid: 'XX-YY-ZZ-123'});
+    const id = mwOpenLinkIdSubModule.getId(P_CONFIG_MOCK);
+    expect(id).to.be.deep.equal({id: {eid: 'XX-YY-ZZ-123'}});
+  });
+});