REST Resource: bidders.biddingFunctions

Stay organized with collections Save and categorize content based on your preferences.

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),
  "state": enum (State)
}
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.
state

enum (State)

Output only. The state of the bidding function.

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 debug string that may be used for remote debugging and troubleshooting of a bidder-provided bidding function. The debug string should not contain a user identifier. The maximum length of the debug string is 200 bytes. 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. In addition, the debug string can be inserted into the creative HTML snippet through macro substitution if the following string is included in the snippet: “%%DEBUG_STRING%%”. Ensure the debug string complies with Platform Program Policies. Sample Bidding Function:

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!"
  }
}

State

Possible states of functions that can be run for the server-side TURTLEDOVE simulations.

Enums
STATE_UNSPECIFIED Default value that should not be used.
ACTIVE An active function. Only ACTIVE bidding functions or ad scoring functions are made available for the server-side TURTLEDOVE simulations. Every account is limited to 10 active bidding functions per account.
ARCHIVED A function that is no longer made available for invocation in a simulation and instead archived. An archived function can later be made active by activating the function through biddingFunctions.activate.

Methods

activate

 Activates an existing bidding function.

archive

 Archives an existing bidding function.

create

 Creates a new bidding function.

list

 Lists the bidding functions that a bidder currently has registered.