Beeswax

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

Scope of Targeting Values

Behavior

Pseudo-code Example

Within a single targeting key

Values are always ORed together (outside of segment targeting, below).

country = (UK OR US OR CA)

Different targeting keys within a single targeting module

Values are ORed together within a targeting key.

Values can then either be ANDed or ORed across targeting keys within the same module.

country = (US OR CA) AND region = Detroit

OR

country = (US OR CA) OR region = London

Across targeting keys across modules

Values are ORed together within a targeting key, then ANDed across keys in different modules. You cannot OR across modules.

country = (US OR CA) AND domain = cnn.com

Segment targeting

Segment targeting may optionally use fully free-form boolean expressions.

(Segment-A AND Segment-B) AND NOT (Segment-C or Segment-D)

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 endpoint. 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.

Predicate

Behavior

all

All targeting within the expression must be true to match.

any

If any targeting within the expression is true, match.

none

All targeting within the expression must NOT be true to match

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.

Comparator

Behavior

equals

Value must be an exact match to the value field.

in_range

Value must be between the range of values, where the value field are expressed as a list like [1,100].

boolean_expression

Evaluate the boolean expression contained in the value field.

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": {}
        }

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. Line Items creation and editing are still supported only in the 0.5 API.

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
}

Updated 12 days ago


Targeting


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.