Linking Catalog Items to Ads

A key benefit of using Kevel Catalog is the efficiency gained by using Catalog Item data to create batches of Ads. This process is made possible using Ad Templates and Creative Templates. These templates allow you to define a set mapping for specific types of Ads and placements depending on your use case. For example, you may want to use one attribute of a Catalog Item in a featured placement on your homepage and a different attribute on a search results page. You could create two different templates to accommodate these different placements. When creating ads that target these placements all you need to do is select the Catalog item that will populate your pre-defined template with the appropriate fields.

Ad Templates define a mapping between Catalog item attributes and Kevel Ad and Creative fields. It is possible to set any Ad and Creative attribute from product data including Creative Template fields.

Creative Templates define a fixed schema to store native ad data and ensure that Decision Requests always return a consistent format. Using Creative Templates also unlocks granular filtering of candidate ads with Kevel's AdQuery feature.

📘

Managing Creative and Ad Templates

Creative Templates can be managed through the Creative Template API or through Kevel Studio.

At this time, Ad Templates are configured by Solutions Architects and Kevel Support.

Step 1: Define a Creative Template

The core of the Creative Template creation process is the same when making a template that will be used with Catalog items: give the template a name, description, and set of fields. Include a field for each facet you wish to filter on. For each filterable field, enable AdQuery.

📘

AdQuery

AdQuery is a Decision API feature that filters which ads get selected based on properties of the ads. It provides fine-grained controls on the ad request side—think of AdQuery as querying over ads in a database and returning selections that match your query.

Step 2: Define an Ad Template

Once you have defined a Creative Template, you can work with your Kevel team to define an Ad Template. The central piece of an Ad Template is a set of mappings that correlate properties of Catalog items to Ad and Creative attributes.

Ad Template Properties

Ad Template Mapping Properties

Propagating Catalog Item Updates to Ads

When you create an Ad derived from Catalog data (a product ad), Kevel stores a "provenance" record. This record contains the Ad ID, Catalog Item ID, and the Ad Template ID. When the source Catalog item changes, the Ad Template will be re-evaluated and the corresponding Ad data will be updated to match the linked item's data. The exception is a field you have changed on the Ad yourself. Kevel treats that field as yours and leaves it alone (see Protecting Fields from Catalog Updates).

For example, if the price of one of your products changes and you deliver an updated version of your product feed file to Kevel, all Ads linked to that product will show the updated price automatically. The exception is an Ad where you changed the price field manually.

Kevel can also automatically disable and re-enable ads from serving depending on the availability of each item in the Catalog. For this to be configured, Kevel needs each item in the Catalog to have a field representing the availability of the item, e.g. inStock: true/false. During the Catalog ingestion process, Kevel will determine if any Ads that utilize the associated Catalog data should be disabled or re-enabled. Alternatively, Kevel can map ad-activeness to the presence of an item in the Catalog so that if an item doesn’t appear in the next Catalog sync, any Ads associated with items that have been removed from the Catalog will be disabled (or deleted, depending on your desired configuration).

If you turn a product ad on or off yourself, that choice sticks. Kevel stops enabling or disabling that Ad based on Catalog availability, as described in the next section. Ads configured to be deleted when their item leaves the Catalog are still deleted.

Protecting Fields from Catalog Updates

Both Catalog updates and your own edits can change the same Ad. To keep your edits from being overwritten on the next Catalog sync, Kevel tracks which fields on each Ad and Creative you have taken over. These are called protected fields.

• Changing a field protects it. If you change a field on a product ad or its Creative in the Management API or the Kevel UI, that field is protected on that Ad. Later Catalog updates skip it and keep your value. Every other field keeps updating from the Catalog.
• Only real changes count. Saving a field with the value it already has does not protect it. A client that sends back the whole Ad on every update does not freeze every field.
• Creative Template fields are protected one at a time. Changing headline protects headline. The Creative's other template fields keep syncing.
• Overrides are protected from the start. Fields you set with Overrides when you create Ads from products are applied once at creation. They then belong to you, so Catalog updates do not change them.
• The link to the Catalog item is always Kevel's. The Ad's product link can't be protected and always follows the Catalog.

📘

Protected fields stay protected

A field stays protected until Kevel removes the protection. There is no supported way to view or clear protected fields yourself today, in the Kevel UI or the API. If an Ad has stopped picking up a Catalog change, or you want a field to resume syncing, contact Kevel Support.