Requêtes d'annonces

Toutes les requêtes d'annonces de produits nécessitent le placement du contexte, son catalogId, ainsi que le maxNumberOfAds que vous souhaitez afficher au client. En outre, votre requête doit inclure le customerId et le sessionId du contexte.

Emplacements de recherche

Les emplacements de recherche sont généralement les plus faciles à demander. Ils nécessitent qu'un searchTerm soit spécifié dans la requête, comme dans l'exemple ci-dessous :

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9",
    "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
    "placement": "search",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "chocolate",
    "options": {
   						 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3    
}

Emplacements de catégories

Les emplacements de catégories nécessitent que l'élément productFilters soit précisé dans la requête. L'exemple ci-dessous vous montre où envoyer les filtres de catégories :

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9",
    "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
    "placement": "category",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 ["category:Cupboard/Snacks"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}

Au fur et à mesure que des catégories supplémentaires sont ajoutées, vous devez mettre à jour votre appel API en conséquence.

📘
Recommandation
Il est préférable d'envoyer le niveau de catégorie le plus bas dans votre requête d'annonce à Epsilon Retail Media lorsque les clients parcourent des catégories plus avancées.
Ainsi, au lieu de spécifier une requête en chaîne au niveau 3 de L1 + L2 + L3, vous ne devez spécifier que la catégorie L3.

Emplacements des catégories de ventes croisées

Les requêtes d'emplacement pour les catégories de ventes croisées sont très similaires à celles des catégories classiques. Vous devez préciser la catégorie exacte pour laquelle vous demandez des annonces. Il s'agit généralement de la page sur laquelle vous vous trouvez. Il vous faut indiquer la catégorie dans le productFilters de la requête. L'exemple ci-dessous vous montre où envoyer les filtres de catégories :

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9",
    "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
    "placement": "category-cross-sell",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 ["category:Cupboard/Snacks"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}

Au fur et à mesure que des catégories supplémentaires sont ajoutées, vous devez mettre à jour votre appel API en conséquence.

📘
Fusionner le ciblage des catégories organiques et des ventes croisées ?
Si vous souhaitez fusionner une requête d'annonce de catégorie organique et de ventes croisées dans un même emplacement, vous devez mettre en œuvre une logique de fusion et de diffusion à vos clients. Cela relève de l'intégrateur, bien que chez Epsilon Retail Media, nous serons ravis d'être consultés.
En général, nous vous conseillons d'afficher des annonces de catégories organiques, et de positionner les annonces de ventes croisées après les organiques.

Emplacements de requête large

Sur des emplacements larges, tels que des pages d'accueil ou de paiement, il n'est pas nécessaire de préciser l'élément productFilters dans la requête. Tous les filtres que le détaillant souhaiterait spécifier (en promotion, nouveauté, etc.) peuvent être spécifiés dans le productFilters afin de garantir qu'Epsilon Retail Media ne diffuse que des publicités conformes aux exigences.

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9",
    "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
    "placement": "home",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 []
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}

Améliorations des requêtes

En ce qui concerne les emplacements de recherche, de catégorie et de requête large, nous vous conseillons d'envisager les améliorations ci-dessous afin d'optimiser votre expérience utilisateur.

Pagination des requêtes

Lors de la génération d'annonces de produits, vous recevrez un memoryToken qui pourra être envoyé lors de requêtes ultérieures afin d'exclure les publicités précédemment diffusées. Vous pouvez ensuite envoyer ce memoryToken dans une requête d'annonce ultérieure, et Epsilon Retail Media exclura de notre réponse toute annonce précédemment diffusée pour le même contexte.

