Standard Ad Server Protocol - datacratic/rtbkit GitHub Wiki

This document describes the JSON protocol used by the standard ad server connector.

##Impression Win Integration

The format for the Impression Win data source is:

{
    "timestamp":NUMBER,    // Floating pt, secs since epoch GMT, event ts
    "bidTimestamp":NUMBER, // Floating pt, optional, ts of the bid
    "auctionId":STRING,
    "adSpotId":STRING,
    "accountId":STRING,    // To help match bid requests to wins
    "winPrice":NUMBER,     // Floating point
    "userIds":[STRING],
    "dataCost":NUMBER,     // Floating point, optional, default: 0.0
    "winMeta":OBJECT        // JSON Container for additional fields
}

An example:

{
    "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":{}
}

With the exception of bidTimestamp, the above fields are required. You can include additional fields if they are available, by making them the key/value pairs in the nested JSON value for the winMetakey. A bidTimestamp is shown here because it is desirable to include if available. This way, the RTBkit stack can uses it to de­dupe event data and as an additional attribute to assist with matching wins, clicks and conversions to bid requests. It is more important for wins than for clicks and conversions. ##Click Integration

The format for the Click data source is:

{
    "timestamp":NUMBER,    // Floating pt, secs since epoch GMT, event ts
    "bidTimestamp":NUMBER, // Floating pt, optional, ts of the bid
    "auctionId":STRING,
    "adSpotId":STRING,
    "userIds":[STRING],
    "event":STRING         // Value is always "click"
}

An example:

{
    "timestamp":1365517883.9742889404,
    "bidTimestamp":1365517882.6742439502,
    "auctionId":"4BZkWjMDeAWZ",
    "adSpotId":"604356",
    "userIds":["27978154­a122­11e2­74b7­6cea00000002"],
    "event":"click"
}

##Conversion Integration (Optional)

Conversions should be collected for campaigns that have conversion ­related goals, typically CPA. There are two types of optimization possible from conversions, auction-matched and user-matched.

For auction-matched conversions, RTBkit will attempt to resolve attribution of the conversion, associating the conversion with a particular auction and ad impression win. Alternatively, if you cannot correlate auctionId and spotId to conversions but can provide a userId, RTBkit can use that to resolve conversion attribution.

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

{
    "timestamp":NUMBER,    // Floating pt, secs since epoch GMT, event ts
    "bidTimestamp":NUMBER, // Floating pt, optional, ts of the bid
    "payout":FLOAT,        // Value of the conversion
    "auctionId":STRING,
    "adSpotId":STRING,
    "event":STRING         // Value is always "conversion"
}

An example:

{
    "timestamp":1365517883.9742889404,
    "bidTimestamp":1365517882.6742439502,
    "payout":0.12345,
    "auctionId":"4BZkWjMDeAWZ",
    "adSpotId":"604356",
    "event":"conversion"
}

The format for a user-matched Conversion data source, using userId for attribution, is:

{
    "timestamp":NUMBER,    // Floating pt, secs since epoch GMT, event ts
    "payout":FLOAT,        // Value of the conversion
    "userId":STRING,
    "event":STRING         // Value is always "conversion"
}

An example:

{
    "timestamp":1365517883.9742889404,
    "payout":0.12345,
    "userId":"4BZkWjMDeAWZ",
    "event":"conversion"
}