Send a category in decision requests

Sending a category tells Kevel which category page in your site or app each request comes from. Developers add one string to each placement in the Decision API request. It applies whichever approach you use to target by category.

Why send a category

• Reporting. The value appears as Placement Category in reports, so you can report performance by category, and fill rate where your network has it enabled.
• Category targeting. Category targeting and category bid modifiers compare the value with the rules on your Flights and Ads. It is the field they match on.
• No change to selection on its own. Sending a category does not change which Ads are selected until an Ad has category rules, so you can add it without affecting delivery.

What each approach sends

This page is about the category field. Each approach matches on a different field of the request, so what you send depends on the approach you use.

How it works

The category field sits inside each entry of the placements array, not at the root of the request. Each slot on a page can carry its own category. Kevel trims spaces at the start and end, splits the value at your network's delimiter for logs and reports, and compares the whole value with category rules. See How category targeting matches Ads.

Before you start

Where it applies. Every Decision API request. It is required for category targeting and category bid modifiers. With the other approaches it is optional, and it adds Placement Category to your reports.

What you need. A category value for each category page on your site or app. If you use category targeting, each value must equal an ID in the category list Kevel sets up for your network (matching is case-sensitive). The list can be your site's own category taxonomy or come from your product catalog.

What it does not do. It does not carry a category on every kind of request. Only the Decision API (/api/v2) reads category, so Ads that have category rules do not serve through /ados, /amp, /api/v1, /s/ or /vast3. It does not accept more than 200 characters. A longer value returns a 400 for the whole request, so shorten it or use an ID. Matching uses whole-string matching independent of leading and trailing whitespace, including the delimiter value. The delimiter splits the value into levels for logs and reports.

Add the category to each placement

Purpose. Give Kevel the category of the page for every placement on it.

1. Choose a value for each category page. Use an ID or a name, and keep the same value for the same page on every request.
2. Add category to each placement. Send a string.
3. Deploy the change. There is no new endpoint and no campaign change.

POST https://e-{networkId}.adzerk.net/api/v2
Content-Type: application/json

{
  "placements": [
    {
      "divName": "sponsored-slot-1",
      "networkId": 12345,
      "siteId": 98765,
      "adTypes": [5],
      "category": "Electricals > Computing > Laptops"
    }
  ]
}

Validation. After some requests, run a report grouped by Placement Category, as described in Report on categories. Your values appear, with levels joined by >, for example Electricals > Computing > Laptops. A single value such as 4412 appears as 4412. In the Ad Server UI, grouping reports by Placement Category is enabled per network, so ask your Kevel representative if you do not see it.

Choose the format

You can send a single value, such as an ID or a name, or a breadcrumb with levels separated by a delimiter.

• Single value. One value is one category in reports, with no levels.
• Breadcrumb. Kevel splits the value at the delimiter, trims whitespace around each level, and logs the levels in order. Reports show the levels joined with >.

If your site has a category hierarchy, send a breadcrumb. The delimiter is > unless Kevel has set another for your network. You cannot change it yourself. Contact your Kevel representative to change it. Send one format consistently.

How to keep category targeting aligned with your catalog

Category targeting lets advertisers choose the category pages their Ads appear on. Kevel keeps each choice as it was saved and does not change it when your catalog changes. So when a product leaves a category, its Ads keep that category and can still serve on that page.

If a placement serves product Ads and you want to ensure promoted products are relevant to the navigational category, Kevel recommends adding an AdQuery filter on an AdQuery-enabled, catalog-synced Creative Template field. Advertisers can still target the categories they choose, and the filter makes sure an Ad serves only on the categories its product carries in your catalog. Nothing is added to or removed from the advertiser's choices.

For more information, see Alternative category targeting methods: Filter by category with AdQuery.

What you need

• A Creative Template field on your product Ads, such as ctCategories, that holds each product's categories as an array. Link it to your catalog so it updates when a product's categories change. Your Kevel representative can set up the link. See Propagating Catalog Item Updates to Ads.
• The field's values in the same form as your category values. If you send category IDs, the field holds IDs. If you send full paths, it holds full paths.

Add the filter

1. Check the field. Open one product Ad and confirm the field holds the product's current categories, in the same form as your category values.

2. Add an AdQuery clause on each placement, with the same value you send in category. If the placement already has an adQuery, add the clause to it. An Ad must match every clause.

   JSON

   "category": "Grocery > Dairy > Yogurt",
   "adQuery": {
     "ctCategories": { "in": ["Grocery > Dairy > Yogurt"] }
   }

3. Decide what happens to Ads without the field. Set nullValuesMatch to false to keep out Ads whose Creative has no value in the field. Set it to true if other Ads on the placement, such as banners, should stay eligible. See Using Arrays and Operators.

Validation. Choose an Ad that still targets a category its product has left. A request for that category no longer returns the Ad. A request for a category the product still has, and the Ad targets, returns it.

Old categories. Once the filter is live, categories a product has left no longer change where its Ads serve, but they still appear on the Ads. Advertisers can remove them in Console. To remove them from many Ads at once, contact your Kevel representative.

Limits

Troubleshooting

Related

• Category targeting
• Set up category targeting
• How category targeting matches Ads
• Report on categories
• AdQuery
• Decision API request reference