RTB setting

From Service Manual Kadam.net
Revision as of 10:52, 20 February 2019 by Admin (Talk | contribs)

Jump to: navigation, search

Introduction

RTB auction (SSP) provides advertising space owners with the opportunity to conduct real-time bidding by selecting the best deals offered by advertisers.

How RTB works (real-time bidding)

Real-time bidding is the interaction between an advertising inventory at the SSP (sell-side platform) auction and the sellers (advertising platforms) that use http post protocol. All advertising inventory that meets the requirements is available to site owners through the RTB infrastructure.
The following principle describes how an auction works, and it gives a brief overview of the process. For more detailed description, see the section “Description of the workflow":

    1. RTB SSP (Real-time bidding sell-side platform) receives an advertising request from the seller and selects a list of buyers for the auction
    2. RTB SSP sends a request to customers from the selected list
    3. Each buyer from the list receives a request and evaluates its ability to participate in the auction, responds to the request 4. RTB SSP holds an auction based on bids received from buyers
    5. RTB SSP "delivers" the announcement of the bidding winner among advertisers to the seller of advertising space on the site
    6. RTB SSP sends auction results to auction participants

About the document

The document describes the connection of a DSP (demand-side platform) or advertiser to an RTB SSP (sell-side platform). The SSP interface is designed according to the OpenRTB v.2.3 protocol specification
http://www.iab.net/media/file/OpenRTB-API-Specification-Version-2-3.pdf

Terms and definitions

Bid request - request from RTB SSP sent to buyers (advertisers) to bargain their promotional offers
Bid response - buyer's response to RTB SSP as bidding bid
CPM (Cost per mille) - price per one thousand ad impressions
RTB (Real-time bidding) - real-time bidding, the principle of the delivery of advertising to the seller of real-time advertising space
SSP (sell-side platform) - real-time bidding system representing the interests of sellers (owners of sites)
DSP (demand-side platform) - an advertising system representing the interests of buyers (advertisers)
Impression - teaser, banner, separate advertisement

Workflow description

Each request to the buyer (advertiser) is accompanied by the following steps:
1. Selection of the buyer in real time
After receiving a request to display advertising from the seller (platform), the RTB auction selects a list of buyers for setting advertising rates. The bids that have the highest chances to win the auction are chosen.
2. Bid request from RTB SSP
RTB auction sends requests to selected buyers (advertisers). The request contains technical information necessary for the “delivery” of the advertisement, as well as a set of targeting for this request. If the same buyer (advertiser) has several ads that match the targeting request from advertising space seller, then the RTB auction includes all incoming bidding that match the request.
3. Buyer’s response (bid response)
The buyer receives a request from the RTB auction and assesses the possibility of participation in the auction. As a response, the buyer sends an offer with a bid price or does not respond to the request if he does not have any offers for the request. The buyer must respond to the request within the allotted time interval, otherwise he will lose the opportunity to participate in the auction. In case of several bidding offers, the buyer must respond to a request for answers with the price of all his proposals, which he is ready to bargain for.
4. Auction
When all bids are received (in the allotted time to accept responses from buyers), an auction takes place. Sellers have the opportunity to specify the minimum price for the site on which they are selling the place. Each winning bid must be higher than the minimum price that the seller has placed on the site. All materials are subjected to mandatory moderation in the RTB SSP system.
5. Result Notification
RTB SSP sends notification of results to each participant in each individual auction.

Requests to DSP

A request to a DSP (or customer) is a collection of information:

    - about the advertising platform;
    - about the visitor of this advertising platform;
    - about the device from which the visitor logged in;
    - about the list of advertising spaces for advertising;

The DSP request is in json format, that is, [content_type] => application /json.


Example DSP /Buyer Request

