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

Transakcja (zakup/koszyk/wishlist)

Endpoint do wysyłania eventów transakcyjnych: zakupów, dodania do koszyka oraz wishlisty. Eventy te są wysyłane po interakcjach użytkownika, które mogą zostać zaatrybuowane do kampanii reklamowej.

Parametr eventId jest opcjonalny, ale mocno rekomendowana jest jego wysyłka, ponieważ służy on do wykrywania duplikatów eventów i dzięki niemu wartości wyliczanej atrybucji nie będą zawyżane.

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

Parametry:

eventId: Unikalny identyfikator eventu do deduplikacji (wymagany)
kind: Typ transakcji (wymagany) - możliwe wartości:
- PURCHASE - zakup
- CART - dodanie do koszyka
- WISHLIST - dodanie do wishlisty
shopId: Identyfikator sklepu w formacie UUID (wymagany)
currency: Kod waluty, np. PLN, EUR, USD (wymagany)
locale: Lokalizacja, np. pl_PL, en_US (opcjonalny)
products: Lista produktów w transakcji (wymagana)
- shopProductId: ID produktu w sklepie (wymagany)
- price: Cena produktu (wymagana)
- quantity: Ilość (wymagana)

Headery:

uid: User ID - identyfikator użytkownika do cross-browser tracking (opcjonalny)
cid: Client ID - identyfikator klienta do cross-browser tracking (wymagany)

ℹ️

Stare endpointy /v1/events/purchase, /v1/events/cart i /v1/events/wishlist nadal działają, ale są oznaczone jako deprecated. Dokumentacja starych endpointów dostępna jest tutaj.

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, wejścia na stronę oraz transakcje (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_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
              }
            ]
          }
        }
      ]
    }'

Typy eventów:

CLICK: Event kliknięcia w reklamę (produktu sponsorowanego lub reklamy graficznej)
- showId: Wartość showId z odpowiedzi reklamy
PAGE_VIEW: Event wejścia na stronę
- data: Obiekt PageView z takimi samymi parametrami jak endpoint wejścia na stronę
TRANSACTION: Event transakcyjny (zakup, koszyk, wishlist)
- data: Obiekt Transaction z takimi samymi parametrami jak endpoint transakcji. Parametry uid i cid dla eventów transakcyjnych muszą być przekazane w obiekcie data.
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));
}