Reklama graficzna

Integracja przez API

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: daje największą swobodę w prezentacji reklamy na stronie.

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

POST https://dispatcher.ahevds.com/v1/banner/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/banner/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 wartość 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. Do zapytania emisyjnego powinny być przekazywane te parametry, które zostały podane w konfiguracji slotu jako targetowanie.

Endpoint przyjmuje nagłówki cid oraz uid.

Przykładowa odpowiedź API:

HTTP/1.1 200 
Content-Type: application/json;charset=utf-8

{
  "data": [
    {
      "slotHash": "8cc4ba26-bb96-46f1-975c-a6a21243bb05",
      "ads": [
        {
          "bannerId": "4732",
          "bannerUrl": "https://adshero.com/",
          "mobileDeepLink": "https://adshero.com/",
          "showId": "eyJhbGciOiJSUzUxMiJ9.eyJhZHVuaXQiOiJhRDhJQTFuVHphaUk5RFphdkpmMnllNkdBZlJTenJpZlZyS3AveEdjVS83NFNwR2tsWTdZai9HYzJIQ2hZYzhUNFRXcFppdFNtWTZELzFQTEVKc21TanMvbGZubUNjZWhYSjMvczIwdG1NQ2NqS3BpS2NFa1kzZVN3VXVKbytsbThpY2dUMzdjb0ZZeCtqV3VEcC9aa0lYWnhOMkJvY3lzVThmN2NrL09FY2hWVGtPU0QrTlZSY28yRXVwUTM4QlhnWUJhR2ZRV1hOeFpqdzdvMGdEUkRaMmpTa1FmKzVnT011SEdGbzJwZ0FCTG1aTklFNWlTNFZCbUZRenFDVXVCRkNteE5PQzZTTDdXWGplVVFqT3VwVlhUWnVZTzVsQ0dYcU1Sb0JyUCtaaWljSThHd2NTbFZPSnB5UVRMb1N2eU80VDY2Y3p5blpFWUs1eHJDRGtCZWhDSk1zMkpYbDJzQ1ZMSVlOQzRLMFg1MktTMGRSMXdLMlJZQnVyZGVKM28waldJQ0QvN3ZEaFVuemNnODJCNTJhRjYwZEpkbVQ1cEJ1RldoWlpzcldoT21lQWZTTUxiU0RKWnNZd1ZQdCt0SjVwWGhoclUxYldIaElXckVTd1FTZEs3T3Exd2NROVFiMXJQL1dMR1BtMUpTa2hFQXlUeC9KZlhJK3RXY05JdXlsd1AyYjZ6ZHhFOXB2UDJESDFUT0RnRFBIRzg0ajBMQ1owTkVFT01VbGxjenlzWDNRanJSaVp3OHM4QTBTSEphL1lSV1Q4M3ZlVWdBa2U4dEU2bnpTTXRrMlFGMVh6SzZXbUFtSzNOSFhiNjMzRFdGd3VlcmpKUEVYcmFsOGhYZEJ3L0FlcTU4N2k1cHJOVXlKRG52Zz09IiwidHlwZSI6IkJBTk5FUiJ9.U4VJZH2YvrM50tTLrW5wldAaFgVN12104TLH9L0eRnzLluFkQYyL_WgFvQ90iCvKEHr97W_DrhhJj5J34n2mH_cIMDqxYSIiMxejeHfmx7Rn5xYZjlfrfFjl4eLGorC9jf_ayUvXo-2T7BzZeuwIDlAi3q-BL6nuwShIQ6hg8-vynq5l0QrvCjrMLNqsvUh4bt0IVGDEleVcMByfPw7bo9ZhS0qFwBxTTNKsf6mFuC4pOJrNh6w-vGIPKewfQpkq26jANhjlNIWkAXYCItCza3uVjvCbxjg_9M1PwVofsmxcj1GJmDQN0bNbRoQcxZeOBV1NcuRxdihFu_JV2_bw7w",
          "requestId": "|b1k7w9d6qwCBkAVFANzxRoQWyxYXpX5KyylO.7XZsrc_",
          "slotHash": "8cc4ba26-bb96-46f1-975c-a6a21243bb05",
          "shopId": "cf196098-c935-4ac4-83f2-aece5185602a",
          "lang": null,
          "currency": null,
          "autoPromo": false,
          "bannerLogoUrl": null,
          "bannerImageUrl": null,
          "adFormatId": "0f76d848-0977-422a-8f12-251b5b5c3ca7",
          "shopProductIds": ["BAM-SWA-BLA-MIN"],
          "images": [
            {
              "width": 930,
              "height": 180,
              "imageId": "1b56a006-f3be-4684-9008-e41e41aab41d.png",
              "imageUrl": "https://prd-cdn-images-prx.ahevds.com/1b56a006-f3be-4684-9008-e41e41aab41d.png"
            }
          ],
          "textFields": [
            {
              "type": "TITLE",
              "value": "Pierwszy"
            },
            {
              "type": "CTA",
              "value": "KLIK!"
            },
            {
              "type": "BG_COLOR",
              "value": "#ff00ff"
            }
          ]
        }
      ]
    }
  ],
  "meta": null,
  "clientId": "v2.937064567.1728059604"
}

