Link

Implementing OA.JS

To implement oa.js, call the start(config) function with a configuration object. start(config) is the only function you need to call when you need to trigger resolution.

The recommendation is to place oa.js in the header of the page to ensure identities make it into the bid-stream. Since these identities are stored in a cookie for subsequent page views the impact to page performance is very small. The standard way to call this function in an asynchronous manner is to utilize the oa.js command queue.

example of an asynchronous implementation

var oajsConfig = {
    "storage_type": "cookie", // "cookie" or "localStorage"
    "email": "email@email.com", // plain-text user email address if available
    "placementID": "16", // LiveRamp placement id
    "tdidPartnerID": "openx", // Trade Desk ID partner id
    "oaID": "6789", // OpenAudience account id
}

window.oajs = window.oajs || {cmd: []};
oajs.cmd.push(function() {
    oajs.start(oajsConfig)
});

(function() {
    var oa = document.createElement("script");
    oa.async = true;
    oa.type = "text/javascript";
    oa.src = 'https://oa.openxcdn.net/oa.js';
    document.head.appendChild(oa);
}());

Prebid.js Bidstream Integration Type

The bidstream integration type supported by oa.js is Prebid. To set up Prebid.js with oa.js identifiers, prebid core version 2.34.0+ is required, but we recommend to update to the latest version of Prebid.js. Once you are on a supported version, include the User ID and IdentityLink ID modules.

  • IdentityLink: oa.js exposes the window.ats namespace to communicate with the prebid User ID module and enable PII based resolution via LiveRamp.
  • UnifiedID: oa.js optimizes retrieval of the UnifiedID into prebid by reading the pbjs.getConfig() settings in your page and reading or setting the UnifiedID cookie you have configured.

Once you have your new Prebid.js file configured and downloaded, make sure you update your call to pbjs.setConfig to pass the required information to the UnifiedID and IdentityLink user ID modules.

IdentityLink example

pbjs.setConfig({
    userSync: {
        userIds: [{
            name: 'identityLink',
            params: {
                pid: '16'
            },
            storage: {
                type: 'cookie',
                name: 'idl_env',
                expires: 1
            }
        }],
        syncDelay: 5000
    }
});

Configuration Options

This section contains the list of required fields and optional fields.

oaID (required)

oaID is your Open Audience ID. It is a required field, please contact your account manager to confirm your ID.

placementID (optional)

placementID is optional to enable identity resolution via LiveRamp. The LiveRamp API does not require authentication, therefore you may use either the OpenAudience placementID value (16) or your own placementID you have been given directly by LiveRamp. LiveRamp also offers identity resolution utilizing email addresses or phone numbers.

For more information, see the User Identifiers section.

tdidPartnerID (optional)

tdidPartnerID is an optional field to enable identity resolution via The Trade Desk. You may use either the OpenAudience tdidPartnerID value (openx) or your own tdidPartnerID you have been given directly by The Trade Desk.

User Identifiers

oa.js can improve the resolution of the user if there are user identifiers available in the page. Currently email address and phone number are supported. Phone numbers are only supported in the United States and are expected to be passed as a ten character string of integers with all formatting removed. These identifiers can be passed as plain text to oa.js and they are hashed via SHA256 in the browser before being sent to the server for resolution.

User identifiers are passed as follows:

{
  "placementID": 16,
  "storage": "cookie",
  "oaID": "6789",
  "email": "oajs@openx.com"
}


or

{
  "placementID": 16,
  "storage": "cookie",
  "oa_id": "12345",
  "phone": "1234567890"
}


You can also send pre-hashed email addresses. You must remove all whitespace and lowercase the email before you hash. You can pass SHA256, MD5, and SHA1. Including all hash permutations increases your match rate.

{
  "placementID": 16,
  "emailHashes": [
    "b364fe946d9982c6c547d5637645f9c3dd60ca2aa174e551718509d5dee66ab7",
    "b2c0928035d5f521a880381dc7ec85df7b7e06b3",
    "4466aba660dd65e279fb8700f7ff1cb9"
  ]
}


Lastly, instead of passing identifiers directly, you can use the css_selectors field to input an array of css selector. oa.js is instructed to watch those elements in an attempt to find an email address.

Identity Storage (optional)

Identifiers are stored in a first-party cookie by default. You can alternatively write identifiers into localStorage by changing the storageType attribute.

{
  "placementID": 16,
  "storage": "localStorage",
  "oa_id": "12345"
}

Segments (optional)

The segments field can be used to attach segment identifiers to users. These segments can later be used to break out audience reporting of your users.

{
  "placementID": 16,
  "storage": "cookie",
  "oa_id": "12345",
  "email": "oajs@openx.com",
  "segments": ["sports_fan", "gardening"]
}

Tags (optional)

The tags field can be used to attach tag identifiers to users. These tags can later be used to break out audience reporting of your users. Tags are similar to segments but offer free-form key value pair functionality.

{
  "placementID": 16,
  "storage": "cookie",
  "oa_id": "12345",
  "email": "oajs@openx.com",
  "tags": {"metro": "San Francisco", "pub_id": "123"}
}

Logging (debugging)

oa.js does not log any event by default. If you require to enable logging during development, set logging to debug.

{
  "placementID": 16,
  "logging": "debug"
}


For more information on how to implement oa.js, refer to the Samples page.