> 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/it/feature-integrations/suggested-keywords.md). # Parole chiave consigliate Le **parole chiave consigliate** collegano i **termini di ricerca** ai **codici prodotto** nel tuo catalogo. Quando gli inserzionisti creano le campagne, tali termini appaiono durante il **Targeting** (selezione delle parole chiave di ricerca) per i prodotti che aggiungono. Gli inserzionisti possono scegliere tra i suggerimenti invece di digitare solo parole chiave personalizzate, migliorando l'allineamento con la modalità di indicizzazione delle ricerche del tuo sito e con la mappatura desiderata tra SKU e query.
**Le parole chiave consigliate possono essere fornite in due modi:** 1. **Epsilon Parole chiave generate dall'IA** — Epsilon genera, classifica e carica le coppie prodotto-parola chiave per tuo conto. **Non è richiesto** mantenere un file di parole chiave separato per tali suggerimenti quando questo percorso è la tua unica fonte. La generazione utilizza il contesto del prodotto e del catalogo, il comportamento di ricerca degli acquirenti e i segnali allineati alle tue **regole aziendali del retailer** (ad esempio il brand conquesting e altri vincoli del programma). 2. **Feed TSV gestito dal retailer** — Sincronizzi un file che mappa ciascun `product_code` a uno o più `search_term` valori, con grado e tipo opzionali. Gestisci le parole chiave consigliate per ciascun prodotto. I retailer possono scegliere di utilizzare **Epsilon solo parole chiave generate**, **solo il tuo file**, o **entrambi** (ad esempio suggerimenti IA **sovrapposti** a un elenco esistente, o una **sostituzione** coordinata durante il rollout per gestire deliberatamente le approvazioni esistenti). Se Epsilon fornisce **parole chiave consigliate da IA** per il tuo programma e **non** hai bisogno di un feed TSV del retailer, inizia con [**Passaggio 3: Attiva le parole chiave suggerite dall'IA (beta)**](#step-3-activate-ai-suggested-keywords-beta)**. Utilizza**[**Passaggio 2: Crea il file TSV**](#step-2-optional-build-the-tsv-file-retailer-supplied-path) solo quando mantieni o integri le parole chiave tramite file. ### Perché utilizzare le parole chiave consigliate? * Orientare gli inserzionisti verso termini di ricerca ad alto intento e accurati per il prodotto * Mostrare termini a cui gli inserzionisti potrebbero non pensare senza una guida * Aumentare la concorrenza su parole chiave di valore rimanendo all'interno delle regole del programma * Ridurre il lavoro manuale sui file quando la generazione tramite IA è abilitata **Questa guida copre** * Prerequisiti e flusso end-to-end * Autenticazione API per i flussi di lettura/convalida * Attivazione dell'IA passo dopo passo (beta) e implementazione TSV opzionale * Test in Sandbox, checklist per il go-live, risoluzione dei problemi ### Regole di erogazione Quando gli inserzionisti aggiungono parole chiave **consigliate** a una campagna, **solo i prodotti collegati a quella parola chiave** sono idonei all'erogazione su termini di ricerca del cliente corrispondenti. L'interfaccia utente mostra quali prodotti si mappano a quali parole chiave consigliate:
I termini di ricerca **personalizzati** scelti dall'inserzionista si applicano in genere a tutti i prodotti della campagna in base alle regole di posizionamento; le selezioni **consigliate** limitano l'idoneità utilizzando la mappatura \*\*retailer / Epsilon. ## Prerequisiti Utilizza questa checklist prima di iniziare. * [ ] **Retailer** integrato (o in corso di integrazione) con Epsilon Retail Media, inclusa la sincronizzazione del catalogo. * [ ] **Accesso alla Sandbox** per l'interfaccia utente della campagna e le API dove convaliderai le parole chiave (quando disponibile per il tuo programma). * [ ] **Per la consegna TSV:** bucket GCS (o percorso) **predisposto da Epsilon**, e credenziali che il tuo team può utilizzare per caricare oggetti (metodo confermato con Epsilon—spesso chiave dell'account di servizio o accesso federato). Nota: se stai solo definendo l'ambito, questo viene gestito nell'ambito del processo di attivazione se stai fornendo parole chiave. * [ ] **Contatto tecnico** che possa caricare file, eseguire controlli API e coordinarsi con Epsilon sulle pianificazioni di inserimento e sui passaggi di consegne. * [ ] **Consapevolezza della release:** l'idoneità del prodotto per parola chiave per i suggerimenti richiede la piattaforma (vedere le Regole di erogazione sopra). *** ## Panoramica del flusso di integrazione 1. Confermi con Epsilon come verranno fornite le parole chiave:Epsilon generate\*\*, **file TSV**, o **entrambi**. 2. Se stai fornendo un file, caricalo nel bucket GCS predisposto da Epsilon. 3. Epsilon abilita la funzionalità e (per i file) acquisisce il tuo file. Per le parole chiave **IA**, Epsilon si allinea sulle regole, sulla sovrapposizione opzionale rispetto alla sostituzione e sulla convalida in staging. 4. I dati arrivano come **parole chiave consigliate** nella piattaforma. 5. Esegui la **verifica** nella tua sandbox direttamente nell'interfaccia utente prima del lancio per i tuoi inserzionisti. 6. Vai **in produzione** e comunichi ai team degli inserzionisti che le parole chiave consigliate sono disponibili. *** ## Guida all'implementazione passo dopo passo ### Passo 1: Conferma il tuo modello di fornitura con Epsilon Scopo\ Evita di costruire una pipeline di file se la soluzione **solo IA** soddisfa le tue esigenze, o evita di duplicare il lavoro se Epsilon sovrapporrà/sostituirà gli elenchi per te. **Cosa devi fare** * Decidi: **Solo IA**, **Solo TSV**, o **entrambi**. * Conferma **sovrapposizione** rispetto a **sostituzione** per qualsiasi dato di parole chiave consigliate esistente. * Conferma quali **posizionamenti** esistono (`ORGANIC` solo rispetto anche a `CROSS_SELL` / `SUBSTITUTE`). *** ### Passo 2: Attiva le parole chiave consigliate da IA **Scopo**\ Ottieni parole chiave generate da Epsilone filtrate da regole nella piattaforma **senza** mantenere un TSV. **Cosa devi fare** 1. Coinvolgi Epsilon\*\* — Fornisci le tue **regole aziendali** specifiche (ad esempio il brand conquesting) e come i nuovi dati dovrebbero relazionarsi agli elenchi esistenti se sincronizzi già le parole chiave consigliate (**sovrapposizione** rispetto a **sostituzione**). 2. Testa in sandbox\*\* — Collabora con Epsilon per caricare o rivedere le parole chiave in **staging/sandbox**. Esegui una prova di **Targeting** nell'interfaccia utente della campagna: seleziona i prodotti e conferma che le frasi consigliate appaiano corrette. 3. Produzione\*\* — Dopo l'approvazione finale, Epsilon abilita la produzione. **Comunica** ai team degli inserzionisti che le parole chiave suggerite sono attive (l'interfaccia utente le mostrerà una volta abilitate). **Come funzionano i suggerimenti di parole chiave tramite AI** 1. **Comprendere il prodotto** - La modellazione utilizza l'intento del prodotto, il contesto del retailer e la lingua. 2. **Generare parole chiave** - Le parole chiave candidate vengono prodotte a partire da tale comprensione. 3. **Classificare** - Le parole chiave vengono selezionate utilizzando i dati sugli annunci e sulla ricerca in modo che le regole del programma (ad esempio il conquesting del brand o le politiche specifiche del retailer come il targeting degli ingredienti di un prodotto) siano rispettate. 4. **Caricare per l'UI** — Le coppie prodotto-parola chiave vengono memorizzate nello stesso sistema utilizzato dal flusso delle **parole chiave suggerite** nella configurazione della campagna. **Governance** * Il comportamento di approvazione (**revisione automatica rispetto a manuale del retailer**) dipende dalla **configurazione del programma** concordata con Epsilon. * Se disponi di **uno storico limitato di query pubblicitarie**, ti potrebbe essere chiesto di condividere un **breve campione di richieste di ricerca organica on-site** (ad esempio di circa **sette giorni**) in modo che la generazione corrisponda al reale linguaggio degli acquirenti. * **I cataloghi molto grandi** possono limitare la generazione ai prodotti con **attività pubblicitaria recente** (ad esempio circa gli **ultimi 90 giorni**) anziché a ogni SKU: conferma con Epsilon. * Le **parole chiave suggerite generate dall'AI (beta)** attualmente si concentrano su casi d'uso di ricerca **organica**; il supporto per altri tipi di posizionamento potrebbe essere esteso. **Convalida** * Le parole chiave suggerite appaiono nel **Targeting** della sandbox per i prodotti nell'ambito. * Il comportamento di approvazione (revisione automatica rispetto a manuale) corrisponde alla configurazione del programma. **Errori comuni** | Errore | Soluzione | | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | Le parole chiave sembrano non in linea con il brand o con le politiche | Perfeziona le regole aziendali con Epsilon e esegui nuovamente la revisione sandbox | | Pochi o nessun suggerimento per cataloghi di grandi dimensioni | Conferma se la generazione è limitata alle SKU pubblicizzate di recente | *** ### (Opzionale per il Passaggio 2): Crea il tuo file TSV (percorso fornito dal retailer) **Scopo**\ Fornisci righe autorevoli **product\_code → search\_term** (e livello/tipo opzionali). **Cosa devi fare** * Genera un file separato da tabulazioni di collegamenti tra prodotti e parole chiave. * Utilizza la codifica **UTF-8** e le interruzioni di riga **LF**. * Includi una riga d'intestazione che corrisponda ai nomi dei campi utilizzati dalle specifiche del feed; come minimo: `product_code`, `search_term`, `search_term_type`. Vedi [Modelli di dati e definizioni dei campi](#data-models--field-definitions). * Mieni circa **\~20 parole chiave suggerite per prodotto** per ragioni di fruibilità. * Ripeti `product_code` su più righe per più termini; usa `**search_term_type`\*\* quando hai più tipi di posizionamento. * Convalida il file, quindi consegnalo al bucket GCS Epsilon dispone. **Nota:** Quando sincronizzi un feed retailer, Epsilon Retail Media predispone un **bucket GCS** per i rilasci. Le operazioni sulla piattaforma devono completare la configurazione: prevedi dei tempi di lavorazione per l'attivazione. **Esempio di file (snippet)** ``` product_code search_term search_term_rank search_term_type abc123 cereal 1 ORGANIC abc123 cereals 2 ORGANIC 12345 milk 1 CROSS_SELL ``` Convalida * Apri in un editor di testo: campi separati da **tabulazione**, nessuna interruzione di riga vagante con solo CR. * Verifica a campione che diversi `product_code` valori esistano nel feed del tuo **catalogo**. **Errori comuni** | Errore | Soluzione | | -------------------------------------- | -------------------------------------------------------------------------- | | Virgole CSV al posto delle tabulazioni | Esporta nuovamente come TSV | | ID prodotto errati | Allinea con `gtin` / `item` utilizzato nella sincronizzazione del catalogo | | Troppe righe per SKU | Riduci ai termini di maggior valore | *** ### Passaggio 3: Verifica i suggerimenti nell'interfaccia utente **Scopo**\ Intercetta problemi di mappatura dell'ultimo minuto prima della produzione. **Cosa devi fare** * In **sandbox**, crea o modifica una campagna, seleziona i posizionamenti che supportano le parole chiave suggerite, aggiungi i prodotti, apri **Targeting** / selezione parole chiave. * Conferma le frasi suggerite per prodotto e che il comportamento **personalizzato** rispetto a **suggerito** corrisponda alle tue aspettative (vedi \*\*Regole di erogazione in **Panoramica**). * Conferma che le selezioni **suggerite** limitino i prodotti idonei a quelli collegati nel feed o nella pipeline AI. **Convalida** * Nell'interfaccia utente della sandbox: le parole chiave suggerite appaiono per i prodotti collegati alle parole chiave nel file o nella pipeline AI. * I suggerimenti si allineano alle aspettative di posizionamento e catalogo. **Errori comuni** | Errore | Soluzione | | ------------------------------------------ | -------------------------------------------------------------------------------------- | | Suggerimenti solo su un catalogo | Esegui il backfill degli altri cataloghi o regola l'ambito del catalogo della campagna | | Tipo di posizionamento errato visualizzato | TAM rivede posizionamento ↔ `search_term_type` configurazione | *** ## Modelli di dati e definizioni dei campi ### TSV (file retailer) | Campo | Tipo | Obbligatorio | Descrizione | Valori accettati | | ---------------------- | ------- | ------------ | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | `product_code` | stringa | Sì | Identificatore del prodotto del retailer; uguale al catalogo `gtin` / `item` ove applicabile | Non vuoto; deve esistere nel catalogo sincronizzato | | `search_term` | stringa | Sì | Parola chiave o frase suggerita per lo SKU | Testo UTF-8; evitare caratteri di controllo | | `search_term_rank` | intero | No | Rilevanza relativa; **1** è la più alta | Interi positivi; più basso = priorità più alta | | `search_term_type` | stringa | No | Mappa le righe sui tipi di \*\*posizionamento | `ORGANIC`, `CROSS_SELL`, `SUBSTITUTE`; l'impostazione predefinita è trattata come `ORGANIC` se omesso | | (interruzioni di riga) | — | — | Formato file | LF\*\*; codifica file \*\*UTF-8 | ### Tipi di posizionamento e `search_term_type` `search_term_type` si allinea con i tipi di posizionamento: **ORGANIC**, **CROSS\_SELL** e **SUBSTITUTE**. La maggior parte dei programmi dei retailer utilizza un singolo posizionamento **ricerca organica** per gli annunci dei risultati di ricerca standard. **CROSS\_SELL** e **SUBSTITUTE** sono **posizionamenti separati** sulla pagina di ricerca (o inventario correlato) con una diversa intenzione di erogazione: non sono semplicemente colonne aggiuntive nella stessa asta organica. Il tuo Technical Account Manager confermerà quali posizionamenti esistono per il tuo namespace. **Come si differenziano i tipi di posizionamento** * **Organico** — Annunci abbinati all'intenzione di ricerca dell'acquirente per il prodotto (ad esempio un prodotto cola per "cola"). * **Cross-sell** — Intenzione complementare (ad esempio pizza per "cola"). * **Sostituto** — Intenzione per prodotto simile (ad esempio un'altra variante di cola per "cola"). È possibile sincronizzare **un feed per tipo di posizionamento** o **combinare i tipi in un unico file** (ripetere `product_code` con diversi `search_term_type`). Il tuo Technical Account Manager configura i posizionamenti in modo che il tipo di suggerimento corretto appaia per superficie. Le parole chiave suggerite possono essere **mostrate o nascoste per posizionamento**. Tipi combinati per un prodotto: | product\_code | search\_term | search\_term\_rank | search\_term\_type | | ------------- | ------------ | ------------------ | ------------------ | | 12345 | biscotti | 1 | ORGANIC | | 12345 | biscotto | 2 | ORGANIC | | 12345 | latte | 1 | CROSS\_SELL | **Nota:** La maggior parte dei programmi utilizza solo posizionamenti di ricerca **organici**. `CROSS_SELL` e `SUBSTITUTE` corrispondono a **posizionamenti aggiuntivi**, non a "colonne extra" nello stesso slot organico—conferma quali posizionamenti utilizzi con il tuo Technical Account Manager. ### Cataloghi multipli Implementa le parole chiave suggerite su **tutti** i cataloghi nel tuo namespace quando possibile (sia dal tuo feed, dalla generazione di IA, o da entrambi). Ciò riduce la confusione sul brand quando un catalogo contiene suggerimenti e altri no. Per le campagne multi-catalogo, se solo un catalogo contiene dati, le campagne che dipendono dalle selezioni suggerite si comporteranno completamente solo su quel catalogo. \## *** ## Test, Sandbox e Go-Live **Ambiente Sandbox / test** * Convalida i suggerimenti dell'interfaccia utente nel passaggio **Targeting** della campagna. **Casi di test di esempio** | Test | Passaggi | Risultato atteso | | --------------------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | Suggerimenti dell'interfaccia utente visibili | Aggiungi prodotti nella campagna sandbox; apri **Targeting** | Le parole chiave suggerite appaiono per prodotto | | Regola di erogazione | Seleziona una parola chiave suggerita collegata a un sottoinsieme di prodotti | Solo i prodotti collegati sono idonei per quel termine | | Copertura multi-catalogo | Ripeti il controllo dell'interfaccia utente tra i cataloghi nel namespace | Suggerimenti presenti su tutti i cataloghi con dati (o ambito documentato) | Checklist per il Go-Live * [ ] TSV ingerito senza errori (se si utilizza il percorso del file) o pipeline di IA approvata (se si utilizza la versione beta) * [ ] Parole chiave suggerite visibili nell'interfaccia utente sandbox per prodotti rappresentativi * [ ] I namespace multi-catalogo hanno copertura su tutti i cataloghi (o ambito documentato) * [ ] Comunicazione con l'inserzionista inviata prima o al momento dell'abilitazione in produzione * [ ] L'API Partner restituisce le righe attese in produzione (verifica a campione) *** ## Risoluzione dei problemi e FAQ **Problema:** I suggerimenti non appaiono mai nell'interfaccia utente.\ **Causa probabile:** Ingestione non abilitata, catalogo errato o posizionamento non configurato.\ Soluzione:\*\* Conferma con Epsilon che l'ingestione GCS o la pipeline IA sia attiva; verificare il mappaggio del posizionamento per `search_term_type`. **Possiamo usare un TSV per più tipi di posizionamento?**\ Sì. Ripeti `product_code` su più righe con valori `search_term_type` diversi. Il tuo Technical Account Manager configura quali tipi mostrare per ciascun posizionamento. **Cosa succede se abbiamo più cataloghi in uno stesso namespace?**\ Implementa le parole chiave suggerite su tutti i cataloghi, quando possibile. Le campagne che dipendono dalle selezioni suggerite funzionano a pieno regime solo sui cataloghi contenenti dati. **Quando contatti il supporto, includi:** * Namespace e ID del catalogo * Esempio `product_code` e atteso `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/it/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.