Requêtes d'annonces
Les bannières publicitaires X sont générées sur le point de terminaison /bannerx
. Toutes les requêtes de bannières X nécessitent les éléments contentStandardId
et bannerSlotIds
auxquels vos requêtes d'annonces sont liées. En outre, votre appel de bannière doit contenir les éléments de contexte suivants : customerId
,sessionId
,placement
et catalogId
.
Lorsque vous émettez une requête de bannières publicitaires X, vous pouvez préciser le nombre maximum de bannières que vous souhaitez recevoir par espace de bannière. Vous pouvez contrôler cela grâce au paramètre maxNumberOfAds
.
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/bannerx HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
"customerId": "wertg5432a",
"sessionId": "ec9-4e07-881d-3e9",
"placement": "search",
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"searchTerm": "chocolate",
"options": {
"filterMode": "AndOr"
},
"contentStandardId": "c61941e2-1435-460b-9d2b-5d838e3dba9c",
"bannerSlotIds": [
{
"slotId": "<SLOT_ID>",
"maxNumberOfAds": 1
},
{
"slotId": "<SLOT_ID>",
"maxNumberOfAds": 2
}
]
}
Emplacements de catégories
Les emplacements de catégories nécessitent que l'élément productFilters
. L'exemple ci-dessous vous montre où envoyer les filtres de catégories :
POST $BASE_URL/v1/ads/bannerx HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
"customerId": "wertg5432a",
"sessionId": "ec9-4e07-881d-3e9",
"placement": "category",
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"productFilters": [
["category:Cupboard/Snacks"]
],
"options": {
"filterMode": "AndOr"
},
"contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
"bannerSlotIds": [
{
"slotId": "<SLOT_ID>",
"maxNumberOfAds": 1
},
{
"slotId": "<SLOT_ID>",
"maxNumberOfAds": 2
}
}
Au fur et à mesure que des catégories supplémentaires sont ajoutées, vous devriez mettre à jour votre appel API en conséquence.
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",
"placement": "category-cross-sell",
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"productFilters": [
["category:Cupboard/Snacks"]
],
"options": {
"filterMode": "AndOr"
},
"contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
"bannerSlots": [
{
"slotId": "<SLOT_ID>",
"maxNumberOfAds": 1
},
{
"slotId": "<SLOT_ID>",
"maxNumberOfAds": 2
}
],
"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 CitrusAd, 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 dans la requête l'élément productFilters
. Le détaillant peut préciser les filtres de son choix (en promotion, nouveauté, etc.) dans l'élément productFilters
, de manière à garantir que CitrusAd diffuse uniquement des annonces répondant aux exigences, comme dans l'exemple ci-dessous :
POST $BASE_URL/v1/ads/bannerx HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
"customerId": "wertg5432a",
"sessionId": "ec9-4e07-881d-3e9",
"placement": "home",
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"productFilters": [
[]
],
"options": {
"filterMode": "AndOr"
},
"contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
"bannerSlotIds": [
{
"slotId": "<SLOT_ID>",
"maxNumberOfAds": 1
},
{
"slotId": "<SLOT_ID>",
"maxNumberOfAds": 2
}
}
Améliorations des requêtes
Nous vous conseillons d'envisager les améliorations ci-dessous afin d'optimiser votre expérience utilisateur.
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/bannerx HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
"customerId": "wertg5432a",
"sessionId": "ec9-4e07-881d-3e9",
"placement": "search",
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"searchTerm": "chocolate",
"productFilters": [
["category:Cupboard"],["dietary:Gluten-free"]
],
"options": {
"filterMode": "AndOr"
},
"contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
"bannerSlotIds": [
{
"slotId": "<SLOT_ID>",
"maxNumberOfAds": 1
},
{
"slotId": "<SLOT_ID>",
"maxNumberOfAds": 2
}
}
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
, comme dans l'exemple ci-dessous :
POST $BASE_URL/v1/ads/bannerx HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
"customerId": "wertg5432a",
"sessionId": "ec9-4e07-881d-3e9",
"placement": "search",
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"searchTerm": "chocolate",
"productFilters": [
["category:Cupboard"],["dietary:Gluten-free"],["location:Westenbury"]
],
"options": {
"filterMode": "AndOr"
},
"contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
"bannerSlotIds": [
{
"slotId": "<SLOT_ID>",
"maxNumberOfAds": 1
},
{
"slotId": "<SLOT_ID>",
"maxNumberOfAds": 2
}
}
La réponse de la bannière X
Toutes les réponses suivent le même format JSON. Tout le contenu requis pour afficher la bannière est fourni dans la réponse. Si aucun composant n'est configuré pour la bannière (par exemple, aucune image Hero secondaire), CitrusAd ne diffusera pas la propriété.
{
"ads": [
{
"contentStandardId": "c619d1e2-1435-460b-9d2b-5d838e3dba9c",
"slotId": "<SLOT_ID>",
"banners": [
{
"citrusAdId": "shotgun__vW5pOojxDfN7T9VwaXWQLF2wKw3NzE0MTA3",
"citrusCampaignName": "CitrusAd-Example-Category-Banner-X-Ad-52793b405f1347b22e72a38c5a08699b",
"citrusContentStandardId": "c619d1e2-1435-460b-9d2b-5d838e3dba9c",
"citrusSlotId": "<SLOT_ID>",
"citrusExpiry": "2021-05-17T02:47:52.849995214Z",
"headingText": "Banner Advertisement for Magnum Double Ice Cream with a product image and shop now button",
"bannerText": "<strong>Magnum Double Ice Cream</strong>",
"bannerTextColour": "6e6c6c",
"ctaFlag": true,
"ctaText": "Shop now",
"ctaTextAccessibility": "for Magnum products",
"ctaLink": "https://www.tesco.com/groceries/en-GB/search?query=magnums",
"backgroundColour": "e1d6ac",
"heroImage": "https://cdn.flavedo.io/s/9b93e7f9-d747-4c8b-bcba-2357b280a3b3",
"heroImageAltText": "Magnums",
"tags": {},
"gtins": [
"7714107",
"7733636",
"7733657",
"7163379",
"7733628"
],
"position": 1
}
]
},
{
"contentStandardId": "c619d1e2-1435-460b-9d2b-5d838e3dba9c",
"slotId": "<SLOT_ID>",
"banners": [
{
"citrusAdId": "shotgun_kZp9yTCMm71vTo7iyQaK9I_YB09FUFYzNzBTQ0FO",
"citrusCampaignName": "milo-campaign-lakjsdf09kj",
"citrusContentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
"citrusSlotId": "<SLOT_ID>",
"citrusExpiry": "2021-05-17T02:47:52.849995214Z",
"headingText": "A banner for Milo with a product image and a shop now button",
"bannerText": "<strong>Try Milo Cereal</strong>",
"bannerTextColour": "48a94c",
"heroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8851d59f0574",
"heroImageAltText": "Milo product image",
"ctaFlag": true,
"ctaText": "Shop now",
"ctaTextAccessibility": "for Milo products",
"ctaLink": "retailer.com/everything/search/heritage%20mill?pageNumber=1",
"secondaryHeroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8m435c34r",
"secondaryHeroImageAltText": "Milo Logo",
"secondaryHeroMode": "landscape",
"backgroundColour": "895b5b",
"backgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
"backgroundImagePosition": "FILL",
"secondaryBackgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
"tags": {},
"gtins": [
"16309011",
"57312011",
"65250011"
],
"position": 1
}
]
}
]
}
L'AD_ID id
correspond à l'identifiant de votre annonce utilisé dans les rapports d'impressions et de clics. Reportez-vous à la référence pour plus d'informations sur chaque chaîne.
Balises de suivi tierces
Pour les bannières publicitaires x, CitrusAd prend en charge le transfert de balises de suivi tierces au détaillant. Ces balises sont utilisées par les annonceurs pour vérifier leurs performances via un tiers de confiance.
CitrusAd prend en charge les balises de suivi ci-dessous :
- DoubleVerify (Javascript et Image)
- DCM Click
- DCM Impression
- IAS
- Adform Impression
- Cliquez sur Adform
Lorsqu'une balise de suivi est configurée pour une campagne, elle s'affiche comme champ pertinent dans l'objet trackingTags
suivant. Remarque : si aucune balise n'a été configurée pour une campagne, l'objet tags
et trackingTags
restera vide.
{
"ads": [
{
"contentStandardId": "c619d1e2-1435-460b-9d2b-5d838e3dba9c",
"slotId": "<SLOT_ID>",
"banners": [
{
"citrusAdId": "shotgun__vW5pOojxDfN7T9VwaXWQLF2wKw3NzE0MTA3",
"citrusCampaignName": "CitrusAd-Example-Category-Banner-X-Ad-52793b405f1347b22e72a38c5a08699b",
"citrusContentStandardId": "c619d1e2-1435-460b-9d2b-5d838e3dba9c",
"citrusSlotId": "<SLOT_ID>",
"citrusExpiry": "2021-05-17T02:47:52.849995214Z",
"headingText": "Banner Advertisement for Magnum Double Ice Cream with a product image and shop now button",
"bannerText": "<strong>Magnum Double Ice Cream</strong>",
"bannerTextColour": "6e6c6c",
"ctaFlag": true,
"ctaText": "Shop now",
"ctaTextAccessibility": "for Magnum products",
"ctaLink": "https://www.tesco.com/groceries/en-GB/search?query=magnums",
"backgroundColour": "e1d6ac",
"heroImage": "https://cdn.flavedo.io/s/9b93e7f9-d747-4c8b-bcba-2357b280a3b3",
"heroImageAltText": "Magnums",
"tags": {},
"trackingTags": {
"ADFORM_CLICK": "https://track.adform.net...",
"ADFORM_IMPRESSION": "<img src=\"https://track.adform.net...",
"DCM_CLICK": "https://ad.doubleclick.net/ddm/trackclk/...",
"DCM_IMPRESSION": "<IMG SRC=\"https://ad.doubleclick.net/ddm/trackimp/...",
"DV": "<script src=\"https://cdn.doubleverify.com/dvtp_src.js?ctx=...",
"DV_IMAGE": "<img src=\"https://tps.doubleverify.com/visit.jpg?ctx=..."
},
"gtins": [
"7714107",
"7733636",
"7733657",
"7163379",
"7733628"
],
"position": 1
}
]
}
]
}
CitrusAd étant une intégration de serveur à serveur, les balises de suivi tierces nécessitent un développement supplémentaire par le détaillant. Contactez votre responsable de compte technique si vous souhaitez utiliser cette fonctionnalité.
tags
objetPour les balises DoubleVerify (Javascript) et DCM, il se peut que
tags
l'objet soit également renseigné. La meilleure pratique consiste à utiliser l'optiontrackingTags
réponse.
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": [
{
"contentStandardId": "c619d1e2-1435-460b-9d2b-5d838e3dba9c",
"slotId": "<SLOT_ID>",
"banners": [
{
"citrusAdId": "shotgun__vW5pOojxDfN7T9VwaXWQLF2wKw3NzE0MTA3",
"citrusCampaignName": "CitrusAd-Example-Category-Banner-X-Ad-52793b405f1347b22e72a38c5a08699b",
"citrusContentStandardId": "c619d1e2-1435-460b-9d2b-5d838e3dba9c",
"citrusSlotId": "<SLOT_ID>",
"citrusExpiry": "2021-05-17T02:47:52.849995214Z",
"headingText": "Banner Advertisement for Magnum Double Ice Cream with a product image and shop now button",
"bannerText": "<strong>Magnum Double Ice Cream</strong>",
"bannerTextColour": "6e6c6c",
"ctaFlag": true,
"ctaText": "Shop now",
"ctaTextAccessibility": "for Magnum products",
"ctaLink": "https://www.tesco.com/groceries/en-GB/search?query=magnums",
"backgroundColour": "e1d6ac",
"heroImage": "https://cdn.flavedo.io/s/9b93e7f9-d747-4c8b-bcba-2357b280a3b3",
"heroImageAltText": "Magnums",
"tags": {},
"gtins": [
"7714107",
"7733636",
"7733657",
"7163379",
"7733628"
],
"position": 1,
"sellerId": "1ben32-ss3d43-amea"
}
]
},
{
"contentStandardId": "c619d1e2-1435-460b-9d2b-5d838e3dba9c",
"slotId": "<SLOT_ID>",
"banners": [
{
"citrusAdId": "shotgun_kZp9yTCMm71vTo7iyQaK9I_YB09FUFYzNzBTQ0FO",
"citrusCampaignName": "milo-campaign-lakjsdf09kj",
"citrusContentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
"citrusSlotId": "<SLOT_ID>",
"citrusExpiry": "2021-05-17T02:47:52.849995214Z",
"headingText": "A banner for Milo with a product image and a shop now button",
"bannerText": "<strong>Try Milo Cereal</strong>",
"bannerTextColour": "48a94c",
"heroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8851d59f0574",
"heroImageAltText": "Milo product image",
"ctaFlag": true,
"ctaText": "Shop now",
"ctaTextAccessibility": "for Milo products",
"ctaLink": "retailer.com/everything/search/heritage%20mill?pageNumber=1",
"secondaryHeroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8m435c34r",
"secondaryHeroImageAltText": "Milo Logo",
"secondaryHeroMode": "landscape",
"backgroundColour": "895b5b",
"backgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
"backgroundImagePosition": "FILL",
"secondaryBackgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
"tags": {},
"gtins": [
"16309011",
"57312011",
"65250011"
],
"position": 1
}
]
}
]
}
Balises de suivi tierces
À paraître dans la version 44
Cette fonctionnalité est prévue pour la version 44.0. Le
tags
tableau est déjà fourni dans la réponse.
CitrusAd prend en charge le transfert de balises de suivi tierces au détaillant. Ces balises sont utilisées par les annonceurs pour vérifier leurs performances via un tiers de confiance.
CitrusAd prend en charge les balises de suivi ci-dessous :
- DoubleVerify
- DCM Click
- DCM Impression
- IAS
Lorsqu'une balise de suivi est configurée pour une campagne, elle s'affiche comme champ pertinent dans l'objet tags
suivant. Remarque : si aucune balise n'a été configurée pour une campagne, l'objet tags
restera vide.
{
"ads": [],
"banners": [
{
"id": "banner_XeemTeq59HapGSp4vccOYfBq_yvc3zMzNjM2",
"contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
"slotId": "<SLOT_ID>",
"imageUrl": "https://cdn.flavedo.io/s/-oW-C3cEViSSO2krWkwOBUXOhvUdhHOySx-YQLGZ1lA=",
"linkUrl": "https://www.retailer.com/link",
"altText": "Your local ice cream",
"text": "",
"gtins": [
"7733628",
"7714107",
"7163379",
"7733636",
"7733657"
],
"expiry": "2021-05-17T01:49:17.75503253Z",
"tags": {
"dv": "<script src=\"https://cdn.doubleverify.com/dvtp_src.js?ctx=919421&cmp=1074060503&sid=1073907024&plc=1075810393&adsrv=115&btreg=&btadsrv=&crt=&tagtype=&dvtagver=6.1.src\" type=\"text/javascript\"></script>",
"dcmClick": "<script ..../>",
"dcmImpression": "<script.... />",
"ias": "<script.... />" }
}
],
"products": [],
"memoryToken":"85ykKVv-luDHMWLZx2d6xcPq6sF7CgkJCSJDb3VudGVyIjogIjIiLAoJCQkiQWRzIjogWwoJCQkJImRpc3BsYXlfV05VV0NwQkRKMUpKNm5wdVZSVExvOU40TUxzNE1UWTBOemt5TWc9PSIsCgkJCQkiZGlzcGxheV9MME5NUHRxNmdCcVFvREJOd3J0dE9UTGJoWk0xTVRFeU9UYzRPUT09IiwKCQkJCSJkaXNwbGF5XzlCcEpmdUpaWk9VXzgyaWpFM3VCczgxd3VVczRNekkwTnpVeE5nPT0iLAoJCQkJImRpc3BsYXlfcW1VU1p4TkpMQ0lqeWQwdTFJRDk0RmxVZ0pnNE16STBOelV4Tnc9PSIsCgkJCQkiZGlzcGxheV9oeHlFZktCUnRrNWlxMThMQzE1SDJHcEN3QjgxTVRFeU9UYzVNQT09IiwKCQkJCSJkaXNwbGF5X1NkcjFEcU5aUEFtcGh0Q1FIUndoYUxFT1B0RXhNamsxT1RJNE5BPT0iLAoJCQkJImRpc3BsYXlfeVlSai1qV2Ntc2ozNzhrel9PMm0yOVlwTjhJeE5EazNPRE00TXc9PSIsCgkJCQkiZGlzcGxheV9Xbm9NZGZuLTRTVmhxcF9xQzVvLWxoT0paNm8xTkRJeE1UUTROdz09IgoJCQldLAoJCQkiVFRMIjogMTYyODk4NTYwMAoJCX0="
}
CitrusAd étant une intégration de serveur à serveur, les balises de suivi tierces nécessitent un développement supplémentaire par le détaillant.