API para socios

Solicitud de anuncios de banner

Solicitud de anuncios

Dado que los anuncios y banners de productos se generan en el mismo endpoint, si el contexto de su ubicación es el mismo, puede solicitar anuncios de productos en la misma solicitud que los banners.

La cantidad de anuncios de productos que pueden recibirse se configura definiendo el parámetro maxNumberOfAds . El número de banners que pueden recibirse se puede configurar con la propiedad maxNumberOfAds por slotID única.

Todas las solicitudes de anuncios de banner requieren la contentStandardId y la bannerSlots para los que solicita anuncios. Además, la llamada de banner debe incluir la customerId,sessionId,placementy del contexto. catalogId.

📘

Puede que note algunos cambios aquí.

Vamos a cambiar la forma en la que solicita anuncios de banner de CitrusAd. Si ya está integrado, puede solicitar una propiedad llamada bannerSlotIds. La hemos sustituido por nuestra nueva capacidad bannerSlots . Si desea consultar cómo solicitar anuncios con la propiedad bannerSlotIds , vaya a la parte inferior de esta página.

Se prevé que esta capacidad bannerSlots se puso en marcha en septiembre de 2022.

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"
 							 },
    "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
    "bannerSlots": [
           {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 1
    },
    {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 2
    }
    ],           
    "maxNumberOfAds": 3    
}

Ubicaciones de categorías

Las ubicaciones de categorías requieren que se especifiquen productFilters en la solicitud. A continuación se muestra un ejemplo de 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"
 							 },
    "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.

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/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"
 							 },
    "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
    "bannerSlots": [
           {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 1
    },
    {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 2
    }
    ], 
    "maxNumberOfAds": 3
}

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/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"
 							 },
    "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
    "bannerSlots": [
           {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 1
    },
    {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 2
    }
    ], 
    "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, 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",
    "productFilters": [
     	 ["category:Cupboard"],["dietary:Gluten-free"],["location:Westenbury"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
    "bannerSlots": [
           {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 1
    },
    {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 2
    }
    ], 
    "maxNumberOfAds": 3
}

Utilizar el parámetro bannerSlotIds (anterior)

Si ya está integrado, puede que solicite anuncios con bannerSlotIds en lugar de bannerSlots. Esta es una matriz de cadenas en la que especificaría las posiciones publicitarias para las que necesita anuncios. Hemos mejorado nuestra función para que pueda solicitar más de un anuncio para el mismo banner. Si le interesa, tendrá que mejorar su integración con el método bannerSlots descrito anteriormente.

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"
 							 },
    "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
    "bannerSlotIds": [
        "<SLOT_ID>","<SLOT_ID>"
    ], 
    "maxNumberOfAds": 3
}

La respuesta del anuncio de banner

Todas las respuestas siguen el mismo formato JSON. Si solicita anuncios de productos, la matriz ads se propagará como se muestra en el ejemplo que aparece a continuación. Los banners propagan la matriz banners , por lo que el contenido solo se devuelve para las posiciones de banner con anuncios.

