> 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/ko/generating-ads/product-ads/requesting-product-ads-1.md). # 상품 광고 요청 ## 광고 요청 모든 상품 광고 요청에는 컨텍스트의 `placement`, 그리고 `catalogId`,뿐만 아니라 `maxNumberOfAds` 고객에게 표시하고자 하는 항목입니다. 또한 요청에는 컨텍스트의 `customerId` 및 `sessionId`. ### 검색 지면 검색 지면은 일반적으로 요청하기 가장 쉽습니다. 아래 예시와 같이 요청에 `searchTerm` 를 지정해야 합니다. ```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 } ``` ### 카테고리 지면 카테고리 지면은 요청에 `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": "category", "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b", "productFilters": [ ["category:Cupboard/Snacks"] ], "options": { "filterMode": "AndOr" }, "maxNumberOfAds": 3 } ``` 추가 카테고리를 둘러볼 때 그에 맞게 API 호출을 업데이트해야 합니다. {% hint style="info" %} 권장 사항 광고 요청 시 가장 하위 수준의 카테고리를 전송하여 Epsilon Retail Media 고객이 더 깊은 카테고리로 탐색함에 따라 효과를 높이는 것이 권장 사항입니다. L1 + L2 + L3의 레벨 3에서 체인 요청을 지정하는 대신 L3 카테고리만 지정하면 됩니다. {% endhint %} ### 교차 판매 카테고리 지면 교차 판매 카테고리 지면은 카테고리 지면과 매우 유사한 요청을 가집니다. 광고를 요청할 정확한 카테고리를 지정해야 합니다. 이는 일반적으로 현재 있는 페이지입니다. `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": "category-cross-sell", "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b", "productFilters": [ ["category:Cupboard/Snacks"] ], "options": { "filterMode": "AndOr" }, "maxNumberOfAds": 3 } ``` 추가 카테고리를 둘러볼 때 그에 맞게 API 호출을 업데이트해야 합니다. {% hint style="info" %} 자연스러운 카테고리 타겟팅과 교차 판매 카테고리 타겟팅을 병합하시겠습니까? 자연스러운 카테고리 광고 요청과 교차 판매 카테고리 광고 요청을 단일 지면으로 병합하려면 고객에게 병합 및 전달 로직을 구현해야 합니다. 이는 통합 담당자의 책임이지만 Epsilon Retail Media 상담을 언제든지 환영합니다. 일반적으로 자연스러운 카테고리 광고를 먼저 노출하고, 자연스러운 지면 뒤에 카테고리 교차 판매 광고를 위치시키는 것을 권장합니다. {% endhint %} ### 확장 검색 지면 홈 페이지나 결제 페이지와 같은 확장 지면은 요청에 별도의 `productFilters` 를 지정할 필요가 없습니다. 리테일러가 지정하고자 하는 모든 필터(제안 중, 신상품 등)는 `productFilters` 에 지정하여 Epsilon Retail Media 가 요구 사항 내에서만 광고를 제공하도록 할 수 있습니다. ```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 } ``` ### 요청 개선 사항 검색, 카테고리 및 확장 검색 지면에서는 사용자 경험을 향상시키기 위해 아래의 개선 사항을 고려하는 것이 좋습니다. #### 요청 페이지네이션 상품 광고를 생성할 때 이전 요청에서 제공된 광고를 제외하기 위해 이후 요청에서 보낼 수 있는 `memoryToken` 를 받게 됩니다. 그런 다음 이 `memoryToken` 후속 광고 요청 시 및 Epsilon Retail Media 동일한 컨텍스트에 대해 이전에 제공된 모든 광고를 광고 응답에서 제외합니다. 검토해 주세요 [페이지네이션](/retail-media-interface/integration/ko/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 } ``` #### 필터링된 검색 고객이 검색 결과를 필터링하는 경우 컨텍스트를 확장하여 다음을 제공할 수 있습니다. `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"] ], "options": { "filterMode": "AndOr" }, "maxNumberOfAds": 3 } ``` #### 위치별 필터링 카탈로그에서 위치 필터를 동기화하는 경우 컨텍스트를 확장하여 고객의 매장 위치를 제공할 수 있습니다. `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 } ``` ## 상품 광고 응답 모든 상품 광고 응답은 동일한 JSON 형식을 따릅니다. 상품 광고는 다음에 반환됩니다. `ads` 배열, 아래 예시와 같이: ```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=" } ``` 이 `id` 필드는 노출 및 클릭 보고서에 사용되는 광고 ID입니다. `position` 필드는 다음에서의 위치를 정의합니다. Epsilon Retail Media 페이로드. 각 문자열에 대한 자세한 내용은 참조 문서를 참조하세요. {% hint style="info" %} 다음을 읽고 준수해야 합니다. `position` 고정 게재 지면이 올바르게 표시되도록 하기 위한 필드입니다. {% endhint %} ### 마켓플레이스 sellerId 마켓플레이스 판매자를 온보딩하는 경우 추가적인 정보를 볼 수 있습니다. `sellerId` 응답의 광고당. 이는 제공되는 캠페인을 소유한 팀의 seller ID가 UI에 구성되어 있는 경우에만 표시됩니다. 아래 예시는 sellerId가 있는 광고 하나와 없는 광고 하나를 보여줍니다. ```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" %} 이 섹션의 문자열에 대해 잘 모르는 경우 다음을 방문하세요. [상품 광고 참조 문서](/retail-media-interface/integration/ko/references/product-ad-reference-1.md) 페이지. {% endhint %} ## 디지털 서비스법 Epsilon Retail Media 유통업체가 유럽 연합(EU) 규정을 준수하도록 지원합니다. [디지털 서비스법](https://commission.europa.eu/strategy-and-policy/priorities-2019-2024/europe-fit-digital-age/digital-services-act_en) (DSA) 의무. DSA는 온라인 콘텐츠 규제, 투명한 광고 및 허위 정보를 목표로 EU 전역에 통일된 규칙 세트를 설정합니다. 자세한 내용은 다음을 참조하세요. [디지털 서비스법](/retail-media-interface/integration/ko/feature-integrations/digital-services-act.md). ### 예시 광고 요청 ``` { "placement": "search-only", "catalogId": "zesty-fruits-catalog", "searchTerm": "lime", "maxNumberOfAds": 5, "options": { "filterMode": "AndOr", "includeAdvertiserInfo": true, }, } ``` ### 예시 광고 응답 ``` { "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/ko/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.