파트너 API
가이드

카테고리 게재 위치를 사용하여 제품 광고 생성

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

  • customerId
  • sessionId
  • 게재위치
  • 카탈로그 ID
  • productFilters
  • 표시할 최대 광고 수

사전 필수 조건

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

제품 광고 카탈로그 추가

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

캠페인 생성 및 카테고리 구성

캠페인을 만들고 카테고리를 구성했는지 확인합니다. 자세한 내용은 4단계: 타깃 기준 구성을 참조하세요.

API 키 및 기본 URL 가져오기

  1. 유효한 API 키가 있어야 합니다. 다음에 따라 API 키를 가져올 수 있습니다.

    1. Epsilon Retail Media 팀 계정에 로그인합니다.

    2. 페이지 오른쪽 상단으로 이동하여 드롭다운 메뉴를 클릭합니다.

    3. 드롭다운 메뉴에서 통합 설정을 선택합니다.

    4. API 키 탭을 클릭합니다. 초기 상태에는 비밀 API 키가 숨겨져 있습니다. 표시 버튼을 클릭하면 확인할 수 있습니다. 클릭 후 비밀 API 키를 복사합니다. API 호출 시 이 키를 사용합니다.

  2. 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 객체여야 합니다. 카테고리 게재 위치 지정 시 productFilters 요청 본문에 포함되어야 합니다.

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

요청 예시

JSON 요청은 "찬장/스낵" 카테고리와 관련된 광고의 카테고리 개제 위치를 지정하는 데 사용됩니다. 여기에는 고객 ID, 세션 ID, 카탈로그 ID, 필터링 옵션이 포함되며 최대 광고 수를 3개로 설정합니다.

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": "category",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 ["category:Cupboard/Snacks"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}

교차 판매 카테고리 게재 위치에 대한 광고 생성

교차 판매 카테고리 게재 위치는 일반 카테고리 게재 위치와 비슷하지만 특별히 교차 판매 제품의 타기팅 광고에 사용됩니다. 교차 판매 시나리오에서는 사용자가 현재 탐색 중인 카테고리를 기반으로 상호 보완적인 제품을 추천하는 것을 목표로 합니다.

광고를 생성할 정확한 카테고리를 지정해야 합니다. 이 카테고리는 일반적으로 사용자가 탐색 중인 현재 페이지에 표시되는 카테고리입니다.

요청 예시

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", 
    "placement": "category-cross-sell",
    "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 ["category:Cupboard/Snacks"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}

오가닉 및 교차 판매 카테고리 타게팅 병합

오가닉 광고(조회 중인 카테고리와 관련된 광고)와 교차 판매 광고(관련 카테고리 또는 제품에 대한 광고)를 단일 광고 게재 위치에 결합하려는 경우 이 통합을 직접 관리해야 합니다. 여기에는 두 가지 유형의 광고를 병합하고 함께 표시하는 로직을 작성하는 작업이 포함됩니다.

모범 사례:

  • 오가닉 광고 우선: 현재 카테고리와 관련된 광고(오가닉 광고)가 먼저 표시됩니다.
  • 교차 판매 광고 나중: 오가닉 광고가 실행된 후 관련 카테고리 또는 제품에 대한 광고(교차 판매 광고)를 표시합니다.

카테고리 기반 광고 타게팅을 위한 모범 사례

사용자가 여러 카테고리를 탐색할 시에는 현재 탐색 중인 카테고리를 반영하도록 API 호출을 업데이트하는 것이 중요합니다. 이렇게 하면 표시되는 광고가 사용자의 탐색 컨텍스트와 관련성을 유지할 수 있습니다.

Epsilon Retail Media 플랫폼에 광고 요청 시 가장 구체적인(가장 낮은 수준) 카테고리를 전송하는 것이 좋습니다. 가장 심층적인 카테고리 레벨을 타기팅하면 사용자에게 더욱 관련성 높고 정확하게 타기팅된 광고를 제공할 수 있습니다.

시나리오 예시

사용자가 일반 카테고리에서 탐색을 시작한 다음 보다 구체적인 하위 카테고리로 이동합니다.

초기 API 호출

사용자가 "홈" 카테고리를 탐색하는 경우:

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": "category",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 ["category:Home"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}

API 호출 업데이트

사용자가 "홈 > 가구" 하위 카테고리로 이동하는 경우:

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": "category",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 ["category:Home/Furniture"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}

최종 API 호출

사용자가 "홈 > 가구 > 의자" 하위 카테고리로 이동하는 경우:

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": "category",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 ["category:Home/Furniture/Chairs"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}

사용자가 검색하는 가장 구체적인 카테고리를 반영하도록 API 호출을 업데이트하면 관련성이 높은 광고가 제공될 수 있습니다. 여러 카테고리 수준(L1 + L2 + L3)에 걸쳐 연결된 요청을 지정하는 대신 가장 관련성 높은 카테고리 수준(L3)을 지정하는 것이 좋습니다.

다음 단계

업데이트됨 5개월 전