Overview

Attribution refers to the practice of identifying and attributing the influence of advertising on consumer behavior and purchasing decisions. In the digital advertising landscape, attribution plays a crucial role in understanding the impact and effectiveness of sponsored or promoted products and other ad formats in driving sales and revenue for businesses.

With Kevel, you can attribute any ad format to retail transactions—not just product listing ads (PLAs)—by defining a set of attributable products, categories, and brands associated with an ad. For PLAs this is set automatically based on the product metadata when using the “create ads from products” workflow in the UI or API via pre-defined Ad Template mappings. For display ads, sponsored brands and other formats, the set of attributable sales is explicitly set to match advertiser goals from specific product collection promotions to more general brand awareness campaigns.

There are four components to a successful attribution setup. These are outlined here with more details for each on the remainder of this page:

1. Catalog setup
   1. Product feed synced with Kevel. Catalog data is used when processing purchase events to determine the category and brand associated with the purchased product ID. Product data also enables an enhanced UI experience during the campaign setup step and enriches product-based reports.
2. Campaign setup
   1. A Campaign with at least one Flight that has Attribution Settings configured for post-click and/or post-view lookback window and product match.
   2. One or more Ads in the Flight with Attributable Items set. For PLAs this is set automatically using the Ad Template selected in the Create Ads from Products workflow. For non-PLAs this is set on a per-ad basis (more details below).
3. Ad impressions and clicks
   1. Ad interaction events associated with an end user. When a user sees or clicks on an attribution-enabled Ad, a touchpoint is recorded.
4. Purchase event stream
   1. Ongoing stream of transaction data sent to Kevel's purchase event endpoint. When purchase events are received, Kevel looks for touchpoints from #2 for the same user that made the purchase.

Catalog Setup

To support attribution processing, product feeds must contain the following fields on each item. Exact names may vary and will be mapped to aliases as part of the Kevel Catalog setup process:

• Main Category ID
  • The ID of the leaf 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.
• Main Category Name
• Brand ID
• Brand Name
• Product Name
• Product ID
  • The ID of items that should be used for "same product" matches by Kevel's Attribution model. This could be the primary 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
• Merchant ID [optional]
  • Required for marketplaces where multiple merchants sell the same product. When supplied, reports will include this dimension too.
• Merchant Name [optional]

Campaign Setup

Attribution settings are configured on Flights and Ads:

• Flight (applies to all associated Ads)
  • Post-Click and Post-View Lookback Windows
  • Post-Click and Post-View Match Types
• Ad
  • Attributable Items — one or more product, category, or brand that, when purchased, can be attributed to this Ad

Lookback Windows

A lookback window refers to a specific time period during which user interactions with sponsored product ads are attributed to conversions or actions. It determines how far back in time advertisers track and attribute conversions to their ad campaigns. Kevel supports both view-through and click-through attribution:

• View-through attribution: This match type attributes conversions to users who view a sponsored product ad but do not click on it. If a user views an ad and later converts within the designated lookback window, the conversion is attributed to the ad.
• Click-through attribution: In this match type, conversions are attributed when a user clicks on a sponsored product ad and directly completes the desired action, such as making a purchase.

Kevel supports lookback windows of 1, 7, 14 and 30 days. Alternatively, you can select ‘none’ to not perform a specific kind of attribution.

Attribution Match Types

Attribution match types define the criteria used to match user interactions with sponsored product ads to conversions or actions. They determine how closely the interaction aligns with the attributed conversion.

In sponsored product attribution, different attribution models can be used to understand the impact of advertising on consumer behavior and conversions. Among these models, three commonly used ones are same product attribution, same brand and category attribution, and same brand attribution. Let's explore the differences between them:

Same Product Attribution

Same product attribution focuses on attributing conversions specifically to the exact product that was advertised. In this model, the conversion is attributed only when a customer clicks or interacts with a sponsored product ad and subsequently completes a purchase of the same product that was advertised.

For example, if a customer clicks on a sponsored product ad for a specific brand of headphones and then purchases those exact headphones, the conversion is attributed to the same product.

Same Brand and Category Attribution

Same brand and category attribution expands the scope of attribution beyond the exact product to include other products within the same brand and category. In this model, the conversion is attributed when a customer interacts with a sponsored product ad for a specific brand and category and makes a purchase of any product within that brand and category.

For instance, if a customer clicks on a sponsored product ad for a particular brand of running shoes but ends up purchasing a different model of running shoes from the same brand, the conversion is attributed.

Same Brand Attribution

