Move from AdQuery category filtering to category targeting

AdQuery category filtering is the approach where your site sends an AdQuery on the placement, and Kevel keeps only the Ads whose Creative Template field holds the category of the page. This page is for ad ops and developers who store the categories an Ad targets in such a field and want to move those Ads to category targeting. That includes media owners whose advertisers choose categories in Console. To weigh the options first, see Transitioning to category targeting from an alternate approach.

Two kinds of AdQuery category filter

AdQuery can filter by category in two ways, and only one of them moves. See Filter by category.

• Categories an Ad targets. A Creative Template field holds the categories the advertiser or your team chose for the Ad, and your request queries it with the page's category. Console fills a field named ctKevelCategoryTargets this way. Category targeting replaces this filter: the categories become rules on the Ad.
• Categories a product belongs to. A field such as ctCategories holds the product's own categories, and your Catalog can keep it up to date. See Propagating Catalog item updates to Ads. Your request queries it with the page's category. This is your say on which products are relevant on a page. It stays, and it combines with category targeting.

When to move and when to stay

AdQuery category filtering and category targeting are both supported. Each is one condition, and an Ad serves only when it passes every condition it has. The two combine: the advertiser's choice of categories and your filter on what is relevant must both allow the Ad.

Move when you want:

• The matched category in reports. AdQuery filters are not reported as a category. Category rules add Placement Category (Matched).
• Category bid modifiers. AdQuery has none. Category bid modifiers match the category exactly, and are set in the Ad Server UI or Management API.
• Include and exclude rules on the Ad. Your team manages them in the Ad Server UI or Management API, from a list Kevel loads, instead of through a template field.

Stay with AdQuery when:

• You filter on a product's own categories. That filter answers a different question: which products you are willing to show on a page. Keep it.
• You want your Catalog to decide where an Ad can serve. Category rules are saved IDs and do not follow your Catalog. When a product leaves a category, its Ads keep the rule. An AdQuery on a field that your Catalog keeps up to date means an Ad serves only where the advertiser's choice and the Catalog agree.
• You filter on other properties. Price, size and similar fields stay in AdQuery. Category rules do not replace them.

What changes and what you keep

What happens to the template field. It stays on the Creative Template and on every Ad, and nothing removes the values. Console keeps writing it on each Product ad and Native Product ad it saves, alongside the new rule. Console shows an Ad's categories from its rule when it has one and from the field when it does not, so the Console screen looks the same either way. After you remove the clause, your requests stop querying the field and it no longer affects delivery. Leave it in place, because it is your way back.

What Console does for existing Ads. Console saves a rule as well as the field each time an advertiser saves a Product ad or Native Product ad. This happens where category targeting is enabled for your network. An existing Ad gets its rule the next time it is saved in Console. Console writes the rule only when it saves, so an Ad that nobody saves keeps only its template value. To update many Ads at once, contact your Kevel representative.

Running both together. An Ad can carry the field and the rule at once. It serves only where both pass. When the rule holds the same categories as the field, delivery does not change.

Before you start

Where it applies. Ads whose Creative holds the categories they target in an AdQuery field, on Decision API requests. In Console, it applies to Product ads and Native Product ads on placements where Kevel has enabled Categories.

What you need.

• The page category you already work out for your AdQuery, sent as category on each placement. See Send a category in decision requests.
• Your Kevel representative, who enables category targeting for your network and loads the list of categories.
• Access to the Ad Server UI or the Management API, to read and add category rules.

What it does not do.

• It does not change your AdQuery. You remove the clause yourself, when every Ad that relied on it has a rule.
• It does not copy values to your Ads. Console adds a rule when it saves an Ad. For other Ads, you add the rules.
• It does not follow your Catalog. A rule stays on an Ad after its product leaves the category. Keep an AdQuery on the product's categories to limit the Ad to pages the product still belongs to.
• It does not match a parent's children. Matching is exact, so select each category you want.
• It does not give Console an exclude control. Console offers Include only. Set Exclude rules on Ads you manage in the Ad Server UI or Management API, and change the category rules of Console-booked Ads in Console. Category bid modifiers in Console are coming soon.

Move AdQuery category filtering step by step

The order matters. Send the category first, and keep the AdQuery clause until every Ad has a rule.

Find the AdQuery clauses you run

Purpose. Separate the clause that moves from the ones that stay.

1. Read a live request. Find each adQuery clause that uses the page's category.
2. Sort the clauses. A clause on a field that holds the categories an Ad targets moves. A clause on a product's own categories, and clauses on price or size, stay.

"adQuery": {
  "ctKevelCategoryTargets": { "in": ["cat7"] },
  "ctCategories": { "in": ["cat7"] }
}

In this request, the first clause moves and the second stays.

Validation. You can name the field that holds the categories an Ad targets, and the clause that queries it.

Send the category on every placement

Purpose. Give Kevel the category of each page before any rule depends on it. Nothing changes in delivery.

1. Add category to each placement. Send the same value your AdQuery uses for the page, such as cat7. Put it inside each entry of placements, and keep the adQuery. Use one value for each page. Matching is case-sensitive. Reports show each value as sent.
2. Cover every placement where an Ad with category rules should serve. An Ad with any category rule is not eligible on a request that has no category.

