> 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/sk/generating-ads/product-ads/requesting-product-ads-1.md). # Žiadosť o produktové reklamy ## Žiadosť o reklamy Všetky žiadosti o reklamu na produkt vyžadujú kontextové `placement`, a `catalogId`, ako aj `maxNumberOfAds` , ktoré by ste chceli zobraziť zákazníkovi. Okrem toho by vaša žiadosť mala obsahovať kontextové `customerId` a `sessionId`. ### Umiestnenia vo vyhľadávaní Umiestnenia vo vyhľadávaní sú zvyčajne najjednoduchšie na vyžiadanie. Vyžadujú, aby v žiadosti boli špecifikované `searchTerm` , ako v príklade nižšie: ```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 } ``` ### Kategóriové umiestnenia Kategóriové umiestnenia vyžadujú, aby v žiadosti boli špecifikované `productFilters` . Príklad nižšie ukazuje, kde by ste poslali kategóriové filtre: ```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 } ``` Keď zákazníci prechádzajú ďalšie kategórie, musíte príslušne aktualizovať svoje API volanie. {% hint style="info" %} Najlepšia prax Najlepšou praxou je odosielať najnižšiu úroveň kategórie do vašej žiadosti o reklamu, Epsilon Retail Media keď zákazníci prechádzajú do hlbších kategórií. Namiesto špecifikovania reťazenej žiadosti na úrovni 3 v tvare L1 + L2 + L3 by ste špecifikovali iba kategóriu L3. {% endhint %} ### Kategóriové umiestnenia pre kros-sel Kategóriové umiestnenia pre kros-sel majú veľmi podobnú žiadosť ako kategóriové umiestnenia. Budete chcieť špecifikovať presnú kategóriu, pre ktorú žiadate reklamy. Zvyčajne ide o stránku, na ktorej sa nachádzate. Špecifikujte kategóriu v `productFilters` žiadosti. Príklad nižšie ukazuje, kde by ste poslali kategóriové filtre: ```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 } ``` Keď zákazníci prechádzajú ďalšie kategórie, musíte príslušne aktualizovať svoje API volanie. {% hint style="info" %} Spájanie organického a kros-selového kategóriového cielenia? Ak chcete spojiť žiadosť o organickú a kros-selovú kategóriovú reklamu do jedného umiestnenia, budete musieť pre svojich zákazníkov implementovať logiku spájania a doručovania. Je to zodpovednosť integrátora, hoci Epsilon Retail Media radi pomôžeme s konzultáciou. Všeobecne odporúčame zobrazovať organické kategóriové reklamy a umiestňovať kros-selové reklamy pre pozíciu a kategóriu až po organických umiestneniach. {% endhint %} ### Široké umiestnenia Široké umiestnenia, ako sú domovské stránky alebo stránky košíka, nevyžadujú, aby v žiadosti boli špecifikované akékoľvek `productFilters` . Akékoľvek filtre, ktoré by predajca chcel špecifikovať (v akcii, novinky atď.), môžu byť špecifikované v `productFilters` , aby sa zabezpečilo, že Epsilon Retail Media zobrazia iba reklamy zodpovedajúce požiadavkám. ```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 } ``` ### Vylepšenia žiadosti Pri umiestneniach vo vyhľadávaní, kategóriových a širokých umiestneniach vám odporúčame zvážiť nižšie uvedené vylepšenia na zlepšenie používateľského zážitku. #### Stránkovanie žiadostí Pri generovaní reklám na produkty dostanete `memoryToken` , ktorý je možné odoslať v nasledujúcich žiadostiach na vylúčenie predtým zobrazených reklám. Tento `memoryToken` potom môžete odoslať v nasledujúcej žiadosti o reklamu a Epsilon Retail Media vylúči akúkoľvek predtým zobrazenú reklamu pre rovnaký kontext z našej odpovede s reklamami. Pred implementáciou si prosím skontrolujte [Pagination](/retail-media-interface/integration/sk/feature-integrations/pagination.md) . ```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 } ``` #### Filtrované vyhľadávania Ak váš zákazník filtruje svoje vyhľadávanie, môžete rozšíriť svoj kontext a poskytnúť `productFilters`. Nižšie je príklad, kde zákazník filtruje podľa kategórie "Cupboard" a diétneho obmedzenia "Gluten-free". Rovnaký princíp je možné aplikovať na akékoľvek kategóriové alebo široké umiestnenie. ```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 } ``` #### Filtrovanie podľa lokality Ak synchronizujete filtre lokalít vo svojom katalógu, môžete rozšíriť svoj kontext tak, aby poskytoval lokalitu predajne zákazníka v `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 } ``` ## Odpoveď s reklamami na produkty Všetky odpovede s reklamami na produkty používajú rovnaký formát JSON. Reklamy na produkty sa vracajú v poli `ads` , ako v príklade nižšie: ```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=" } ``` Pole `id` je vaše ID reklamy použité v prehľadoch zobrazení a kliknutí. Pole `position` definuje pozíciu v Epsilon Retail Media dátach. Viac informácií o každom reťazci nájdete v referenčnej dokumentácii. {% hint style="info" %} Mali by ste si prečítať a rešpektovať pole `position` , aby sa zabezpečilo správne zobrazenie pre Fixné umiestnenie. {% endhint %} ### sellerId pre trhovisko Ak zapájate predajcov z trhoviska, v odpovedi môžete uvidieť dodatočné `sellerId` pre každú reklamu. Toto sa zobrazí iba vtedy, ak má tím, ktorý vlastní zobrazovanú kampaň, v UI nakonfigurované ID predajcu. Príklad nižšie zobrazuje jednu reklamu s sellerId a jednu bez neho. ```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" %} Ak si nie ste istí reťazcami v tejto sekcii, navštívte stránku [Product ad reference](/retail-media-interface/integration/sk/references/product-ad-reference-1.md) . {% endhint %} ## Digital Services Act Epsilon Retail Media pomáha predajcom plniť ich povinnosti v rámci Európskej únie (EÚ) [Digital Services Act](https://commission.europa.eu/strategy-and-policy/priorities-2019-2024/europe-fit-digital-age/digital-services-act_en) (DSA). DSA stanovuje jednotný súbor pravidiel naprieč EÚ so zameraním na reguláciu online obsahu, transparentnú reklamu a dezinformácie. Pre viac informácií si pozrite [Digital Services Act](/retail-media-interface/integration/sk/feature-integrations/digital-services-act.md). ### Príklad žiadosti o reklamu ``` { "placement": "search-only", "catalogId": "zesty-fruits-catalog", "searchTerm": "lime", "maxNumberOfAds": 5, "options": { "filterMode": "AndOr", "includeAdvertiserInfo": true, }, } ``` ### Príklad odpovede s reklamou ``` { "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/sk/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.