Same brand attribution takes a broader approach by attributing conversions to the overall brand rather than specific products or categories. In this model, the conversion is attributed when a customer interacts with a sponsored product ad for a specific brand and makes a purchase of any product from that brand, regardless of the category.

For example, if a customer clicks on a sponsored product ad for a particular brand of smartphones and then purchases a laptop from the same brand, the conversion is attributed to the same brand.

Merchant-Aware Attribution

The following additional options are available to marketplace customers. These can be used together or independently:

Same Merchant Attribution

This is the broadest possible match between an ad and a purchased product. To get this match, a shopper purchases a product that's only connection to the attributed ad was that it was sold by a merchant that matches attribution criteria on the ad. This option is useful in marketplace settings where individual sellers (merchants) have individual storefronts and sell products across multiple categories and brands. In this setting, a merchant may promote one product and in turn attract shoppers to their storefront driving sales of a wider range of products.

Require Merchant Match

In tandem with the match types defined above, it is also possible to enforce that for each product match level, the purchased product merchant must match the attribution criteria on the ad effectively extending the product match options to be: Same Product + Merchant, Same Category & Brand + Merchant, Same Brand + Merchant, and Same Merchant. To use this functionality you must pass the merchantId parameter on purchase events.

📘

To enable merchant-aware options in the Ad Server UI, contact your account team or Kevel Support.

The choice of attribution model depends on the goals and objectives of advertisers. Same product attribution provides the most specific and granular insights into the direct impact of a particular advertised product. Same brand and category attribution offers a broader view by considering the influence of the brand and category on consumer behavior. Same brand attribution provides a high-level overview of the effectiveness of the brand's advertising efforts across various product categories.

By considering both lookback windows and attribution match types, advertisers can gain a better understanding of how their sponsored product ads impact consumer behavior and conversions. These concepts help marketers make informed decisions about their advertising strategies, optimize their campaigns, and allocate resources effectively to maximize return on investment (ROI).

Attributable Items

For each attribution-enabled Ad, a set of "attributable items" must be defined. This is configured in the Management API on the Ad entity via the AttributionSettings field. This is an object that has a single key AttributableItems, an array of objects with the structure shown in the table below. Each object must have a MatchType key and one or more additional keys depending on the MatchType value.

How to configure attribution using the Management API + examples

Attribute sales of 1 SKU (and, based on Flight settings, its category+brand or brand)
This represents the setup for a standard PLA. In most cases, PLAs are created using the “create ads from products” workflow in the UI or API via pre-defined Ad Template mappings and this configuration will be set automatically. This example shows how that setup is represented in the Kevel Ad Server and is included for reference of that standard configuration.

{
  "AttributionSettings": {
    "AttributableItems": [
      {
        "MatchType": "SameProduct",
        "ProductId": "01936422964", // Product's ID
        "MerchantId": 111 // Product's Merchant ID
      },
      {
        "MatchType": "SameCategoryBrand",
        "BrandId": 555, // Brand ID for Product
        "CategoryId": 444 // Main Category ID for Product
      },
      {
        "MatchType": "SameBrand",
        "BrandId": 555 // Brand ID for Product
      }
    ]
  }
}

Attribute sales of 2 specific SKUs (and, based on Flight settings, their category+brand or brand)
In this example, both products belong to the same category and brand:

{
  "AttributionSettings": {
    "AttributableItems": [
      {
        "MatchType": "SameProduct",
        "ProductId": "01936422964", // Product 1's ID
        "MerchantId": 111 // Product 1's Merchant ID
      },
      {
        "MatchType": "SameProduct",
        "ProductId": "01936422965", // Product 2's ID
        "MerchantId": 111 // Product 2's Merchant ID
      },
      {
        "MatchType": "SameCategoryBrand",
        "BrandId": 555, // Common Brand ID for Product 1 and Product 2
        "CategoryId": 444 // Common Main Category ID for Product 1 and Product 2
      },
      {
        "MatchType": "SameBrand",
        "BrandId": 555 // Common Brand ID for Product 1 and Product 2
      }
    ]
  }
}

In this example, the products belong to different categories and the same brand:

