Este documento proporciona una guía completa sobre cómo generar anuncios de productos en función de categorías específicas. Cada solicitud de API debe incluir detalles sobre el contexto, como:

• customerId
• sessionId
• Ubicación
• ID del catálogo
• productFilters
• El número máximo de anuncios que se van a mostrar

Requisitos

Debe completar los siguientes pasos antes de empezar a solicitar anuncios de productos para su ubicación en las búsquedas.

Añadir catálogos de productos

Asegúrese de que los productos se hayan añadido a los catálogos y se hayan sincronizado con la plataforma Epsilon Retail Media.

Crear una campaña y configurar categorías

Asegúrese de haber creado una campaña y configurado categorías. Para obtener más información, consulte el Paso 4: Configurar criterios de segmentación.

Obtener las claves de API y la URL base

1. Debe tener una clave de API válida. Para obtener las claves de API, haga lo siguiente:

   1. Inicie sesión en la cuenta de equipo de Epsilon Retail Media.

   2. Navegue hasta la parte superior derecha de la página y haga clic en el menú desplegable.

   3. Seleccione Configuración de integración en el menú desplegable.

      

   4. Haga clic en la pestaña Clave API . Su clave API secreta estará inicialmente oculta. Para verla, haga clic en el botón Mostrar . Una vez sea visible, copie su clave API secreta. Utilice esta clave para realizar llamadas a la API.

2. Debe tener la URL base del punto de conexión de la API. Por ejemplo, https://staging-test.citrusad.com/v1/ads/generate HTTP/1.1. Consulte a su gestor técnico de cuentas para conocer la URL base.

Generar anuncios para ubicaciones de categoría

Siga los siguientes pasos para generar anuncios de productos.

Solicitud HTTP

Punto de conexión: /v1/ads/generate

Método: POST

Encabezados:

• accept: application/json
• content-type: application/json
• Authorization: Basic <API_KEY>

Solicitar parámetros

El cuerpo de la solicitud debe ser un objeto JSON que contenga los siguientes campos. Para especificar ubicaciones de categoría, productFilters debe incluirse en el cuerpo de la solicitud.

Ejemplo de solicitud

La solicitud JSON se utiliza para especificar una ubicación de categoría para los anuncios relacionados con la categoría «Despensa/Aperitivos». Incluye la identificación de cliente, la identificación de sesión, la identificación de catálogo y las opciones de filtrado y establece el número máximo de anuncios en 3.

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",
    "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
    "placement": "category",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 ["category:Cupboard/Snacks"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}

Generar anuncios para ubicaciones de categoría de venta cruzada

Las ubicaciones de categoría de venta cruzada son similares a las ubicaciones de categoría normales, pero se utilizan específicamente para segmentar los anuncios de productos de venta cruzada. En una situación de venta cruzada, su objetivo es recomendar productos complementarios en función de la categoría actual que está explorando el usuario.

Debe especificar la categoría exacta para la que desea generar anuncios. Esta categoría suele ser la que se muestra en la página actual por la que está navegando el usuario.

Ejemplo de solicitud

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",
    "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 ["category:Cupboard/Snacks"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}

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

Si su objetivo es combinar anuncios orgánicos (anuncios relevantes para la categoría que se está viendo) y anuncios de venta cruzada (anuncios para categorías o productos relacionados) en una sola ubicación de anuncio, tendrá que gestionar esta integración por su cuenta. Esto implica escribir la lógica para fusionar y mostrar ambos tipos de anuncios juntos.

Buenas prácticas:

• Los anuncios orgánicos en primer lugar: muestre primero los anuncios relevantes para la categoría actual (anuncios orgánicos).
• Anuncios de venta cruzada en segundo lugar: a continuación, muestre anuncios para categorías o productos relacionados (anuncios de venta cruzada) después de los anuncios orgánicos.

Buenas prácticas para la segmentación de anuncios basada en categorías

Cuando los usuarios navegan por diferentes categorías, es crucial actualizar la llamada a la API para que refleje la categoría actual que se está viendo. Esto garantiza que los anuncios mostrados sigan siendo relevantes para el contexto de navegación del usuario.

Se recomienda enviar la categoría más específica (nivel más bajo) de su solicitud de anuncio a la plataforma Epsilon Retail Media. La segmentación por el nivel de categoría más profundo proporciona anuncios más relevantes y segmentados con mayor precisión para el usuario.

Escenario de ejemplo

Un usuario comienza a navegar en una categoría general y luego navega a una subcategoría más específica.

Llamada API inicial

Cuando el usuario navega por la categoría «Hogar»:

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",
    "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
    "placement": "category",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 ["category:Home"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}

Llamada API actualizada

Cuando el usuario navega a la subcategoría «Hogar > Muebles»:

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",
    "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
    "placement": "category",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 ["category:Home/Furniture"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}

Llamada API final

Cuando el usuario siga navegando a «Hogar > Muebles > Sillas»:

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",
    "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
    "placement": "category",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 ["category:Home/Furniture/Chairs"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}

Al actualizar la llamada a la API para que refleje la categoría más específica que está explorando el usuario, se asegura de que los anuncios publicados sean muy relevantes. En lugar de especificar una solicitud encadenada en varios niveles de categoría (L1 + L2 + L3), se recomienda especificar el nivel de categoría más profundo (L3).

Siguientes pasos

• Generar anuncios de productos mediante la ubicación en la búsqueda
• Optimizar la orientación de anuncios