Object definition
Below are the definitions of the various objects involved in the request.
Request Object
The highest bid item contains a globally unique bid or auction ID. This mandatory “ID” attribute requires at least one “imp” (for example, impression) object. Other attributes are optional, since the exchange can set default values. The default column defines how additional parameters should be interpreted if explicit values ​​are not provided.

                                                                                                                                                                                                                                                                                                                           
Field Type Default Description
id string - The unique identifier of the request rate, provided by the exchange
imp array of objects - Array of impression objects. Multiple impression auctions can be listed in one single bid. At least one bid is required for the correct bid.
site object - see site object
device object - see device object
user object - see user object
ext object - This object is a prototype that can contain custom JSON agreed by the parties to an OpenRTB transaction that supports the flexibility of the standards defined in this specification. Described in the example request to the DSP /customer
at int 2 Auction principle. If "1", then the first auction. If "2", then the second auction. Additional types of auctions can be determined in accordance with the business rules of the exchange.

Impression object
The “imp” object describes the position of an ad or an impression at an auction. The “Default” column defines how additional parameters should be interpreted if explicit values ​​are not provided.

                                                                                                                                                                                                                                           
Field Type Default Description
id string - The unique identifier for this impression in the context of the bid rate (as a rule, the cost starts from 1, and increases to n values ​​per n number of impressions).
banner Object - Link to the banner object. Any banner or video object (or both, if the impression allows) should be included in the presentation of the object; both objects do not have to be included. See Banner Object
ext object - This object is a prototype that can contain custom JSON agreed by the parties in an OpenRTB transaction
bidfloor float 0 The minimum bid for each material that will be transmitted in response to a request.
bidfloorcur string RUB The currency in which the minimum bid is specified.

Banner object
If the impression is put up for auction and is displayed, the banner object must be included directly in the presentation of the object. The “Default” column shows how additional parameters should be interpreted if explicit values ​​are not provided.

                                                                                                                       
Field Type Default Description
w int32 - The width of the impression in pixels. Some types of ads that are not limited by the size of this area are not required, but it is strongly recommended to include this information when possible.
h int32 - The height of the impression in pixels. Some types of ads that are not limited by the size of this area are not required, but it is strongly recommended to include this information when possible.

Site Object
The site object should be included if the ad supports content as part of the website. The bid request must not contain both the site object and the application object. If the parameter is not specified, it should say “unknown.” This feature is useful for providing the page URl or site ID, however, it is not mandatory.

                                                                                                                                                                                                                                                                                   
Field Type Default Description
id string - Exchange Site ID
page string - URL of the page where impressions will be displayed.
domain string - The domain of the site used to block the side of the advertiser. For example, "foo.com".
cat Array of strings - An array of IAB content categories for a common site. Cm. Table 6.1 "Content Categories" of the OpenRTB 2.1 specification
pagecat Array of strings - The IAB array of content categories for the current page. Cm. Table 6.1 "Content Categories" of the OpenRTB 2.1 specification
content object - See Content object

Content object
The content object itself and all its parameters are optional, therefore, no default value is provided. If the parameter is not specified, it should be considered unknown. This object describes the content in which the impression appears. This object can be useful in a situation where the syndicated content contains impressions that do not necessarily coincide with the publisher’s general content. Sharing may or may not give a complete understanding of the page where the content works as a result of the syndication method.

                                                                                               
Field Required? Type Default Description
keywords Optional string - Comma-delimited list of keywords describing the content.

Device Object
A device object provides information related to a device, including its equipment, platforms, and location. This device may apply to mobile phones, computers, set-up boxes or any other digital devices.
The device object itself and all its parameters are optional, so no default value is provided. If the parameter is not specified, it should be considered as unknown.
In general, the most important field is the IP address (to perform a geo-search for the applicant).

                                                                                                                       
Field Type Default Description
ua String - User Agent Browser String
ip String - IPv4 address closest to device

User object
The "user" object contains information known or received about a person (device user). The user object itself and all its parameters are optional, so the default value is not provided. If the optional parameter is not specified, it should be considered as unknown.

                                                                                                                                                                                                                                               
Field Required? Type Default Description
id Required string - The unique consumer ID of this user in the auction.
buyeruid Optional string - DSP user ID
yob Optional int32 - Year of birth as a 4 digit number.
gender Optional string - Paul, as "M" men, "F" women, "O" Other. (Zero indicates unknown).

