Sponsored Products

Integration via API /v1/dsa/raw/batch

In the API integration model, AdsHero is solely responsible for selecting ads. They are rendered by a service querying AdsHero for ads.

This is the recommended integration method: it ensures a consistent way of displaying ads alongside other products in the shop and allows enriching displayed offers with information not available in the feed. Additionally, it responds more quickly to changes in product availability and price, as the product feed is refreshed every hour.

When querying for ads for multiple ad units simultaneously, the /v1/dsa/raw/batch endpoint guarantees that we will not return duplicate ads (the same ads across different ad units).

A basic ad request (emission request) looks as follows:

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 '{
        "targeting": [
          {
            "slotHash": "{slotHash}",
            "adCount": 1
          }
        ]
      }'

• slotHash is the ad unit identifier available in the publisher’s panel on the list of ad units (menu “Slots”).
• adCount (in the example with a value of 1) is the maximum number of ads to be returned.

The given endpoint selects ads for a list of slots. The targeting list contains one object for each ad unit (slot) for which emission (ad selection) is to be performed.

A single element of the targeting list may contain more parameters. Their necessity depends on the algorithm of the ad unit and the placement.

The endpoint accepts headers cid and uid.

Example API response:

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": "Toy Basket Large - Silver Mint",
          "productHref": "https://funwithmum.com/en/toy-basket-large-silver-mint",
          "productImageName": "311d5d048124aa8efe301b30b5e9fba3.jpg",
          "productPrice": 149.0,
          "productSalePrice": 119.2,
          "showId": "eyJhbGciOiJSUzUxMiJ9.eyJhZHVuaXQiOiJhRDhJQTFuVHphaUk5RFphdkpmMnlROVFKQzVham9GTXVxOVdXYmR0aVFjQTNoVGFnUHprbE9vZzZ2N3N2cDJwT3kxdUxMY1hKaGhBQUJpbG1rT2thR3dtaXRGK1ZxWmlMWjg0SS9mMEFPY1l5T3lyc2p5K0k1OXdhSUhuVG5hNjhpY2dUMzdjb0ZZeCtqV3VEcC9aa013SFh0cDlKMC9HdkRMVTJYa1VsVzNVQk9SOU9Ea0Zha1pGSFlJRU12ODVwTWQ3alZyZkN3elRYSE1zcmh2YVNaMmpTa1FmKzVnT011SEdGbzJwZ0FCSHRzNmtONkFKTVUyVytWdHp5Y1h1N3d0K3gzenRvKzVTQTFMTHFqZ1dpbEJ2Rk1hRk1ZNTFGaHBESVBYN1lVNi81MExkNHFMeWZWQ3FSazd1dVpaRDdkVzRHWW4yaTU1VDJnMnI5T2pBb0doWnBOdENCMVFJd0N6LzhBeTBHZ1hmdTRuRzJRZmkrR2ZMdjZCN0gwbmFValA2QkVCMlJGODFSd0NtRE0wcWVNTG1uZlIxUmhkQlNCSTd5a2xyQW9VTzZvOW00MXdjWk9jeWJNSmMrOWVMODR6ZlBNenFXL3J6K095QUYyMFducTBncmErMTRmaFNmQkZjNFZocGRySTlpWUVpU3I2QjlTT1BERTlOQ0ljK1BHd29GWEhmVWVvc0tybmtOSUdoNVJ6ei9SQmhZazc4OW42ei9QbEZrU25nTFF6NVRSa0RwWXZ5cWNPQWt4em45MTBJdS9MWktoOGRkWW1LeWpnTFg2L29ZOFdKV3hlQU5aeWt4ZnVMSnp1bitzWmV0ZlJIeEJvSXMyd1NVREo4WE42MGx1T2QvdVRuYjlDNkpjQ2NKZTZVelU4bkF3OXRHVG10ZUJUbFJMQ2J5MnExQVovL284NWtUbm5FbGtRb1lNSjA5Q1pXcVZVb2Fpb05PVGpzY1FxenIrcUhYOS95N2hDZlBISHhKV2M9IiwidHlwZSI6IlBST0RVQ1QifQ.qCuqv1BFHKcKwOTzvXYsNl7LiL14Dv99RNttosDOYa5z2d_fkXmqIiY-Jq4CSRspFljn5BvwPJZsOf_KgK1Zhga4jHm4f8EX1-i--76lGWepbcgeSTOMkUmCrq22O_TLKGeCbPj7MjL8B--nI_hBvI924X7FqF59XOMUCAmdwgg5RP2EsEwHmrpPdOQ9oh4YjtEXzTzuYFdd9ftGHgL0-rYdTZ5vx0q_p8AbiP9_tBvVuMvwyfu4yuGPsOCY41qFW6C2xsoPAg_kQrx5kwgGE8ZGnj3YCfjphfWmz_nlwVwQ7WODanW_kpdr02K78gN5D2Pbz2IfGXzK0vw0sXZNfw",
          "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"
}

