PAIR: Support for Generic TechLab Version

[therevoltingx]

Clean Room Configuration

{
    userSync: {
      userIds: [{
        name: 'pairId',
        params: {
          mode: "open",
          liveramp: {
            storageKey: '_lr_pairId'
          },
          habu: {
            storageKey: '_habu_pairId'
          }
       },
    }]
  }
}

Bid Request

{
  "ext": {
    "eids": [
      "source": "iabtechlab.com",
      "uids": [
        {
          "id": "0x1234", // using clean room A
          "atype": 3
        },
        {
          "id": "0x456", // using clean room B
          "atype": 3
        }
      ]
    ]
  }
}

References

• https://github.com/InteractiveAdvertisingBureau/openrtb/blob/main/extensions/2.x_official_extensions/eids.md#object--extended-identifier-uids-
• Pair Id Module: generates multiple eids with same source #10479
• userId: group UIDs by source when possible #10488

[patmmccann]

your general approach is breaking and unlikely to be merged. I would recommend chatting before continuing

[pm-harshad-mane]

In future IAB may support another Alt ID, so the source for PAIR should clearly mention what it is.
Can we mention it as "pair-iab-tl.com"?

[therevoltingx]

isn't that what atype is for? like a single source can have multiple id types?

[jdwieland8282]

Here are the existing atype definitions https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/main/AdCOM%20v1.0%20FINAL.md#list_agenttypes

[pm-harshad-mane]

atype identifies the user agent types a user identifier is from.
IABTechLab may have another ID with same atype in future hence we should have clear identification in source that tells its a PAIR.

[pm-harshad-mane]

@therevoltingx mentioned we will have a unique atype to identify eid as a PAIR

[therevoltingx]

Make this configurable. Should be the DSP

[therevoltingx]

this is not included in the bid request at all. this is the owner of the module. we need prebid to confirm.
the prefered thing to do is to leave as-is.

[therevoltingx]

what is this? I assumed it was the ID type which is now a techlab id type

[therevoltingx]

confirm that this value was assigned to pair protocol

[jdwieland8282]

Identity PMC recommend that the IAB TL close this PR and open a new PR for their cleanroom implementation.

[pm-harshad-mane]

Sorry for the late update :-)

The code in the original pairIdSystem and the new module (which will have a PR created) will have a lot of duplication.

We talked about needing to change some parameter values, like switching the source from “google.com” to “iabtechlab.com” and updating or removing the GVL.

To avoid duplicating code, we can add a new optional “mode” parameter to the module. This parameter will adjust these values based on its setting.

If the “mode” parameter isn’t specified, the module will work the same as before with the original values (backward compatible). However, if the “mode” is set to “open,” the module will slightly change its behavior, like altering the source parameter to "iabtechlab.com" and the GVL reference.

[therevoltingx]

@pm-harshad-mane

I really like the idea. But for the eids method, how can I access the configuration? Gonna dig in but if you could point me to how I can access the config there that would be very helpful

[pm-harshad-mane]

@therevoltingx the getId method has access t o config and it is returning the id in eids format.
Which eids method are you referring to?

[therevoltingx]

@pm-harshad-mane I'm referring to line 103 in pairIdSystem.js. You can see the line here: https://github.com/prebid/Prebid.js/blob/master/modules/pairIdSystem.js#L103

The eids module attribute is called by modules/userId/eids.js: https://github.com/prebid/Prebid.js/blob/master/modules/userId/eids.js#L67

Which helps construct the final bid request object. That does not seem to have access to config.

[pm-harshad-mane]

@dgirardi can you help us? we are trying to avoid code duplication

[jlquaccia]

hey @therevoltingx @pm-harshad-mane, was taking a look into the code around the prebid pair module a bit from my end. what about something like this?

pbjs.setConfig:

userSync: {
  userIds: [{
    name: "pairId",
    storage: {
      type: "html5",
      name: "pairId"
    },
    params: {
      mode: "open"
    }
  }],
}

and then the following modifications to the pairIdSystem.js file (which could be further modified as needed):

/**
 * This module adds PAIR Id to the User ID module
 * The {@link module:modules/userId} module is required
 * @module modules/pairIdSystem
 * @requires module:modules/userId
 */

