> 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/pt-br/feature-integrations/suggested-keywords.md).
# Palavras-chave sugeridas
**Palavras-chave sugeridas** vinculam **termos de busca** a **códigos de produto** no seu catálogo. Quando os anunciantes criam campanhas, esses termos aparecem durante o **Direcionamento** (seleção de palavras-chave de busca) para os produtos que eles adicionam. Os anunciantes podem escolher a partir de sugestões em vez de digitar apenas palavras-chave personalizadas, o que melhora o alinhamento com a forma como seu site indexa a busca e como você deseja que as campanhas mapeiem SKUs para consultas.
**As palavras-chave sugeridas podem ser fornecidas de duas maneiras:**
1. **Epsilon Palavras-chave geradas por IA** — Epsilon gera, classifica e carrega pares de produto–palavra-chave em seu nome. Você **não precisa** manter um arquivo de palavras-chave separado para essas sugestões quando esse caminho for sua única fonte. A geração usa o contexto do produto e do catálogo, o comportamento de busca do comprador e sinais alinhados às suas **regras de negócios do varejista** (por exemplo, conquista de marca e outras restrições do programa).
2. **Feed TSV gerenciado pelo varejista** — Você sincroniza um arquivo que mapeia cada `product_code` a um ou mais `search_term` valores, com classificação e tipo opcionais. Você gerencia as palavras-chave sugeridas por produto.
Os varejistas podem optar por usar **Epsilon apenas palavras-chave geradas**, **apenas seu arquivo**, ou **ambos** (por exemplo, sugestões de IA **sobrepostas** a uma lista existente ou uma **substituição** coordenada durante o lançamento para que as aprovações existentes sejam tratadas deliberadamente).
Se Epsilon estiver fornecendo **palavras-chave sugeridas por IA** para seu programa e você **não** precisar de um feed TSV do varejista, comece com o [**Passo 3: Ativar palavras-chave sugeridas por IA (beta)**](#step-3-activate-ai-suggested-keywords-beta)**. Use o**[**Passo 2: Criar o arquivo TSV**](#step-2-optional-build-the-tsv-file-retailer-supplied-path) apenas quando você mantiver ou complementar palavras-chave via arquivo.
### Por que usar palavras-chave sugeridas?
* Orientar os anunciantes para termos de busca de alta intenção e precisos para o produto
* Exibir termos em que os anunciantes podem não pensar sem orientação
* Aumentar a concorrência em palavras-chave valiosas enquanto permanece dentro das regras do programa
* Reduzir o trabalho manual com arquivos quando a geração por IA estiver ativada
**Este guia abrange**
* Pré-requisitos e fluxo de ponta a ponta
* Autenticação de API para fluxos de leitura/validação
* Ativação da IA passo a passo (beta) e implementação opcional de TSV
* Testes em sandbox, lista de verificação para entrada em operação, solução de problemas
### Regras de veiculação
Quando os anunciantes adicionam palavras-chave **sugeridas** a uma campanha, **apenas os produtos vinculados a essa palavra-chave** estão qualificados para serem veiculados em termos de busca correspondentes dos clientes.
A interface do usuário mostra quais produtos se mapeiam para quais palavras-chave sugeridas:
Termos de busca **personalizados** escolhidos pelo anunciante geralmente se aplicam aos produtos da campanha de acordo com as regras de posicionamento; seleções **sugeridas** restrigem a elegibilidade usando o mapeamento \*\*do varejista / Epsilon.
## Pré-requisitos
Use esta lista de verificação antes de começar.
* [ ] **Varejista** integrado (ou em andamento) com Epsilon Retail Media, incluindo a sincronização de catálogo.
* [ ] **Acesso ao sandbox** para a interface do usuário e APIs da campanha onde você validará as palavras-chave (quando disponível para seu programa).
* [ ] **Para entrega em TSV:** Bucket do GCS (ou caminho) **provisionado por Epsilon**, e credenciais que sua equipe pode usar para carregar objetos (método confirmado com Epsilon—frequentemente chave de conta de serviço ou acesso federado). Note que, se você estiver apenas definindo o escopo, isso será tratado como parte do processo de ativação, caso esteja fornecendo palavras-chave.
* [ ] **Contato técnico** que possa carregar arquivos, executar verificações de API e coordenar com Epsilon sobre cronogramas de ingestão e transições.
* [ ] **Conscientização de lançamento:** a elegibilidade de produtos por palavra-chave para sugestões exige a plataforma (consulte as Regras de exibição acima).
***
## Visão Geral do Fluxo de Integração
1. Você confirma com Epsilon como as palavras-chave serão fornecidas: \*\*geradas porEpsilon , **arquivo TSV**, ou **ambos**.
2. Se você estiver fornecendo um arquivo, carregue-o no bucket do GCS provisionado por Epsilon.
3. Epsilon ativa a funcionalidade e (para arquivos) ingere seu arquivo. Para palavras-chave de **IA**, Epsilon alinha as regras, sobreposição opcional vs substituição e validação em ambiente de staging.
4. Os dados chegam como **palavras-chave sugeridas** na plataforma.
5. Você **verifica** em seu sandbox diretamente na UI antes do lançamento para seus anunciantes.
6. Você **entra em operação** na produção e informa às equipes de anunciantes que as palavras-chave sugeridas estão disponíveis.
***
## Guia de Implementação Passo a Passo
### Passo 1: Confirme seu modelo de fornecimento com Epsilon
Objetivo\
Evite criar um pipeline de arquivos se **apenas IA** atender às suas necessidades, ou evite duplicar trabalho se Epsilon for sobrepor/substituir listas para você.
**O que você precisa fazer**
* Decida: **Apenas IA**, **Apenas TSV**, ou **Ambos**.
* Confirme **sobreposição** vs **substituição** para quaisquer dados de palavras-chave sugeridas existentes.
* Confirme quais **posicionamentos** existem (`ORGANIC` apenas vs também `CROSS_SELL` / `SUBSTITUTE`).
***
### Passo 2: Ativar palavras-chave sugeridas por IA
**Objetivo**\
Obtenha palavras-chave geradas por Epsilone filtradas por regras na plataforma **sem** manter um TSV.
**O que você precisa fazer**
1. Engaje\*\* com a Epsilon— Forneça suas **regras de negócios** específicas (por exemplo, conquista de marca) e como os novos dados devem se relacionar com as listas existentes se você já sincroniza palavras-chave sugeridas (**sobreposição** vs **substituição**).
2. Teste no sandbox\*\* — Trabalhe com Epsilon para carregar ou revisar palavras-chave em **staging/sandbox**. Faça um teste simulado do **Targeting** na interface de usuário da campanha: escolha produtos e confirme se as frases sugeridas parecem corretas.
3. Production\*\* — Após a aprovação final, Epsilon ativa a produção. **Você** comunica às equipes de anunciantes que as palavras-chave sugeridas estão ativas (a UI as exibirá assim que forem ativadas).
**Como funcionam as sugestões de palavras-chave por IA**
1. **Entenda o produto** - A modelagem usa a intenção do produto, o contexto do varejista e o idioma.
2. **Gere palavras-chave** - As palavras-chave candidatas são produzidas a partir desse entendimento.
3. **Classifique** - As palavras-chave são selecionadas usando dados de anúncios e buscas para que as regras do programa (por exemplo, conquista de marca ou políticas específicas do varejista, como direcionamento a ingredientes de um produto) sejam respeitadas.
4. **Carregue para a UI** — Os pares produto–palavra-chave são armazenados no mesmo sistema usado pelo fluxo de **palavra-chave sugerida** na configuração da campanha.
**Governança**
* O comportamento de aprovação (**revisão automática vs manual do varejista**) depende da **configuração do programa** acordada com Epsilon.
* Se você tiver **pouco histórico de consultas de anúncios**, pode ser solicitado que compartilhe uma **pequena amostra de solicitações de busca orgânica no site** (por exemplo, cerca de **sete dias**) para que a geração corresponda ao idioma real do comprador.
* **Catálogos muito grandes** podem limitar a geração a produtos com **atividade publicitária recente** (por exemplo, cerca dos **últimos 90 dias**) em vez de cada SKU—confirme com Epsilon.
* **Palavras-chave sugeridas geradas por IA (beta)** atualmente se concentram em casos de uso de busca **orgânica**; o suporte para tipos de posicionamento adicionais pode ser expandido.
**Validação**
* As palavras-chave sugeridas aparecem no **Targeting** do sandbox para produtos no escopo.
* O comportamento de aprovação (revisão automática vs manual) corresponde à configuração do programa.
**Erros comuns**
| Erro | Solução |
| ----------------------------------------------------------- | --------------------------------------------------------------------------------- |
| As palavras-chave parecem fora da marca ou fora da política | Refine as regras de negócios com Epsilon e execute novamente a revisão do sandbox |
| Poucas ou nenhuma sugestão para catálogos grandes | Confirme se a geração está limitada a SKUs anunciados recentemente |
***
### (Opcional para a Etapa 2): Crie seu arquivo TSV (caminho fornecido pelo varejista)
**Objetivo**\
Fornecer linhas autoritativas de **product\_code → search\_term** (e classificação/tipo opcionais).
**O que você precisa fazer**
* Gerar um arquivo separado por tabulações de vinculações de produtos e palavras-chave.
* Usar codificação **UTF-8** e quebras de linha **LF**.
* Incluir uma linha de cabeçalho que corresponda aos nomes de campo que sua especificação de feed usa; no mínimo: `product_code`, `search_term`, `search_term_type`. Veja [Modelos de Dados e Definições de Campos](#data-models--field-definitions).
* Mantenha cerca de **\~20 palavras-chave sugeridas por produto** para facilitar a usabilidade.
* Repita `product_code` em várias linhas para vários termos; use `**search_term_type`\*\* quando você tiver vários tipos de posicionamento.
* Valide o arquivo e, em seguida, entregue-o ao bucket do GCS que o Epsilon fornece.
**Nota:** Quando você sincroniza um feed de varejista, Epsilon Retail Media fornece um **bucket do GCS** para envios. As operações da plataforma devem concluir a configuração—considere o tempo de processamento para a ativação.
**Exemplo de arquivo (trecho)**
```
product_code search_term search_term_rank search_term_type
abc123 cereal 1 ORGANIC
abc123 cereals 2 ORGANIC
12345 milk 1 CROSS_SELL
```
Validação
* Abra em um editor de texto: campos separados por **tabulação**, sem quebras de linha isoladas apenas com CR.
* Verifique aleatoriamente se vários `product_code` valores existem no seu feed de **catálogo**.
**Erros comuns**
| Erro | Solução |
| --------------------------------- | --------------------------------------------------------------- |
| Vírgulas CSV em vez de tabulações | Reexporte como TSV |
| IDs de produto incorretos | Alinhe com o `gtin` / `item` usado na sincronização do catálogo |
| Muitas linhas por SKU | Reduza para os termos de maior valor |
***
### Etapa 3: Verificar sugestões na UI
**Objetivo**\
Identificar problemas de mapeamento de última hora antes da produção.
**O que você precisa fazer**
* No **sandbox**, crie ou edite uma campanha, selecione posicionamentos que suportem palavras-chave sugeridas, adicione produtos, abra o **Targeting** / seleção de palavras-chave.
* Confirme as frases sugeridas por produto e se o comportamento **personalizado** vs **sugerido** corresponde às suas expectativas (veja \*\*Regras de veiculação em **Visão geral**).
* Confirme se as seleções **sugeridas** restrigem os produtos elegíveis àqueles vinculados no seu feed ou pipeline de IA.
**Validação**
* Na sua UI do sandbox: as palavras-chave sugeridas aparecem para produtos vinculados a palavras-chave no seu arquivo ou pipeline de IA.
* As sugestões se alinham às expectativas de posicionamento e catálogo.
**Erros comuns**
| Erro | Solução |
| -------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Sugestões em apenas um catálogo | Faça o preenchimento retroativo de outros catálogos ou ajuste o escopo do catálogo da campanha |
| Exibição do tipo de posicionamento incorreto | O TAM revisa o posicionamento ↔ `search_term_type` configuração |
***
## Modelos de Dados e Definições de Campos
### TSV (arquivo do varejista)
| Campo | Tipo | Obrigatório | Descrição | Valores aceitos |
| ------------------ | ------- | ----------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `product_code` | string | Sim | Identificador de produto do varejista; igual ao catálogo `gtin` / `item` onde aplicável | Não vazio; deve existir no catálogo sincronizado |
| `search_term` | string | Sim | Palavra-chave ou frase sugerida para o SKU | Texto UTF-8; evite caracteres de controle |
| `search_term_rank` | integer | No | Relevância relativa; **1** é a mais alta | Inteiros positivos; menor = maior prioridade |
| `search_term_type` | string | No | Mapeia linhas para tipos de \*\*posicionamento | `ORGANIC`, `CROSS_SELL`, `SUBSTITUTE`; padrão tratado como `ORGANIC` se omitido |
| (quebras de linha) | — | — | Formato do arquivo | LF\*\*; codificação do arquivo \*\*UTF-8 |
### Tipos de posicionamento e `search_term_type`
`search_term_type` alinha-se com os tipos de posicionamento: **ORGANIC**, **CROSS\_SELL** e **SUBSTITUTE**.
A maioria dos programas de varejistas usa um único posicionamento de **busca orgânica** para anúncios de resultados de busca padrão. **CROSS\_SELL** e **SUBSTITUTE** são **posicionamentos separados** na página de busca (ou inventário relacionado) com intenções de veiculação diferentes — eles não são apenas colunas extras no mesmo leilão orgânico. Seu Technical Account Manager confirma quais posicionamentos existem para seu namespace.
**Como os tipos de posicionamento diferem**
* **Orgânico** — Anúncios correspondentes à intenção de busca do comprador para o produto (por exemplo, um produto de cola em "cola").
* **Venda cruzada** — Intenção complementar (por exemplo, pizza em "cola").
* **Substituto** — Intenção de produto similar (por exemplo, outra variante de cola em "cola").
Você pode sincronizar **um feed por tipo de posicionamento** ou **combinar tipos em um único arquivo** (repetir `product_code` com diferentes `search_term_type`). Seu Technical Account Manager configura os posicionamentos para que o tipo de sugestão correto apareça por superfície. Palavras-chave sugeridas podem ser **exibidas ou ocultadas por posicionamento**.
Tipos combinados para um produto:
| product\_code | search\_term | search\_term\_rank | search\_term\_type |
| ------------- | ------------ | ------------------ | ------------------ |
| 12345 | cookies | 1 | ORGANIC |
| 12345 | cookie | 2 | ORGANIC |
| 12345 | milk | 1 | CROSS\_SELL |
**Nota:** A maioria dos programas usa apenas posicionamentos de busca **orgânica**. `CROSS_SELL` e `SUBSTITUTE` correspondem a **posicionamentos adicionais**, não a "colunas extras" no mesmo espaço orgânico — confirme com seu Technical Account Manager com quais posicionamentos você opera.
### Múltiplos catálogos
Implemente palavras-chave sugeridas em **todos** os catálogos no seu namespace quando possível (seja do seu feed, geração por IA ou ambos). Isso reduz a confusão da marca quando um catálogo tem sugestões e outros não.
Para campanhas de múltiplos catálogos, se apenas um catálogo tiver dados, as campanhas que dependem de seleções sugeridas só se comportarão totalmente nesse catálogo.
\##
***
## Testes, Sandbox e Go-Live
**Ambiente de teste / Sandbox**
* Valide as sugestões da UI na etapa de **Direcionamento** da campanha.
**Casos de teste de exemplo**
| Teste | Etapas | Resultado esperado |
| -------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| Sugestões da UI visíveis | Adicione produtos na campanha de sandbox; abra **Direcionamento** | Palavras-chave sugeridas aparecem por produto |
| Regra de veiculação | Selecione uma palavra-chave sugerida vinculada a um subconjunto de produtos | Apenas produtos vinculados qualificados para esse termo |
| Cobertura de múltiplos catálogos | Repita a verificação da UI em todos os catálogos no namespace | Sugestões presentes em todos os catálogos com dados (ou escopo documentado) |
Checklist de go-live
* [ ] TSV ingerido sem erros (se usar caminho de arquivo) ou pipeline de IA aprovado (se usar beta)
* [ ] Palavras-chave sugeridas visíveis na UI do sandbox para produtos representativos
* [ ] Namespaces de múltiplos catálogos têm cobertura em todos os catálogos (ou escopo documentado)
* [ ] Comunicação com o anunciante enviada antes ou no momento da ativação em produção
* [ ] API do parceiro retorna as linhas esperadas em produção (verificação pontual)
***
## Solução de problemas e FAQ
**Problema:** As sugestões nunca aparecem na UI.\
**Causa provável:** Ingestão não habilitada, catálogo incorreto ou posicionamento não configurado.\
Solução:\*\* Confirme com a Epsilon se a ingestão do GCS ou o pipeline de IA está ativo; verifique o mapeamento de posicionamento para `search_term_type`.
**Podemos usar um TSV para vários tipos de posicionamento?**\
Sim. Repita `product_code` em várias linhas com diferentes `search_term_type` valores. Seu Technical Account Manager configura quais tipos aparecem por posicionamento.
**E se tivermos vários catálogos em um namespace?**\
Implemente palavras-chave sugeridas em todos os catálogos quando possível. Campanhas que dependem de seleções sugeridas só funcionam totalmente em catálogos com dados.
**Ao entrar em contato com o suporte, inclua:**
* Namespace e ID do catálogo
* Amostra de `product_code` e o 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/pt-br/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.