Standard Ad Server Protocol

This document describes the JSON protocol used by the standard ad server connector. Please note that his protocol is an example of what information you would need to do win, click and conversion matching on a very general level in the PAL.

##Impression Win Integration

The format for the Impression Win data source is:

{
    "timestamp":FLOAT,          // REQUIRED Win timestamp in
                                // seconds since epoch GMT
    "bidRequestId":STRING,      // REQUIRED Must match a bidRequestId 
                                // (auctionId from the exchange)
                                // that the system has bidded on
    "impid":STRING,             // REQUIRED Must match the corresponding
                                // impId that the system had bid on
                                // for that particular bidRequestId
    "price":FLOAT,              // REQUIRED Price paid for the 
                                // corresponding bid request
    "userIds":ARRAY of STRING,  // OPTIONAL Array of strings of the
                                // userIds related to this win
    "passback":STRING           // OPTIONAL Extra information to be
                                // passed on
}

An example:

{
    "timestamp":1365517883.9742889404,
    "bidRequestId":"4BZkWjMDeAWZ",
    "impid":"604356",
    "price":0.8493150684931507,
    "userIds" : ["some-user-id", "another-user-id"]
}

The above fields are required. The userIds field is optional and only require an array of strings. The passback value is also optional and will take a string.

##Click Integration

The format for the Click data source is:

{
    "timestamp":FLOAT,          // REQUIRED Click timestamp in
                                // seconds since epoch GMT
    "bidRequestId":STRING,      // REQUIRED Must match a bidRequestId
                                // (auctionId from the exchange)
                                // that the system has won on
    "impid":STRING,             // REQUIRED Must match the corresponding
                                // impId that the system has won
                                // on for that particular bidRequestId
    "type":STRING               // REQUIRED Value is always "CLICK"
}

An example:

{
    "timestamp":1365517883.9742889404,
    "bidRequestId":"4BZkWjMDeAWZ",
    "impid":"604356",
    "type":"CLICK"
}

##Conversion Integration (Optional)

Conversions should be collected for campaigns that have conversion ­related goals, typically CPA. Auction-matched is actually the only supported type of optimization.

For auction-matched conversions, RTBkit will attempt to resolve attribution of the conversion, associating the conversion with a particular auction and ad impression win.

The format for an auction-matched Conversion data source, using bidRequestId and impId for attribution, is:

{
    "timestamp":FLOAT,          // REQUIRED Conversion timestamp :
                                // seconds since epoch GMT
    "bidRequestId":STRING,      // REQUIRED Must match a bidRequestId
                                // (auctionId from the exchange)
                                // that the system has won on
    "impid":STRING,             // REQUIRED Must match the 
                                // corresponding impId that
                                // the system has won on for
                                // that particular bidRequestId
    "type":STRING               // REQUIRED Value is always "CONVERSION"
}

An example:

{
    "timestamp":1365517883.9742889404,\
    "bidRequestId":"4BZkWjMDeAWZ",
    "impid":"604356",
    "type":"CONVERSION"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    
}