API para socios
Guías

Optimizar la orientación de anuncios

En este documento se describen las mejores prácticas para generar anuncios de productos en las ubicaciones de búsqueda, categoría y amplia visualización (inicio, pago, especiales, etc.). La implantación de estas estrategias hace que sus anuncios sean más relevantes y específicos, lo que mejora la fidelización y la satisfacción del usuario. Las mejoras incluyen paginación, búsquedas filtradas y filtrado basado en la localización geográfica para un enfoque publicitario personalizado.

Para generar anuncios de productos mediante ubicaciones de búsqueda y categorías, consulte los siguientes temas:

Solicitudes de paginación

La paginación es una técnica utilizada para gestionar grandes conjuntos de datos dividiéndolos en páginas o segmentos discretos. En el contexto de la generación de anuncios de productos, la paginación garantiza que los usuarios no se vean abrumados por demasiados anuncios a la vez y que los anuncios vistos anteriormente no se publiquen de forma redundante.

Cuando genera anuncios de productos, la respuesta incluye un memoryToken. Este token ayuda a realizar un seguimiento de los anuncios que ya se han publicado. Al incluir esto memoryToken en las solicitudes de anuncios posteriores, puede asegurarse de que los anuncios publicados anteriormente se excluyan de la nueva respuesta al anuncio, lo que mejora la experiencia del usuario al presentar anuncios nuevos y relevantes.

  • Solicitud inicial: genere anuncios de productos y reciba memoryToken en la respuesta.
  • Solicitudes posteriores: incluya memoryToken en solicitudes de anuncios posteriores para excluir los anuncios mostrados anteriormente de la respuesta.

Para obtener más información, consulte Paginación.

Solicitar parámetros

El cuerpo de la solicitud debe ser un objeto JSON que contenga los siguientes campos:

objetotipoDescripción
customerIdcadena, obligatorioIdentificador único para el cliente. Lo proporciona su distribuidor.
sessionIdcadena, obligatorioIdentificador único de la sesión. Es necesario para la atribución y lo proporciona el minorista.
Ubicacióncadena, obligatorioContexto en el que se muestra el anuncio (por ejemplo, "search").
ID del catálogocadena, obligatorioIdentificador único del catálogo de productos desde el que se filtran los productos. Puede obtener el catalogID en la interfaz de usuario de Epsilon Retail Media o en la tienda.
maxNumberOfAdsentero, obligatorioNúmero máximo de anuncios que se van a mostrar.
Término de búsquedacadena, necesario para ubicaciones de búsquedaTérmino que se buscará dentro del catálogo.
memoryTokencadena, obligatorioToken para excluir anuncios mostrados anteriormente.
opcionesobjeto, opcionalOpciones adicionales, como los modos de filtrado AndOr. Si se especifican, el sistema utilizará las condiciones "Y" y "O" para afinar los resultados de la búsqueda.

Ejemplo de solicitud

En el siguiente ejemplo, la solicitud de anuncio inicial es para la ubicación de búsqueda con el término «chocolate». El memoryToken se incluye para garantizar que los anuncios mostrados anteriormente para el mismo término de búsqueda y contexto se excluyan de la respuesta. El objeto options especifica el modo de filtrado y maxNumberOfAds establece el límite del número de anuncios que se generarán en la respuesta.

Al aprovechar la paginación y los tokens de memoria, puede ofrecer una experiencia publicitaria más dinámica y atractiva para sus usuarios, evitando la redundancia y mejorando la relevancia.

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    
}

Ejemplo de respuesta

Todas las respuestas de anuncios de productos siguen un formato JSON estándar. Los anuncios de productos se devuelven en la matriz de anuncios.

  • id: la identificación de anuncio que se utiliza en los informes de impresiones y clics.
  • gtin: el número de artículo comercial mundial del producto.
  • discount: detalles sobre los descuentos aplicables al anuncio.
    • amount: importe del descuento.
    • minPrice: precio mínimo para el descuento.
    • maxPerCustomer: número máximo de artículos que un cliente puede comprar con el descuento.
  • expiry: la fecha y hora de caducidad del anuncio.
  • position: la posición del anuncio en la carga útil de respuesta. Siempre debe leer y respetar el campo de posición para asegurarse de que las ubicaciones de tenencia fija aparezcan correctamente.
{
    "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="
}

Al incorporar vendedores del mercado, puede sellerId campo puede aparecer en la respuesta del anuncio. Este campo solo se incluye si el equipo propietario de la campaña ha configurado una identificación de vendedor en la interfaz de usuario de Epsilon Retail Media.