DSP request example /advertiser (buyer)

{
   "id": "140835804423031",
   "imp": [
      {
         "id": "1",
         "banner": {
             "w": 120,
             "h": 120
         },
         "ext": {
            "ad_type": 10, //10 - teaser, 20 - banner, 40 - clickunder, 70 - video
            "limit": 1 //number of teasers for teaser block
         },
         "bidfloor": 1.2,
         "bidfloorcur": "RUB"
       }
   ],
   "site": {
      "id": "34524253",
      "page": "http://testdomain.ru/bolezni-u-vzrosluh.html",
      "domain": "testdomain.ru",
      "cat": [
         "IAB7"
      ],
      "pagecat": [
         "IAB7"
      ],
      "content": {
         "keywords": "treatment, children, disease, osteoporosis"
      }
   },
   "device": {
      "ua": "Mozilla /5.0 (Macintosh; Intel Mac OS X 10_9_4) AppleWebKit /537.36 (KHTML, like Gecko) Chrome /36.0.1985.143 Safari /537.36",
      "ip": "95.31.8.193"
   },
   "user": {
       "id": "ssp140533010201346370"
   },
   "at": 2
}

Example of a valid DSP response

Object definition
Below are the definitions of the various objects involved in responding to a request.

Answer rate object
The top level of the response rate object is defined below. At least one “seatbid” object is required, which includes at least one impression.

                                                                                                                               
Field Type Definition
id String Request Bid ID
cur String The currency in which the bet is made. In the current version, only “RUB” is available.
seatbid Array of objects array of seatbid objects

Seat Bid Object
Since a request rate can include several offers, each ‘seatbid’ object can contain several bids relating to different offers. Hence, in addition to including the price of the offer, each ‘bid’ object must include the ID of the offer to which it refers to.

                                                               
Field Type Definition
Bid Array of objects Array of object rates; each object rate refers to an imp object in the request rate. One imp object can have many object stakes.

Bid Object (Bid)

                                                                                                                                                                                                                                                                                               
Field Type Definition
id String Bid object ID is selected by the bidder for tracking and debugging. Useful when multiple bets per show are shown for a given place.
impid String ID of the impression object to which this rate applies.
adid String ID that refers to an ad to use in case if the bid wins.
ext Object For teaser format. Additional object rate extensions.
price Float Bid price per thousand impressions.
nurl String Win URL notification. Please note that the ad is usually tagged, but this is not necessary for returning via URLs
adm String A part representing an advertising banner in the HTML format or an advertising video or a link for a clicker
iurl String Only for DSP response when requesting video. Link to advertising video.

An example of a valid DSP response when requesting a banner (with html-part):

{
  "id": "6",
  "seatbid": [
    {
       "bid": [
         {
            "id": 1,
            "impid": "1",
            "adid": 1085932,
            "adm": "<a target='_blank'href='http://test_url.com/test'> <img src = 'http: //test/test.gif' width = '300' height = '300 '> </a> ",
            "price": 2.6269636,
            "nurl": "http://domain.ru/?dsp_win&bid=${AUCTION_PRICE}&ads=$ {AUCTION_AD_ID} & auctionID = $ {AUCTION_ID}"
          }
       ]
     }
   ]
}

An example of a valid DSP response when requesting a teaser:

