> 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/generating-ads/product-ads/requesting-product-ads-1.md). # Richiesta di annunci di prodotto ## Richiesta di annunci Tutte le richieste di annunci di prodotto richiedono il contesto `placement`, e `catalogId`, nonché il `maxNumberOfAds` che desideri mostrare al cliente. Inoltre, la tua richiesta dovrebbe includere il contesto `customerId` e `sessionId`. ### Posizionamenti di ricerca I posizionamenti di ricerca sono in genere i più semplici da richiedere. Richiedono che sia specificato un `searchTerm` nella richiesta, come nell'esempio seguente: ```http POST $BASE_URL/v1/ads/generate HTTP/1.1 accept: application/json content-type: application/json Authorization: Basic { "customerId": "wertg5432a", "sessionId": "ec9-4e07-881d-3e9", "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE", "placement": "search", "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b", "searchTerm": "chocolate", "options": { "filterMode": "AndOr" }, "maxNumberOfAds": 3 } ``` ### Posizionamenti per categoria I posizionamenti per categoria richiedono che sia specificato `productFilters` nella richiesta. L'esempio seguente mostra dove inviare i filtri di categoria: ```http POST $BASE_URL/v1/ads/generate HTTP/1.1 accept: application/json content-type: application/json Authorization: Basic { "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 } ``` Man mano che vengono esaminate ulteriori categorie, è necessario aggiornare la chiamata API di conseguenza. {% hint style="info" %} Best practice È una best practice inviare il livello di categoria più basso nella richiesta di annunci a Epsilon Retail Media man mano che i clienti navigano in categorie più profonde. Invece di specificare una richiesta concatenata sul livello 3 di L1 + L2 + L3, dovresti specificare solo la categoria L3. {% endhint %} ### Posizionamenti per categoria di cross-selling I posizionamenti per categoria di cross-selling hanno una richiesta molto simile ai posizionamenti per categoria. Vorrai specificare l'esatta categoria per la quale stai richiedendo gli annunci. Questa è in genere la pagina in cui ti trovi. Specifica la categoria nel `productFilters` della richiesta. L'esempio seguente mostra dove inviare i filtri di categoria: ```http POST $BASE_URL/v1/ads/generate HTTP/1.1 accept: application/json content-type: application/json Authorization: Basic { "customerId": "wertg5432a", "sessionId": "ec9-4e07-881d-3e9", "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE", "placement": "category-cross-sell", "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b", "productFilters": [ ["category:Cupboard/Snacks"] ], "options": { "filterMode": "AndOr" }, "maxNumberOfAds": 3 } ``` Man mano che vengono esaminate ulteriori categorie, è necessario aggiornare la chiamata API di conseguenza. {% hint style="info" %} Unire il targeting per categoria organico e di cross-selling? Se desideri unire una richiesta di annunci per categoria organica e di cross-selling in un unico posizionamento, dovrai implementare la logica di unione e di erogazione per i tuoi clienti. Questa è una responsabilità dell'integratore, sebbene Epsilon Retail Media sia lieta di offrire una consulenza. In generale, consigliamo di mostrare annunci di categoria organici e di posizionare gli annunci di cross-selling di categoria e posizione dopo i posizionamenti organici. {% endhint %} ### Posizionamenti a corrispondenza generica I posizionamenti generici come la pagina iniziale o la pagina di pagamento non richiedono di specificare alcun `productFilters` nella richiesta. Eventuali filtri che il retailer desidera specificare (in offerta, nuovo, ecc.) possono essere specificati nel `productFilters` per garantire che Epsilon Retail Media servano annunci solo all'interno dei requisiti. ```http POST $BASE_URL/v1/ads/generate HTTP/1.1 accept: application/json content-type: application/json Authorization: Basic { "customerId": "wertg5432a", "sessionId": "ec9-4e07-881d-3e9", "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE", "placement": "home", "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b", "productFilters": [ [] ], "options": { "filterMode": "AndOr" }, "maxNumberOfAds": 3 } ``` ### Miglioramenti della richiesta Sui posizionamenti di ricerca, di categoria e a corrispondenza generica, ti consigliamo di valutare i miglioramenti seguenti per migliorare l'esperienza utente. #### Impaginazione delle richieste Quando generi annunci di prodotto, riceverai un `memoryToken` che può essere inviato in richieste successive per escludere gli annunci serviti in precedenza. Puoi quindi inviare questo `memoryToken` in una richiesta di annunci successiva, e Epsilon Retail Media escluderà qualsiasi annuncio servito in precedenza per lo stesso contesto dalla nostra risposta pubblicitaria. Ti invitiamo a rivedere [Paginazione](/retail-media-interface/integration/it/feature-integrations/pagination.md) prima dell'implementazione. ```http POST $BASE_URL/v1/ads/generate HTTP/1.1 accept: application/json content-type: application/json Authorization: Basic { "customerId": "wertg5432a", "sessionId": "ec9-4e07-881d-3e9", "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE", "placement": "search", "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b", "searchTerm": "chocolate", "memoryToken":"85ykKVv-luDHMWLZx2d6xcPq6sF7CgkJCSJDb3VudGVyIjogIjIiLAoJCQkiQWRzIjogWwoJCQkJImRpc3BsYXlfV05VV0NwQkRKMUpKNm5wdVZSVExvOU40TUxzNE1UWTBOemt5TWc9PSIsCgkJCQkiZGlzcGxheV9MME5NUHRxNmdCcVFvREJOd3J0dE9UTGJoWk0xTVRFeU9UYzRPUT09IiwKCQkJCSJkaXNwbGF5XzlCcEpmdUpaWk9VXzgyaWpFM3VCczgxd3VVczRNekkwTnpVeE5nPT0iLAoJCQkJImRpc3BsYXlfcW1VU1p4TkpMQ0lqeWQwdTFJRDk0RmxVZ0pnNE16STBOelV4Tnc9PSIsCgkJCQkiZGlzcGxheV9oeHlFZktCUnRrNWlxMThMQzE1SDJHcEN3QjgxTVRFeU9UYzVNQT09IiwKCQkJCSJkaXNwbGF5X1NkcjFEcU5aUEFtcGh0Q1FIUndoYUxFT1B0RXhNamsxT1RJNE5BPT0iLAoJCQkJImRpc3BsYXlfeVlSai1qV2Ntc2ozNzhrel9PMm0yOVlwTjhJeE5EazNPRE00TXc9PSIsCgkJCQkiZGlzcGxheV9Xbm9NZGZuLTRTVmhxcF9xQzVvLWxoT0paNm8xTkRJeE1UUTROdz09IgoJCQldLAoJCQkiVFRMIjogMTYyODk4NTYwMAoJCX0=", "options": { "filterMode": "AndOr" }, "maxNumberOfAds": 3 } ``` #### Ricerche filtrate Se il tuo cliente filtra la sua ricerca, puoi estendere il tuo contesto per fornire `productFilters`. Di seguito è riportato un esempio in cui il cliente filtra per la categoria "Dispensa" e la restrizione alimentare "Senza glutine". Questo stesso principio può essere applicato a qualsiasi categoria o posizionamento a corrispondenza generica. ```http POST $BASE_URL/v1/ads/generate HTTP/1.1 accept: application/json content-type: application/json Authorization: Basic { "customerId": "wertg5432a", "sessionId": "ec9-4e07-881d-3e9", "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE", "placement": "search", "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b", "searchTerm": "chocolate", "productFilters": [ ["category:Cupboard"],["dietary:Gluten-free"] ], "options": { "filterMode": "AndOr" }, "maxNumberOfAds": 3 } ``` #### Filtraggio per posizione Se stai sincronizzando i filtri di posizione nel tuo catalogo, puoi estendere il tuo contesto per fornire la posizione del negozio del cliente nel `productFilters`: ```http POST $BASE_URL/v1/ads/generate HTTP/1.1 accept: application/json content-type: application/json Authorization: Basic { "customerId": "wertg5432a", "sessionId": "ec9-4e07-881d-3e9", "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE", "placement": "search", "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b", "searchTerm": "chocolate", "productFilters": [ ["category:Cupboard"],["dietary:Gluten-free"],["location:Westenbury"] ], "options": { "filterMode": "AndOr" }, "maxNumberOfAds": 3 } ``` ## La risposta dell'annuncio prodotto Tutte le risposte degli annunci prodotto seguono lo stesso formato JSON. Gli annunci prodotto vengono restituiti nell'array `ads` , come nell'esempio seguente: ```json { "ads": [ { "id": "display_QqHaKRrKlFm1Wxr9c_DXJN4HSE3NzMzNjM2", "gtin": "7733636", "discount": { "amount": 0, "minPrice": 0, "maxPerCustomer": 0 }, "expiry": "2021-05-12T04:17:50.400902957Z", "position": 1 }, { "id": "display_NzsHqP0_iQedlo9VnrO2vqkwi_k3NzMzNjI4", "gtin": "7733628", "discount": { "amount": 0, "minPrice": 0, "maxPerCustomer": 0 }, "expiry": "2021-05-12T04:17:50.400908257Z", "position": 2 }, { "id": "display_xNeShqidaMuEqiJ0zNdt-Gzygjs3NzE0MTA3", "gtin": "7714107", "discount": { "amount": 0, "minPrice": 0, "maxPerCustomer": 0 }, "expiry": "2021-05-12T04:17:50.400912929Z", "position": 3 }, { "id": "display_3rGiryPskhQusmsf43nghbQwnqo3NzMzNjU3", "gtin": "7733657", "discount": { "amount": 0, "minPrice": 0, "maxPerCustomer": 0 }, "expiry": "2021-05-12T04:17:50.400917769Z", "position": 4 } ], "banners": [], "products": [], "memoryToken":"85ykKVv-luDHMWLZx2d6xcPq6sF7CgkJCSJDb3VudGVyIjogIjIiLAoJCQkiQWRzIjogWwoJCQkJImRpc3BsYXlfV05VV0NwQkRKMUpKNm5wdVZSVExvOU40TUxzNE1UWTBOemt5TWc9PSIsCgkJCQkiZGlzcGxheV9MME5NUHRxNmdCcVFvREJOd3J0dE9UTGJoWk0xTVRFeU9UYzRPUT09IiwKCQkJCSJkaXNwbGF5XzlCcEpmdUpaWk9VXzgyaWpFM3VCczgxd3VVczRNekkwTnpVeE5nPT0iLAoJCQkJImRpc3BsYXlfcW1VU1p4TkpMQ0lqeWQwdTFJRDk0RmxVZ0pnNE16STBOelV4Tnc9PSIsCgkJCQkiZGlzcGxheV9oeHlFZktCUnRrNWlxMThMQzE1SDJHcEN3QjgxTVRFeU9UYzVNQT09IiwKCQkJCSJkaXNwbGF5X1NkcjFEcU5aUEFtcGh0Q1FIUndoYUxFT1B0RXhNamsxT1RJNE5BPT0iLAoJCQkJImRpc3BsYXlfeVlSai1qV2Ntc2ozNzhrel9PMm0yOVlwTjhJeE5EazNPRE00TXc9PSIsCgkJCQkiZGlzcGxheV9Xbm9NZGZuLTRTVmhxcF9xQzVvLWxoT0paNm8xTkRJeE1UUTROdz09IgoJCQldLAoJCQkiVFRMIjogMTYyODk4NTYwMAoJCX0=" } ``` Il `id` campo è l'ID del tuo annuncio utilizzato nei report sulle impressioni e sui clic. Il `position` campo definisce la posizione nel Epsilon Retail Media payload. Fai riferimento alla documentazione per ulteriori informazioni su ciascuna stringa. {% hint style="info" %} Dovresti leggere e rispettare il `position` campo per garantire che i posizionamenti Canone fisso vengano visualizzati correttamente. {% endhint %} ### sellerId del marketplace Se stai integrando i venditori del marketplace, potresti vedere un valore aggiuntivo `sellerId` per annuncio nella risposta. Questo apparirà solo se il team proprietario della campagna servita ha un ID venditore configurato nell'interfaccia utente. L'esempio seguente mostra un annuncio con un sellerId e uno senza. ```json { "ads": [ { "id": "display_QqHaKRrKlFm1Wxr9c_DXJN4HSE3NzMzNjM2", "gtin": "7733636", "discount": { "amount": 0, "minPrice": 0, "maxPerCustomer": 0 }, "expiry": "2021-05-12T04:17:50.400902957Z", "position": 1 }, { "id": "display_NzsHqP0_iQedlo9VnrO2vqkwi_k3NzMzNjI4", "gtin": "7733628", "sellerId": "2834-ascre-2wcr4", "discount": { "amount": 0, "minPrice": 0, "maxPerCustomer": 0 }, "expiry": "2021-05-12T04:17:50.400908257Z", "position": 2 } ], "banners": [], "products": [], "memoryToken":"85ykKVv-luDHMWLZx2d6xcPq6sF7CgkJCSJDb3VudGVyIjogIjIiLAoJCQkiQWRzIjogWwoJCQkJImRpc3BsYXlfV05VV0NwQkRKMUpKNm5wdVZSVExvOU40TUxzNE1UWTBOemt5TWc9PSIsCgkJCQkiZGlzcGxheV9MME5NUHRxNmdCcVFvREJOd3J0dE9UTGJoWk0xTVRFeU9UYzRPUT09IiwKCQkJCSJkaXNwbGF5XzlCcEpmdUpaWk9VXzgyaWpFM3VCczgxd3VVczRNekkwTnpVeE5nPT0iLAoJCQkJImRpc3BsYXlfcW1VU1p4TkpMQ0lqeWQwdTFJRDk0RmxVZ0pnNE16STBOelV4Tnc9PSIsCgkJCQkiZGlzcGxheV9oeHlFZktCUnRrNWlxMThMQzE1SDJHcEN3QjgxTVRFeU9UYzVNQT09IiwKCQkJCSJkaXNwbGF5X1NkcjFEcU5aUEFtcGh0Q1FIUndoYUxFT1B0RXhNamsxT1RJNE5BPT0iLAoJCQkJImRpc3BsYXlfeVlSai1qV2Ntc2ozNzhrel9PMm0yOVlwTjhJeE5EazNPRE00TXc9PSIsCgkJCQkiZGlzcGxheV9Xbm9NZGZuLTRTVmhxcF9xQzVvLWxoT0paNm8xTkRJeE1UUTROdz09IgoJCQldLAoJCQkiVFRMIjogMTYyODk4NTYwMAoJCX0=" } ``` {% hint style="info" %} Se non sei sicuro delle stringhe in questa sezione, visita la [Riferimento per l'annuncio prodotto](/retail-media-interface/integration/it/references/product-ad-reference-1.md) pagina. {% endhint %} ## Digital Services Act Epsilon Retail Media aiuta i retailer a soddisfare i loro obblighi dell'Unione Europea (UE) [Legge sui servizi digitali](https://commission.europa.eu/strategy-and-policy/priorities-2019-2024/europe-fit-digital-age/digital-services-act_en) (DSA). Il DSA stabilisce un insieme unificato di regole in tutta l'UE, con l'obiettivo di regolamentare i contenuti online, la pubblicità trasparente e la disinformazione. Per ulteriori informazioni, consulta [Legge sui servizi digitali](/retail-media-interface/integration/it/feature-integrations/digital-services-act.md). ### Esempio di richiesta di annuncio ``` { "placement": "search-only", "catalogId": "zesty-fruits-catalog", "searchTerm": "lime", "maxNumberOfAds": 5, "options": { "filterMode": "AndOr", "includeAdvertiserInfo": true, }, } ``` ### Esempio di risposta di annuncio ``` { "ads": [ { "id": "display_QqHaKRrKlFm1Wxr9c_DXJN4HSE3NzMzNjM2", "gtin": "7733636", "discount": { "amount": 0, "minPrice": 0, "maxPerCustomer": 0 }, "expiry": "2021-05-12T04:17:50.400902957Z", "position": 1, "metadata": { "advertiserInfo": { "advertiser": "Bob's advertising agency", "onBehalfOf": "Brand company inc", } } }, .... ], "banners": [], "products": [], "memoryToken": "85ykKVv-………" } ``` --- # 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/generating-ads/product-ads/requesting-product-ads-1.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.