OpenRTB 2.x — Push notifications

Hosts: {rtb_domain} is your network's RTB domain, used by the bidder endpoints; a network without a dedicated RTB domain uses its ad domain there. {ad_domain} is the network's ad-serving domain. Inside the panel both are filled in for you.

Browser push subscribers. The optional subage* fields tell you how stale a subscriber is.

Endpoint#

URL

POST https://{rtb_domain}/openrtb/get.go?token={token}

Bid Request#

ext.type = "push". subage is optional subscription age; one of subage (days), subage_dt (date string), subage_ts (unix timestamp). The OpenRTB Native object on imp.native is also accepted as an optional alternative — same shape as the Native topic. SSP campaigns are bound to one ad type, so the gateway knows the expected shape from the campaign config.

User-context fields (device.ip, device.ua, device.language, device.geo.country, device.w / device.h, device.ext.*, user.id) must reflect the end visitor, never the bidder's server — see the Banner topic for the full rule.

Standard

{
  "id": "your_id",
  "imp": [{
    "id": "your_id",
    "tagid": "placementid",
    "bidfloor": 0.00,
    "bidfloorcur": "USD",
    "ext": {
      "subid": "",
      "type": "push",
      "subage": 10,
      "subage_dt": "2024-10-01",
      "subage_ts": 1727827200
    }
  }],
  "site": {
    "id": "1", "domain": "site.com",
    "publisher": { "id": "1" },
    "page": "http://site.com/page.html"
  },
  "device": {
    "ua": "{user_agent}",
    "ip": "{client_ip}",
    "language": "{language}",
    "geo": { "country": "{country}", "ipservice": 3 },
    "ext": {
      "accept_language": "{accept_language}",
      "remote_addr": "{client_ip}",
      "requested_with": "{requested_with}"
    },
    "h": {browser_h}, "w": {browser_w}
  },
  "user": { "id": "5a80e2e5857d86a298e013ab0091c17e" },
  "curr": ["USD"],
  "at": 1
}

Native-style (optional)

{
  "id": "your_id",
  "imp": [{
    "id": "your_id",
    "tagid": "placementid",
    "bidfloor": 0.00,
    "bidfloorcur": "USD",
    "ext": {
      "subid": "",
      "type": "push",
      "subage": 10
    },
    "native": {
      "request": "{\"native\":{\"plcmttype\":1,\"plcmtcnt\":1,\"assets\":[{\"id\":1,\"required\":1,\"title\":{\"len\":140}},{\"id\":2,\"required\":0,\"img\":{\"type\":3,\"wmin\":300,\"hmin\":250}},{\"id\":3,\"required\":0,\"data\":{\"type\":2,\"len\":140}}]}}",
      "ver": "1.2"
    }
  }],
  "site": {
    "id": "1", "domain": "site.com",
    "publisher": { "id": "1" },
    "page": "http://site.com/page.html"
  },
  "device": {
    "ua": "{user_agent}",
    "ip": "{client_ip}",
    "language": "{language}",
    "geo": { "country": "{country}", "ipservice": 3 },
    "ext": {
      "accept_language": "{accept_language}",
      "remote_addr": "{client_ip}",
      "requested_with": "{requested_with}"
    },
    "h": {browser_h}, "w": {browser_w}
  },
  "user": { "id": "5a80e2e5857d86a298e013ab0091c17e" },
  "curr": ["USD"],
  "at": 1
}

Bid Response#

adm carries a stringified JSON payload with the push fields. The OpenRTB Native admarkup is also accepted as an optional alternative — match whichever request shape you used.

Bid wrapper (push JSON)

{
  "id": "your id",
  "seatbid": [{
    "bid": [{
      "id": "our id",
      "impid": "your_id",
      "price": 0.001,
      "nurl": "https://your-dsp.com/win?bid=${AUCTION_BID_ID}&price=${AUCTION_PRICE}",
      "adm": "{\"title\":\"Ad Title\",\"description\":\"Ad Description\",\"link\":\"https://site.com\",\"icon\":\"https://site.com/icon.png\",\"image\":\"https://site.com/image.jpg\",\"pixel\":\"https://site.com/track\"}"
    }]
  }]
}

AdMarkup — push JSON

{
  "id": "your id",
  "cpc": 0.001,
  "title": "Ad Title",
  "description": "Ad Description",
  "content": "Ad Description",
  "link": "https://site.com",
  "icon": "https://site.com/icon.png",
  "image": "https://site.com/image.jpg",
  "pixel": "https://site.com/track"
}

Bid wrapper — native (optional)

{
  "id": "your id",
  "seatbid": [{
    "bid": [{
      "id": "our id",
      "impid": "your_id",
      "price": 0.0272,
      "nurl": "https://your-dsp.com/win?bid=${AUCTION_BID_ID}&price=${AUCTION_PRICE}",
      "ext": { "btype": "native" },
      "adm": "{\"native\":{\"link\":{\"url\":\"https://site.com/index.html\"},\"eventtrackers\":[{\"event\":1,\"method\":1,\"url\":\"https://mysite.com/tracker\"}],\"assets\":[{\"id\":1,\"title\":{\"text\":\"Title\"}},{\"id\":2,\"img\":{\"url\":\"https://mysite.com/image.png\",\"w\":300,\"h\":250}},{\"id\":3,\"data\":{\"value\":\"Description\"}}]}}"
    }]
  }]
}

AdMarkup — native (optional)

{
  "native": {
    "link": { "url": "https://site.com/index.html" },
    "eventtrackers": [
      { "event": 1, "method": 1, "url": "https://mysite.com/tracker" }
    ],
    "assets": [
      { "id": 1, "title": { "text": "Title" } },
      { "id": 2, "img": { "url": "https://mysite.com/image.png", "w": 300, "h": 250 } },
      { "id": 3, "data": { "value": "Description" } }
    ]
  }
}

Win notice (nurl)#

Optional: put a nurl on your bid and we call it (server-side GET) when your bid wins. When you send no nurl but do send burl, we call burl instead. The standard OpenRTB auction macros in the URL are filled in before the call — see the list below. Banner, video, native, push and full-page wins: we call it once, when the ad is actually shown. Pop, redirect and mail-click wins have no render step, so we call it right after the auction. Leave nurl out and no win notice is sent.

Example

https://your-dsp.com/win?bid=${AUCTION_BID_ID}&price=${AUCTION_PRICE}

Supported macros

${AUCTION_PRICE}     winning price, same unit and currency as bid.price
${AUCTION_CURRENCY}  always USD
${AUCTION_BID_ID}    your bid.id
${AUCTION_IMP_ID}    the impid of the winning bid
${AUCTION_ID}        the id of our bid request