Documentation
API
Events

Events

Events for sponsored offers:

  • Sponsored product impression — required
  • Sponsored product click — required
  • Adding product to wishlist — optional
  • Adding product to cart — optional
  • Purchase — required

Events for banner ads:

  • Banner ad impression — required
  • Banner ad click — required
  • Adding product to wishlist — optional
  • Adding product to cart — optional
  • Purchase — required

Sponsored Product Impression

Event triggered when the user sees a sponsored product ad (visible in the browser). This only applies to sponsored offers — different endpoints are prepared for banner ads.

POST https://dispatcher.ahevds.com/v1/dsa/view-event HTTP/2
Content-Type: application/json
cid: {cid}
uid: {uid}

{
  "showId": "{showId}"
}
curl --location --request POST 'https://dispatcher.ahevds.com/v1/dsa/view-event' \
    --header 'Content-Type: application/json' \
    --header 'cid: {cid}' \
    --header 'uid: {uid}' \
    --data '{
      "showId": "{showId}"
    }'

Note: Use the value of the showId field from the ad returned in the ad slot (without the quotation marks).

Example code for monitoring ad visibility is available here. This is one possible solution and the final implementation may vary depending on the framework and page implementation.

Sponsored Product Click

Event triggered when the user clicks the ad and is redirected to the product page. This only applies to sponsored offers — different endpoints are prepared for banner ads.

POST https://dispatcher.ahevds.com/v1/dsa/click-event HTTP/2
Content-Type: application/json
cid: {cid}
uid: {uid}

{
  "showId": "{showId}"
}
curl --location --request POST 'https://dispatcher.ahevds.com/v1/dsa/click-event' \
    --header 'Content-Type: application/json' \
    --header 'cid: {cid}' \
    --header 'uid: {uid}' \
    --data '{
      "showId": "{showId}"
    }'

Note: Use the value of the showId field from the ad returned in the ad slot (without the quotation marks).

Banner Ad Impression

Event triggered when the user sees a banner ad (visible in the browser). This only applies to banner ads — different endpoints are prepared for sponsored offers.

POST https://dispatcher.ahevds.com/v1/banner/dsa/view-event HTTP/2
Content-Type: application/json
cid: {cid}
uid: {uid}

{
  "showId": "{showId}"
}
curl --location --request POST 'https://dispatcher.ahevds.com/v1/banner/dsa/view-event' \
    --header 'Content-Type: application/json' \
    --header 'cid: {cid}' \
    --header 'uid: {uid}' \
    --data '{
      "showId": "{showId}"
    }'

Note: Use the value of the showId field from the ad returned in the ad slot (without the quotation marks).

Example code for monitoring ad visibility is available here. This is one possible solution and the final implementation may vary depending on the framework and page implementation.

Banner Ad Click

Event triggered when the user clicks the ad and is redirected to the URL provided in the ad. This only applies to banner ads — different endpoints are prepared for sponsored offers.

POST https://dispatcher.ahevds.com/v1/banner/dsa/click-event HTTP/2
Content-Type: application/json
cid: {cid}
uid: {uid}

{
  "showId": "{showId}"
}
curl --location --request POST 'https://dispatcher.ahevds.com/v1/banner/dsa/click-event' \
    --header 'Content-Type: application/json' \
    --header 'cid: {cid}' \
    --header 'uid: {uid}' \
    --data '{
      "showId": "{showId}"
    }'

Transaction (purchase/cart/wishlist)

Endpoint for sending transaction events: purchases, adding to cart, and adding to wishlist. These events are sent after user interactions that can be attributed to an advertising campaign.

The eventId parameter is optional, but sending it is strongly recommended as it is used for detecting duplicate events and thanks to it, the calculated attribution values will not be inflated.

POST https://dispatcher.ahevds.com/v1/ev/transaction HTTP/2
Content-Type: application/json
uid: {uid}
cid: {cid}

