> 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/category-cross-sell/integration-requirements.md).

# Requisiti di integrazione

## Panoramica ad alto livello

Come parte di questa integrazione, dovrai fare quanto segue

1. Implementare una richiesta pubblicitaria aggiuntiva per il posizionamento della categoria cross-sell.
   1. Questo include il lavoro per posizionare e visualizzare gli annunci sul tuo sito, nonché per segnalare clic e impressioni
   2. Gli ordini devono essere forniti a Epsilon Retail Media come parte della tua integrazione standard
2. Se sincronizzi gli ID categoria con Epsilon Retail Mediadovrai utilizzare l'API [filterMapping](/retail-media-interface/integration/it/citrus-filter-mapping-api/filtermapping.md) per fornire valori leggibili dall'utente per la selezione della categoria nell'interfaccia utente
   1. Questo si applica solo se sei integrato con ID categoria invece che con i nomi. (ad esempio quando richiedi annunci, i tuoi filtri sono `category:123j-dsef-er` invece di `category:Milk`
3. (Consigliato) - sincronizzare le mappature cross-sell delle categorie, per automatizzare l'approvazione e ridurre il carico di gestione delle campagne.

## Richiesta pubblicitaria e integrazione del sito

### Richiesta pubblicitaria

Poiché il cross-sell di categoria richiede un posizionamento autonomo, dovrai integrare una richiesta pubblicitaria aggiuntiva per ciascun tipo di annuncio per cui stai integrando il cross-sell di categoria.

Il formato della tua richiesta dovrebbe corrispondere alla richiesta pubblicitaria della categoria cross-sell come elencato di seguito

* [Annuncio prodotto - richiesta di annunci di cross-selling per categoria](/retail-media-interface/integration/it/generating-ads/product-ads/requesting-product-ads-1.md#cross-sell-category-placements)
* [Annuncio banner - richiesta di annunci di cross-selling per categoria](/retail-media-interface/integration/it/generating-ads/banner-ads-static/requesting-banner-ads.md#cross-sell-category-placements)
* Banner X richiesta di annunci di categoria cross-sell

### Segnalazione di impressioni e clic

Dopo aver integrato la richiesta pubblicitaria, dovrai anche assicurarti di segnalare correttamente clic e impressioni per ciascun annuncio mostrato. Assicurati di leggere [Segnalazione di impression e clic](/retail-media-interface/integration/it/data-api/api-overview/reporting-impressions-clicks.md).

### Segnalazione degli ordini

In genere, la maggior parte delle integrazioni segnala tutte le informazioni sugli ordini a Epsilon Retail Media come da integrazione standard. Devi assicurarti di segnalare correttamente tutti gli ordini a Epsilon Retail Media come da [Dati degli ordini](/retail-media-interface/integration/it/data-api/order-data-1.md).

## Mappature dei filtri

L'endpoint filter mapping può essere utilizzato per mappare i tuoi ID categoria a valori leggibili dall'utente. Questo è richiesto se sincronizzi gli ID categoria poiché l'interfaccia utente mostra i valori ai tuoi utenti.

{% hint style="info" %}
Se sincronizzi categorie leggibili dall'utente nel tuo catalogo prodotti con Epsilon Retail Mediaquesto passaggio non sarà necessario.
{% endhint %}

Gli utenti non capiranno cosa sia `category:12345-abcde` L'API filterMapping può essere utilizzata per mappare il valore al nome della categoria pertinente sul tuo sito, come `category:Pantry`.

Non esiste un metodo basato su file per sincronizzare queste informazioni, deve essere fatto tramite l'API [filterMapping](/retail-media-interface/integration/it/citrus-filter-mapping-api/filtermapping.md) API.

{% hint style="warning" %}
Man mano che crei categorie aggiuntive sul tuo sito, dovrai assicurarti che l'API filterMapping venga utilizzata per aggiornare le categorie.
{% endhint %}

## Mappature cross-sell di categoria (consigliato)

È vivamente consigliato, quando si integra questo tipo di posizionamento, di fornire una mappatura delle categorie a cui è consentito indirizzarsi a vicenda. Questo può semplificare le tue operazioni dopo il lavoro di integrazione iniziale. L'esperienza dell'inserzionista è semplificata per consentire solo le categorie che sono già selezionabili.

Inoltre, è anche possibile configurare l'approvazione automatica per le campagne di categoria cross-sell, quando vengono fornite le mappature cross-sell.

### Metodi di integrazione

* Sei in grado di utilizzare l'API [crossSellCategory](/retail-media-interface/integration/it/crosssellcategory-api/crosssellcategory.md) per creare e gestire le mappature come richiedi.
* In alternativa, sei in grado di fornire un file TSV a un bucket GCS ospitato da Epsilon Retail Media con il formato elencato di seguito.

#### Integrazione API

Tutte le informazioni richieste possono essere viste nel riferimento dell'API [crossSellCategory](/retail-media-interface/integration/it/crosssellcategory-api/crosssellcategory.md) Riferimento API.

#### Integrazione tramite file

Se si integra tramite file, Epsilon Retail Media richiede un file per catalogo, di quali categorie è consentito il targeting tra loro.

Ogni riga nel file rappresenta una singola mappatura di una categoria e la categoria a cui può indirizzarsi. Ogni mappatura è monodirezionale (se sincronizzi cioccolato -> latte, i prodotti a base di cioccolato possono apparire nella categoria latte. Se i prodotti a base di latte devono poter apparire su cioccolato, è richiesta una riga aggiuntiva).

Abbiamo bisogno di un feed di dati in formato TSV conforme alle specifiche seguenti:

| nome colonna        | Obbligatorio | Tipo di dato | Descrizione                                                                                                                                  | Esempio            |
| ------------------- | ------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
| `category`          | Obbligatorio | Testo        | Questo è un ID categoria univoco che identifica la categoria del prodotto pubblicizzato.                                                     | `category:cookies` |
| `cross_category_id` | Obbligatorio | Testo        | Questo è un ID categoria univoco che identifica una categoria idonea in cui i prodotti di category\_id possono essere venduti in cross-sell. | `category:milk`    |

Di seguito sono riportate ulteriori specifiche del file:

* I file TSV sono supportati solo
* TSV dovrebbe essere in LF non CRLF
* TSV dovrebbe essere codificato in UTF-8, qualsiasi altro tipo causerà il fallimento del feed
* Convenzione di denominazione richiesta: `^cross_sell_category.*.tsv$`

Un frammento di esempio si presenta come segue:

| categoria        | cross\_category\_id |
| ---------------- | ------------------- |
| category:cookies | category:milk       |
| category:cookies | category:chocolate  |
| category:milk    | category:cookies    |

Questo frammento sopra consente alla categoria **cookies** di fare cross-sell nelle categorie **milk** e **chocolate**. La categoria **milk** può fare cross-sell nella categoria **cookies**. La categoria **chocolate** può essere targettizzata, ma non può indirizzarsi a nessun'altra categoria.

{% hint style="danger" %}
️ Ogni riga è una combinazione di mappatura univoca

È necessario sincronizzare righe uniche per ogni mappatura univoca della categoria cross-sell. Tentando di sincronizzare più cross\_category\_id in una singola riga, l'ingestione del file fallirà.
{% endhint %}

{% hint style="warning" %}
Ordine delle colonne

Assicurati che il tuo file abbia la colonna `category` come prima colonna. Se sincronizzi `cross_category_id` come prima colonna, l'ingestione fallirà.
{% endhint %}

## Processo di attivazione della funzionalità

Una volta pronti per iniziare a sincronizzare il feed dei termini di ricerca suggeriti, Epsilon Retail Media configurerà un bucket GCS in cui inserire i file.

Questa funzionalità è supportata solo sui bucket GCS. I bucket esterni come AWS/Azure/altri non sono supportati.

Il tuo Technical Account Manager saprà guidarti attraverso l'attivazione di questa funzionalità. Poiché Epsilon Retail Mediail team delle operations della piattaforma di deve eseguire una configurazione, si informa che è previsto un tempo di elaborazione aggiuntivo per l'attivazione.


---

# 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/category-cross-sell/integration-requirements.md?ask=<question>&goal=<endgoal>
```

`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.