{
   "id": "5",
   "seatbid": [
      {
       "bid": [
          {
           "id": 1,
           "adid": 0,
           "impid": "1",
           "ext": {
             "ads": [
              {
                "id": 1061077,
                "title": "The bone will disappear in a week!",
                "text": "Found a simple way to cure \" bones \ "! Write down ...",
                "image": "http://domain.ru/1406733540_16197_phpi61ewn.jpg",
                "cpm": 6.0,
                "url": "http://domain.ru/test/test_url"
              },
              {
                "id": 1083442,
                "title": "How to wash the car 3-4 times a year",
                "text": "This is a penny tool carefully concealed car washes!",
                "image": "http://domain.ru/1407217586_9686_phpgqddlm.jpg",
                "cpm": 2.6,
                "url": "http://domain.ru/test/test_url"
              },
              {
                "id": 1087092,
                "title": "Wash your car 2 times a year!",
                "text": "Employees of car washes hide this cheap tool!",
                "image": "http://domain.ru/1407310654_12085_phpm6spfp.jpg",
                "cpm": 2.5,
                "url": "http://domain.ru/test/test_url"
              }
             ]
           },
           "price": 11.1,
           "nurl": "http://domain.ru/?dsp_win&bid=${AUCTION_PRICE}&ads=$ {AUCTION_AD_ID} & auctionID = $ {AUCTION_ID}"
          }
        ]
      }
    ]
}

An example of a valid DSP response when requesting a clicker:

{
   "id": "6",
   "seatbid": [
      {
        "bid": [
           {
             "id": 1,
             "impid": "1",
             "adid": 1085932,
             "adm": "http://test_url.com/test",
             "price": 2.6269636,
             "nurl": "http://domain.ru/?dsp_win&bid=${AUCTION_PRICE}&ads=$ {AUCTION_AD_ID} & auctionID = $ {AUCTION_ID}"
           }
        ]
      }
    ]
}

An example of a valid DSP response when requesting a video:

{
    "id": "6",
    "seatbid": [
       {
         "bid": [
            {
              "id": 1,
              "impid": "1",
              "adid": 30641
              "iurl": "http://videotest.ru/video.flv"
              "adm": "% 3CVAST + version% 3D% 223.0% 22% 3E +% 0D% 0A% 3Cad-
id% 3D% 2230641% 22% 3E +% 0D% 0A% 3CInLine% 3E +% 0D% 0A% 3CAdSystem% 3EAdSystem
+ Name% 3C% 2FAdSystem% 3E% 0D% 0A% 3CAdTitle% 3ETitle% 3C% 2FAdTitle% 3E% 0D% 0A%
3CImpression% 3E% 0D% 0A% 21% 5BCDATA% 5Bhttp% 3A% 2F% 2Fmyimpression.ru% 2F% 3Fc
ommand% 3Dtrack_view% 26skip% 3Dtrue% 5D% 5D% 0D% 0A% 3C% 2FImpression% 3E% 0D% 0
A% 3CCreatives% 3E +% 0D% 0A% 3CCreative% 3E +% 0D% 0A% 3CLinear% 3E +% 0D% 0A% 3CDu
ration% 3E00% 3A00% 3A21% 3C% 2FDuration% 3E +% 0D% 0A% 3CTrackingEvents% 3E +% 0D%
0A% 3CTracking + event% 3D% 22firstQuartile% 22% 3E% 21% 5BCDATA% 5B% 24% 7BTRACK_U
RL% 7D% 5D% 5D +% 0D% 0A% 3C% 2FTracking% 3E% 0D% 0A% 3C% 2FTrackingEvents% 3E +% 0
D% 0A% 3CMediaFiles% 3E +% 0D% 0A% 3CMediaFile + delivery% 3D% 22streaming% 22 + bitrate%
3D% 22600% 22 + width% 3D% 22640% 22 + height% 3D% 22480% 22 + type% 3D% 22video% 2Fx-
flv% 22% 3E% 0D% 0A% 3C% 21% 5BCDATA% 5Bhttp% 3A% 2F% 2Fvideotest.ru% 2Fvideo.flv% 5D
% 5D% 3E% 0D% 0A% 3C% 2FMediaFile% 3E% 0D% 0A% 3C% 2FMediaFiles% 3E +% 0D% 0A% 3C
% 2FLinear% 3E +% 0D% 0A% 3C% 2FCreative% 3E +% 0D% 0A% 3C% 2FCreatives% 3E +% 0D% 0A
% 3C% 2FInLine% 3E +% 0D% 0A% 3C% 2FAd% 3E +% 0D% 0A% 3C% 2FVAST% 3E + "
              "price": 2.6269636,
              "nurl": "http://domain.ru/?dsp_win&bid=${AUCTION_PRICE}&ads=$ {AUCTION_AD_ID} & auctionID = $ {AUCTION_ID}"
             }
          ]
        }
     ]
}