{
  "AttributionSettings": {
    "AttributableItems": [
      {
        "MatchType": "SameProduct",
        "ProductId": "01936422964", // Product 1's ID
        "MerchantId": 111 // Product 1's Merchant ID
      },
      {
        "MatchType": "SameProduct",
        "ProductId": "01936422965", // Product 2's ID
        "MerchantId": 111 // Product 2's Merchant ID
      },
      {
        "MatchType": "SameCategoryBrand",
        "BrandId": 555, // Product 1's Brand ID
        "CategoryId": 444 // Product 1's Main Category ID
      },
      {
        "MatchType": "SameCategoryBrand",
        "BrandId": 555, // Product 2's Brand ID
        "CategoryId": 445 // Product 2's Main Category ID
      },
      {
        "MatchType": "SameBrand",
        "BrandId": 555 // Common Brand ID for Product 1 and Product 2 
      }
    ]
  }
}

Attribute sales from 2 brands to this Ad

{
  "AttributionSettings": {
    "AttributableItems": [
      {
        "MatchType": "SameBrand",
        "BrandId": 58
      },
      {
        "MatchType": "SameBrand",
        "BrandId": 3935
      }
    ]
  }
}

Attribute sales of 2 specific SKUs (and, based on Flight settings, their category+brand or brand) AND 1 additional brand

{
  "AttributionSettings": {
    "AttributableItems": [
      {
        "MatchType": "SameProduct",
        "ProductId": "01936422964", // Product 1's ID
        "MerchantId": 111 // Product 1's Merchant ID
      },
      {
        "MatchType": "SameProduct",
        "ProductId": "01936422965", // Product 2's ID
        "MerchantId": 111 // Product 2's Merchant ID
      },
      {
        "MatchType": "SameCategoryBrand",
        "BrandId": 555, // Common Brand ID for Product 1 and Product 2
        "CategoryId": 444 // Common Main Category ID for Product 1 and Product 2
      },
      {
        "MatchType": "SameBrand",
        "BrandId": 555 // Common Brand ID for Product 1 and Product 2
      },
      {
        "MatchType": "SameBrand",
        "BrandId": 556 // Additional Brand ID not associated with products above
      }
    ]
  }
}

Attribute sales of 1 specific SKU (and, based on Flight settings, its category+brand or brand or merchant)
Note MerchantId field is present on all Attributable Items to satisfy MatchMerchant setting on Flight.

{
  "AttributionSettings": {
    "AttributableItems": [
      {
        "MatchType": "SameProduct",
        "ProductId": "01936422964", // Product's ID
        "MerchantId": 111 // Product's Merchant ID
      },
      {
        "MatchType": "SameCategoryBrand",
        "BrandId": 555, // Product's Brand ID
        "CategoryId": 444, // Product's Category ID
        "MerchantId": 111 // Product's Merchant ID
      },
      {
        "MatchType": "SameBrand",
        "BrandId": 555, //  Product's Brand ID
        "MerchantId": 111 // Product's Merchant ID
      },
      {
        "MatchType": "SameMerchant",
        "MerchantId": 111 // Product's Merchant ID
      }
    ]
  }
}

Limits, validation, and other considerations

A maximum of 10 attributable items across all match types can be added to a single Ad. A minimum of 1 attributable item of any match type must be included when setting AttributableItems. To clear attribution settings and disable attribution for an Ad, set AttributionSettings to NULL.

In order to match sales at all possible levels (same product, same category + brand, same brand), for ads not directly derived from products, such as native ads and display ads, attributable items must explicitly set each of these values according to their match preferences on Kevel Ads. Categories and brands will not be automatically inferred from products within an Ad’s AttributionSettings, nor will a specific product match be inferred from a brand or category+brand specified in AttributionSettings.

Therefore, API users should take care to align attribution settings between the Flight and the Ads within that Flight.

How to configure Ad-level attribution criteria using the Ad Server UI

From the Flight editor screen, create or edit an Ad and scroll to the Attribution Setting panel (below Creative Details). Expand the panel to specify the products, categories, brands, and/or merchants that make a purchase eligible for attribution to that Ad.

Purchase Event Stream

In order to log purchase data with Kevel, send a server-side event for each purchase completed.

You will send a GET request to a network-specific endpoint following this format, where 123 is the Kevel network ID: https://e-123.adzerk.net/c/123/purchase

The following parameters are required for any attribution set up:

• userKey multiple userKey values are accepted, representing the userKey(s) this customer was seen on in previous ad requests. If you don't have a solution for gathering and sending the different relevant userKey(s) you can leverage Kevel Audience for this purpose
• timestamp (ISO 8601 (eg. 2017-01-19T16:27:20.974Z) but we also support unix epoch time)
• quantity The quantity of items in this transaction (line item of an order)
• price The product price of the line item. The total amount for the line item will be quantity * price