{
  "eventId": "{eventId}",
  "kind": "PURCHASE",
  "shopId": "{shopId}",
  "currency": "{currency}",
  "locale": "{locale}",
  "products": [
    {
      "shopProductId": "{shopProductId}",
      "price": 0,
      "quantity": 0
    }
  ]
}
curl --location --request POST 'https://dispatcher.ahevds.com/v1/ev/transaction' \
    --header 'Content-Type: application/json' \
    --header 'uid: {uid}' \
    --header 'cid: {cid}' \
    --data '{
      "eventId": "{eventId}",
      "kind": "PURCHASE",
      "shopId": "{shopId}",
      "currency": "{currency}",
      "locale": "{locale}",
      "products": [
        {
          "shopProductId": "{shopProductId}",
          "price": 0,
          "quantity": 0
        }
      ]
    }'

Parameters:

  • eventId: Unique event identifier for deduplication (required)
  • kind: Transaction type (required) - possible values:
    • PURCHASE - purchase
    • CART - adding to cart
    • WISHLIST - adding to wishlist
  • shopId: Shop identifier in UUID format (required)
  • currency: Currency code, e.g., PLN, EUR, USD (required)
  • locale: Localization, e.g., pl_PL, en_US (optional)
  • products: List of products in the transaction (required)
    • shopProductId: Product ID in the shop (required)
    • price: Product price (required)
    • quantity: Quantity (required)

Headers:

  • uid: User ID - user identifier for cross-browser tracking (optional)
  • cid: Client ID - client identifier for cross-browser tracking (required)
ℹ️
Old endpoints /v1/events/purchase, /v1/events/cart and /v1/events/wishlist still work but are marked as deprecated. Documentation for old endpoints is available here.

Page view

Event sent when a user visits a page, regardless of whether an ad unit is present on a page. By default, it is optional, but when integrating with external systems, sending this event may be necessary for attribution.

POST https://dispatcher.ahevds.com/v1/ev/page-view HTTP/2
Content-Type: application/json

{
  "cid": "{cid}",
  "uid": "{uid}",
  "gclid": "{gclid}",
  "utmSource": "{utm_source}",
  "utmMedium": "{utm_medium}",
  "utmCampaign": "{utm_campaign}",
  "id": "{page_view_123}",
  "referer": "https://adshero.com/previous-page",
  "shopId": "{shopId}",
  "shopProductId": "{shopProductId}"
}
curl --location --request POST 'https://dispatcher.ahevds.com/v1/ev/page-view' \
    --header 'Content-Type: application/json' \
    --data '{
      "cid": "{cid}",
      "uid": "{uid}",
      "gclid": "{gclid}",
      "utmSource": "{utm_source}",
      "utmMedium": "{utm_medium}",
      "utmCampaign": "{utm_campaign}",
      "id": "{page_view_123}",
      "referer": "https://adshero.com/previous-page",
      "shopId": "{shopId}",
      "shopProductId": "{shopProductId}"
    }'

Parameters:

  • cid: user’s cid (optional, will be assigned by the endpoint if missing)
  • uid: user’s uid (optional)
  • gclid: Google Ads click identifier (optional)
  • utmSource: utm_source tag (optional)
  • utmMedium: utm_medium tag (optional)
  • utmCampaign: utm_campaign tag (optional)
  • id: unique page view identifier (required)
  • referer: URL of the page where the user is located (required)
  • shopId: shop identifier, visible in the AdsHero panel in shop settings (required)
  • shopProductId: product identifier (id in the product feed) presented on the page where the user is located, if they are on a product page (optional)

Batch Events

Endpoint for sending multiple events in a single HTTP request. Allows combining different event types in one batch: views, clicks, page views, and transactions (maximum 1000 events per request).

POST https://dispatcher.ahevds.com/v1/ev/batch HTTP/2
Content-Type: application/json

