adlooxRtdProvider.md

Overview

Module Name: Adloox RTD Provider
Module Type: RTD Provider
Maintainer: [email protected]

Description

RTD provider for adloox.com. Contact [email protected] for information.

This provider fetches segments and populates the First Party Data attributes, some examples of the segments as described by the Adloox 'Google Publisher Tag Targeting Guidelines' and where they are placed are:

• Page segments are placed into ortb2.site.ext.data.adloox_rtd:
  • ok: boolean (use to capture if our module successfully ran)
• Device segments are placed into ortb2.user.ext.data.adloox_rtd:
  • ivt: boolean
  • ua_old: boolean
  • ip: list of strings describing classification of IP (eg. rfc-special, iab-dc, ...)
• AdUnit segments are placed into AdUnit.ortb2Imp.ext.data.adloox_rtd:
  • {dis,vid,aud}: an list of integers describing the likelihood the AdUnit will be visible
  • atf: an list of integers describing the percentage of pixels visible at auction
    • measured at pre-auction time using the Intersection Module; if not enabled then this measurement is not available

N.B. this provider does not offer or utilise any user orientated data

These segments are also sent to your ad server but are translated using the following rules:

• prepended the segment name with adl_
• segments are filtered out when their value is either:
  • empty string ("")
  • zero (0)
  • boolean false
  • empty list/array

For example:

• ortb2.site.ext.data.adloox_rtd.ok is translated to adl_ok
• ortb2.user.ext.data.adloox_rtd.ivt is translated to adl_ivt
• AdUnit.ortb2Imp.ext.data.adloox_rtd.dis is translated to adl_dis

Example

To view an example of an Adloox integration look at the example provided in the Adloox Analytics Adapter documentation.

Integration

To use this, you must also integrate the Adloox Analytics Adapter as shown below:

pbjs.setConfig({
  ...

  realTimeData: {
    auctionDelay: 100,             // see below for guidance
    dataProviders: [
      {
        name: 'intersection',
        waitForIt: true
      },
      {
        name: 'adloox',
        waitForIt: true,
        params: {                  // optional, defaults shown
          thresholds: [ 50, 60, 70, 80, 90 ],
          slotinpath: false
        }
      }
    ]
  },

  ...
});
pbjs.enableAnalytics({
  provider: 'adloox',
  options: {
    client: 'adlooxtest',
    clientid: 127,
    platformid: 0,
    tagid: 0
  }
});

You may optionally pass a subsection params in the params block to the Adloox RTD Provider, these will be passed through to the segment handler as is and as described by the integration guidelines.

N.B. If you pass params to the Adloox Analytics Adapter, id1 (AdUnit.code) and id2 (%%gpid%%) must describe a stable identifier otherwise no usable segments will be served and so they must not be changed; if id1 for your inventory could contain a non-stable random number please consult with us before continuing

Though our segment technology is fast (less than 10ms) the time it takes for the users device to connect to our service and fetch the segments may not be. For this reason we recommend setting auctionDelay no lower than 100ms and if possible you should explore using user-agent sourced information such as NetworkInformation.{rtt,downlink,...} to dynamically tune this for each user.

Prebid Ad Slot

To create reliable segments, a stable description for slots on your inventory needs to be supplied which is typically solved by using the Prebid Ad Slot.

You may use one of two ways to do achieve this:

• for display inventory using GPT you may configure Prebid.js to automatically use the full ad unit path
  1. include the gptPreAuction module
  2. wrap both pbjs.setConfig({...}) and pbjs.enableAnalytics({...}) with googletag.cmd.push(function() { ... })
• set gpid (or pbadslot) in the first party data variable AdUnit.ortb2Imp.ext.gpid (or AdUnit.ortb2Imp.ext.data.pbadslot) for all your ad units

Timeouts

It is strongly recommended you increase any failsafe timeout you use by at least the value you supply to auctionDelay above.

Adloox recommends you use the following (based on examples provided on the Prebid.js website)

FAILSAFE_TIMEOUT = AUCTION_DELAY + (3 * PREBID_TIMEOUT)