Nodejs bidding agents

This page describes how to build a bidding agent in node.js.

Bidding Agent Method Reference

This reference describes the methods that are available in the BiddingAgent object.

Constructor

var RTBkit = require('rtb');
var services = require('services');

var zookeeperUri = "localhost:2181"; // must point to same Zookeeper as routers
var installation = "kittens";

var services = new services.ServiceProxies();
services.useZookeeper(zookeeperUri, installation);
var agent = new RTBkit.BiddingAgent("myAgent", serviceProxies);
agent.onBidRequest = function( ... ){ agent.doBid( ... ); } 
agent.start()
agent.doConfig( ... )

Bidding Agent Control Methods

init()

Initialize the bidding agent. This needs to be called first of all.

start()

Start the bidding agent. This will create the background thread that takes care of communicating with the routers.

close()

Stop the bidding agent and shut everything down. This is rarely needed apart from in testing.

Bidding Agent Response Methods

doConfig(configuration)

Tell the router how this bidding agent is configured so that it may start sending bid requests to the agent. Configuration is a JSON blob that tells the exchange what bid requests and creatives are available.

doBid(auctionId, bids, meta)

Return a bid for the given auction. This can be done either synchronously (within onBidRequest) or asynchronously.

doPong(router, sent, received, payload)

The router will send a "ping" every second to each bidding agent. This method is used to respond to that message. The router can use the response time of these messages to determine if the bidding agent is overloaded. Note that if there is asynchronous bid processing that happens, then ideally the doPong would be sent through the same pathway so that the router can detect if there is something that is jamming up the bidding.

Event Handlers

onBidRequest(timestamp, auctionId, bidRequest, bids, timeAvailableMs, augmentations)

This callback will be called when the bidding agent receives an auction from a router.

onPing(router, timestamp, args)

This callback will be called when a router has pinged the bidding agent. The router should respond by passing through the given arguments to doPong().

onError(timestamp, description, message)

The router couldn't parse something that was sent from the bidding agent. A description of the error and the original message that was sent are provided.

Bid Result Handlers

These methods are called in response to a doBid() method. The router guarantees that exactly one of these callbacks will be called for every time that doBid() is called for a valid router.

onWin("WIN", timestamp, confidence, auctionId, spotNum, secondPrice, bidRequest,
      ourBid, accountInfo, metadata, augmentations, uids)

The auction was won. The SecondPrice field contains the win price.

onLoss("LOSS", timestamp, confidence, auctionId, spotNum, secondPrice, bidRequest,
       ourBid, accountInfo, metadata, augmentations, uids)

The auction was not won by this agent.

onNoBudget("NOBUDGET", timestamp, confidence, auctionId, spotNum, secondPrice,
           bidRequest, ourBid, accountInfo, metadata, augmentations, uids)

There was not sufficient budget available for the bidding agent to bid the price it chose.

onTooLate("TOOLATE", timestamp, confidence, auctionId, spotNum, secondPrice,
          bidRequest, ourBid, accountInfo, metadata, augmentations, uids)

The router received this bid after the bid response had already been sent back to the exchange.

onInvalidBid("INVALIDBID", timestamp, confidence, auctionId, spotNum, secondPrice,
             bidRequest, ourBid, accountInfo, metadata, augmentations, uids)

The router received an invalid bid from the bidding agent.

onDroppedBid("DROPPEDBID", timestamp, confidence, auctionId, spotNum, secondPrice,
             bidRequest, ourBid, accountInfo, metadata, augmentations, uids)

The auction dropped this bid. Normally this is because the auctionId is unknown or the bid was delayed for so long that the router has erased it from its internal storage.

Delivery Methods

onImpression(timestamp, auctionId, spotId, spotIndex, bidRequest, bidMeta, winMeta,
             impressionMeta, clickMeta, augmentations, visits)

This is called once the ad server notifies that an impression was served for the given auction. Depending upon the exchange, the information here may or may not be the same as that in the win.

onClick(timestamp, auctionId, spotId, spotIndex, bidRequest, bidMeta, winMeta,
        impressionMeta, clickMeta, augmentations, visits)

A click was received for the given auction.

onVisit(timestamp, auctionId, spotId, spotIndex, bidRequest, bidMeta, winMeta,
        impressionMeta, clickMeta, augmentations, visits)

A visit was received to a site that was pixeled as a post-conversion event for a user to whom an impression was shown in the last hour.