Solicitud de anuncios

Los anuncios de banner x se generan en el endpoint /bannerx . Todas las solicitudes de banner x requieren el contentStandardId y la bannerSlotIds para el que solicita anuncios. Además, la llamada de banner debe incluir el contexto del customerId,sessionId,placementy del contexto. catalogId.

Al solicitar anuncios de banner x, puede especificar el número máximo de banners que desea recibir por posición de banners. Puede controlarlo con el maxNumberOfAds .

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/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
    }
  ]
}

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/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
    }
}

Cuando examine categorías adicionales, debe actualizar su llamada API en consecuencia.

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"
 							 },
    "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
    "bannerSlots": [
           {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 1
    },
    {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 2
    }
    ],            
    "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 muestre anuncios dentro de los requisitos, como en el ejemplo que aparece a continuación:

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
    }
}

Solicitud de mejoras

Le recomendamos que considere lo siguiente para mejorar su experiencia de usuario.

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/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
    }
}

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, como en el ejemplo que aparece a continuación:

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 respuesta del banner x

Todas las respuestas siguen el mismo formato JSON. Todo el contenido necesario para renderizar el banner se proporciona en la respuesta. Si el banner no tiene un componente configurado (como una imagen principal secundaria), CitrusAd no mostrará la propiedad.

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

La id es el campo correspondiente a su ID de anuncio utilizada en los informes de impresiones y clics. Consulte la referencia para obtener más información sobre cada cadena.

Etiquetas de seguimiento de terceros

Para los anuncios de banner x, CitrusAd admite la etiqueta de seguimiento de terceros al minorista. Los anunciantes utilizan estas etiquetas para que un tercero de confianza verifique su rendimiento.

CitrusAd admite las siguientes etiquetas de seguimiento:

Doble verificación (JavaScript e imagen)
Clic en DCM
Impresión de DCM
IAS
Impresión del formulario de anuncio
Clic en el formulario de anuncio

Si una campaña tiene configurada una etiqueta de seguimiento, se presentará como el campo relevante en el objeto trackingTags que aparece a continuación. Tenga en cuenta que, si una campaña no tiene una etiqueta configurada, el objeto tagsy trackingTags permanecerá vacío.

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

Como CitrusAd es una integración de servidor a servidor, las etiquetas de seguimiento de terceros requieren un desarrollo adicional por parte del minorista. Póngase en contacto con el administrador técnico de su cuenta si desea utilizar esta función.

📘
tags objeto
Para las etiquetas de verificación doble (Javascript) y DCM, es posible que también aparezca tags el objeto rellenado. Se recomienda utilizar la respuesta trackingTags .

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

Etiquetas de seguimiento de terceros

📘
Próximamente en la versión 44
Está previsto que esta capacidad se publique en la versión 44.0. La tags matriz ya se proporciona en la respuesta.

CitrusAd admite la transferencia de etiquetas de seguimiento de terceros al minorista. Los anunciantes utilizan estas etiquetas para que un tercero de confianza verifique su rendimiento.

CitrusAd admite las siguientes etiquetas de seguimiento:

Doble verificación
Clic en DCM
Impresión de DCM
IAS

Si una campaña tiene configurada una etiqueta de seguimiento, se presentará como el campo relevante en el objeto tags que aparece a continuación. Tenga en cuenta que, si una campaña no tiene una etiqueta configurada, el objeto tags permanecerá vacío.

{
    "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="
}

Como CitrusAd es una integración de servidor a servidor, las etiquetas de seguimiento de terceros requieren un desarrollo adicional por parte del minorista.

Solicitud de anuncios de banner x

Solicitud de anuncios

Buscar ubicaciones

Ubicaciones de categorías

Ubicaciones de categorías de venta cruzada

📘
¿Fusión de segmentación por categoría orgánica y de venta cruzada?

Ubicaciones de concordancia amplia

Solicitud de mejoras

Búsquedas filtradas

Filtrado por ubicación

La respuesta del banner x

Etiquetas de seguimiento de terceros

📘
`tags` objeto

ID de vendedor del mercado web

Etiquetas de seguimiento de terceros

📘
Próximamente en la versión 44

Solicitud de anuncios

Buscar ubicaciones

Ubicaciones de categorías

Ubicaciones de categorías de venta cruzada

📘¿Fusión de segmentación por categoría orgánica y de venta cruzada?

Ubicaciones de concordancia amplia

Solicitud de mejoras

Búsquedas filtradas

Filtrado por ubicación

La respuesta del banner x

Etiquetas de seguimiento de terceros

📘tags objeto

ID de vendedor del mercado web

Etiquetas de seguimiento de terceros

📘Próximamente en la versión 44

📘
¿Fusión de segmentación por categoría orgánica y de venta cruzada?

📘
`tags` objeto

📘
Próximamente en la versión 44