파트너 API
API 참조

제품 광고 요청

광고 요청

모든 광고 요청에는 다음이 필요합니다. 컨텍스트의 placement, catalogId, 고객에게 표시할 maxNumberOfAds . 또한 요청에 다음이 포함되어야 합니다. 컨텍스트의 customerId 및 sessionId.

검색 게재위치

검색 게재위치는 일반적으로 요청하기 가장 쉬운 항목으로 아래 예와 같이 요청에 searchTerm 을 지정해야 합니다.

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    
}

카테고리 게재위치

카테고리 게재위치의 경우 요청에 productFilters 를 지정할 필요가 없습니다. 아래 예시는 카테고리 필터를 전송할 위치를 표시합니다.

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
}

추가 카테고리가 검토되므로 API 호출을 적절하게 업데이트해야 합니다.

📘

모범 사례

고객이 카테고리 심층 탐색 시 CatrusAd에 가장 낮은 수준의 카테고리를 보내는 것이 가장 좋습니다.

L1 + L2 + L3의 수준 3에 체인 요청을 지정하는 대신 L3 카테고리만 지정합니다.

교차 판매 카테고리 게재위치

교차 판매 카테고리 게재위치는 카테고리 게재위치와 요청 방식이 매우 유사합니다. 귀하는 광고 요청 시 정확한 카테고리를 지정하고 싶을 것입니다. 다음은 일반적으로 현재 사용 중인 페이지입니다. 요청의 productFilters 에 카테고리를 지정하십시오. 아래 예시는 카테고리 필터를 전송할 위치를 표시합니다.

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

추가 카테고리가 검토되므로 API 호출을 적절하게 업데이트해야 합니다.

📘

오가닉 및 교차 판매 카테고리 타게팅을 병합하시겠습니까?

오가닉 및 교차 판매 카테고리 광고 요청을 단일 게재위치로 병합하려면 고객에게 병합 및 전달 로직을 실행해야 합니다. CitrusAd에서 자세히 상담해 드리나 이는 통합 담당자의 직무입니다.

일반적으로 오가닉 게재위치 후에 오가닉 카테고리 광고, 위치 및 카테고리 교차 판매 광고를 표시하는 것이 좋습니다.

광범위 일치 게재위치

홈 또는 체크아웃 페이지 등의 광범위한 게재위치에서는 요청에 productFilters 를 지정할 필요가 없습니다. 소매업체가 지정하려는 모든 필터(프로모션, 신상품 등)는 CitrusAd가 요구 사항을 충족하는 광고만 제공하도록 productFilters CitrusAd가 요구 사항 내에서 광고만 제공할 수 있습니다.

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

요청 개선

검색, 카테고리 및 광범위한 일치 게재위치에서는 사용자 경험을 향상시키기 위해 아래의 개선사항을 고려해야 합니다.

페이지 매김 요청

제품 광고 생성 시 이전에 게재된 광고를 제외하기 위한 후속 요청에서 보낸 memoryToken 이는 이전에 제공된 광고를 제외하기 위해 후속 요청에서 전송될 수 있습니다. 그런 다음 이 memoryToken 을 후속 광고 요청에서 보낼 수 있으며 CitrusAd는 동일한 컨텍스트에 대해 이전에 실행된 광고를 광고 반응에서 제외합니다.

실행하기 전에 페이지 매김 을 검토하십시오.

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",
    "memoryToken":"85ykKVv-luDHMWLZx2d6xcPq6sF7CgkJCSJDb3VudGVyIjogIjIiLAoJCQkiQWRzIjogWwoJCQkJImRpc3BsYXlfV05VV0NwQkRKMUpKNm5wdVZSVExvOU40TUxzNE1UWTBOemt5TWc9PSIsCgkJCQkiZGlzcGxheV9MME5NUHRxNmdCcVFvREJOd3J0dE9UTGJoWk0xTVRFeU9UYzRPUT09IiwKCQkJCSJkaXNwbGF5XzlCcEpmdUpaWk9VXzgyaWpFM3VCczgxd3VVczRNekkwTnpVeE5nPT0iLAoJCQkJImRpc3BsYXlfcW1VU1p4TkpMQ0lqeWQwdTFJRDk0RmxVZ0pnNE16STBOelV4Tnc9PSIsCgkJCQkiZGlzcGxheV9oeHlFZktCUnRrNWlxMThMQzE1SDJHcEN3QjgxTVRFeU9UYzVNQT09IiwKCQkJCSJkaXNwbGF5X1NkcjFEcU5aUEFtcGh0Q1FIUndoYUxFT1B0RXhNamsxT1RJNE5BPT0iLAoJCQkJImRpc3BsYXlfeVlSai1qV2Ntc2ozNzhrel9PMm0yOVlwTjhJeE5EazNPRE00TXc9PSIsCgkJCQkiZGlzcGxheV9Xbm9NZGZuLTRTVmhxcF9xQzVvLWxoT0paNm8xTkRJeE1UUTROdz09IgoJCQldLAoJCQkiVFRMIjogMTYyODk4NTYwMAoJCX0=",
    "options": {
                         "filterMode": "AndOr"
                             },
    "maxNumberOfAds": 3    
}

필터링된 검색

고객이 검색을 필터링하는 경우 컨텍스트를 확장하여 productFilters를 제공할 수 있습니다. 아래는 고객이 "찬장" 및 식이 제한 "글루텐 프리" 카테고리로 필터링하는 예시입니다. 이와 동일한 방식을 모든 카테고리 또는 광범위한 일치 게재위치에 적용할 수 있습니다.

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",
    "productFilters": [
     	 ["category:Cupboard"],["dietary:Gluten-free"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}

위치별 필터링

카탈로그에서 위치 필터를 동기화하는 경우 아래 예와 같이 컨텍스트를 확장하여 productFilters:

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",
    "productFilters": [
     	 ["category:Cupboard"],["dietary:Gluten-free"],["location:Westenbury"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}

제품 광고 반응

모든 제품 광고 반응은 동일한 JSON 형식을 따릅니다. 제품 광고는 아래의 예시와 같이 ads 배열로 반환됩니다.

{
    "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 필드는 CitrusAd 페이로드의 위치를 정의합니다. 각 문자열에 대한 자세한 정보는 참조를 확인하십시오.

📘

고정 테넌시 배치가 올바르게 표시되도록 하려면 position 필드를 잘 읽고 준수해야 합니다.

마켓플레이스 sellerId

마켓플레이스 셀러의 경우 반응에 광고당 추가 sellerId 가 표시될 수 있습니다. 이것은 실행 중인 캠페인을 소유한 팀이 UI에 구성된 Seller Id를 가지고 있는 경우에만 나타납니다. 아래는 SellerId가 있는 광고와 SellerId가 없는 광고의 예시입니다.

{
    "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="
}

📘

이 섹션의 문자열에 대해 알아보려면 제품 광고 참조 페이지를 방문하십시오.