Eventy

Eventy dla ofert sponsorowanych:

Wyświetlenie produktu sponsorowanego — wymagany
Kliknięcie produktu sponsorowanego — wymagany
Dodanie produktu do wishlisty — opcjonalny
Dodanie produktu do koszyka — opcjonalny
Zakup w sklepie — wymagany

Eventy dla reklamy graficznej:

Wyświetlenie reklamy graficznej — wymagany
Kliknięcie reklamy graficznej — wymagany
Dodanie produktu do wishlisty — opcjonalny
Dodanie produktu do koszyka — opcjonalny
Zakup w sklepie — wymagany

Wyświetlenie produktu sponsorowanego

Event wysyłany, gdy użytkownik zobaczy reklamę (jest widoczna w przeglądarce). Dotyczy to tylko oferty sponsorowanej — dla reklamy graficznej są przygotowane oddzielne endpointy.

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

Jako showId należy przekazać (bez “wąsów”) wartość pola showId z reklamy zwróconej w emisji, którą klient zobaczył.

Przykładowy kod do monitorowania widoczności reklamy jest dostępny tutaj. To jedno z możliwych rozwiązań i w zależności od frameworka oraz implementacji strony, docelowe rozwiązanie może się różnić.

Kliknięcie produktu sponsorowanego

Event wysyłany, gdy użytkownik kliknie reklamę i zostanie przekierowany na stronę produktu. Dotyczy to tylko oferty sponsorowanej — dla reklamy graficznej są przygotowane oddzielne endpointy.

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

Jako showId należy przekazać (bez “wąsów”) wartość pola showId z reklamy zwróconej w emisji, którą klient zobaczył.

Wyświetlenie reklamy graficznej

Event wysyłany, gdy użytkownik zobaczy reklamę (jest widoczna w przeglądarce). Dotyczy to tylko reklamy graficznej — dla ofert sponsorowanych są przygotowane oddzielne endpointy.

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

Jako showId należy przekazać (bez “wąsów”) wartość pola showId z reklamy zwróconej w emisji, którą klient zobaczył.

Kliknięcie reklamy graficznej

Event wysyłany, gdy użytkownik kliknie reklamę i zostanie przekierowany na podany w reklamie URL. Dotyczy to tylko reklamy graficznej — dla ofert sponsorowanych są przygotowane oddzielne endpointy.

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

Zakup oraz dodanie produktu do koszyka/wishlisty

Eventy wysyłane po interakcjach użytkownika, które mogą zostać zaatrybuowane do kampanii reklamowej. Należy wysyłać wszystkie takie zdarzenia: określenie, czy konkretne zdarzenie (zakup produktu, dodanie do koszyka) jest powiązane z jakąkolwiek kampanią reklamową jest po stronie AdsHero.

Parametry eventId oraz brand i sellerId w jsonie opisującym produkt są w przypadku eventów tego typu opcjonalne. Mimo wszystko mocno rekomendowana jest wysyłka eventId, ponieważ służy on do wykrywania duplikatów eventów i dzięki niemu wartości wyliczanej atrybucji nie będą zawyżane.

W przypadku tych eventów jest inna domena, pod którą są one wysyłane: event-dispatcher.ahevds.com zamiast dispatcher.ahevds.com.

Zakup:

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

Dodanie do koszyka:

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

Dodanie do wishlisty:

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

Wejście na stronę

Zdarzenie wysyłane, gdy użytkownik wejdzie na stronę, niezależnie od tego, czy na stronie wyświetlana jest jednostka reklamowa. Domyślnie jest ono opcjonalne, ale w przypadku integracji z zewnętrznymi systemami jego wysyłka może być konieczna dla liczenia atrybucji.

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

Parametry:

cid: cid użytkownika (opcjonalny, zostanie nadany przez endpoint, jeśli go nie ma)
uid: uid użytkownika (opcjonalny)
gclid: identyfikator kliknięcia z Google Ads (opcjonalny)
utmSource: tag utm_source (opcjonalny)
utmMedium: tag utm_medium (opcjonalny)
utmCampaign: tag utm_campaign (opcjonalny)
id: unikalny identyfikator odsłony (wymagane)
referer: adres URL strony, na której jest użytkownik (wymagane)
shopId: identyfikator sklepu, widoczny w panelu AdsHero w ustawieniach sklepu (wymagane)
shopProductId: identyfikator produktu (id z feeda produktowego) prezentowanego na stronie, na której jest użytkownik, jeśli jest on na stronie produktu (opcjonalny)

Batchowa wysyłka eventów

Endpoint do wysyłania wielu eventów w jednym zapytaniu HTTP. Pozwala na łączenie w jednej paczce różnych typów eventów: wyświetlenia, kliknięcia oraz wejścia na stronę (maksymalnie 1000 eventów na zapytanie).

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

Typy eventów:

CLICK: Event kliknięcia w reklamę (produktu sponsorowanego lub reklamy graficznej)
- showId: Wartość showId z odpowiedzi reklamy
PAGE_EVENT: Event wejścia na stronę
- data: Obiekt PageView z takimi samymi parametrami jak endpoint wejścia na stronę
VIEW: Event wyświetlenia reklamy (produktu sponsorowanego lub reklamy graficznej)
- showId: Wartość showId z odpowiedzi reklamy

Wykrywanie wyświetlenia reklamy

Aby wykryć, czy element jest widoczny w przeglądarce użytkownika, można wykorzystać API IntersectionObserver dostępne w JavaScript w przeglądarce. Zakładając, że reklama jest wyświetlana w elemencie div o podanym id, możemy to zrobić w następujący sposób (fragment kodu strony, do umieszczenia na frontendzie):

function observeAd(divId, showId, cid, uid) {
  let options = {
    root: null,
    // za pomocą parametru threshold można sterować
    // jaka część reklamy musi być widoczna, by wysłać 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();
  // w zależności od typu reklamy - oferta sponsorowana lub reklama graficzna - request
  // wysyłany jest pod /v1/dsa/view-event lub /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));
}

Dostęp do API Jednostki reklamowe