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

PropertyDescription
NameName of the Catalog to identify it in user interfaces
ID KeyThe key associated with the unique identifier of this Catalog’s items (e.g. SKU). This key must appear in the data for items synced to this Catalog. Note that the ID Key cannot be changed after the catalog is created.

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

PropertyDescription
KeyThe key of the attribute in product item data (e.g. price)
TypeAcceptable values:

- string (supports prefix query)
- text (supports full text query)
- number (supports range query)
- boolean
- datetime (supports range query)
- ref (the ID of an item in another Kevel Catalog)
CardinalityAcceptable values: one or many. Identifies whether the values for this search key will be an array or single value. Note: cardinality many is not supported for keys of type text.
Catalog IDThe ID of another Kevel Catalog that contains the definition of ref type search keys. Supported for search keys of type ref only. See Referenced Catalogs section for more information.
UI ConfigSee table below for options

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

PropertyDescription
Display ColumnBoolean that controls whether the Key is displayed as a column in the products table
Display FilterBoolean that controls whether the Key is displayed as a filter alongside the products table
TypeaheadBoolean that controls whether filter is a typeahead/autocomplete style input. When true, distinct values from the related table for this Key will be listed in the filter dropdown. When false, a standard text input element is rendered.
Filter by OneBoolean that controls whether filter is single or multi-select
Filter by RangeBoolean that controls whether the filter is a single or range (minimum and maximum values) input. Only applicable for number type Keys
LabelA friendly name for the Key used for column headers and filter input labels. If this is not set, the Key is used verbatim. For example, your source product data may have an attribute prod_primary_brand that can be displayed as simply Brand
OrderThe relative order to display the search key. If not set, the order the keys were created determines the display order. Note: Kevel's Management UI allows users to reorder and hide product table columns to meet their individual preferences that are saved in browser local storage—if present, those settings override the Order set here.
Allowed ValuesWhere a filter has a dropdown of selectable items, the items displayed will be limited to this list of IDs in the related table.
Ancestors KeyReference to the attribute name in the ref Catalog that holds data about the ancestors of a given item. Used in the display of filters where the items are of a hierarchical nature, for example product categories or other taxonomies.

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:

AliasDescription
kevel/nameThe name of the item. This is used by the Management UI when displaying the product table and Creatives derived from Catalog data will use this for their Title
kevel/imageA publicly-accessible URL for the primary product image. This is used by the Management UI when displaying the product table and Creatives derived from Catalog data may use too
kevel/product-idThe ID of items that should be used for "same product" matches by Kevel's Attribution model. This could be the ID Key or a non-unique ID (e.g. UPC) that may be shared across items in the Catalog—for example, a t-shirt may appear in the Catalog multiple times for each available size or color but all of those items share the same UPC
kevel/brand-idThe ID of the brand that this item belongs to. This is used for "same brand" matches by Kevel's Attribution model.
kevel/brand-nameThe name of the brand that this item belongs to. This is used for Reporting purposes.
kevel/main-category-idThe ID of the main or primary category this item belongs to. This is used for "same category" matches by Kevel's Attribution model. For example, an item may belong to a set of hierarchical categories: Toys > Games > Board Games. In this case, Board Games would be the main category.
kevel/main-category-nameThe name of the main or primary category this item belongs to. This is used for Reporting purposes.
kevel/categoriesAn array of categories that this item belongs to.
kevel/merchant-idThe ID of the merchant that sells this item. This can be used to enhance reporting for marketplaces that offer the same item for sale by multiple merchants or vendors.
kevel/merchant-nameThe name of the merchant that sells this item.

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.

PropertyDescription
id*The unique identifier for this category item.
name*The name of the category as displayed in the Management UI.
parent-idA single ID of the category that is the current item's most direct parent. For level 1 categories, the value of this attribute should be null.
ancestorsAn array of all category IDs that are higher up in the taxonomy tree than the item at hand. For level 1 categories, the value of this attribute should be an empty array [].

* indicates required property

With refs configured as described above, Kevel's Management UI can render rich filters.

With refs configured as described above, Kevel's Management UI can render rich filters that include hierarchical category captions.