Dostępne parametry:

Nazwa	Opis	Dozwolone wartości	Przykład wartości
`slotHash`	Hash jednostki reklamowej dla której dobierane są reklamy.	UUID	`"8cc4ba26-bb96-46f1-975c-a6a21243bb05"`
`adCount`	Maksymalna liczba reklam do zwrócenia.	Liczby całkowite większe od 0.	`2`
`minAdCount`	Minimalna liczba reklam do zwrócenia. Jeżeli nie ma min. liczby reklam w odpowiedzi to zostanie zwrócona pusta lista.	Whole numbers greater than 0.	`1`
`searchData`	Fraza wyszukiwania.	Tekst	`"karma dla kota"`
`currency`	Waluta strony.	3-literowy kod waluty ISO-4217.	`"PLN"`
`productTitle`	Tytuł produktu.	Tekst	`"Kocyk Bambusowy - Mint"`
`productId`	ID produktu (SKU) w obecnym kontekście (np. strona produktu)	SKU produktu (`id` z feedu).	`"BAM-SWA-BLA-MIN"`
`categoryPaths`	Filtr na listę ścieżek kategorii.	Lista wartości tekstowych zgodnych z feedem (`product_type`).	`["Kocyki > Kocyki Dziane > Kocyk Bambusowy"]`
`brand`	Marka produktu.	Marka zgodna z wartościami w feedzie (`brand`).	`"Fun with Mum"`
`profiles`	Lista profili przypisanych do użytkownika, dla którego emitowane są reklamy.	Lista wartości tekstowych.	`["premium_client", "sneakers_lover"]`
`deviceType`	Typ urządzenia, na którym wyświetlana jest emisja. Pole opcjonalne — przy braku nie stosuje się targetowania po urządzeniu.	Tekst. Umowne wartości: `DESKTOP_WEB`, `TABLET`, `MOBILE_WEB`, `MOBILE_APP`. Inne wartości są akceptowane, ale dopasują się tylko do banerów bez targetowania po typie urządzenia.	`"MOBILE_WEB"`
`adType`	Pozwala ograniczyć dobór reklam do tylko autopromo, lub tylko zwykłych reklam.	`ALL`, `AUTOPROMO` lub `SPONSORED`.	`"ALL"`

Dodatkowo akceptujemy nagłówek Referer, który pozwala na targetowanie reklam po URL, na którym znajduje się użytkownik. Nie wymagamy podania całego URL z domeną (ale jest to dozwolone): wystarczy podać względną scieżkę.

Dekorowana odpowiedź

Reklamy graficzne mogą wskazywać produkty z feedu — ich identyfikatory zwracane są w polu shopProductIds. Po włączeniu dekoracji każda reklama z niepustym shopProductIds zostanie dodatkowo wzbogacona o listę products z podstawowymi danymi tych produktów z feedu (bez opisu).

Dekorację kontroluje opcjonalne pole decorateResponse przekazywane w każdym elemencie listy targeting (w emisji pojedynczej — opcjonalny parametr zapytania decorateResponse):

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

Wartość true wymusza dekorację, a false ją wyłącza. Jeżeli pole nie zostanie przekazane, obowiązuje domyślna konfiguracja jednostki reklamowej (ustawienie decorateProducts slotu technicznego).

Przykładowy fragment dekorowanej reklamy:

{
  "bannerId": "4732",
  "shopProductIds": ["BAM-SWA-BLA-MIN"],
  "products": [
    {
      "id": "BAM-SWA-BLA-MIN",
      "availability": "in_stock",
      "price": 149.0,
      "sale_price": 119.2,
      "image_link": "https://prd-cdn-images-prx.ahevds.com/0d3cbe45.png"
    }
  ]
}

Każdy element listy products ma identyczną strukturę jak obiekt productData opisany w sekcji “Dekorowana odpowiedź” dla ofert sponsorowanych.

Oferty Sponsorowane Informacje o emisji