이 문서에서는 지정된 검색 기준에 따라 제품 광고를 생성하는 방법에 대한 종합적인 가이드를 제공합니다. 각 API 요청에는 다음과 같은 컨텍스트 관련 세부 정보가 포함되어야 합니다.

게재위치
카탈로그 ID
customerId
sessionId
검색어
표시할 최대 광고 수

사전 필수 조건

검색 게재 위치에 대한 제품 광고 요청을 시작하기 전에 다음 단계를 완료해야 합니다.

제품 광고 카탈로그 추가

제품이 카탈로그에 추가되고 Epsilon Retail Media Platform과 동기화되었는지 확인합니다.

캠페인 생성 및 검색어 구성

캠페인을 만들고 검색어를 구성했는지 확인합니다. 자세한 내용은 4b단계: 검색어 구성을 참조하세요.

제품 광고에 타기팅할 검색어를 정의합니다(포함 및 제외). 광고에 일치 검색, 구문 검색, 제외 검색어를 지정할 수 있습니다.

정확한 일치:
- 키워드와 정확히 일치하는 검색어를 타게팅합니다.
- 예: 키워드가 "파란색 운동화"인 경우 광고는 다른 단어 없이 정확한 순서로 "파란색 운동화"를 입력한 사용자에게만 표시됩니다.
문구 일치:
- 키워드와 정확히 일치하는 검색어를 타게팅합니다.
- 해당 문구 앞이나 뒤에 추가 단어가 포함된 검색에 광고가 표시됩니다.
- 예: 키워드가 "파란색 운동화"인 경우 광고는 다른 단어 없이 정확한 순서로 "파란색 운동화"를 입력한 사용자에게만 표시됩니다.
- 자세한 내용은 문구 일치 검색어를 참조하세요.
부정적 검색어:
- 캠페인에서 특정 단어나 문구를 제외합니다.
- 관련 없는 검색에 광고가 표시되지 않도록 합니다.
- 예: 신차 광고에 부정적 검색어로 "중고"를 추가하면 중고차를 찾는 사람들에게는 광고가 표시되지 않습니다.

API 키 및 기본 URL 가져오기

유효한 API 키가 있어야 합니다. 다음에 따라 API 키를 가져올 수 있습니다.
1. Epsilon Retail Media 팀 계정에 로그인합니다.
2. 페이지 오른쪽 상단으로 이동하여 드롭다운 메뉴를 클릭합니다.
3. 드롭다운 메뉴에서 통합 설정을 선택합니다.
4. API 키 탭을 클릭합니다. 초기 상태에는 비밀 API 키가 숨겨져 있습니다. 표시 버튼을 클릭하면 확인할 수 있습니다. 클릭 후 비밀 API 키를 복사합니다. API 호출 시 이 키를 사용합니다.
API 엔드포인트의 기본 URL이 있어야 합니다. (예: https://staging-test.citrusad.com/v1/ads/generate HTTP/1.1) 기술 계정 관리자에게 기본 URL을 요청하세요.

광고 생성

다음 단계를 수행하여 광고를 생성합니다.

HTTP 요청

엔드포인트: /v1/ads/generate

방법: POST

헤더:

수락: application/json
콘텐츠 유형: application/json
권한 부여: 기본 <API_KEY>

요청 매개 변수

요청 본문은 다음 필드를 포함하는 JSON 객체여야 합니다:

개체	유형	설명
customerId	문자열, 필수 항목	고객의 고유 식별자로 소매업체에서 제공합니다.
sessionId	문자열, 필수 항목	세션의 고유 식별자로 어트리뷰션에 필요하며 소매업체에서 제공합니다.
게재위치	문자열, 필수 항목	광고가 표시되는 컨텍스트입니다(예: '검색').
카탈로그 ID	문자열, 필수 항목	제품 광고가 필터링되는 제품 광고 카탈로그의 고유 식별자로 Epsilon의 소매 미디어 UI 또는 소매업체에서 CatalogID를 확인할 수 있습니다.
maxNumberOfAds	정수, 필수 항목	표시할 광고의 최대 수입니다.
검색어	문자열, 검색 게재 위치에 필수 항목	카탈로그 내에서 검색할 단어입니다.
옵션	개체, 선택 사항	필터링 모드 `AndOr`과 같은 추가 옵션으로 지정 시 시스템에서 "및"과 "또는" 조건을 모두 사용하여 검색 결과의 범위를 좁힙니다.

요청 예시

이 요청은 검색어와 관련된 최대 3개의 광고를 생성하는 데 사용됩니다. chocolate이러한 광고는 특정 고객(customerId: "wertg5432a") 및 세션(sessionId: "ec9-4e07-881d-3e9")에 대한 검색 결과에 표시됩니다. 광고는 catalogId: "628dbe95-2ec9-4e07-881D-3e9f92ab2e0b"로 식별된 카탈로그에서 생성되며 추가 필터링 옵션(filterMode: "AndOr")이 지정됩니다.

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9",
    "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
    "placement": "search",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "chocolate",
    "options": {
   						 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3    
}

응답 예시

📘
제품 광고에 대한 응답 수신 시 응답에는 일반적으로 이 예시의 GTIN과 같은 제품 코드가 포함됩니다. 소매업체는 광고 응답에 제공된 제품 코드를 사용하여 제품을 표시하는 데 필요한 메타데이터를 조회해야 합니다.
이 예시의 경우 "gtin": "024100191345"가 제품 코드입니다. 소매업체는 이 GTIN을 사용하여 특정 스폰서 제품 광고를 식별하고 표시합니다.

{
    "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": [],
}