Standard Ad Server Protocol

#Introduction

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. In addition, you can include any other fields for added context.

Some commonly available fields include:

• "bidderId"
• "flightId"
• "tagId"
• "url"
• "position"
• "ip"
• "country"
• "region"
• "city"
• "user_agent"
• "deviceType"
• "operatingSystem"
• "browser"
• "referer"
• "protocol"

#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, matched and unmatched.

The format for an unmatched Conversion data source 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
    "event":STRING         // Value is always "conversion"
}

An example:

{
    "timestamp":1365517883.9742889404,
    "bidTimestamp":1365517882.6742439502,
    "payout":0.12345,
    "event":"conversion"
}

For 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 a 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 matched Conversion data source, using userId 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
    "userId":STRING,
    "event":STRING         // Value is always "conversion"
}

An example:

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

#External Wins Integration (Optional)

External Wins are impressions won outside the RTBkit stack. This is useful in some situation where the knowledge of those events can be used to optimize the bidding process. For example, a system could replay logs of past won auctions to learn from them, before being turned on for optimization on live campaigns. Another scenario is while online, there may be certain campaigns you need to run or wish to run without optimization, perhaps to test the impact of optimization. Such a system can learn online from a data source reporting such winning bids, and more effectively optimize a campaign should your bidder begin passing the campaign's bid requests to it.

The format for the External Win data source is:

{
    "auctionId":STRING,
    "winPrice":NUMBER, // Floating point
    "dataCost":NUMBER, // Floating point, optional, default: 0.0
    "bidRequest:OBJECT // The winning Bid Request JSON
}

An example:

{
    "auctionId":"4BZkWjMDeAWZ",
    "winPrice":0.8493150684931507,
    "dataCost":0.0,
    "bidRequest:{...}
}