Validation. Run a report grouped by Placement Category, as described in Report on categories. Your values appear on the pages you expect. The AdQuery filter is not reported as a category, so this also gives you category reporting before you move anything. If Placement Category is not in the Group By panel, ask your Kevel representative to enable it, or run the report through the Reporting API.

Ask Kevel to enable it and load the category list

Purpose. Get a list that your team chooses from, and that equals what your pages send. Kevel performs this step.

1. Send your Kevel representative the values. Each value in the field is a category ID that your pages send, so those strings are the IDs to load. Say whether they come from your product feed or from a separate list. Ask for category targeting to be enabled for your network and the list loaded. Kevel can build the list from your product feed each time it ingests a feed file. If you use a separate list, you keep it current. See Targetable categories.
2. Compare one real value from each source. The value in the field, the value your pages send and the ID in the list must be identical. Matching is case-sensitive. An ID that does not match saves and never serves.

Validation. Category Targeting appears in the Flight sidebar, and the Categories picker lists your categories. GET /v1/category-catalog returns them with Id, Name and ParentId. The picker and the endpoint read the first 10,000 categories.

Add category rules to your Ads

Purpose. Give each Ad the rule its template field implies.

1. Add rules to Console Product ads and Native Product ads. An existing Ad gets its rule when it is saved in Console. Save the Ads you want to move, or contact your Kevel representative to update many at once.
2. Add rules to the Ads you manage in the Ad Server UI or Management API. For each Ad, add an include rule for every category its field holds. Where all the Ads in a Flight target the same categories, put the rules on the Flight. An Ad with its own rules uses them instead of its Flight's. The steps are in Set up category targeting.
3. Read the values from the Creative. In the Management API, the field's values are in the Creative's TemplateValues. Send each as CategoryTargeting with Id set to the value and IsExclude set to false, and send the full list on every update. An update that leaves it out clears the saved rules, unless your network uses partial updates.
4. Check the limit. A Flight or Ad holds 25 category rules by default. If an Ad's field holds more, ask your Kevel representative to raise the limit before you add the rules.

Validation. For a sample of Ads, the rules match the field. Console shows the same categories whether an Ad has a rule or only the field, so check in the Ad Server UI or read CategoryTargeting through the Management API.

Compare with the AdQuery still in place

Purpose. See what the rules do alone, before the clause goes.

Keep the clause. An Ad with a rule for each category in its field passes both conditions, so delivery is unchanged. Then compare. On a test network, or on one site or placement, send the same request with the clause and without it. Compare the Ads returned and the fill rate. Allow a few minutes after you save rules, because a decision can briefly return mixed results right after an edit.

The last two rows are the risk. An Ad in the last column serves on every category page the moment the clause goes.

Validation. The results match the table, and equivalent Ads return with the same fill rate on both requests.

Check that every Ad has a rule

Purpose. Keep any Ad from losing its only targeting when the clause goes.

1. List the Ads that rely on the field. Include every Ad whose Creative holds values in it.
2. Check each for a rule. Look at Category Targeting on its Flight, at Delivery Settings on the Ad, or at CategoryTargeting in the Management API.
3. Add a rule to each Ad that has none. Save it in Console, or add the rule in the Ad Server UI or Management API.
4. Decide about Ads with an empty field. A clause written with nullValuesMatch set to false, which is the default, leaves out an Ad whose field has no value. Such an Ad does not match the clause today, and it would serve on every category page without the clause. Add a rule, or pause the Ad.
5. Test without the clause. Send a category the Ad should not serve on. The Ad must not return.

Validation. No Ad in your sample returns for a category it should not serve on.

Remove the AdQuery clause

Purpose. End with one mechanism for the categories an Ad targets.

1. Start with one site or placement. Remove the clause there and watch the Ads returned and the fill rate.
2. Remove only the clause on the targeted categories. Keep the clause on the product's own categories, and the clauses on price, size and other properties.
3. Roll out to the other placements. Do it as you did the first.
4. Leave the field and its values in place. They cost nothing, and they are your way back.

Validation. Ads still serve on the pages that match their categories. A report grouped by Placement Category (Matched) shows the matched categories, and a report grouped by Placement Category shows fill rate in line with what it was.

Roll back

Put the AdQuery clause back on your requests. The template field still holds every Ad's values, so the AdQuery behaves as before. The rules can stay, and an Ad then passes both again. To remove them, delete the categories on the Flight or Ad. In the Ad Server UI, remove each category in Category Targeting on the Flight, or in Delivery Settings on the Ad. Removal saves at once. In the Management API, send CategoryTargeting as an empty list.

If you ask Kevel to turn category targeting off for your network, delete the rules first. With it off, Kevel ignores saved rules, so Ads that carried them serve on every category page, including Ads that excluded categories.

What reporting looks like before and after

• Before. AdQuery filters are not reported as a category. If your pages send category, Placement Category shows requests, impressions, clicks, revenue and fill rate for each page.
• After. Placement Category (Matched) shows the category that matched an Ad's include rule. An Ad that only excludes categories has no matched category, and neither does an Ad without rules.
• Fill rate by category. Read it from Placement Category. Placement Category (Matched) is a performance dimension, so request counts and fill rate do not apply to it.
• Console. Category reporting in Console is coming soon.

See Report on categories.

Troubleshooting

Related

• Transitioning to category targeting from an alternate approach
• Set up category targeting
• Send a category in decision requests
• Category targeting in Console
• AdQuery