Oferty Sponsorowane

Integracja przez API /v1/dsa/raw/batch

W modelu integracji przez API AdsHero odpowiada wyłącznie za dobór reklam. Ich wyświetlanie realizowane jest przez serwis odpytujący AdsHero o reklamy.

Jest to zalecany sposób integracji: gwarantuje spójny sposób wyświetlenia reklam razem z resztą produktów w sklepie i pozwala wzbogacić wyświetlane oferty o informacje, których nie ma w feedzie. Dodatkowo szybciej reaguje na zmiany dostępności i ceny produktów, ponieważ feed produktowy odświeżany jest co godzinę.

W przypadku odpytywania o reklamy dla wielu jednostek reklamowych równocześnie, dla endpointu /v1/dsa/raw/batch gwarantujemy, że nie zwrócimy duplikatów reklam (te same reklamy na różnych jednostach reklamowych).

Podstawowe zapytanie o reklamy (request emisyjny) wygląda następująco:

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

{
  "targeting": [
    {
      "slotHash": "{slotHash}",
      "adCount": 1
    }
  ]
}

curl --location --request POST 'https://dispatcher.ahevds.com/v1/dsa/raw/batch' \
    --header 'Content-Type: application/json' \
    --header 'cid: {cid}' \
    --header 'uid: {uid}' \
    --data-raw '{
      "targeting": [
        {
          "slotHash": "{slotHash}",
          "adCount": 1
        }
      ]
    }'

• slotHash to identyfikator jednostki reklamowej dostępny w panelu wydawcy (sklepu) na liście jednostek reklamowych (menu “Sloty”).
• adCount (w przykładzie o wartości 1) to maksymalna liczba reklam, które mają być zwrócone.

Podany endpoint dobiera reklamy dla listy slotów. Lista targeting zawiera po jednym obiekcie dla każdej jednostki reklamowej (slot), dla którego ma zostać wykonana emisja (dobór reklam).

Pojedynczy element listy targeting może zawierać więcej parametrów. Ich obowiązkowość zależy od algorytmu jednostki reklamowej oraz miejsca docelowego.

Endpoint przyjmuje nagłówki cid oraz uid.

Przykładowa odpowiedź API:

HTTP/2 200 OK
Content-Type: application/json

{
  "data": [
    {
      "slotHash": "a64bb352-32c4-4742-8108-f6fd3358e4e3",
      "ads": [
        {
          "adUnitId": "F5LkM5IBjTNmMwTTXR1p",
          "systemProductId": "66b0bf29f9210e6f3a1ee09d",
          "shopProductId": "BAS-FOR-TOY-SIL-MIN",
          "productTitle": "Kosz na Zabawki Duży - Silver Mint",
          "productHref": "https://funwithmum.com/pl/kosz-na-zabawki-duzy-silver-mint",
          "productImageName": "311d5d048124aa8efe301b30b5e9fba3.jpg",
          "productPrice": 149.0,
          "productSalePrice": 119.2,
          "showId": "eyJhbGciOiJSUzUxMiJ9.eyJhZHVuaXQiOiJhRDhJQTFuVHphaUk5RFphdkpmMnlROVFKQzVham9GTXVxOVdXYmR0aVFjQTNoVGFnUHprbE9vZzZ2N3N2cDJwT3kxdUxMY1hKaGhBQUJpbG1rT2thR3dtaXRGK1ZxWmlMWjg...",
          "requestId": "|AOZxmKInMj7QA3Txkk1Pm8dXlDS7EKlwKwfQ.Ir5sQj_",
          "slotHash": "a64bb352-32c4-4742-8108-f6fd3358e4e3",
          "shopId": "cf196098-c935-4ac4-83f2-aece5185602a",
          "lang": "pl",
          "currency": "PLN",
          "brand": "Fun with Mum",
          "categoryId": null,
          "autoPromo": false,
          "productImageUrl": "https://prd-cdn-images-prx.ahevds.com/311d5d048124aa8efe301b30b5e9fba3.jpg"
        }
      ]
    }
  ],
  "meta": null,
  "clientId": "v2.633061515.1727455341"
}

Dostępne parametry:

Przykładowy request ze wszystkimi polami wyglądałby tak (w rzeczywistości nigdy nie będą wymagane wszystkie parametry równocześnie):

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

