Integration Endpoints - datacratic/rtbkit GitHub Wiki

One common use case of RTBkit is to provide an extensible integration mechanism between existing bidding infrastructures. For example, an RTB stack could forward some requests to another (often more specialized) RTB stack and process the result before sending a response to the exchange.

In this scenario, the existing bidder needs to send a bid request and read back the response. In most case, it should also forward wins and ad server events.

This document will explain how to setup and use the integration endpoints tool to do just that.

#Instance

A quick and easy way to get running is to simply create an instance that we are making available to the public and send requests to it. The endpoints running there are setup exactly as what follows.

The AMI is updated periodically and is currently: ami-31acd858

#Integration endpoints

The tool provides 4 endpoints.

  1. An endpoint for bid requests
  2. An endpoint for wins
  3. An endpoint for campaign events

By default, they are configured to run on ports 18142 to 18145.

#Examples

The following are examples of requests that can be performed on those endpoints. By default, the setup will use the OpenRTBExchangeConnector and the StandardAdServerConnector.

See Standard Ad Server Protocol for more details on the ad server protocol.

##Bid request

By default, this endpoint is an OpenRTB exchange connector on port 18142 and will accept only POST requests made on the /auctions resource. Here is an example of a bid request message accepted by the endpoint:

curl -d '{"id":"f4093ca4834dfd750452aba7ce0ca00c2705a80a","at":2,"tmax":893,"imp":[{"id":"1","tagid":"30027","banner":{"w":160,"h":600,"battr":[9,1,14014,14002,8,14,14019,3],"api":[]}}],"site":{"id":"14463","domain":"discovery.com","name":"","cat":["IAB1"],"page":"","publisher":{"id":"2147483647"},"ext":{"mopt":0}},"device":{"ua":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_8_3) AppleWebKit/537.31 (KHTML, like Gecko) Chrome/26.0.1410.65 Safari/537.31","ip":"10.83.4.24","language":"en","devicetype":2,"js":1,"geo":{"country":"USA","region":"TX"}},"user":{"id":"edcbabb5691ece950fa9da145ee1cf871183ca4d","buyeruid":"asdf","ext":{"sessiondepth":1}}}' http://localhost:18142/auctions --header "x-openrtb-version: 2.1" -vv -H "Content-Type:application/json"

##Win

By default, this endpoint is on port 18143 and will accept only POST requests. Here is an example of a win message accepted by the endpoint:

curl -d '{"timestamp":1365517883.9742889404,"bidTimestamp":1365517882.6742439502,"auctionId":"4BZkWjMDeAWZ","adSpotId":"604356","accountId":"5","winPrice":0.8493150684931507,"userIds":["27978154­a122­11e2­74b7­6cea00000002"],"dataCost":0.0,"winMeta":{}}' http://localhost:18143 -vv -H "Content-Type:application/json"

##Campaign event

By default, this endpoint is on port 18144 and will accept only POST requests. Here is an example of a click message accepted by the endpoint:

curl -d '{"timestamp":1365517883.9742889404,"bidTimestamp":1365517882.6742439502,"auctionId":"4BZkWjMDeAWZ","adSpotId":"604356","userIds":["27978154­a122­11e2­74b7­6cea00000002"],"event":"click"}' http://localhost:18144 -vv -H "Content-Type:application/json"

#Preparation

First, make sure that you have a working build of RTBkit and that all tests are passing. The process is described here.

Then, to start the integration endpoint, simply do:

$> ./build/x86_64/bin/integration_endpoints

This will start the endpoint.

#Configuration

To configure the endpoints, edit the file example/integration-config.json.