> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topsort.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Banner Attribution

> Learn how to use the auctions API to achieve banner purchase attribution.

Attributing conversions to the right campaign is vital for optimizing campaign performance and enabling data-driven decisions. Because banners can link to several kinds of targets, setting up attribution requires a bit more work compared to listings.
In this example, you'll learn how to set up attribution for banners that link to products, brands, or vendors.
Let's get started.

# Overview

In the context of banner attribution, the primary goal is to track and attribute conversions resulting from interactions with a banner and products associated with the banner you've configured in Topsort. Sometimes a user may view a banner, click on it, and then make a purchase later. In such cases, it's essential to attribute the purchase to the banner that initially caught the user's attention.

## Common Practice/Recommendation

When a user views a banner within a page, any subsequent purchases of products associated with the banner by the same user should be attributed to the banner campaign.

# Implementation: Attribution Methods

Currently, there are **two primary methods** for attributing a purchase to a banner within the platform, depending on the type of landing page the banner redirects to: one is product detail & listing pages (PDP & PLP), and the other is vendor pages.

## 1. Product Detail & Listing Pages (PDP & PLP)

This method involves sending a `resolvedBidId` along with an `additionalAttribution` object in a follow-up event linked to a specific product. The user journey follows this sequence:

### **Step 1:** **Page Loads with a Banner**

* A page loads with a banner that has won a Topsort auction.
* If the banner is set to charge by CPM (Cost Per Mille), a **banner impression event** should be sent to Topsort, including the `resolvedBidId` from the auction response, for billing purposes.
* If the user clicks on the banner and it’s set to charge by CPC (Cost Per Click), a **banner click event** should be sent to Topsort, again using the `resolvedBidId` from the auction response, for billing purposes.

### **Step 2:** **User Click and Redirection**

* Upon clicking the banner, the user is redirected to the specified landing page.
* From this point, different event requirements come into play depending on the type of banner landing page:

  **Case 1.1. PDP (Product Detail Page)**

  * If the banner redirects to a Product Detail Page, a **product click event** should be reported to Topsort when the user clicks on the banner.
  * This event must include the `resolvedBidId` from the banner and the `additionalAttribution` object.
  * In this case, the `additionalAttribution` object should have:
    * **`id`**: Product ID of the clicked product.
    * **`type`**: Set as "product".
  * This approach ensures that any subsequent purchase of the product is attributed to the original banner.

  Example of a click event with the `additionalAttribution` object:

  ```json theme={null}
  {
    "clicks": [
      {
        "id": "9dcb05ad-9bb4-40da-bd71-663cab413564",
        "resolvedBidId": "ChAGcYkXyzR3q5UEOql7QpBd...",
        "placement": {
          "path": "/home/banner-destination-page"
        },
        "occurredAt": "2024-10-23T06:03:21.403Z",
        "opaqueUserId": "7205415c-179f-4f7f-9fde-3ca8e7f16bc7",
        "additionalAttribution": {
          "id": "MKJY40600",
          "type": "product"
        }
      }
    ]
  }
  ```

  **Case 1.2. PLP (Product Listing Page)**

  * If the banner leads to a Product Listing Page, a **product click event** should be sent to Topsort only after the user clicks on one of the listed products.
  * This event should include both the `resolvedBidId` from the banner and an `additionalAttribution` object.
  * This ensures that any subsequent purchase of the clicked product is correctly attributed to the initial banner.

  **Case 1.3. BLP (Brand or Vendor Landing Page)**

  * If the banner leads to a brand or vendor page, and the goal is to attribute subsequent purchases to that brand/vendor, then **Halo attribution** should be used. See the next section for more details.

## 2. Vendor attribution

When the banner redirects to a vendor landing page or if all products purchased from a vendor after seeing a banner related to it should be attributed, then we use Halo attribution. This kind of attribution indirectly links a purchase to the banner by associating the vendor or brand from the `resolvedBidId` of the original banner event. This ensures that purchases are attributed even when the conversion path is not direct. Halo attribution can work in two ways:

### **2.1. Vendor Only Attribution:**

Banners can attribute all purchases of products from a specific vendor to the banner that led the user to the vendor's page. Communicate with the Topsort team to set up this attribution method at [support@topsort.com](mailto:support@topsort.com).

### **2.2. Vendor + Other Attribution:**

This approach is used when not all banners redirect to vendor pages and multiple landing page types exist. The flow is the same as described in [Product Detail & Listing Pages (PDP & PLP)](#1-product-detail--listing-pages-pdp--plp), but each purchased product item must be reported with its vendor ID. Example:

```json theme={null}
{
  "purchases": [
    {
      "id": "06581ac9-0098-7797-b913-820b6bbbbed4",
      "opaqueUserId": "065e8780-d526-789c-a813-cd1a9ab08d8e",
      "occurredAt": "2024-10-28T07:43:54-06:00",
      "items": [
        {
          "vendorId": "VEIA929919",
          "unitPrice": 900,
          "quantity": 1,
          "productId": "MKQUJ9191"
        }
      ]
    }
  ]
}
```