Available parameters:

An example request with all fields would look like this (in practice, not all parameters will be required simultaneously):

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": "cat food",
      "excludeShopProductsIds": [
        "BAM-SWA-BLA-MIN"
      ],
      "priceMin": 1.23,
      "priceMax": 12.3,
      "currency": "PLN",
      "brand": "Fun with Mum",
      "productTitle": "Bamboo Blanket - Mint",
      "shopProductId": "BAM-SWA-BLA-MIN",
      "attributes": [
        {
          "name": "color",
          "value": "red"
        }
      ],
      "categoryIds": [
        "113",
        "114"
      ],
      "categoryPaths": [
        "Blankets > Knit Blankets > Bamboo Blanket"
      ],
      "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 '{
       "targeting": [
         {
           "slotHash": "a64bb352-32c4-4742-8108-f6fd3358e4e3",
           "adCount": 2,
           "searchData": "cat food",
           "excludeShopProductsIds": [
             "BAM-SWA-BLA-MIN"
           ],
           "priceMin": 1.23,
           "priceMax": 12.3,
           "currency": "PLN",
           "brand": "Fun with Mum",
           "productTitle": "Bamboo Blanket - Mint",
           "shopProductId": "BAM-SWA-BLA-MIN",
           "attributes": [
             {
               "name": "color",
               "value": "red"
             }
           ],
           "categoryIds": [
             "113",
             "114"
           ],
           "categoryPaths": [
             "Blankets > Knit Blankets > Bamboo Blanket"
           ],
           "adType": "ALL"
         }
       ]
     }'

attributes Parameter

attributes serves to further filter products. The values of these parameters do not affect the quality of the ad matching: they only guarantee that the returned offers will have the given attribute values.

Each attribute is received in the form:

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

name is the attribute name, and value is its value.

We accept the following attributes (from the feed):

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

And all attributes passed in product_detail.

Difference between categoryIds and categoryPaths

We recommend using categoryPaths and categoryIds only if it is not possible to pass categoryPaths. Category paths carry more context information and allow for better ad matching.

There is no need and we do not recommend passing both categoryPaths and categoryIds simultaneously.

categoryPaths is a list of full category paths. For example, when a user searches for products and has selected a category in which to search for products, it is best to pass e.g. Blankets > Knit Blankets as one of the categoryPaths (in the case of searching on listing it will usually be the only category). On the product page, we recommend passing all the categories to which the product belongs as a list of categoryPaths.

categoryIds is a list of individual nodes or category leaves. For example, on a product page belonging to the category Blankets > Knit Blankets > Bamboo Blanket, you can pass Bamboo Blanket as one of the elements of categoryIds. In the case of a listing, we recommend passing the ID of the category in which the user is searching for products.

Integration via JS scripts

In the case of integration via JS scripts, handling cid is entirely on the AdsHero side. uid is not supported, making it impossible to link user activity across devices. More details about cid and uid can be found here.

Integration with the emission script involves pasting the following fragment into the page code:

<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} is the id of the HTML element that should be replaced by the ad. It can be, for example, a <div> element:

<div id="dsa-id"/>

Where dsa-id is passed as the {elementId}.

Other parameters: