Solicitud de anuncios
Todas las solicitudes de anuncios de productos requieren el contexto de placementy del contexto. catalogId, así como el maxNumberOfAds que desea mostrar al cliente. Además, su solicitud debe incluir el contexto de customerId y sessionId.
Buscar ubicaciones
Las ubicaciones de búsqueda suelen ser las más fáciles de solicitar. Requieren que se especifique un searchTerm en la solicitud, como en el ejemplo que aparece a continuación:
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
}
Ubicaciones de categorías
Las ubicaciones de categorías requieren que se especifiquen productFilters en la solicitud. El siguiente ejemplo muestra a dónde enviaría los filtros de categoría:
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
}
Cuando examine categorías adicionales, debe actualizar su llamada API en consecuencia.
Mejores prácticas
Es recomendable enviar el nivel más bajo de categoría a su solicitud de anuncio a CitrusAd a medida que los clientes navegan por categorías más profundas.
En lugar de especificar una solicitud encadenada en el nivel 3 de L1 + L2 + L3, solo debe especificar la categoría L3.
Ubicaciones de categorías de venta cruzada
Las ubicaciones de categoría de venta cruzada tienen una solicitud muy similar a las ubicaciones de categoría. Deberá especificar la categoría exacta para la que desea solicitar anuncios. Esta suele ser la página en la que se encuentra. Especifique la categoría en el productFilters de la solicitud. El siguiente ejemplo muestra a dónde enviaría los filtros de categoría:
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
}
Cuando examine categorías adicionales, debe actualizar su llamada API en consecuencia.
¿Fusión de segmentación por categoría orgánica y de venta cruzada?
Si desea fusionar una solicitud de anuncios de categoría orgánica y de venta cruzada en una sola ubicación, necesitará aplicar una lógica de fusión y entrega para sus clientes. Esto es la responsabilidad del integrador, aunque CitrusAd se complace en ser consultado.
En general, le recomendamos que muestre anuncios de categoría orgánica y anuncios de categoría de posición y de venta cruzada tras las ubicaciones orgánicas.
Ubicaciones de concordancia amplia
Las ubicaciones amplias, como las páginas de inicio o de pago, no requieren que se especifiquen productFilters en la solicitud. Todos los filtros que el minorista quiera aplicar (en oferta, nuevo, etc.) pueden especificarse en los productFilters para garantizar que CitrusAd solo distribuya anuncios dentro de los requisitos.
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
}
Solicitud de mejoras
En las ubicaciones de búsqueda, categoría y coincidencia amplia, le aconsejamos que considere lo siguiente para mejorar su experiencia de usuario.
Paginación de solicitudes
Al generar anuncios de productos, recibirá un memoryToken que puede enviarse en solicitudes posteriores para excluir los anuncios proporcionados anteriormente. A continuación, puede enviar este memoryToken en una solicitud de anuncio posterior y CitrusAd excluirá cualquier anuncio mostrado anteriormente para el mismo contexto de nuestra respuesta del anuncio.
Consulte Paginación antes de aplicarla.
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
}
Búsquedas filtradas
Si su cliente filtra la búsqueda, puede ampliar el contexto para proporcionar productFilters. A continuación se muestra un ejemplo en el que el cliente filtra por la categoría "Aparador" y por la restricción dietética "Sin gluten". Este mismo principio puede aplicarse a cualquier categoría o ubicación de coincidencia amplia.
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
}
Filtrado por ubicación
Si está sincronizando filtros de ubicación en su catálogo, puede ampliar el contexto para proporcionar la ubicación de la tienda del cliente en los 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 respuesta del anuncio del producto
Todas las respuestas de anuncios de productos tienen el mismo formato JSON. Los anuncios de productos se devuelven en ads como en el ejemplo siguiente:
{
"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="
}
La id es el campo correspondiente a su ID de anuncio utilizada en los informes de impresiones y clics. La position en el campo define la posición en la carga útil de CitrusAd. Consulte la referencia para obtener más información sobre cada cadena.
Debe leer y respetar el campo
positionpara asegurarse de que las ubicaciones de posición fija aparezcan correctamente.
ID de vendedor del mercado web
Si incorpora vendedores del mercado, puede ver uno adicional sellerId por anuncio en la respuesta. Solo aparecerá si el equipo propietario de la campaña que se envía tiene un ID de vendedor configurado en la interfaz de usuario. El siguiente ejemplo muestra un anuncio con ID de vendedor y otro sin él.
{
"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 no conoce con seguridad las cadenas de caracteres de esta sección, visite la página de referencia de anuncios de productos.