Bidding Strategies

Buzz supports the ability to bid on impressions using flexible "bidding strategies" that are implemented into the Line Items. Each Line Item has a single bidding field, in which the bidding strategy, and all required parameters for that strategy, are defined. A list of existing strategies is here: List of Bidding Strategy Modules and Keys.

The format for the bidding field is as follows:

{
	"bidding_strategy": "<bidding_strategy_name>",
	"bid_shading": false,
	"bid_shading_win_rate_control":"NORMAL",
	"values": {
		"<bidding_key1>": "<bidding_value1>",
		"<bidding_key2>": "<bidding_value2>"
	},
	"custom": false
}

For example, if you want to set a static CPM bid of $1.21, use the "CPM" bidding strategy as follows:

{
	"bidding_strategy": "CPM",
	"values": {
		"cpm_bid": 1.21
	},
	"bid_shading": true,
	"bid_shading_win_rate_control":"NORMAL",
        "pacing": "lifetime",
        "pacing_behavior": "even",
        "multiplier": "1.000",
        "catchup_behavior": "immediate",
	"custom": false
}

If you want to use the pacing behavior, multiplier and catchup behavior, please set all three keys. If you wish to set only one (e.g., multiplier), you should still include the other two keys, setting them to their default values.

CPA Example

If you want to set a CPA bidding strategy, use the "CPA" bidding strategy as follows:

{
	"bidding":{
        "strategy":"CPA",
		"values": {
            "max_bid": 1,
    	    "cpa_event": 126,
    	    "cpa_target": 0.5
		},
	    "pacing": "lifetime",
    		"pacing_behavior": "even",
    		"multiplier": "1.02",
    		"catchup_behavior": "ahead",
	    "custom": false,
        "bid_shading_control":null
    }
}

Please specify the event ID that has enough number of attributed conversions for model training; otherwise, an error message will appear.

API Usage

Like Targeting or Creative Attributes, you can use the API to either validate bidding strategies with a POST, or get a list of fields for a bidding strategy, with a GET. The API endpoint for bidding strategies including the /bidding/ path is as follows:

curl -X POST -b cookies.txt [host]/rest/bidding/cpm -d '{"bidding_strategy":"CPM","bid_shading":false,"values":{"cpm_bid":1.21},"pacing":"none"}'

JSON Structure

The Bidding Strategy JSON has the following fields:

Key	Example value	Description
key	cpm_bid	Keys are defined in the modules. For a list of modules and keys, see List of Bidding Strategy Modules and Keys.
bid_shading	false	Whether to apply an algorithm to reduce the bid based on historical price performance. This feature needs to be enabled for your account and for the specified bidding strategy. Fees may apply.
bid_shading_win_rate_control	NORMAL	When `bid_shading` is set to `true`, this field determines how aggressive the Bid Shading algorithm should be. Valid values are `MORE_AGGRESSIVE`, `NORMAL`, and `LESS_AGGRESSIVE` with a default of `NORMAL`.
values	1.12	A value for the key. This can be an int, string, number, or array, depending on the key Unlike Targeting or Creative Attributes, the value is not required to be in an array.
custom	false	Used to indicate whether the bidding logic is on a Beeswax server or a custom algorithm. This field will generally be set automatically by the system and can be safely omitted.
pacing	lifetime	If a bidding strategy can be paced, the `pacing` value can be set to `daily`, `flight`, or `lifetime`. If it cannot be paced, then it should be set to `none`. The `flight` type may only be used if the Line Item has Line Item Flights enabled and every flight includes a budget.
pacing_behavior	even	This setting attempts to spend slightly faster than Even. The pacing_behavior value can be set to `even` or `ahead`.
multiplier	1.000	Select a number between `1.000 - 2.000` to multiply against the budget to artificially inflate it, causing the pacing algorithm to pace towards the “larger” budget. The multiplier value must be a string within the specified range (1.000 - 2.000).
catchup_behavior	even	Defines which catch-up methodology should be applied in scenarios when pacing needs to catch-up to the desired rate. The catchup_behavior value can be set to `immediate`, `even` or `ahead`