Targeting

📘

Migration Notes from 0.5 API

While the Buzz 0.5 and 2.0 APIs co-exist, your individual account must be set to work with one or the other APIs with regard to targeting. If you are not sure whether your account is ready to work with the new targeting-expressions resources please contact your account manager.

Targeting is at the heart of any bidding system. In Buzz, every Line Item must be associated with a set of targeting parameters that determines which ads are eligible to serve on which auctions. This process of matching yields a binary result: either the Line Item is eligible or it is not eligible. This is separate from the process of determining the amount to bid on an auction, which may be accomplished using a wide variety of technology and techniques.

Targeting Modules and Keys

Using the Buzz API you may create complex and powerful Targeting Expressions that use boolean relationships to determine whether to match a given auction. Targeting Expressions are built around a framework of targeting modules and targeting keys within those modules (see: List of Targeting Modules and Keys).

A targeting module is a grouping for related keys that may be used for targeting. For example, the geo module groups fields relating to geography. Within the geo module are multiple targeting keys such as cities, regions, zip_code_lists, etc. Targeting modules are useful for organizing related fields, but also they play a role in generating boolean expressions. The table below summarizes the how different combinations of targeting modules and keys are evaluated.

How Targeting Expressions are Evaluated

Exploring Targeting Modules and Keys

📘

Migration Notes from 0.5 API

• Targeting Modules and Keys are largely unchanged between the Buzz 0.5 and Buzz 2.0 APIs, but some Keys have moved into different Modules.
• The Buzz 0.5 /targeting resource for discovering keys with a GET request has been replaced by /ref/targeting-keys.
• The Buzz 0.5 POST to /targeting for testing targeting expressions is not supported in 2.0.

A list of targeting modules and keys may be found at: List of Targeting Modules and Keys.

To use the API to explore targeting keys and retrieve other metadata use the /ref/targeting-keys resource as shown below:

#Retrieve all keys
curl -X GET "[host]/rest/v2/ref/targeting-keys" -b cookies.txt

#Retrieve one or more specific keys by module
curl -X GET "[host]/rest/v2/ref/targeting-keys?module=geo" -b cookies.txt

This resource will return useful metadata about the targeting key, including the available comparators and the resource to query for value values. An example is shown below:

{
	"name": "environment_type",
	"comparators": [
		"equals"
	],
	"module": "environment",
	"choices": null,
	"choices_url": "http://stingersbx.api.beeswax.com/rest/v2/ref/environment-types",
	"related_field": "id",
	"usage_tips": null
}

Targeting Expressions

To create or edit targeting for a Line Item you use the /targeting-expressions resource. This replaces the targeting_template endpoint from the Buzz 0.5 API and should be both more powerful and easier to use.

The syntax of a targeting-expression is a set of expressions organized by targeting module and targeting key. Each expression includes two layers of "predicates" which determine the and/or logic both between targeting keys and within targeting keys.

The first predicate determines how to evaluate targeting keys within a targeting module. As described above, the default behavior is to "AND" these keys, in which case the all predicate is used. But you may also use any between keys in order to change the evaluation logic to "OR".

Within a targeting key's predicate the expression then contains a comparator and a value. For example, the JSON snippet "comparator":"equals", "value":"foo" means "match if the value is foo". Not all comparators are supported for all targeting keys -- you can see which ones in the response to the /ref/targeting-keys endpoint described above.

Below are some truncated snippet examples of expressions:

