REST Resource: bidders.biddingFunctions

Resource: BiddingFunction

The bidding function to be executed as part of the TURTLEDOVE simulation experiment bidding flow.

JSON representation
{
  "name": string,
  "biddingFunction": string,
  "type": enum (FunctionType)
}
Fields
name

string

The name of the bidding function that must follow the pattern: bidders/{bidder_account_id}/biddingFunctions/{bidding_function_name}.

biddingFunction

string

The raw Javascript source code of the bidding function.

type

enum (FunctionType)

The type of the bidding function to be created.

FunctionType

Possible types of functions that can be run in the TURTLEDOVE simulation.

Enums
FUNCTION_TYPE_UNSPECIFIED Default value that should not be used.
TURTLEDOVE_SIMULATION_BIDDING_FUNCTION

Bidding function that can be used by Authorized Buyers in the original TURTLEDOVE simulation. See documentation on the TURTLEDOVE simulation at https://developers.google.com/authorized-buyers/rtb/turtledove.

The function takes in a Javascript object, inputs, that contains the following named fields: openrtbContextualBidRequest OR googleContextualBidRequest, customContextualSignal, interestBasedBidData, interestGroupData, and returns the bid price CPM. Example:

/* Returns a bid price CPM.
 *
 * @param {Object} inputs an object with the
 *                 following named fields:
 *                   - openrtbContextualBidRequest
 *                         OR googleContextualBidRequest
 *                   - customContextualSignal
 *                   - interestBasedBidData
 *                   - interestGroupData
 */
function biddingFunction(inputs) {
  ...
  return inputs.interestBasedBidData.cpm
      * inputs.customContextualSignals.placementMultiplier;
}
FLEDGE_BIDDING_FUNCTION

Buyer's interest group bidding function that can be used by Authorized Buyers in the FLEDGE simulation. See the FLEDGE explainer at https://github.com/WICG/turtledove/blob/main/FLEDGE.md#32-on-device-bidding.

The function takes one argument, inputs, that contains an object with the following named fields of the form:

{
   "interestGroup" : {
     "ad" : [
               "buyerCreativeId": "...",   # Ad creative ID
               "adData": { # JSON object }
     ],
     "userBiddingSignals": {
.        # JSON object
     }
    },
    "auctionSignals": {
      "url": # string,
      "slotVisibility": # enum value,
      "slotDimensions": [ {
         "height": # number value
         "width": # number value
       } ]
    },
    "perBuyerSignals": {
      # JSON object
    },
    "trustedBiddingSignals": {
      # JSON object
    },
    "browserSignals": {
      "recent_impression_ages_secs": [
        # Array of integers. Not yet populated.
      ]
    }
}

interestGroup: An object containing a list of ad objects, which contain the following named fields:

  • buyerCreativeId: The ad creative ID string.
  • adData: Any JSON value of the bidder's choosing to contain data associated with an ad provided in BidResponse.ad.adslot.ad_data for the Google Authorized Buyers protocol and BidResponse.seatbid.bid.ext.ad_data for the OpenRTB protocol.
  • userBiddingSignals: Any JSON value of the bidder's choosing containing interest group data that corresponds to user_bidding_signals (as in FLEDGE). This field will be populated from BidResponse.interest_group_map.user_bidding_signals for Google Authorized Buyers protocol and BidResponse.ext.interest_group_map.user_bidding_signals for the OpenRTB protocol.

auctionSignals: Contains data from the seller. It corresponds to the auction signals data described in the FLEDGE proposal. It is an object containing the following named fields:

  • url: The string URL of the page with parameters removed.
  • slotVisibility: Enum of one of the following potential values:
  • NO_DETECTION = 0

  • ABOVE_THE_FOLD = 1
  • BELOW_THE_FOLD = 2
  • slotDimensions: A list of objects containing containing width and height pairs in width and height fields, respectively, from BidRequest.adslot.width and BidRequest.adslot.height for the Google Authorized Buyers protocol and BidRequest.imp.banner.format.w and BidRequest.imp.banner.format.h for the OpenRTB protocol.

perBuyerSignals: The contextual signals from the bid response that are populated in BidResponse.interest_group_bidding.interest_group_buyers.per_buyer_signals for the Google Authorized Buyers protocol and BidResponse.ext.interest_group_bidding.interest_group_buyers.per_buyer_signals for the OpenRTB protocol. These signals can be of any JSON format of your choosing, however, the buyer's domain name must match between:

  • the interest group response in BidResponse.interest_group_map.buyer_domain for the Google Authorized Buyers protocol or in BidResponse.ext.interest_group_map.buyer_domain for the OpenRTB protocol.
  • the contextual response as a key to the map in BidResponse.interest_group_bidding.interest_group_buyers for the Google Authorized Buyers protocol or in BidResponse.ext.interest_group_bidding.interest_group_buyers for the OpenRTB protocol.

In other words, there must be a match between the buyer domain of the contextual per_buyer_signals and the domain of an interest group.

trustedBiddingSignals: The trusted bidding signals that corresponds to the trusted_bidding_signals in the FLEDGE proposal. It is provided in the interest group response as BidResponse.interest_group_map.user_bidding_signals for the Google Authorized Buyers protocol and BidResponse.ext.interest_group_map.user_bidding_signals for the OpenRTB protocol. This field can be any JSON format of your choosing.

browserSignals: An object of simulated browser-provider signals. It is an object with a single named field, recent_impression_ages_secs, that contains a list of estimated number value recent impression ages in seconds for a given interest group. recent_impression_ages_secs is not yet populated.

The function returns the string creative ID of the selected ad, the bid price CPM, and (optionally) selected product IDs. In addition, the bidding function may populate an optional string debug token that may be useful for remote debugging of a bidding function performing unexpectedly. This debug string is available in BidResponseFeedback (https://developers.google.com/authorized-buyers/rtb/realtime-bidding-guide#bidresponsefeedback-object) and BidFeedback (https://developers.google.com/authorized-buyers/rtb/openrtb-guide#bidfeedback), for the Google protocol and openRTB protocol respectively. Example:

function biddingFunction(inputs) {
  ...
  return {
    "buyerCreativeId": "ad_creative_id_1",
    "bidPriceCpm": 0.3,
    "productIds": ["product_id_1", "product_id_2", "product_id_3"]
    "debugString": "Bidding function executed successfully!"
  }
}

Methods

create

Creates a new bidding function.

list

Lists the bidding functions that a bidder currently has registered.