"docs.beeswax.com" has a new address: "api-docs.freewheel.tv/beeswax." Please update your bookmarks accordingly.

Frequency Caps

Buzz supports frequency caps at both Campaigns and Line Items. Within each frequency capping statement, Buzz can support multiple caps. For example, you may wish to cap ads at once per hour AND at 5 times per day. These multiple statements are stored in a JSON document within the respective object. A frequency_cap_type field determines the data used for capping, as described below.

Validation of Frequency Cap Consistency

When submitting a set of frequency caps for a single object, Buzz will perform an additional check to see if the entirety of the set is logical and does not contain any contradictory statements. For example, you cannot cap one ad per day and also cap two ads per hour. The frequency cap set will fail if either:

  • More than one cap in the same statement has the exact same duration. e.g.: [{"duration":3600,"impressions":2},{"duration":3600,"impressions":1}]
  • A cap in the same statement has a lesser duration with the same or greater impressions. e.g. [{"duration":3600,"impressions":1},{"duration":3500,"impressions":2}]

Validation at Line Item Level

When submitting frequency caps at the Line Item level, the caps will also be compared to the Campaign which owns the line item. The check will determine whether the Line Item contains any frequency caps with a lesser duration and the same or greater number of impressions. e.g.

  • Campaign frequency cap: [{"duration":3600,"impressions":1}]
  • Line Item cap: [{"duration":3500,"impressions":2}].

Line Items must have the same frequency_cap_type and frequency_cap_vendor as the Campaign, if either are set at the Campaign level.

Validation at Campaign Level

When changing existing frequency caps or adding new ones to an existing Campaign, the caps will also be compared to any Line Items which belong to that Campaign. The check will determine whether the Line Item contains any frequency caps with a lesser duration and the same or greater number of impressions. e.g.

  • Campaign frequency cap: [{"duration":3600,"impressions":1}]
  • Line Item cap: [{"duration":3500,"impressions":2}].

Campaigns must also have the same frequency_cap_type as all Line Items, if it is set at both levels.

JSON Structure

KeyExample valueDescription
frequency_cap[{"duration":3600,"impressions":2}, {"duration":86400","impressions":5}]An list of sets, each in the format {"duration":<seconds>,"impressions":<impressions>}. Buzz sets a maximum number of frequency caps of 3 per object. Both duration and impressions fields must be present.

Example JSON

{"frequency_cap":
 	[
    {"duration":3600,"impressions":2}
  ]
}

Frequency Cap Types

Beeswax supports flexible ways to use inbound auction data to frequency cap. Which method is used depends on the frequency_cap_type field defined at the Campaign and Line Item level. Important note: Not all types are supported by default and your account may need to be enabled for some of the more advanced types. Please reach out to your account manager or support for more details.

frequency_cap_type ValueNameDescription
0 (default)StandardUse the browser cookie OR the device ID to cap.
1IP AddressUse the IP address of the end-user as included in the bid request. Ignore values where the final octet is truncated or where due to GDPR or other privacy regulation we do not have consent to use the full IP address.
2Standard with FallbackUse the browser cookie or device ID when present, then fall back to IP address when not present.
3Customer ID with FallbackUse an auction-provided customer ID when present, then fall back to the Standard option when customer ID is not present.
4 *Person IDUsing a third-party vendor's graph to frequency cap across devices at a person level.
5 *Person ID with FallbackSame as above, but when the person cannot be identified a cookie or device ID is used.
6 *Household IDUsing a third-party vendor's graph to frequency cap across devices at a household level.
7 *Household ID with FallbackSame as above, but when the person cannot be identified a cookie or device ID is used.

* When using one of the person- or household-level frequency cap types, the frequency_cap_vendor field must be set, and charges may apply. Also note, this feature must be enabled on your account.