Creating Catalogs

Catalog Data Needs: What to Consider

When deciding on what data to share with Kevel, you should consider what’s needed to satisfy the three categories of usage for product data in Kevel’s systems (some of which may overlap):

1. Campaign management — product attributes needed to find and add the right products to campaigns by your AdOps team. If you plan to use Kevel Self Serve, you should consider what your advertisers need as well.
2. Targeting — product attributes stored on ads to ensure the most relevant sponsored listing is shown to end users. This typically matches the filters available on your website (eg categories, price, brand) so that Kevel can effectively narrow the candidate list of ads to match the specific facets active on a given product listing page
3. Rendering — product details required to display the sponsored listing on your website or app. Some integrations only need the SKU and lookup details in their systems after winning ads are returned. Others want ad responses to match organic listings (eg images, title, description, link).

Catalog Definition

To begin the process of ingesting your catalog of items, Kevel first needs to understand the shape of the catalog data and how that data will be used. To do so, you'll define search keys to help filter the data, and aliases to correlate your unique product attribute keys with Kevel's reserved keys.

The only required property of a Catalog definition is a unique identifier for items, but there are other recommended configurations to create the best experience for AdOps users and enable Attribution and Reporting functionality detailed in the sections that follow.

Catalog Definition Properties

Search Keys

Defining Catalog search keys enables granular, custom filtering of items in that Catalog. For example, defining a search key for "price" enables searches like "show me all items that have a price greater than $50" or "show me all items that have a price between $100–$500." Product Catalog items are often categorized—so, defining a search key for "category" enables searches like "show me all items that have the category shirts or blouses."

Search keys are optional. If you don't specify any search keys when you create a Catalog, you can search items by the ID Key defined for that Catalog.

Search Key Properties

Kevel's Management UI for creating Ads from products can be customized to create the optimal experience for campaign managers. For each search key, you can configure the following UI Configuration.

UI Configuration

Aliases

Aliases allow you to correlate your unique product attribute keys with Kevel systems. This means you don't have to change your naming conventions when connecting your item feed to Kevel. The following aliases are recommended to create the best experience for UI users and enable Attribution and Reporting functionality:

Referenced Catalogs

As noted in the Search Keys section above, one of the Search Key Types is ref, a reference (by ID) to an item in another Catalog. Refs reduce the size of items stored in product Catalogs and reduce data duplication by storing details on referenced attributes centrally instead of repeating those details on every product item.

Category taxonomy data is the most common use of refs. To use refs in this way, include an attribute with name categories (e.g.) on each product item that is an array (cardinality: many) of category IDs. For example:

...  
"categories": [  
  141259,  
  135968,  
  137174,  
  136361  
]  
...

The details of these categories are stored in a separate Catalog which can be synced independently of the product Catalog—these category definitions can even be shared across multiple product Catalogs offering further efficiencies. Here is an example item in a categories "feed" file:

{  
    "id": 136361,  
    "name": "Clutch Bags",  
    "parent-id": 135971,  
    "ancestors": [  
        135971,  
        141258  
    ]  
}

These items have the properties detailed in the table below. Note that aliases can also be used in this context so the literal property names can differ from this example.

*indicates required property

Targetable categories

Category targeting reads its list of categories from a separate table, not from your product Catalog. The table type is kevel/targetable-categories. The Ad Server UI and Console pickers use the table to list the categories people can target, and GET /v1/category-catalog returns it. To use the categories on Flights and Ads, see Set up category targeting.

The table feeds the pickers only. Kevel does not read it when it selects Ads. A Flight or Ad keeps matching its saved category IDs if you later remove a category from the table.

The name kevel/categories belongs to two other things: a table type that Console's product category picker reads, and an alias on a products table that lists each product's categories (see Aliases). Neither is the table category targeting reads.

Table rules

One table per network. A network has exactly one table of this type. GET /v1/category-catalog returns a 400 when the network has none or has more than one. The endpoint does not combine tables.

• None: "No kevel/targetable-categories table is configured for this network."
• More than one: "More than one kevel/targetable-categories table is configured for this network."

Row keys. Each row exposes these keys.

Each row must expose kevel/category-id, either as a literal key or through an alias that maps it to your ID field. A row that has neither comes back with a null Id.

One row for each level. Every level of the hierarchy is its own row. Where your IDs are full paths, the ID is the full path, the name is the last level, and the parent is the path above it:

Who sets up the table

The table is separate from your product catalog. It can hold your site's own category taxonomy, with no connection to your products, or Kevel can build it from the categories in your product feed and refresh it each time the feed is ingested. Your Kevel representative sets it up. After that, you can update it through the Catalog Management API.

Size and checking

Category targeting currently supports up to 10,000 categories in the table. If you have more, contact your Kevel representative so we can review how to support you.

A category that is not in the table still matches when a Flight or Ad carries its ID, which you can set through the Management API.

To check the table, call List Category Catalog, GET /v1/category-catalog, with your Management API key. A 200 returns the rows as Id, Name and ParentId.