> For the complete documentation index, see [llms.txt](https://help.citrusad.com/retail-media-interface/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.citrusad.com/retail-media-interface/integration/es/feature-integrations/suggested-keywords.md).
# Palabras clave sugeridas
Las **palabras clave sugeridas** vinculan los **términos de búsqueda** con los **códigos de producto** de tu catálogo. Cuando los anunciantes crean campañas, esos términos aparecen durante la **Segmentación** (selección de palabras clave de búsqueda) para los productos que añaden. Los anunciantes pueden elegir entre sugerencias en lugar de escribir solo palabras clave personalizadas, lo que mejora la alineación con la forma en que tu sitio indexa las búsquedas y cómo quieres que las campañas mapeen los SKU a las consultas.
**Las palabras clave sugeridas se pueden proporcionar de dos formas:**
1. **Epsilon Palabras clave generadas por IA** — Epsilon genera, clasifica y carga pares de producto-palabra clave en tu nombre. **No estás obligado** a mantener un archivo de palabras clave independiente para esas sugerencias cuando esta vía es tu única fuente. La generación utiliza el contexto del producto y del catálogo, el comportamiento de búsqueda de los compradores y señales alineadas con tus **reglas de negocio de retail** (por ejemplo, la conquista de marcas y otras restricciones del programa).
2. **Feed TSV gestionado por el retailer** — Sincronizas un archivo que mapea cada `product_code` a uno o más `search_term` valores, con rango y tipo opcionales. Tú gestionas las palabras clave sugeridas por producto.
Los retailers pueden elegir usar **Epsilon solo palabras clave generadas**, **solo tu archivo** o **ambos** (por ejemplo, sugerencias de IA **superpuestas** en una lista existente, o un **reemplazo** coordinado durante el despliegue para que las aprobaciones existentes se gestionen deliberadamente).
Si Epsilon está suministrando **palabras clave sugeridas por IA** para tu programa y **no** necesitas un feed TSV de retailer, comienza con [**Paso 3: Active las palabras clave sugeridas por IA (beta)**](#step-3-activate-ai-suggested-keywords-beta)**. Utiliza**[**Paso 2: Cree el archivo TSV**](#step-2-optional-build-the-tsv-file-retailer-supplied-path) solo cuando mantengas o complementes palabras clave mediante un archivo.
### ¿Por qué usar palabras clave sugeridas?
* Orientar a los anunciantes hacia términos de búsqueda de alta intención y precisos para el producto
* Mostrar términos en los que los anunciantes podrían no pensar sin orientación
* Aumentar la competencia en palabras clave valiosas mientras se mantiene dentro de las reglas del programa
* Reducir el trabajo manual con archivos cuando la generación por IA está activada
**Esta guía cubre**
* Requisitos previos y flujo de extremo a extremo
* Autenticación de API para flujos de lectura/validación
* Activación paso a paso de IA (beta) e implementación opcional de TSV
* Pruebas en sandbox, lista de verificación para el lanzamiento, resolución de problemas
### Reglas de publicación
Cuando los anunciantes añaden palabras clave **sugeridas** a una campaña, **solo los productos vinculados a esa palabra clave** son elegibles para mostrarse en términos de búsqueda coincidentes de los clientes.
La interfaz de usuario muestra qué productos se mapean a qué palabras clave sugeridas:
Los términos de búsqueda **personalizados** elegidos por el anunciante normalmente se aplican a todos los productos de la campaña según las reglas de ubicación; las selecciones **sugeridas** restringen la elegibilidad utilizando el mapeo \*\*retailer / Epsilon.
## Requisitos previos
Utiliza esta lista de comprobación antes de empezar.
* [ ] **Retailer** incorporado (o en proceso) con Epsilon Retail Media, incluida la sincronización del catálogo.
* [ ] **Acceso a sandbox** a la interfaz de usuario de campañas y a las API donde validarás las palabras clave (cuando esté disponible para tu programa).
* [ ] **Para la entrega de TSV:** Bucket de GCS (o ruta) **aprovisionado por Epsilon**, y credenciales que tu equipo pueda usar para cargar objetos (método confirmado con Epsilon—a menudo clave de cuenta de servicio o acceso federado). Ten en cuenta que si solo estás delimitando el alcance, esto se gestiona como parte del proceso de activación si vas a suministrar palabras clave.
* [ ] **Contacto técnico** que pueda cargar archivos, ejecutar comprobaciones de API y coordinarse con Epsilon sobre programas de ingesta y transiciones.
* [ ] **Conocimiento del lanzamiento:** la elegibilidad del producto por palabra clave para sugerencias requiere la plataforma (consulta las Reglas de publicación anteriores).
***
## Resumen del flujo de integración
1. Confirmas con Epsilon cómo se suministrarán las palabras clave:Epsilon generadas\*\*, **archivo TSV** o **ambos**.
2. Si vas a proporcionar un archivo, cárgalo en el bucket de GCS aprovisionado por Epsilon.
3. Epsilon activa la función y (para archivos) ingiere tu archivo. Para palabras clave de **IA**, Epsilon se alinea en cuanto a reglas, superposición opcional frente a reemplazo y validación en staging.
4. Los datos llegan como **palabras clave sugeridas** a la plataforma.
5. **Verificas** en tu sandbox directamente en la interfaz de usuario antes del lanzamiento para tus anunciantes.
6. Te **pones en marcha** en producción y comunicas a los equipos de anunciantes que las palabras clave sugeridas están disponibles.
***
## Guía de implementación paso a paso
### Paso 1: Confirma tu modelo de suministro con Epsilon
Propósito\
Evita crear una canalización de archivos si el enfoque de **solo IA** satisface tus necesidades, o evita duplicar el trabajo si Epsilon superpondrá/reemplazará listas por ti.
**Lo que debes hacer**
* Decide: **solo IA**, **solo TSV** o **ambos**.
* Confirma la **superposición** frente al **reemplazo** para cualquier dato de palabras clave sugeridas existente.
* Confirma qué **ubicaciones** existen (`ORGANIC` solo frente a también `CROSS_SELL` / `SUBSTITUTE`).
***
### Paso 2: Activa las palabras clave sugeridas por IA
**Propósito**\
Consigue palabras clave generadas por Epsilony filtradas por reglas en la plataforma **sin** mantener un TSV.
**Lo que debes hacer**
1. Ponte en contacto con Epsilon\*\* — Proporciona tus **reglas de negocio** específicas (por ejemplo, la conquista de marcas) y cómo deben relacionarse los nuevos datos con las listas existentes si ya sincronizas palabras clave sugeridas (**superposición** frente a **reemplazo**).
2. Prueba en sandbox\*\* — Trabaja con Epsilon para cargar o revisar palabras clave en **staging/sandbox**. Realiza una simulación de **Segmentación** en la interfaz de usuario de la campaña: elige productos y confirma que las frases sugeridas se ven correctas.
3. Producción\*\* — Tras la aprobación final, Epsilon habilita la producción. **Tú** comunicas a los equipos de los anunciantes que las palabras clave sugeridas están activas (la interfaz de usuario las mostrará una vez habilitadas).
**Cómo funcionan las sugerencias de palabras clave por IA**
1. **Comprender el producto**: El modelado utiliza la intención del producto, el contexto del minorista y el idioma.
2. **Generar palabras clave**: Las palabras clave candidatas se producen a partir de esa comprensión.
3. **Clasificar**: Las palabras clave se seleccionan mediante datos de anuncios y búsquedas para que se respeten las reglas del programa (por ejemplo, el brand conquesting o las políticas específicas del minorista, como la segmentación según los ingredientes de un producto).
4. **Cargar para la interfaz de usuario**: Los pares producto-palabra clave se almacenan en el mismo sistema que utiliza el flujo de **palabras clave sugeridas** en la configuración de la campaña.
**Gobernanza**
* El comportamiento de aprobación (**revisión automática frente a manual del minorista**) depende de la **configuración del programa** acordada con Epsilon.
* Si tienes **poco historial de consultas de anuncios**, es posible que se te pida que compartas una **pequeña muestra de solicitudes de búsqueda orgánica en el sitio** (por ejemplo, de unos **siete días**) para que la generación se adapte al lenguaje real de los compradores.
* Los **catálogos muy grandes** pueden delimitar la generación a productos con **actividad publicitaria reciente** (por ejemplo, de los **últimos 90 días**) en lugar de cada SKU; confírmalo con Epsilon.
* Las **palabras clave sugeridas generadas por IA (beta)** se centran actualmente en casos de uso de búsqueda **orgánica**; el soporte para tipos de ubicación adicionales podría ampliarse.
**Validación**
* Las palabras clave sugeridas aparecen en **Segmentación** del entorno de pruebas para los productos dentro del alcance.
* El comportamiento de aprobación (revisión automática frente a manual) coincide con la configuración del programa.
**Errores comunes**
| Error | Solución |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Las palabras clave no se ajustan a la marca o a las políticas | Refina las reglas de negocio con Epsilon y vuelve a ejecutar la revisión en el entorno de pruebas |
| Pocas o ninguna sugerencia para catálogos grandes | Confirma si la generación está delimitada a los SKU con publicidad reciente |
***
### (Opcional para el Paso 2): Crea tu archivo TSV (ruta proporcionada por el minorista)
**Propósito**\
Suministrar filas autoritativas de **product\_code → search\_term** (y rango/tipo opcionales).
**Lo que debes hacer**
* Genera un archivo separado por tabulaciones con las vinculaciones entre productos y palabras clave.
* Utiliza la codificación **UTF-8** y saltos de línea **LF**.
* Incluye una fila de encabezado que coincida con los nombres de campo que utiliza la especificación de tu feed; como mínimo: `product_code`, `search_term`, `search_term_type`. Consulta [Modelos de datos y definiciones de campos](#data-models--field-definitions).
* Mantén alrededor de **\~20 palabras clave sugeridas por producto** para facilitar la usabilidad.
* Repite `product_code` en varias líneas para múltiples términos; utiliza `**search_term_type`\*\* cuando tengas varios tipos de ubicaciones.
* Valida el archivo y luego entrégalo en el bucket de GCS que Epsilon asigne.
**Nota:** Cuando sincronizas un feed de un minorista, Epsilon Retail Media asigna un **bucket de GCS** para las entregas. Las operaciones de la plataforma deben finalizar la configuración; prevé un tiempo de demora para la activación.
**Archivo de ejemplo (fragmento)**
```
product_code search_term search_term_rank search_term_type
abc123 cereal 1 ORGANIC
abc123 cereals 2 ORGANIC
12345 milk 1 CROSS_SELL
```
Validación
* Abre en un editor de texto: campos separados por **tabulación**, sin saltos de línea aislados que solo contengan CR.
* Haz una comprobación aleatoria de que varios valores de `product_code` existan en tu feed de **catálogo**.
**Errores comunes**
| Error | Solución |
| ------------------------------------- | ---------------------------------------------------------------------- |
| Comas de CSV en lugar de tabulaciones | Vuelve a exportar como TSV |
| IDs de producto incorrectos | Alinea con `gtin` / `item` utilizado en la sincronización del catálogo |
| Demasiadas líneas por SKU | Recorta a los términos de mayor valor |
***
### Paso 3: Verifica las sugerencias en la interfaz de usuario
**Propósito**\
Detecta problemas de mapeo de último momento antes de la producción.
**Lo que debes hacer**
* En el **entorno de pruebas**, crea o edita una campaña, selecciona las ubicaciones que admitan palabras clave sugeridas, añade productos, abre **Segmentación** / selección de palabras clave.
* Confirma las frases sugeridas por producto y que el comportamiento **personalizado** frente a **sugerido** coincida con tus expectativas (consulta \*\*Reglas de publicación en **Descripción general**).
* Confirma que las selecciones **sugeridas** restrinjan los productos elegibles a aquellos vinculados en tu feed o canal de IA.
**Validación**
* En tu interfaz de usuario del entorno de pruebas: las palabras clave sugeridas aparecen para los productos vinculados a palabras clave en tu archivo o canal de IA.
* Las sugerencias se alinean con las expectativas de la ubicación y el catálogo.
**Errores comunes**
| Error | Solución |
| ------------------------------------------ | --------------------------------------------------------------------------- |
| Sugerencias solo en un catálogo | Completa los demás catálogos o ajusta el alcance del catálogo de la campaña |
| Se muestra un tipo de ubicación incorrecto | TAM revisa la ubicación ↔ `search_term_type` configuración |
***
## Modelos de datos y definiciones de campos
### TSV (archivo del minorista)
| Campo | Tipo | Requerido | Descripción | Valores aceptados |
| ------------------ | ------- | --------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| `product_code` | string | Sí | Identificador de producto del retailer; igual que el catálogo `gtin` / `item` cuando corresponda | No vacío; debe existir en el catálogo sincronizado |
| `search_term` | string | Sí | Palabra clave o frase sugerida para el SKU | Texto UTF-8; evite caracteres de control |
| `search_term_rank` | integer | No | Relevancia relativa; **1** es la más alta | Enteros positivos; menor = mayor prioridad |
| `search_term_type` | string | No | Mapea filas a tipos de \*\*placement | `ORGANIC`, `CROSS_SELL`, `SUBSTITUTE`; el valor predeterminado se trata como `ORGANIC` si se omite |
| (finales de línea) | — | — | Formato de archivo | LF\*\*; codificación de archivo \*\*UTF-8 |
### Tipos de ubicación y `search_term_type`
`search_term_type` se alinea con los tipos de ubicación: **ORGANIC**, **CROSS\_SELL** y **SUBSTITUTE**.
La mayoría de los programas de retailers utilizan una única ubicación de **búsqueda orgánica** para los anuncios de resultados de búsqueda estándar. **CROSS\_SELL** y **SUBSTITUTE** son **ubicaciones independientes** en la página de búsqueda (o inventario relacionado) con una intención de entrega diferente: no son solo columnas adicionales en la misma subasta orgánica. Su Technical Account Manager le confirmará qué ubicaciones existen para su espacio de nombres.
**En qué se diferencian los tipos de ubicación**
* **Orgánico** — Anuncios que coinciden con la intención de búsqueda del comprador para el producto (por ejemplo, un producto de cola para "cola").
* **Venta cruzada** — Intención complementaria (por ejemplo, pizza para "cola").
* **Sustituto** — Intención de producto similar (por ejemplo, otra variante de cola para "cola").
Puede sincronizar **un feed por tipo de ubicación** o **combinar tipos en un solo archivo** (repetir `product_code` con diferente `search_term_type`). Su Technical Account Manager configura las ubicaciones para que el tipo de sugerencia correcto aparezca por superficie. Las palabras clave sugeridas se pueden **mostrar u ocultar por ubicación**.
Tipos combinados para un producto:
| product\_code | search\_term | search\_term\_rank | search\_term\_type |
| ------------- | ------------ | ------------------ | ------------------ |
| 12345 | cookies | 1 | ORGANIC |
| 12345 | cookie | 2 | ORGANIC |
| 12345 | milk | 1 | CROSS\_SELL |
**Nota:** La mayoría de los programas solo utilizan ubicaciones de búsqueda **orgánica**. `CROSS_SELL` y `SUBSTITUTE` corresponden a **ubicaciones adicionales**, no a "columnas extra" en el mismo espacio orgánico; confirme con su Technical Account Manager con qué ubicaciones opera.
### Múltiples catálogos
Implemente las palabras clave sugeridas en **todos** los catálogos de su espacio de nombres cuando sea posible (ya sea desde su feed, generación por IA o ambos). Esto reduce la confusión de marca cuando un catálogo tiene sugerencias y otros no.
Para campañas de catálogos múltiples, si solo un catálogo tiene datos, las campañas que dependen de las selecciones sugeridas solo funcionarán por completo en ese catálogo.
\##
***
## Pruebas, Sandbox y Salida a producción
**Sandbox / entorno de prueba**
* Valide las sugerencias de la IU en el paso de **Segmentación** de la campaña.
**Casos de prueba de ejemplo**
| Prueba | Pasos | Resultado esperado |
| -------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| Sugerencias de la IU visibles | Añada productos en la campaña del sandbox; abra **Segmentación** | Las palabras clave sugeridas aparecen por producto |
| Regla de entrega | Seleccione una palabra clave sugerida vinculada a un subconjunto de productos | Solo los productos vinculados son elegibles para ese término |
| Cobertura de múltiples catálogos | Repita la comprobación de la IU en todos los catálogos del espacio de nombres | Sugerencias presentes en todos los catálogos con datos (o alcance documentado) |
Lista de verificación para la salida a producción
* [ ] TSV ingerido sin errores (si usa la ruta del archivo) o pipeline de IA aprobado (si usa la versión beta)
* [ ] Palabras clave sugeridas visibles en la IU del sandbox para productos representativos
* [ ] Los espacios de nombres de catálogos múltiples tienen cobertura en todos los catálogos (o alcance documentado)
* [ ] Comunicación con el anunciante enviada antes o durante la habilitación en producción
* [ ] La API de socios devuelve las filas esperadas en producción (comprobación puntual)
***
## Solución de problemas y preguntas frecuentes
**Problema:** Las sugerencias nunca aparecen en la IU.\
**Causa probable:** Ingesta no habilitada, catálogo incorrecto o ubicación no configurada.\
Solución:\*\* Confirme con Epsilon que la ingestión de GCS o el pipeline de IA estén activos; verifica el mapeo de ubicaciones para `search_term_type`.
**¿Podemos usar un TSV para varios tipos de ubicación?**\
Sí. Repite `product_code` en varias líneas con diferentes `search_term_type` valores. Tu Account Manager Técnico configura qué tipos se muestran por ubicación.
**¿Qué pasa si tenemos varios catálogos en un mismo namespace?**\
Implementa las palabras clave sugeridas en todos los catálogos cuando sea posible. Las campañas que dependen de selecciones sugeridas solo funcionan totalmente en catálogos que tengan datos.
**Al contactar al soporte, incluye:**
* Namespace e ID del catálogo
* Muestra `product_code` y esperado `search_term`
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://help.citrusad.com/retail-media-interface/integration/es/feature-integrations/suggested-keywords.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.