이 문서에서는 지정된 검색 기준에 따라 제품 광고를 생성하는 방법에 대한 종합적인 가이드를 제공합니다. 각 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	문자열, 필수 항목	세션의 고유 식별자로 어트리뷰션에 필요하며 소매업체에서 제공합니다.
dtmcookieid	문자열, 필수 항목	dtmCookieId는 Epsilon의 퍼스트 파티 쿠키에서 가져옵니다. 이를 통해 사용자 상호 작용을 정확하게 추적 및 어트리뷰션할 수 있습니다.
게재위치	문자열, 필수 항목	광고가 표시되는 컨텍스트입니다(예: '검색').
카탈로그 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": [],
}