{
  "events": [
    {
      "type": "VIEW",
      "showId": "{showId}"
    },
    {
      "type": "CLICK",
      "showId": "{showId}"
    },
    {
      "type": "PAGE_VIEW",
      "data": {
        "cid": "{cid}",
        "uid": "{uid}",
        "gclid": "{gclid}",
        "utmSource": "{utm_source}",
        "utmMedium": "{utm_medium}",
        "utmCampaign": "{utm_campaign}",
        "id": "{page_view_123}",
        "referer": "https://adshero.com/previous-page",
        "shopId": "{shopId}",
        "shopProductId": "{shopProductId}"
      }
    },
    {
      "type": "TRANSACTION",
      "data": {
        "eventId": "{eventId}",
        "kind": "PURCHASE",
        "shopId": "{shopId}",
        "currency": "{currency}",
        "locale": "{locale}",
        "cid": "{cid}",
        "uid": "{uid}",
        "products": [
          {
            "shopProductId": "{shopProductId}",
            "price": 0,
            "quantity": 0
          }
        ]
      }
    }
  ]
}
curl --location --request POST 'https://dispatcher.ahevds.com/v1/ev/batch' \
    --header 'Content-Type: application/json' \
    --data '{
      "events": [
        {
          "type": "VIEW",
          "showId": "{showId}"
        },
        {
          "type": "CLICK",
          "showId": "{showId}"
        },
        {
          "type": "PAGE_VIEW",
          "data": {
            "cid": "{cid}",
            "uid": "{uid}",
            "gclid": "{gclid}",
            "utmSource": "{utm_source}",
            "utmMedium": "{utm_medium}",
            "utmCampaign": "{utm_campaign}",
            "id": "{page_view_123}",
            "referer": "https://adshero.com/previous-page",
            "shopId": "{shopId}",
            "shopProductId": "{shopProductId}"
          }
        },
        {
          "type": "TRANSACTION",
          "data": {
            "eventId": "{eventId}",
            "kind": "PURCHASE",
            "shopId": "{shopId}",
            "currency": "{currency}",
            "locale": "{locale}",
            "cid": "{cid}",
            "uid": "{uid}",
            "products": [
              {
                "shopProductId": "{shopProductId}",
                "price": 0,
                "quantity": 0
              }
            ]
          }
        }
      ]
    }'

Event types:

  • CLICK: Ad click event (sponsored product or banner ad)
    • showId: The showId value from the ad response
  • PAGE_VIEW: Page view event
  • TRANSACTION: Transaction event (purchase, cart, wishlist)
    • data: Transaction object with the same parameters as the transaction endpoint. The uid and cid parameters for transaction events must be passed in the data object.
  • VIEW: Ad impression event (sponsored product or banner ad)
    • showId: The showId value from the ad response

Ad Visibility Detection

To detect whether an element is visible in the user’s browser, you can use the IntersectionObserver API available in JavaScript in the browser. Assuming the ad is rendered in a div element with a given id, you can do it as follows (snippet for frontend implementation):

function observeAd(divId, showId, cid, uid) {
  let options = {
    root: null,
    // The threshold parameter controls
    // what portion of the ad must be visible to send the event
    threshold: 0.5,
  };
  let callback = function (entries) {
    entries.forEach(e => {
      if (e.isIntersecting) {
        sendViewEvent(showId, cid, uid);
        observer.unobserve(e.target);
      }
    });
  };
  let observer = new IntersectionObserver(callback, options);
  observer.observe(window.getElementById(divId));
}

function sendViewEvent(showId, cid, uid) {
  const xhttp = new XMLHttpRequest();
  // Depending on the ad type - sponsored offer or banner ad - the request
  // is sent to /v1/dsa/view-event or /v1/banner/dsa/view-event
  xhttp.open("POST", "https://dispatcher.ahevds.com/v1/dsa/view-event", true);
  xhttp.setRequestHeader('cid', cid)
  xhttp.setRequestHeader('uid', uid)
  xhttp.setRequestHeader('Content-type', 'application/json');
  const params = {
    'showId': showId
  };
  xhttp.send(JSON.stringify(params));
}