import { submodule } from '../src/hook.js';
import {getStorageManager} from '../src/storageManager.js'
import { logInfo } from '../src/utils.js';
import {MODULE_TYPE_UID} from '../src/activities/modules.js';

/**
 * @typedef {import('../modules/userId/index.js').Submodule} Submodule
 */

const MODULE_NAME = 'pairId';
const PAIR_ID_KEY = 'pairId';
const DEFAULT_LIVERAMP_PAIR_ID_KEY = '_lr_pairId';

const MODE_CONFIG = {
  default: {
    source: 'google.com',
    gvlid: 755
  },
  open: {
    source: 'iabtechlab.com',
    gvlid: 999
  },
};

export const storage = getStorageManager({moduleType: MODULE_TYPE_UID, moduleName: MODULE_NAME});

function pairIdFromLocalStorage(key) {
  return storage.localStorageIsEnabled() ? storage.getDataFromLocalStorage(key) : null;
}

function pairIdFromCookie(key) {
  return storage.cookiesAreEnabled() ? storage.getCookie(key) : null;
}

/** @type {Submodule} */
export const pairIdSubmodule = {
  /**
   * used to link submodule with config
   * @type {string}
   */
  name: MODULE_NAME,
  /**
   * used to specify vendor id
   * @type {number}
   */
  gvlid: MODE_CONFIG.default.gvlid,
  /**
   * decode the stored id value for passing to bid requests
   * @function
   * @param { string | undefined } value
   * @returns {{pairId:string} | undefined }
   */
  decode(value) {
    return value && Array.isArray(value) ? {'pairId': value} : undefined
  },
  /**
   * Performs action to obtain ID and return a value in the callback's response argument.
   * @function getId
   * @param {Object} config - The configuration object.
   * @param {Object} config.params - The parameters from the configuration.
   * @returns {{id: string[] | undefined}} The obtained IDs or undefined if no IDs are found.
   */
  getId(config) {
    const mode = (config && config.params && config.params.mode) || 'default';
    const selectedModeConfig = MODE_CONFIG[mode] || MODE_CONFIG.default;
    const source = selectedModeConfig.source;

    this.gvlid = selectedModeConfig.gvlid;
    this.eids.pairId.source = source;

    const pairIdsString = pairIdFromLocalStorage(PAIR_ID_KEY) || pairIdFromCookie(PAIR_ID_KEY)
    let ids = []
    if (pairIdsString && typeof pairIdsString == 'string') {
      try {
        ids = ids.concat(JSON.parse(atob(pairIdsString)))
      } catch (error) {
        logInfo(error)
      }
    }

    const configParams = (config && config.params) || {};
    if (configParams && configParams.liveramp) {
      let LRStorageLocation = configParams.liveramp.storageKey || DEFAULT_LIVERAMP_PAIR_ID_KEY;
      const liverampValue = pairIdFromLocalStorage(LRStorageLocation) || pairIdFromCookie(LRStorageLocation);

      if (liverampValue) {
        try {
          const parsedValue = atob(liverampValue);
          if (parsedValue) {
            const obj = JSON.parse(parsedValue);

            if (obj && typeof obj === 'object' && obj.envelope) {
              ids = ids.concat(obj.envelope);
            } else {
              logInfo('Pairid: Parsed object is not valid or does not contain envelope');
            }
          } else {
            logInfo('Pairid: Decoded value is empty');
          }
        } catch (error) {
          logInfo('Pairid: Error parsing JSON: ', error);
        }
      } else {
        logInfo('Pairid: liverampValue for pairId from storage is empty or null');
      }
    }

    if (ids.length == 0) {
      logInfo('PairId not found.')
      return undefined;
    }

    return {'id': ids};
  },
  eids: {
    'pairId': {
      source: MODE_CONFIG.default.source,
      atype: 571187
    },
  }
};

submodule('userId', pairIdSubmodule);

[jlquaccia]

@dgirardi wondering what your thoughts on the suggestion above might be? seems to work fine locally, but curious if there are any other elements i am not considering..

[therevoltingx]

@jlquaccia
My main concern here is that the caller must call getId() first in order for eids to return the correct values.