API partenaire
Guides

Générez des annonces de produits à l'aide de l'emplacement dans les résultats de recherche

Ce document fournit un guide complet sur la manière de générer des annonces de produits sur la base de critères de recherche spécifiques. Chaque requête API doit inclure des détails sur le contexte, tels que :

  • Emplacement
  • ID du catalogue
  • customerId
  • sessionId
  • Terme de recherche
  • Nombre maximum d’annonces à afficher

Conditions préalables

Vous devez effectuer les étapes suivantes avant de commencer à demander des annonces de produits pour les emplacements de recherche.

Ajouter des catalogues de produits

Assurez-vous que vos produits ont été ajoutés à vos catalogues et synchronisés avec la plateforme Epsilon Retail Media.

Créer une campagne et configurer les termes de recherche

Assurez-vous d’avoir créé une campagne et configuré les termes de recherche. Pour obtenir de plus amples informations, veuillez consulter l’étape 4b : Configurer les termes de recherche.

Définissez les termes de recherche que vous souhaitez cibler (inclure et exclure) pour vos annonces de produits. Vous pouvez préciser une correspondance exacte, une correspondance d’expressions et des termes de recherche négatifs.

  • Correspondance exacte :
    • cible les termes de recherche qui correspondent exactement à vos mots-clés.
    • Exemple : si votre mot-clé est « chaussures de course bleues », votre annonce sera uniquement visible par les utilisateurs qui saisissent « chaussures de course bleues » dans cet ordre précis, sans aucun autre mot.
  • Correspondance d’expressions :
    • cible les termes de recherche qui correspondent exactement à vos mots-clés.
    • votre annonce sera visible pour des recherches comprenant des mots supplémentaires avant ou après l’expression.
    • Exemple : si votre mot-clé est « chaussures de course bleues », votre annonce sera uniquement visible par les utilisateurs qui saisissent « chaussures de course bleues » dans cet ordre précis, sans aucun autre mot.
    • Pour obtenir de plus amples informations, veuillez consulter la section Termes de recherche de correspondance d’expressions.
  • Termes de recherche négatifs :
    • exclut des mots ou des expressions spécifiques de votre campagne.
    • Empêche la diffusion de vos annonces dans des recherches sans lien avec le sujet.
    • Exemple : en ajoutant le terme « occasion » comme terme négatif pour une annonce de voiture neuve, elle ne sera pas visible par les personnes qui recherchent des voitures d’occasion.

Récupérer les clés API et l’URL de base

  1. Vous devez disposer d’une clé API valide. Procédez comme suit :

    1. Connectez-vous au compte de votre équipe Retail Media d’Epsilon.

    2. Allez en haut à droite de la page et cliquez sur le menu déroulant.

    3. Sélectionnez Paramètres d’intégration dans le menu déroulant.

    4. Cliquez sur l’onglet Clé API. Votre clé API secrète est initialement masquée. Pour l’afficher, cliquez sur le bouton Afficher. Une fois visible, copiez-la. Utilisez-la pour effectuer des appels API.

  2. Vous devez avoir l’URL de base pour le point de terminaison d’API. Par exemple, https://staging-test.citrusad.com/v1/ads/generate HTTP/1.1. Vérifiez-la auprès de votre responsable de compte technique.

Générer des annonces

Procédez comme suit pour générer des annonces de produits.

Requête HTTP

Point de terminaison : /v1/ads/generate

Méthode : POST

En-têtes :

  • accepter : application/json
  • content-type : application/json
  • Autorisation : Basic <API_KEY>

Paramètres de la requête

Le corps de la requête doit être un objet JSON contenant les champs suivants :

objettypeDescription
customerIdchaîne, obligatoireL’identifiant unique du client (il est fourni par votre détaillant).
sessionIdchaîne, obligatoireL’identifiant unique de la session. Cette information est nécessaire pour l’attribution (elle est fournie par le détaillant).
dtmcookieidchaîne, obligatoireL'identifiant dtmCookieId est extrait de votre cookie propriétaire Epsilon. Vous pourrez ainsi suivre et attribuer avec précision les interactions des utilisateurs.
Emplacementchaîne, obligatoireContexte dans lequel l’annonce est affichée (par exemple, « recherche »).
ID du cataloguechaîne, obligatoireL’identifiant unique du catalogue de produits à partir duquel les produits sont filtrés. Vous pouvez l'obtenir à partir de l’interface utilisateur Retail Media d’Epsilon ou auprès du détaillant.
maxNumberOfAdsnombre entier, obligatoireNombre maximum d’annonces à afficher
Terme de recherchechaîne, obligatoire pour les emplacements de rechercheTerme à rechercher dans le catalogue
optionsobjet, facultatifOptions supplémentaires telles que les modes de filtrage AndOrSi elle est précisée, le système utilisera les conditions « ET » et « OU » pour affiner les résultats de la recherche.

Exemple de requête

Cette requête est utilisée pour générer jusqu’à 3 annonces pertinentes pour le terme de recherche. chocolateCes annonces seront affichées dans les résultats de recherche pour un client (customerId: "wertg5432a") et une session (sessionId: "ec9-4e07-881d-3e9") spécifiques. Elles seront générées à partir du catalogue identifié par catalogId : "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b", avec des options de filtrage supplémentaires précisées (filterMode: "AndOr").

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    
}

Exemple de réponse

📘

Lorsque vous recevez des réponses à des annonces de produits, elles incluent généralement des codes produit, tels que les GTIN dans cet exemple. Les détaillants doivent utiliser les codes produit fournis dans les réponses publicitaires pour rechercher les métadonnées nécessaires à l’affichage des produits.

Dans cet exemple, le "gtin": "024100191345" est le code produit. Les détaillants l’utiliseront pour identifier et afficher le produit sponsorisé en question.

{
    "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": [],
}

Prochaines étapes

Mis à jour Il y a 5 mois