Please review Pagination prior to implementing.

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9",
    "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
    "placement": "search",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "chocolate",
    "memoryToken":"85ykKVv-luDHMWLZx2d6xcPq6sF7CgkJCSJDb3VudGVyIjogIjIiLAoJCQkiQWRzIjogWwoJCQkJImRpc3BsYXlfV05VV0NwQkRKMUpKNm5wdVZSVExvOU40TUxzNE1UWTBOemt5TWc9PSIsCgkJCQkiZGlzcGxheV9MME5NUHRxNmdCcVFvREJOd3J0dE9UTGJoWk0xTVRFeU9UYzRPUT09IiwKCQkJCSJkaXNwbGF5XzlCcEpmdUpaWk9VXzgyaWpFM3VCczgxd3VVczRNekkwTnpVeE5nPT0iLAoJCQkJImRpc3BsYXlfcW1VU1p4TkpMQ0lqeWQwdTFJRDk0RmxVZ0pnNE16STBOelV4Tnc9PSIsCgkJCQkiZGlzcGxheV9oeHlFZktCUnRrNWlxMThMQzE1SDJHcEN3QjgxTVRFeU9UYzVNQT09IiwKCQkJCSJkaXNwbGF5X1NkcjFEcU5aUEFtcGh0Q1FIUndoYUxFT1B0RXhNamsxT1RJNE5BPT0iLAoJCQkJImRpc3BsYXlfeVlSai1qV2Ntc2ozNzhrel9PMm0yOVlwTjhJeE5EazNPRE00TXc9PSIsCgkJCQkiZGlzcGxheV9Xbm9NZGZuLTRTVmhxcF9xQzVvLWxoT0paNm8xTkRJeE1UUTROdz09IgoJCQldLAoJCQkiVFRMIjogMTYyODk4NTYwMAoJCX0=",
    "options": {
                         "filterMode": "AndOr"
                             },
    "maxNumberOfAds": 3    
}

Recherches filtrées