{
    "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
        }
    ],
    "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": {},
            "position": 1
        },
				{
            "id": "banner_A0KA6mNmFs6sZPb_FvwWe5k6x6c3NzMzNjM3",
            "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
            "slotId": "<SLOT_ID>",
            "imageUrl": "https://cdn.flavedo.io/s/-oW-dfsgrerWkwOBUXOhvUdhHOySx-YQLreGZ1lw=",
            "linkUrl": "https://www.retailer.com/link",
            "altText": "Advertisement for pet food.",
            "text": "",
            "gtins": [
                "16309011",
                "57312011",
                "65250011"
            ],
            "expiry": "2021-05-17T01:49:17.75503253Z",
            "tags": {},
            "position": 2
        }
				],
    "products": [],
     "memoryToken":"85ykKVv-luDHMWLZx2d6xcPq6sF7CgkJCSJDb3VudGVyIjogIjIiLAoJCQkiQWRzIjogWwoJCQkJImRpc3BsYXlfV05VV0NwQkRKMUpKNm5wdVZSVExvOU40TUxzNE1UWTBOemt5TWc9PSIsCgkJCQkiZGlzcGxheV9MME5NUHRxNmdCcVFvREJOd3J0dE9UTGJoWk0xTVRFeU9UYzRPUT09IiwKCQkJCSJkaXNwbGF5XzlCcEpmdUpaWk9VXzgyaWpFM3VCczgxd3VVczRNekkwTnpVeE5nPT0iLAoJCQkJImRpc3BsYXlfcW1VU1p4TkpMQ0lqeWQwdTFJRDk0RmxVZ0pnNE16STBOelV4Tnc9PSIsCgkJCQkiZGlzcGxheV9oeHlFZktCUnRrNWlxMThMQzE1SDJHcEN3QjgxTVRFeU9UYzVNQT09IiwKCQkJCSJkaXNwbGF5X1NkcjFEcU5aUEFtcGh0Q1FIUndoYUxFT1B0RXhNamsxT1RJNE5BPT0iLAoJCQkJImRpc3BsYXlfeVlSai1qV2Ntc2ozNzhrel9PMm0yOVlwTjhJeE5EazNPRE00TXc9PSIsCgkJCQkiZGlzcGxheV9Xbm9NZGZuLTRTVmhxcF9xQzVvLWxoT0paNm8xTkRJeE1UUTROdz09IgoJCQldLAoJCQkiVFRMIjogMTYyODk4NTYwMAoJCX0="
}

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.

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": [
				{
            "id": "banner_XeemTeq59HapGSp4vccOYfBq_yvc3zMzNjM2",
            "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
            "slotId": "<SLOT_ID>",
            "sellerId": "43d-w4-2wcr4",
            "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": {},
            "position": 1
        },
				{
            "id": "banner_A0KA6mNmFs6sZPb_FvwWe5k6x6c3NzMzNjM3",
            "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
            "slotId": "<SLOT_ID>",
            "imageUrl": "https://cdn.flavedo.io/s/-oW-dfsgrerWkwOBUXOhvUdhHOySx-YQLreGZ1lw=",
            "linkUrl": "https://www.retailer.com/link",
            "altText": "Advertisement for pet food.",
            "text": "",
            "gtins": [
                "16309011",
                "57312011",
                "65250011"
            ],
            "expiry": "2021-05-17T01:49:17.75503253Z",
            "tags": {},
            "position": 2
        }
				],
    "products": [],
    "memoryToken":"85ykKVv-luDHMWLZx2d6xcPq6sF7CgkJCSJDb3VudGVyIjogIjIiLAoJCQkiQWRzIjogWwoJCQkJImRpc3BsYXlfV05VV0NwQkRKMUpKNm5wdVZSVExvOU40TUxzNE1UWTBOemt5TWc9PSIsCgkJCQkiZGlzcGxheV9MME5NUHRxNmdCcVFvREJOd3J0dE9UTGJoWk0xTVRFeU9UYzRPUT09IiwKCQkJCSJkaXNwbGF5XzlCcEpmdUpaWk9VXzgyaWpFM3VCczgxd3VVczRNekkwTnpVeE5nPT0iLAoJCQkJImRpc3BsYXlfcW1VU1p4TkpMQ0lqeWQwdTFJRDk0RmxVZ0pnNE16STBOelV4Tnc9PSIsCgkJCQkiZGlzcGxheV9oeHlFZktCUnRrNWlxMThMQzE1SDJHcEN3QjgxTVRFeU9UYzVNQT09IiwKCQkJCSJkaXNwbGF5X1NkcjFEcU5aUEFtcGh0Q1FIUndoYUxFT1B0RXhNamsxT1RJNE5BPT0iLAoJCQkJImRpc3BsYXlfeVlSai1qV2Ntc2ozNzhrel9PMm0yOVlwTjhJeE5EazNPRE00TXc9PSIsCgkJCQkiZGlzcGxheV9Xbm9NZGZuLTRTVmhxcF9xQzVvLWxoT0paNm8xTkRJeE1UUTROdz09IgoJCQldLAoJCQkiVFRMIjogMTYyODk4NTYwMAoJCX0="
}

📘

Si no está seguro de las cadenas de caracteres de esta sección, visite la página de referencia.

Etiquetas de seguimiento de terceros

Para los anuncios de banner, 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. Póngase en contacto con el administrador técnico de su cuenta si desea utilizar esta función.