{
  "targeting": [
    {
      "slotHash": "a64bb352-32c4-4742-8108-f6fd3358e4e3",
      "adCount": 2,
      "searchData": "karma dla kota",
      "excludeShopProductsIds": [
        "BAM-SWA-BLA-MIN"
      ],
      "priceMin": 1.23,
      "priceMax": 12.3,
      "currency": "PLN",
      "brand": "Fun with Mum",
      "productTitle": "Kocyk Bambusowy - Mint",
      "shopProductId": "BAM-SWA-BLA-MIN",
      "attributes": [
        {
          "name": "color",
          "value": "red"
        }
      ],
      "categoryIds": [
        "113",
        "114"
      ],
      "categoryPaths": [
        "Kocyki > Kocyki Dziane > Kocyk Bambusowy"
      ],
      "adType": "ALL"
    }
  ]
}

curl --location --request POST 'https://dispatcher.ahevds.com/v1/dsa/raw/batch' \
    --header 'Content-Type: application/json' \
    --header 'cid: {cid}' \
    --header 'uid: {uid}' \
    --data-raw '{
      "targeting": [
        {
          "slotHash": "a64bb352-32c4-4742-8108-f6fd3358e4e3",
          "adCount": 2,
          "searchData": "karma dla kota",
          "excludeShopProductsIds": [
            "BAM-SWA-BLA-MIN"
          ],
          "priceMin": 1.23,
          "priceMax": 12.3,
          "currency": "PLN",
          "brand": "Fun with Mum",
          "productTitle": "Kocyk Bambusowy - Mint",
          "shopProductId": "BAM-SWA-BLA-MIN",
          "attributes": [
            {
              "name": "color",
              "value": "red"
            }
          ],
          "categoryIds": [
            "113",
            "114"
          ],
          "categoryPaths": [
            "Kocyki > Kocyki Dziane > Kocyk Bambusowy"
          ],
          "adType": "ALL"
        }
      ]
    }'

Parametr attributes

attributes służy dodatkowemu filtrowaniu produktów. Wartości tych parametrów nie wpływają na jakość dopasowania ofert: gwarantują jedynie, że zwrócone zostaną tylko oferty, które posiadają podane wartości atrybutów.

Każdy atrybut przyjmujemy w postaci:

{
  "name": "name",
  "value": "value"
}

name to nazwa atrybutu, a value to jego wartość.

Akceptujemy atrybuty (z feedu):

• adult
• age_group
• color
• energy_efficiency_class
• gender
• google_product_category
• gtin
• material
• mpn
• pattern
• size
• unit_pricing_measure

Oraz wszystkie atrybuty przekazane w product_detail.

Różnica między categoryIds, a categoryPaths

Zalecamy korzystanie z categoryPaths, a z categoryIds tylko, gdy nie ma możliwości przekazania do nas categoryPaths. Ścieżki kategorii niosą więcej informacji o kontekście i pozwalają na lepsze dopasowanie reklam.

Nie ma potrzeby i nie zalecamy przekazywania równocześnie categoryPaths i categoryIds.

categoryPaths to lista pełnych ścieżek kategorii. Np. gdy użytkownik wyszukuje produkty i wybrał kategorię, w której szuka produktów, to najlepiej jest przekazać np. Kocyki > Kocyki Dziane jako jedną z categoryPaths (i w przypadku wyszukiwania na listingu zazwyczaj będzie to jedyna kategoria). Na stronie produktu zalecamy przekazywanie wszystkich kategorii, do których należy produkt, jako listę categoryPaths.

categoryIds to lista pojedynczych węzłów, lub liści kategorii. Np. na stronie produktu należącego do kategorii Kocyki > Kocyki Dziane > Kocyk Bambusowy można przekazać Kocyk Bambusowy jako jeden z elementów categoryIds. W przypadku listingu zalecamy przekazywanie id kategorii, w której użytkownik wyszukuje produkty.

Integracja przez skrypty JS

W przypadku integracji przez skrypty JS obsługa cid jest w całości po stronie AdsHero. uid nie jest obsługiwany, co uniemożliwia powiązanie aktywności użytkownika pomiędzy urządzeniami. Więcej szczegółów o cid i uid znajduje się tutaj.

Integracja ze skryptem emisyjnym polega na wklejeniu następującego fragmentu w kod strony:

<script type="text/javascript" async src=https://dispatcher.ahevds.com/v1/dsa/formatted/{slotHash}/{elementId}/{row}/{col}?
    searchData={searchData}&
    excludedShopProductsIds={excludedShopProductsIds}&
    priceMin={priceMin}&
    priceMax={priceMax}&
    currency={currency}&
    brand={brand}&
    productTitle={productTitle}&
    categoryId={categoryId}&
    shopProductId={shopProductId}&
    attributes=[{"name":"{name}","value":"{value}"}]
    ></script>

{elementId} to id elementu HTML, który ma być podmieniony na reklamę. Może to być np. element <div>:

<div id="dsa-id"/>

Gdzie jako {elementId} przekazywane jest dsa-id.

Pozostałe parametry: