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}"
    }'

Purchase and Adding a Product to Cart/Wishlist

Events sent after user interactions that can be attributed to an advertising campaign. Send all such events: determining whether a particular event (like purchasing a product or adding to a cart) is related to any advertising campaign is the responsibility of AdsHero.

The parameters eventId, brand and sellerId in the JSON describing the product are optional for events of this type. Nevertheless, sending eventId is strongly recommended as it is used for detecting duplicate events and thanks to it, the calculated attribution values will not be inflated.

For these events, there is a different domain they should be sent to: event-dispatcher.ahevds.com instead of dispatcher.ahevds.com.

Purchase:

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

{
  "shopId": "string",
  "currency": "string",
  "products": [
    {
      "shopProductId": "string",
      "productTitle": "string",
      "price": 102.54,
      "quantity": 0,
      "brand": "string",
      "sellerId": "string"
    }
  ],
  "eventId": "string"
}
curl --location --request POST 'https://event-dispatcher.ahevds.com/v1/events/purchase' \
    --header 'Content-Type: application/json' \
    --header 'cid: {cid}' \
    --header 'uid: {uid}' \
    --data '{
      "shopId": "string",
      "currency": "string",
      "products": [
        {
          "shopProductId": "string",
          "productTitle": "string",
          "price": 102.54,
          "quantity": 0,
          "brand": "string",
          "sellerId": "string"
        }
      ],
      "eventId": "string"
    }'

Adding to cart:

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

{
  "shopId": "string",
  "currency": "string",
  "products": [
    {
      "shopProductId": "string",
      "productTitle": "string",
      "price": 102.54,
      "quantity": 0,
      "brand": "string",
      "sellerId": "string"
    }
  ],
  "eventId": "string"
}
curl --location --request POST 'https://event-dispatcher.ahevds.com/v1/events/cart' \
    --header 'Content-Type: application/json' \
    --header 'cid: {cid}' \
    --header 'uid: {uid}' \
    --data '{
      "shopId": "string",
      "currency": "string",
      "products": [
        {
          "shopProductId": "string",
          "productTitle": "string",
          "price": 102.54,
          "quantity": 0,
          "brand": "string",
          "sellerId": "string"
        }
      ],
      "eventId": "string"
    }'

Adding to wishlist:

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

{
  "shopId": "string",
  "currency": "string",
  "products": [
    {
      "shopProductId": "string",
      "productTitle": "string",
      "price": 102.54,
      "quantity": 0,
      "brand": "string",
      "sellerId": "string"
    }
  ],
  "eventId": "string"
}
curl --location --request POST 'https://event-dispatcher.ahevds.com/v1/events/wishlist' \
    --header 'Content-Type: application/json' \
    --header 'cid: {cid}' \
    --header 'uid: {uid}' \
    --data '{
      "shopId": "string",
      "currency": "string",
      "products": [
        {
          "shopProductId": "string",
          "productTitle": "string",
          "price": 102.54,
          "quantity": 0,
          "brand": "string",
          "sellerId": "string"
        }
      ],
      "eventId": "string"
    }'

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, and page views (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_EVENT",
      "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}"
      }
    }
  ]
}
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_EVENT",
          "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}"
          }
        }
      ]
    }'

Event types:

  • CLICK: Ad click event (sponsored product or banner ad)
    • showId: The showId value from the ad response
  • PAGE_EVENT: Page view event
  • 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));
}
API accessSlots