Pretargeting configurations

  • Pretargeting configurations allow bidders to receive only bid requests for impressions matching their targeting criteria, and you can have up to 10 configurations at once.

  • Pretargeting acts as a filter, and you must create at least one configuration to receive bid requests; broadening criteria may increase the number of bid requests received.

  • Targeting values within a top-level field are processed with logical OR, while different fields are processed with logical AND, meaning bid requests must match at least one value in every set pretargeting field.

  • Bid requests can be eligible for multiple pretargeting configurations, and if so, the bid request will contain the billingId of each applicable configuration.

Bidders can use the pretargetingConfigs resource to receive only bid requests for impressions that match their targeting criteria.You can have up to 10 pretargeting configurations at once.

Each pretargeting configuration distributes bid requests across all endpoints. Bid requests aren't always distributed evenly across all endpoints. For example, a pretargeting configuration for specific geographic IDs in a given region might have fewer matches in trading locations that are farther from that region. Endpoints near those farther trading locations might receive fewer bid requests.

Best practices

In order to receive bid requests, you must create at least one pretargeting configuration. Here are some tips for managing your pretargeting configurations:

Scope

Pretargeting is like filtering. You should use pretargeting criteria to filter bid requests to those that are relevant to your use case. If you don't set any pretargeting criteria, you can receive bid requests for all impressions.

If you aren't receiving enough bid requests related to a given pretargeting configuration, you might want to broaden your pretargeting criteria.

Logic

Values in top-level targeting fields are processed with logical OR. This means you can receive bid requests that have at least one of the values you specify in the top-level field. For example, if your pretargeting configuration has languageCodes values en, de, and sv, you might receive bid requests with en, de, or sv as the detected language.

Different fields are processed with logical AND. You only receive bid requests that have a match for at least one value in every pretargeting field you set. For example, if your configuration has languageCodes values en, de, and sv, and includedPlatforms value PERSONAL_COMPUTER, you receive only bid requests that have a detected language of en, de, or sv and a device type of PERSONAL_COMPUTER.

Due to the logical AND across pretargeting fields, you can't include contradictory criteria. For example, including the same value in includedIds and excludedIds in a NumericTargetingDimensions criteria results in an error.

Overlap

Bid requests can be eligible for multiple pretargeting configurations.

You can create up to 10 pretargeting configurations to target different kinds of inventory. Pretargeting configurations can overlap, so a single bid request might be eligible for multiple pretargeting configurations. In this case, the bid request’s billing_id field contains the billingId of each applicable configuration. If multiple billing IDs are found in the bid request, you must specify which billing ID you're bidding on in the bid response’s billing_id field.

Geographic IDs

Some geographic IDs aren't targetable for policy reasons. For example, some regions with small populations can't be targeted because it would violate our privacy policy. Our policies are subject to change. If you specify a geographic ID in your pretargeting configuration’s geoTargeting that becomes invalid at a later date, the ID appears under the invalidGeoIds field at that time. Geographic IDs under invalidGeoIds have no impact on targeting. If a goegraphic ID in invalidGeoIds becomes valid, it's added to your pretargeting configuration's geoTargeting field.

The geo-table.csv file lists targetable geographic IDs, and is updated periodically as IDs are added and removed.

Bid request count

You should configure the maximum QPS for your bidder endpoints, and allow the Callout Quota System to manage the traffic sent to your endpoints for each of your pretargeting configurations.

Here are edge cases where managing maximum QPS at the pretargeting configuration level with maximumQps might be useful:

Receiving too many requests
If the Callout Quota System is sending an unusually large number of bid requests to bidder endpoints for a given pretargeting configuration, you can use maximumQps to manually adjust the number of requests.
Testing a configuration for new inventory
If you're trying to support new inventory, like a new creative format, you can implement a pretargeting configuration targeting only that inventory with a low maximumQps.

For inventory that's targeted by multiple pretargeting configurations, bid requests are sent to the bidder's endpoints, including the billingId for each configuration, as long as at least one of the configurations hasn't reached its maximumQps limit.