DocsToolsSupportNewsApps

Thrift file for Real Time Bidded Exchange protocol

Facebook APIs › Ads › Thrift file for Real Time Bidded Exchange protocol

Following is the thrift file syntax.

Shortcut to sections:

RtbUserContext

    struct RtbUserContext {
      // User IP address
      // IPv4 address: 192.168.1.*
      // IPv6 address: 3f12:1D00:4541:30:230:18ef:*:*
      1: string ipAddressMasked,
      // An identifier of user browser and the device type
      2: string userAgent,
      // User country
      3: string country,
    }

RtbPageContext

    struct RtbPageContext {
      // Page type
      1: i16 pageTypeId,
      // Number of slots available on this page
      // For marketplace ads, one ad takes one slot
      2: i16 numSlots,
    }

            /* Corresponding key for pageTypeId
    enum PageTypeCode {
      PAGE_UNSPECIFIED = 0;
      PAGE_CANVAS = 1;
      PAGE_PROFILE = 2;
      PAGE_SEARCH = 3;
      PAGE_EVENT = 4;
      PAGE_GROUP = 5;
      PAGE_PHOTO = 6;
      PAGE_HOME = 7;
      PAGE_OTHER = 8;
      PAGE_ALBUM = 9;
      PAGE_ADBOARD = 10;
      PAGE_PHOTOS = 11;
      PAGE_PERMALINK = 12;
      PAGE_REQS = 13;
      PAGE_PAGES = 14;
      PAGE_DASHBOARDS = 15;
      PAGE_HOME_FEED = 16;
      PAGE_WEB_MESSENGER = 26;
      PAGE_CALENDAR = 29;
      PAGE_NOTE = 30;
    }
            */

RtbBidRequest

    struct RtbBidRequest {
      // Unique ID generated by FB Ad Exchange
      1: i64 requestId,
      // Partner's user ID stored in the cookie matching table
      2: string partnerMatchId,
      // User context defined above
      3: RtbUserContext userContext,
      // Page context defined above
      4: RtbPageContext pageContext,
      // Is a test or not
      5: optional bool istest = 0,
      // Indicates if View tags are accepted. If false, then bid responses with
      // viewTagUrl in them will be considered invalid.
      6: bool allowViewTag = 0,
    }

            /*
     *** Example of RtbBidRequest in JSON ***

    {
      "requestId":2323423432,
      "partnerMatchId":"kkkkkk",
      "userContext":{
        "ipAddressMasked":"1.2.3.*",
        "userAgent":"User-Agent: Mozilla/5.0 Firefox/12.0",
        "country":"US"
      },
      "pageContext":{
        "pageTypeId":3,
        "numSlots":6
      },
      "istest":true
    }

            */

RtbBid

    struct RtbBid {
      // Ad Group ID, see the definition at
      // https://developers.facebook.com/docs/reference/ads-api/adgroup
      1: i64 adId,
      // A bid in cents
      // Note: the currency is already defined in the account
      2: i32 bidNative,
      // A string to be attched to the click URL
      3: string clickPayload, // base64 encoded preferred
      // A string to be returned on winner notification
      4: string impressionPayload, // base64 encoded preferred
      // dynamic creative spec
      5: optional RtbBidDynamicCreativeSpec dynamicCreativeSpec,
      // view tag
      6: optional string viewTagUrl, // WILL BE DEPRECATED
      7: optional list<string> viewTagUrls,
    }

RtbBidDynamicCreativeSpec

    struct RtbBidDynamicCreativeSpec {
      // The fields below are optional, and will overwrite the corresponding fields
      // in the original ad creative
      1: string title,
      2: string body,
      3: string link,
      4: string creativeHash,
      5: string imageUrl, // imageUrl overwrites creativeHash if both are returned
    }

RtbBidResponse

    struct RtbBidResponse {
      // Request ID specified in the RtbBidRequest
      1: i64 requestId,
      // A list of ads for auction
      2: list<RtbBid> bids,
      // Time taken by DSP in milliseconds to compute the response. i.e. between
      // receiving a bid request and responding with this bid response.
      // This helps calculate the network latency by eliminating the time
      // spent on the DSP side.
      3: optional i64 processingTimeMs;
    }

            /*
     *** Example of RtbBidResponse in JSON ***

    No ad in response

    {
      "requestId":2323423432,
      "bids":[]
    }

    One ad in response

    {
      "requestId":2323423432,
      "bids":[
        {
          "adId":60000001,
          "bidNative":300,
          "clickPayload":"cccccccccc",
          "impressionPayload":"mmmmmmmmmmmmmmmmmmm"
        }
      ]
    }


    Multiple ads in response

    {
      "requestId":2323423432,
      "bids":[
        {
          "adId":60000001,
          "bidNative":300,
          "clickPayload":"cccccccccc",
          "impressionPayload":"mmmmmmmmmmmmmmmmmmm"
        },
        {
          "adId":60000002,
          "bidNative":400,
          "clickPayload":"rrrrrrrrrrrrrr",
          "impressionPayload":"lllllllllllllll"
        }
      ]
    }

            */