The parameters above are used for Kevel's default attribution implementation, but query parameters may be use-case specific and may include custom information based on your attribution scheme and reporting needs. For example, a retail marketplace company may send Kevel the following:

• transactionId The transaction identifier
• productIdProduct identifier, used to lookup product meta data in the Kevel Catalog
• merchantId Optional merchant identifier, used in Marketplaces to identify the seller

Additionally, you can also send LTV related information on each event, namely:

• ltvQuantity the expected additional quantity of items sold to this customer. As a Retailer, you can decide to send the quantity of the particular item in the line item, or it can be representative of the prorated future number of total items expected to be purchased by the customer
• ltvValue the expected additional sales value sold to this customer. As a Retailer can decide to send the sales value for the specific product in the line item or it can be representative of the prorated future value expected to be spent by the customer. This will not be multiplied by ltvQuantity, it is the total value

Additional product information can and should also be provided via Kevel Catalog. For example, a retail marketplace company may complement product information with fields such as:

• Product details
• Brand identifier
• Main category identifier
• In stock indicator

Sample purchase event fully constructed: https://e-123.adzerk.net/c/123/purchase?userKey=marketplaceshopper-456-abc&transactionId=1234567&timestamp=2022-11-02T16%3A27%3A20.974Z&productId=11982758&quantity=1&price=200&merchantId=12478&ltvQuantity=6&ltvValue=1200

It is important to send a consistent UserKey in both the Ad Decision and the Purchase event request so that Kevel is able to perform a look back to determine whether the purchase can be attributable to an ad view or click (depending on attribution settings defined Flight settings).

Generally, this is done by generating a random UserKey on session start and persisting that locally (local storage, or a cookie). Even if the user authenticates midway through their journey, it is important that the same UserKey is sent in purchase events in order for Kevel to be able to correctly attribute conversions to Ads.

Additionally, if products are sold across multiple markets (with multiple currencies), the price value must first be converted to a single currency (defined by the customer).

When the Kevel Ad Server logs a conversion due to attribution:

• A Server to Server Conversion is logged for the relevant ad using event ID 3. (See Event ID definitions)
• The GMV for the relevant ad is incremented by the value of the price value * quantity value in the purchase event.
• The CustomEventCount value in the logged event will be set to the quantity value in the purchase event.
  • There is a single ("EventId": 3) log per attributed purchase event and those logs have CustomEventCount equal to quantity provided on the purchase event—so, if a purchase event includes quantity=2, the event log will contain "CustomEventCount": 2. Kevel's reporting systems honor this event multiplier and increment conversion events per the CustomEventCount value. Therefore the "purchases" column in reports reflects units sold.

📘

Acceptable Delay in Sending Purchase Events

Kevel accepts purchase events for up to 15 days after the lookback window has closed. These purchases must contain a timestamp that falls within the established lookback window but can be sent later. This can be helpful in processing offline transaction feeds on a less frequent cadence or other late arriving transaction data.

Kevel Audience + Kevel Ad Server

For customers using Kevel Audience in combination with Kevel Ad Server, purchase events will instead by synced to Kevel Audience either with the standard event collection approach, or via offline imports. This data will then automatically flow through to Kevel Ad Server for attribution reporting. Learn more about how Audience and the Ad Server can work together to create an enhanced attribution experience on the User Level Attribution page.

End-to-End Testing Steps

1. Create a Campaign with at least one Flight that has Attribution Settings configured for post-click and/or post-view lookback window and product match.
2. Create one or more Ads in the Flight from step 1 with Attributable Items set. For PLAs this is set automatically using the Ad Template selected in the Create Ads from Products workflow.
3. Make an ad decision request that returns the Ad(s) from step 2. Ensure this request includes a user key.
4. Trigger an impression for the Ad using the event URL returned in step 3.
5. Trigger a click event for the Ad using the event URL returned in step 3.
6. Send transaction data to the purchase event endpoint. Ensure a userKey is included that matches step 3.
7. Receive a response from the purchase event endpoint:
   1. 200: Purchase attributed to an Ad; conversion recored
   2. 204: Purchase not attributable; addition details in kevel-debug response header:
      1. "product not found: {productId}" - If the productId was not found in the Catalog
      2. "no attributable item was found for productId {productId}" - ProductId was found in the Catalog, but no matching touch points were found for the user key(s) for this product and/or its category + brand.
   3. 400: Invalid request; addition details in response body:
      1. "required parameter missing: expected userKey, timestamp, productId, quantity and price" - If any of the required parameters are missing.
      2. "maximum of 100 userKeys exceeded" - If there are too many user keys.