#Match any of the deal-ids provided
		"app_site": {
			"all": {
				"deal_id": {
					"any": [{
						"comparator": "equals",
						"value": "adx/deal-123"
					},{
						"comparator": "equals",
						"value": "adx/deal-456"
					}]
				}
			}
      
#Match only if not in Canada or the US
		"geo": {
			"none": {
				"country": {
					"any": [{
						"comparator": "equals",
						"value": "USA"
					},
          {
						"comparator": "equals",
						"value": "CAN"
					}]
				}
			}
      
#Match an OR across targeting keys within the geo module
		"geo": {
				"any": {
					"country": {
						"any": [{
							"value": "USA",
							"comparator": "equals"
						}]
					},
					"metro": {
						"any": [{
							"value": "505",
							"comparator": "equals"
						}]
					}
				}

#Free-form boolean, may only be used with segment targeting key 
		"user": {
			"any": {},
			"all": {
				"segment": {
					"any": [{
						"value": "(stinger-54 OR stinger-1) AND stinger-103",
						"comparator": "boolean_expression"
					}],
					"all": []
				}
			},
			"none": {}
		}

Segment Recency

When evaluating a Targeting Expression that contains the segment targeting key, you may also optionally specify the time range in which the user must have been placed within the segment in order to match targeting by including the recency object. This can be useful, for example, if you wish to show different ads to users who recently visited a website, versus those who may have visited the site several days ago.

The recency object includes the start and end fields. Validation is as follows:

• Either must be present or the recency object must be set to null
• Values must be greater than zero
• Values must be less than or equal to 129,600 (e.g. 90 days)
• start must be less than end when both are present

Below is an example snippet of a Targeting Expression specifying that users within the segment must be between one hour and one day old.

#Segment targeting including recency object 
		"user": {
			"any": {},
			"all": {
				"segment": {
					"any": [],
					"all": [{
						"recency": {
							"start": 60,
							"end": 1560
						},
						"comparator": "equals",
						"value": "stingersbx-1"
					}]
				}
			},
			"none": {}
		}

Associating a Targeting Expression to a Line Item

📘

Migration Notes from 0.5 API

• Buzz 0.5 uses a different object, the targeting_template, to define targeting. Once your account is enabled for targeting-expressions the targeting_template_id field in the Line Item object will no longer be used and will not be editable.
• In Buzz 0.5 a targeting_template could be associated with multiple Line Items (API only, not supported in the UI). In the 2.0 API a targeting-expression may only be associated with one Line Item.
• The Buzz 0.5 concept of strategy is not included in 2.0. The strategy object limits the available targeting keys based on the line_item_type. For example the targeting keys within the video targeting module could only be used on video line items. In Buzz 2.0 this restriction is removed and simplified, though you should be cautious that video-specific targeting may not make logical sense when used on a non-video Line Item.

In order for a Line Item to be made active it must be associated with a targeting-expression. To associate, get the id of the targeting-expression, then PUT that ID on the Line Item resource as shown below (Line Items are still only supported only in the 0.5 API):

curl -X PUT "[host]/rest/line_item" -b cookies.txt -d 
'{"line_item_id":1,"targeting_expression_id":2}'

Programmatic Guaranteed

Programmatic Guaranteed deals are arrangements between publishers and buyers where the expectation is that the buyer will bid and win virtually all available auctions under a specific deal. As a result of this business arrangement, the bidder cannot use many of the targeting, budget and pacing features since they would cause variations in bidding.

A Line Item can be setup as Programmatic Guaranteed by setting the guaranteed field to true. When set, the targeting-expression associated with that Line Item must also have the guaranteed field set to true and targeting will be limited to only include the deal-id targeting parameter. Below is a sample snippet of an expression for a guaranteed Line Item:

{
	"modules": {
		"app_site": {
			"all": {
				"deal_id": {
					"any": [{
						"value": "stv/BEES-DEAL",
						"comparator": "equals"
					}]
				}
			}
		}
	},
	"guaranteed": true,
}

Example Targeting Expression

Complete example of of a targeting-expression:

{
	"id": 2,
	"modules": {
		"app_site": {
			"all": {
				"deal_id": {
					"any": [{
						"comparator": "equals",
						"value": "adx/deal-123"
					}]
				}
			},
			"any": {},
			"none": {
				"domain_list": {
					"any": [{
						"comparator": "equals",
						"value": 2
					}]
				},
				"publisher_id": {
					"any": [{
						"comparator": "equals",
						"value": "adx/pub-456"
					}]
				}
			}
		},
		"environment": {
			"all": {
				"ads_txt": {
					"any": [{
						"comparator": "equals",
						"value": 6
					}, {
						"comparator": "equals",
						"value": 7
					}]
				},
				"environment_type": {
					"any": [{
						"comparator": "equals",
						"value": 0
					}]
				}
			},
			"any": {},
			"none": {}
		},
		"exchange": {
			"all": {
				"inventory_source": {
					"any": [{
						"comparator": "equals",
						"value": "adx"
					}, {
						"comparator": "equals",
						"value": "rp"
					}, {
						"comparator": "equals",
						"value": "pm"
					}, {
						"comparator": "equals",
						"value": "ox"
					}],
				},
				"auction_type": {
					"any": [{
						"comparator": "equals",
						"value": 1
					}]
				}
			},
			"any": {},
			"none": {}
		},
		"geo": {
			"all": {
				"country": {
					"any": [{
						"comparator": "equals",
						"value": "USA"
					}]
				}
			},
			"any": {},
			"none": {}
		},
		"platform": {
			"all": {
				"browser": {
					"any": [{
						"comparator": "equals",
						"value": "Chrome"
					}, {
						"comparator": "equals",
						"value": "Firefox"
					}]
				},
				"bandwidth": {
					"any": [{
						"comparator": "equals",
						"value": 4
					}]
				}
			},
			"any": {},
			"none": {}
		},
		"time": {
			"all": {
				"user_time_of_week": {
					"any": [{
						"comparator": "in_range",
						"value": [480, 539]
					}, {
						"comparator": "in_range",
						"value": [540, 599]
					}, ...]
				}
			},
			"any": {},
			"none": {}
		},
		"user": {
			"all": {
				"segment": {
					"any": [{
						"comparator": "equals",
						"value": "demosbx-1"
					}, {
						"comparator": "equals",
						"value": "demosbx-2"
					}]
				}
			},
			"any": {},
			"none": {}
		}
	},
	"create_date": "2020-06-22 08:22:22",
	"update_date": "2020-07-07 14:31:50",
	"active": true,
	"alternative_id": null,
	"notes": null,
	"name": null,
	"account_id": 2
}