Ejemplo con identificación de vendedor

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

Búsquedas filtradas

Cuando un cliente aplica filtros a su búsqueda, puede mejorar el contexto de su consulta mediante productFilters. Esto le permite segmentar los anuncios con mayor precisión en función de categorías o atributos específicos. A continuación, ofrecemos un ejemplo de cómo filtrar por la categoría «Despensa» y la restricción dietética «Sin gluten». Esta metodología se puede adaptar a cualquier categoría o ubicación de coincidencia amplia.

Solicitar parámetros

El cuerpo de la solicitud debe ser un objeto JSON que contenga los siguientes campos:

objetotipoDescripción
customerIdcadena, obligatorioIdentificador único para el cliente. Lo proporciona su distribuidor.
sessionIdcadena, obligatorioIdentificador único de la sesión. Es necesario para la atribución y lo proporciona el minorista.
Ubicacióncadena, obligatorioContexto en el que se muestra el anuncio (por ejemplo, "search").
ID del catálogocadena, obligatorioIdentificador único del catálogo de productos desde el que se filtran los productos. Puede obtener el catalogID en la interfaz de usuario de Epsilon Retail Media o en la tienda.
maxNumberOfAdsentero, obligatorioNúmero máximo de anuncios que se van a mostrar.
Término de búsquedacadena, necesario para ubicaciones de búsquedaTérmino que se buscará dentro del catálogo.
productFiltersmatriz, requeridaUna matriz que contiene los filtros de categoría.
opcionesobjeto, opcionalOpciones adicionales, como los modos de filtrado AndOr. Si se especifican, el sistema utilizará las condiciones "Y" y "O" para afinar los resultados de la búsqueda.

Ejemplo de solicitud

La solicitud de ejemplo utiliza el método HTTP POST para enviar un objeto JSON al endpoint especificado. La productFilters matriz especifica que la búsqueda debe filtrarse por la categoría «Despensa» y la restricción dietética «Sin gluten». El objeto de opciones establece filterMode en AndOr, lo que permite una combinación flexible de filtros. El maxNumberOfAds campo limita el número de anuncios mostrados a tres.

Siguiendo esta estructura, puede crear campañas publicitarias segmentadas que sean más relevantes para los criterios de búsqueda del cliente, mejorando así la experiencia general del usuario.

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
}

Filtrar por localización geográfica

Cuando sincronice filtros de localización geográfica en su catálogo, puede ampliar el contexto para incluir la ubicación de la tienda del cliente en productFilters. Esta función le permite segmentar los anuncios en función de la ubicación específica de la tienda, lo que mejora la relevancia de los anuncios que se muestran al cliente.

Solicitar parámetros

El cuerpo de la solicitud debe ser un objeto JSON que contenga los siguientes campos:

objetotipoDescripción
customerIdcadena, obligatorioIdentificador único para el cliente. Lo proporciona su distribuidor.
sessionIdcadena, obligatorioIdentificador único de la sesión. Es necesario para la atribución y lo proporciona el minorista.
Ubicacióncadena, obligatorioContexto en el que se muestra el anuncio (por ejemplo, "search").
ID del catálogocadena, obligatorioIdentificador único del catálogo de productos desde el que se filtran los productos. Puede obtener el catalogID en la interfaz de usuario de Epsilon Retail Media o en la tienda.
maxNumberOfAdsentero, obligatorioNúmero máximo de anuncios que se van a mostrar.
Término de búsquedacadena, necesario para ubicaciones de búsquedaTérmino que se buscará dentro del catálogo.
productFiltersmatriz, requeridaUna matriz que contiene los filtros de categoría.
opcionesobjeto, opcionalOpciones adicionales, como los modos de filtrado AndOr. Si se especifican, el sistema utilizará las condiciones "Y" y "O" para afinar los resultados de la búsqueda.

Ejemplo de solicitud

La solicitud de ejemplo utiliza el método HTTP POST para enviar un objeto JSON al endpoint especificado.

  • La productFilters matriz especifica que la búsqueda se debe filtrar por:
    • Categoría: «Despensa»
    • Restricción dietética: «Sin gluten»
    • Ubicación: «Chamberí»
  • El objeto de opciones establece filterMode en AndOr, lo que permite una combinación flexible de filtros.
  • La maxNumberOfAds campo limita el número de anuncios mostrados a tres.

Siguiendo esta estructura, puede crear campañas publicitarias segmentadas que sean más relevantes para los criterios de búsqueda del cliente, mejorando así la experiencia general del usuario.

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
}

Actualizado hace 12 meses