The adm field format of the bid object when requesting a video:
Promotional video must be submitted in accordance with the Video Ad Serving Template (VAST) 3.0 protocol specification (http://www.iab.net/media/file/VASTv3.0.pdf) with the embedded $ {TRACK_URL} macro in the < Tracking event = "firstQuartile"> ... </Tracking> and is encoded in a URL format. If desired, the DSP can also add tracks for 1⁄2, 3⁄4 and full video viewing.
Attention! Only Linear type of advertising video is supported and only with one media file for up to 30 seconds. Acceptable types of media files are mp4, webm, ogg, and flv.

An example of the presentation of video material in XML format and embedded macro:

<VAST version = "3.0">
  <Ad id = "30641">
    <InLine>
      <AdSystem> AdSystem Name </AdSystem> //advertiser name
      <AdTitle> Title </AdTitle> //general name of the material
      <Impression>
      <! [CDATA [http://myimpression.ru/?command=track_view&skip=true]]>
      </Impression> //link that is called when viewing the first frame of video
      <Creatives>
        <Creative>
          <Linear>
            <Duration> 00:00:21 </Duration> //video length
            <TrackingEvents>
              <Tracking event = "firstQuartile">
                <! [CDATA [$ {TRACK_URL} & furl = xxx]]>
              </Tracking> //contains a link that is called when playing a quarter of a video, where xxx is a similar link from DSP
            </TrackingEvents>
            <Mediafiles>
              <MediaFile delivery = "streaming" bitrate = "600" width = "640" height = "480" type = "video /x-flv">
                <! [CDATA [http://videotest.ru/video.flv]]> //link to the advertising video
              </MediaFile>
            </Mediafiles>
          </Linear>
        </Creative>
      </Creatives>
    </InLine>
  </Ad>
</Vast>

After that, the XML structure is encoded in the URL format and placed in the bid.adm field. Reading the display and sending win notice occurs after viewing 25% of the video.

Teaser materials should be represented by separate objects in the response code. The ext.ads field contains an array of material objects, where:

  • id - material identifier
  • title - material title
  • text - text material
  • url - link to transition
  • image - image link
  • cpm - personal cpm of the material (price per 1000 impressions)

If it is not possible to specify the material's individual CPM, then the rate must be indicated in the price field. This rate will be distributed evenly among the materials in the DSP response.
RTB SSP supports the standard set of macros for nurl.
Exceptions are the $ {AUCTION_AD_ID} and $ {AUCTION_PRICE} macros.
The auction takes place at the level of individual materials, not at the block level, so the value of $ {AUCTION_AD_ID} consists of a list of materials that had won the auction and it is separated by a comma.
The macro $ {AUCTION_PRICE} contains the bid of the winning material, in fact the bid of the second of the materials in the auction, taking into account the mechanism of the “auction of the second price”.
And the macro $ {AUCTION_PRICE_TTL} will contain the sum of the bids of materials from the macro $ {AUCTION_AD_ID}, that is, the total amount of the write-off for these bids.

User Synchronization

For DSP, a user synchronization service with KadamSSP is also available under the SSP initiator scheme. The principle of operation is as follows:

    1. KadamSSP calls the match link provided by the DSP with the user id in the SSP system.
    2. DSP recognizes \ creates a user cookie and redirects it to the match link provided by the SSP with its user id or if the user is not interested or the DSP wants to store a matching table on its side - responds to the request with code 204.
    3. KadamSSP contributes to the table.
    4. In the following auctions with this user, the DSP will receive a request with the “user.buyeruid” field and the user id value in the DSP system.

Also, with the cookie service running and the format of storing the match table on the SSP side, the option “Send only matched” is possible, in which only requests are sent to the DSP with the participation of the user for whom an entry has been created in the match table.