RtbNotification

     /*
      * We ALWAYS notify partners of successful impressions (aka win notifications)
      */
    struct RtbNotification {
      // Request ID specified in the RtbBidRequest
      1: i64 requestId,
      // A list of events
      2: list<RtbEvent> events,
      // Is a test or not
      3: optional bool istest = 0,
    }

            /*
     *** Example of Win RtbNotification in JSON ***

    {
      "requestId":2323423432,
      "events":[
        {
          "status":1,
          "type":1,
          "adId":60000001,
          "price":192,
          "position":1,
          "impressionPayload":"mmmmmmmmmmmmmmmmmmm"
        },
        {
          "status":1,
          "type":1,
          "adId":60000002,
          "price":103,
          "position":3,
          "impressionPayload":"lllllllllllllll"
        }
      ]
    }

            */

RtbEvent

    struct RtbEvent {
      // Status of the event: delivered, error
      1: RtbEventStatus status,
      // Type: impression, click (not supported yet)
      2: RtbEventType type,
      // Ad ID provided in RtbBidResponse
      3: i64 adId,
      // Winning CPM price (in cents)
      4: i32 price,
      // Position of ad to be rendered
      5: i16 position,
      // The same impression payload provided in RtbBidResponse
      6: string impressionPayload,
    }


    enum RtbEventStatus {
      RTB_EVENT_STATUS_DELIVERED = 1,
      RTB_EVENT_STATUS_ERROR = 2,
    }

    enum RtbEventType {
      RTB_AUCTION_WIN_IMPRESSION = 1,
    }

RtbErrorNotification

             /*
     * We will also send error notifications for a random sample of bid responses
     * that were rejected by Facebook. However partners can get total error counts
     * through a separate API that contains hourly aggregated stats.
     *
     * When notifying partners of cases unrelated to the bids in the response like
     * timeouts, malformed json, etc. the bidErrors field will not exist.
     */
     struct RtbErrorNotification {
      1: i64 requestId,
      2: RtbResponseStatus responseStatus,
      3: optional list<RtbBidError> bidErrors,
     }


            /*
     *** Example of Error RtbNotification in JSON ***

    {
      "requestId":2323423432,
      "responseStatus": 7, # NO_VALID_BIDS (see RtbResponseStatus)
      "bidErrors": [
        {
          "adId": 60000002,
          "bidStatus": 1, # ERROR_INVALID_AD_ID (see RtbBidStatus)
          "impressionPayload":"lllllllllllllll"
        }
      ]
    }

            */

RtbResponseStatus

            /*
     * Status that captures what happened when a bid request was made to a partner
     * and to notify partners of bid responses that encountered errors.
     * See RtbErrorNotification below to see how it's used.
     */
    enum RtbResponseStatus {
      RESPONSE_UNKNOWN = 0,
      CONNECT_ERROR    = 1,
      TIMEOUT          = 2,
      HTTP_INVALID     = 3,
      JSON_EMPTY       = 4,
      JSON_MALFORMED   = 5,
      NO_BIDS          = 6,
      NO_VALID_BIDS    = 7,
      HAS_VALID_BIDS   = 8,
    }

RtbBidError

    struct RtbBidError {
      1: i64 adId,
      2: RtbBidStatus bidStatus,
      // The same impression payload provided in RtbBidResponse
      3: string impressionPayload,
    }

            /*
     * Status that captures what happened to a bid that was submitted as part of the
     * bid response and to notify partners of bids that encountered errors.
     * See RtbBidError and RtbErrorNotification below to see how it's used.
     */
    enum RtbBidStatus {
      BID_UNKNOWN                       = 0,
      ERROR_INVALID_AD_ID               = 1,
      ERROR_INVALID_VIEW_TAG            = 2,
      ACCEPTED                          = 3,
      ERROR_INVALID_BID_PRICE           = 4,
      ERROR_DISALLOW_VIEW_TAG           = 5,
      ERROR_DISALLOW_DYNAMIC_CREATIVE   = 6,
      ERROR_INVALID_DYNAMIC_CREATIVE    = 7,
      ERROR_INVALID_CREATIVE_TYPE       = 8,
      ERROR_MAX_PAYLOAD_LENGTH_EXCEEDED = 9,
    }
Updated last Tuesday
Facebook © 2013 · English (US)
AboutAdvertisingCareersPlatform PoliciesPrivacy Policy