OpenRTB integration

Introduction

Atomx offers OpenRTB integration for companies interested in automated trading of display ads. We adopted the OpenRTB standard for online display buying and selling. Atomx' RTB was designed as a peer-to-peer system to avoid the need for global synchronization. This allows DSPs and SSPs to maintain their competitive differentiation, while standardizing on the data synchronization tasks we all have in common.

Advantages for Buyers (RTB demand sources):

  • More accurate and cost efficient bidding
  • Real-time access to all user metrics and decision points
  • Ability to optimize with own prediction engine

Advantages for Sellers (RTB supply sources):

  • Higher CPMs for publishers, since bidders will have accurate pre-filters
  • Selling your traffic with the best fitting ad at the highest available price

Steps for the integration of Buyers (RTB demand sources)

  1. Atomx and you will sign a Master Services Agreement, outlining the framework of our cooperation
  2. Buyer will send us an RTB end point and we will start testing at low QPS with one data center / region
  3. If everything is OK, we will scale up the QPS and add other datacenters / regions

At the moment we do not support any special OpenRTB extension. Atomx implements the IAB OpenRTB Project. The spec is available for download: OpenRTB API Specification, V2.3, January 2015

Limitations

On the RTB buy side there are a couple of limitations:

  • Only Banner/pop (desktop/mobile), App and Video buying is supported right now - Native will follow later
  • BidRequest -> tmax (max response time) is always 100ms
  • BidRequest -> at (price type) is always Second Price Plus
  • BidResponse -> cur (currency) always has to be USD in order to be eligible

BidRequest info

In the BidRequest we populate most fields, including:

  • BidRequest -> site -> {id, name, domain, cat, ref, publisher}
  • BidRequest -> device -> {ua, geo, ip, ipv6, devicetype, os, w, h, js, carrier, connectiontype}
  • BidRequest -> user -> {id}

BidRequest extension

We send extra information in the BidRequest -> ext -> ra object. This is an array consisting of detected request attribute IDs. The full and up-to-date list of available request attributes can be found at http://api.atomx.com/v3/request-attributes.

Notes

Some important points:

  • It is required to pass in the following fields in BidResponse -> SeatBid -> Bid as we use these for classifying and blocking specific creatives: {cid , crid, cat, attr}
  • The following fields are highly recommended to be populated: {adomain, iurl}
  • We support providing the ad markup in either BidResponse -> seatbid -> adm or in the win notice

BidRequest example

{
  "cur": [
    "USD"
  ],
  "id": "VgpV7SMBP70zFzseiG8TLQ",
  "imp": [
    {
      "bidfloorcur": "USD",
      "tagid": "1234",
      "banner": {
        "id": "1",
        "h": 250,
        "w": 300
      },
      "id": "1"
    }
  ],
  "site": {
    "publisher": {
      "name": "Sample Publisher",
      "id": "3456"
    },
    "ref": "http://www.sample.com/",
    "cat": [
      "IAB25-3"
    ],
    "domain": "sample.com",
    "name": "Sample Site",
    "id": "6789"
  },
  "device": {
    "connectiontype": 1,
    "carrier": "Unknown",
    "js": 1,
    "os": "Windows",
    "devicetype": 2,
    "ip": "12.23.34.45",
    "geo": {
      "country": "USA",
      "type": 2
    },
    "ua": "Mozilla/4.0 (compatible; MSIE 8.0; Windows NT 6.0; WOW64; Trident/4.0; SLCC2; .NET CLR 2.0.50727; .NET4.0C; .NET4.0E)"
  },
  "user": {
    "id": "VgpV7eIBBSs1iQnp6-mY-g"
  },
  "test": 0,
  "at": 2,
  "tmax": 100
}

Steps for the integration of Sellers (RTB supply sources)

  1. Atomx and you will sign a Master Services Agreement, outlining the framework of our cooperation
  2. We will prepare an RTB end point for each necessary region, and ask you to start testing at low QPS
  3. If everything is OK, you can scale up the QPS. Preferably we have access to a UI where we can control the QPS/endpoint settings

Limitations

On the RTB sell side we have these limitations:

  • Only Banner/pop (desktop/mobile), App and Video selling is supported right now - Native will follow later
  • We need the seller to support BidResponse -> SeatBid -> Bid -> nurl in order to minimize discrepancies - we do not use a client-side pixel
  • We only send bids with BidResponse -> cur (currency) USD - in addition if a floor price is given we only honor those with bidfloorcur USD
  • We need the cookie match table to be hosted on the seller's end

Notes

Some important points:

  • It is required to pass in the following fields in BidRequest -> Imp -> Banner as we need this to find matching creatives: {w, h, btype, battr}
  • It is required to pass in the following fields in BidRequest -> Imp -> Video as we need this to find matching creatives: {protocols, w, h, battr}
  • It is required to pass in the following fields in BidRequest -> Site -> {id, domain, cat} and BidRequest -> Device -> {ua, ip}
  • We will always provide the ad markup in BidResponse -> seatbid -> adm

BidResponse example

{
  "id":"8xee2AZjbl",
  "seatbid":[
    {
      "bid":[
        {
          "id":"Vz16z-8BXGuMNTo69PRZOg",
          "impid":"1",
          "price":1.123,
          "adid":"1",
          "nurl":"http://rtb.ato.mx/win?id=Vz16z-8BXGuMNTo69PRZOg",
          "adm":"Sample ad: <a href=\"https://www.atomx.com/\">Atomx</a>",
          "cid":123,
          "crid":12345,
          "h":300,
          "w":250
        }
      ]
    }
  ],
  "bidid":"Vz16z-8BXGuMNTo69PRZOg",
  "cur":"USD"
}