Requêtes d'annonces
Toutes les requêtes d'annonces de produits nécessitent le placement
et catalogId
du contexte, ainsi que le maxNumberOfAds
que vous souhaitez afficher au client. En outre, votre requête doit inclure le customerId
et sessionId
.
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",
"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
. 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",
"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 plus bas dans votre requête d'annonce à CitrusAd 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",
"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 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
du contexte, de manière à garantir que CitrusAd diffuse uniquement des annonces répondant 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",
"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 demandes 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 CitrusAd exclura toute annonce précédemment diffusée pour le même contexte dans la réponse publicitaire.
Veuillez consulter la section Pagination avant de procéder à la mise en œuvre.
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": "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",
"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",
"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="
}
L'AD_ID id
correspond à l'identifiant de votre annonce utilisé dans les rapports d'impressions et de clics. L'AD_ID position
définit l'emplacement dans la charge utile CitrusAd. 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="
}
Si vous avez un doute sur les chaînes de cette section, veuillez consulter la page Référence des annonces de produits.