Si votre client filtre sa recherche, vous pouvez élargir votre contexte afin de proposer des productFilters. Dans l'exemple ci-dessous, le client choisit de filtrer par catégorie « Cupboard » (Garde-manger), puis par restriction alimentaire « Gluten-free » (Sans gluten). Ce même principe peut être appliqué à n'importe quelle catégorie ou emplacement de requête large.

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9",
    "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
    "placement": "search",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "chocolate",
    "productFilters": [
     	 ["category:Cupboard"],["dietary:Gluten-free"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}

Filtrage par emplacement

Si vous synchronisez les filtres d'emplacement dans votre catalogue, vous pouvez élargir votre contexte afin de proposer l'emplacement de la boutique du client dans les productFilters :

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9",
    "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
    "placement": "search",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "chocolate",
    "productFilters": [
     	 ["category:Cupboard"],["dietary:Gluten-free"],["location:Westenbury"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}

La réponse de l'annonce de produit

Toutes les réponses d'annonces de produits suivent le même format JSON. Les annonces de produits sont renvoyées dans le tableau ads, tel qu'illustré ci-dessous :

{
    "ads": [
        {
            "id": "display_QqHaKRrKlFm1Wxr9c_DXJN4HSE3NzMzNjM2",
            "gtin": "7733636",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400902957Z",
            "position": 1
        },
        {
            "id": "display_NzsHqP0_iQedlo9VnrO2vqkwi_k3NzMzNjI4",
            "gtin": "7733628",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400908257Z",
            "position": 2
        },
        {
            "id": "display_xNeShqidaMuEqiJ0zNdt-Gzygjs3NzE0MTA3",
            "gtin": "7714107",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400912929Z",
            "position": 3
        },
        {
            "id": "display_3rGiryPskhQusmsf43nghbQwnqo3NzMzNjU3",
            "gtin": "7733657",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400917769Z",
            "position": 4
        }
    ],
    "banners": [],
    "products": [],
    "memoryToken":"85ykKVv-luDHMWLZx2d6xcPq6sF7CgkJCSJDb3VudGVyIjogIjIiLAoJCQkiQWRzIjogWwoJCQkJImRpc3BsYXlfV05VV0NwQkRKMUpKNm5wdVZSVExvOU40TUxzNE1UWTBOemt5TWc9PSIsCgkJCQkiZGlzcGxheV9MME5NUHRxNmdCcVFvREJOd3J0dE9UTGJoWk0xTVRFeU9UYzRPUT09IiwKCQkJCSJkaXNwbGF5XzlCcEpmdUpaWk9VXzgyaWpFM3VCczgxd3VVczRNekkwTnpVeE5nPT0iLAoJCQkJImRpc3BsYXlfcW1VU1p4TkpMQ0lqeWQwdTFJRDk0RmxVZ0pnNE16STBOelV4Tnc9PSIsCgkJCQkiZGlzcGxheV9oeHlFZktCUnRrNWlxMThMQzE1SDJHcEN3QjgxTVRFeU9UYzVNQT09IiwKCQkJCSJkaXNwbGF5X1NkcjFEcU5aUEFtcGh0Q1FIUndoYUxFT1B0RXhNamsxT1RJNE5BPT0iLAoJCQkJImRpc3BsYXlfeVlSai1qV2Ntc2ozNzhrel9PMm0yOVlwTjhJeE5EazNPRE00TXc9PSIsCgkJCQkiZGlzcGxheV9Xbm9NZGZuLTRTVmhxcF9xQzVvLWxoT0paNm8xTkRJeE1UUTROdz09IgoJCQldLAoJCQkiVFRMIjogMTYyODk4NTYwMAoJCX0="
}

Le champ id correspond à l'ID de votre annonce utilisé dans les rapports d'impressions et de clics. Le champ position définit l'emplacement dans la charge utile Epsilon Retail Media. Reportez-vous à la référence pour plus d'informations sur chaque chaîne.

📘
Vous devez lire et respecter le champ position pour vous assurer que les emplacements de location fixe s'affichent correctement.

ID de vendeur Marketplace

Lors de l'onboarding de vendeurs Marketplace, vous pouvez voir un sellerId supplémentaire par annonce dans la réponse. Il n'apparaîtra que si l'équipe détentrice de la campagne en cours de diffusion a configuré un ID de vendeur dans l'interface utilisateur. L'exemple ci-dessous montre une annonce avec un ID de vendeur et une autre sans.

{
    "ads": [
        {
            "id": "display_QqHaKRrKlFm1Wxr9c_DXJN4HSE3NzMzNjM2",
            "gtin": "7733636",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400902957Z",
            "position": 1
        },
        {
            "id": "display_NzsHqP0_iQedlo9VnrO2vqkwi_k3NzMzNjI4",
            "gtin": "7733628",
            "sellerId": "2834-ascre-2wcr4",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400908257Z",
            "position": 2
        }
    ],
    "banners": [],
    "products": [],
    "memoryToken":"85ykKVv-luDHMWLZx2d6xcPq6sF7CgkJCSJDb3VudGVyIjogIjIiLAoJCQkiQWRzIjogWwoJCQkJImRpc3BsYXlfV05VV0NwQkRKMUpKNm5wdVZSVExvOU40TUxzNE1UWTBOemt5TWc9PSIsCgkJCQkiZGlzcGxheV9MME5NUHRxNmdCcVFvREJOd3J0dE9UTGJoWk0xTVRFeU9UYzRPUT09IiwKCQkJCSJkaXNwbGF5XzlCcEpmdUpaWk9VXzgyaWpFM3VCczgxd3VVczRNekkwTnpVeE5nPT0iLAoJCQkJImRpc3BsYXlfcW1VU1p4TkpMQ0lqeWQwdTFJRDk0RmxVZ0pnNE16STBOelV4Tnc9PSIsCgkJCQkiZGlzcGxheV9oeHlFZktCUnRrNWlxMThMQzE1SDJHcEN3QjgxTVRFeU9UYzVNQT09IiwKCQkJCSJkaXNwbGF5X1NkcjFEcU5aUEFtcGh0Q1FIUndoYUxFT1B0RXhNamsxT1RJNE5BPT0iLAoJCQkJImRpc3BsYXlfeVlSai1qV2Ntc2ozNzhrel9PMm0yOVlwTjhJeE5EazNPRE00TXc9PSIsCgkJCQkiZGlzcGxheV9Xbm9NZGZuLTRTVmhxcF9xQzVvLWxoT0paNm8xTkRJeE1UUTROdz09IgoJCQldLAoJCQkiVFRMIjogMTYyODk4NTYwMAoJCX0="
}

📘
If you’re unsure about the strings in this section, please visit the Product ad reference page.

Loi sur les Services Numériques

Epsilon Retail Media assists retailers in meeting their European Union (EU) Digital Services Act (DSA) obligations. The DSA establishes a unified set of rules across the EU, targeting the regulation of online content, transparent advertising, and disinformation. For more information, see Digital Services Act.

Exemple de requête d'annonce

{
    "placement": "search-only",
    "catalogId": "zesty-fruits-catalog",
    "searchTerm": "lime",
    "maxNumberOfAds": 5,
    "options": {
   			    "filterMode": "AndOr",
    			"includeAdvertiserInfo": true,
     },
}

Exemple de réponse d'annonce

{
  "ads": [
    {
      "id": "display_QqHaKRrKlFm1Wxr9c_DXJN4HSE3NzMzNjM2",
      "gtin": "7733636",
      "discount": {
        "amount": 0,
        "minPrice": 0,
        "maxPerCustomer": 0
      },
      "expiry": "2021-05-12T04:17:50.400902957Z",
      "position": 1,
      "metadata": {
        "advertiserInfo": {
       "advertiser": "Bob's advertising agency",
          "onBehalfOf": "Brand company inc",
        }
      }
    },
    ....
  ],
  "banners": [],
  "products": [],
  "memoryToken": "85ykKVv-………"
}