> 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/partner/ko/partner-api-overview/campaign-field-definitions.md).
# 캠페인 필드 정의
## 공통 캠페인 필드
이 섹션에서는 상품 광고, 배너, 배너 X와 같은 다양한 유형에 걸쳐 공통으로 사용되는 캠페인 필드를 이해하는 데 도움이 되는 간단한 설명과 예시를 제공합니다. 각 항목에는 필드의 목적과 플랫폼을 위한 대표적인 구현 예시가 포함되어 있습니다.
| 필드 | 목적 및 예시 |
| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | 캠페인을 쉽게 식별할 수 있도록 'Cadbury Chocolate June Clearance'와 같이 홍보하는 제품, 기간 또는 전략과 같은 세부 정보를 포함하는 것이 좋습니다. 이름은 최대 255자까지 입력할 수 있습니다. |
| `namespaceId` | 기본 URL에 위치한 네임스페이스의 고유 식별자입니다. 예를 들어, exampleretailer.citrusad.com에서 namespaceId is exampleretailer.
네임스페이스로 제공한 ID에 대한 리소스가 존재하는지 확인하세요.
|
| `approval.state` | 캠페인의 승인 상태는 지정된 열거형 값만 사용할 수 있습니다. 지원되는 상태는 다음과 같습니다. APPROVAL\_STATE\_APPROVED, APPROVAL\_STATE\_REJECTED, APPROVAL\_STATE\_PENDING.
다음은APPROVAL\_STATE\_UNSPECIFIED 사용할 수 없습니다.
|
| `approval.rejectionReason` | 캠페인이 거부된 이유입니다. 상태가 다음과 같은 경우 필수 필드입니다. `APPROVAL_STATE_REJECTED`. |
| `campaignState` | 캠페인의 활성 상태는 활성, 일시 중지, 초안 또는 보관됨 여부를 나타냅니다. 예를 들어, CAMPAIGN\_STATE\_ACTIVE, CAMPAIGN\_STATE\_DRAFT, CAMPAIGN\_STATE\_UNSPECIFIED.
다음은 CAMPAIGN\_STATE\_UNSPECIFIED 사용할 수 없습니다.
|
| `teamId` | 는 teamId 캠페인 팀의 고유 식별자입니다.
지정된 팀 ID에 대해 리소스가 존재하고 아카이브 플래그가 설정되어 있지 않은지 확인합니다. 또한 템플릿 팀 ID는 캠페인 팀 ID와 일치해야 합니다.
|
| `startTime` | 정확한 ISO-8601 타임스탬프를 사용한 캠페인 시작 시간입니다. 예: 2024-09-01T12:00:00Z.
다음의 경우 이 값을 생략합니다: always on 캠페인.
|
| `endTime` | 캠페인 종료 시간은 정확한 ISO-8601 타임스탬프를 사용하며, 다음이 지정된 경우 반드시 설정해야 합니다: startTime . 예: 2024-09-30T23:59:59Z. 종료 시간은 시작 시간 이후여야 합니다.
다음의 경우 이 값을 생략합니다:always on 캠페인.
|
| `walletId` | 캠페인 비용이 청구될 지갑의 고유 식별자입니다. 예: wallet\_123456789.
- If campaignType 이 'Wildcard'가 아닌 경우 해당 ID에 대한 개체가 존재해야 합니다.
- 지갑 팀 ID는 캠페인 팀 ID와 일치해야 합니다.
- 지갑의 통화 코드는 캠페인 카탈로그의 통화 코드와 일치해야 합니다. 확실하지 않은 경우 고객 통합 엔지니어(CIE)에게 문의하세요.
|
| `placementId` | 캠페인 게재 위치의 고유 식별자입니다. 예: placement\_987654321.
지정된 게재 위치 ID에 대해 리소스가 존재하고 올바른 캠페인에 대응하는지 확인합니다.
|
| `catalogIds` | 리테일러 카탈로그의 고유 식별자입니다. 예: \["329f1e08-d3ee-4e04-90c4-068b3ce6b856","6c29a96a-f55a-497f-b03a-2fed85dd7198" ].
지정된 카탈로그 ID에 대해 리소스가 존재하고 올바른 캠페인에 대응하는지 확인합니다.
|
| `advertisedProducts.
productsByKey` | 캠페인에서 광고하는 제품 코드와 카탈로그 ID의 조합입니다. 캠페인이 두 개의 카탈로그에 표시되는 경우 카탈로그-제품 쌍을 두 개 제공하십시오.
예를 들어, \[{"catalogId": "14edbbc5-a7be-4c54-9f35-767b4ee29fd3","productCode": "ABC123"}].
|
| `targeting.searchTerms` | 캠페인이 타겟팅할 검색어 및 해당 매치 유형입니다. 이 정보는 검색 지면에 대해서만 포함하십시오. 예를 들어, `{"matchType": "MATCH_TYPE_EXACT_MATCH","phrase": "string"}`}. |
| `targeting.excludeFilters` | 타겟팅 단계에서 제외할 필터로, 다음과 일치하는 위치 또는 카테고리 필터여야 합니다: filterClassId. 대부분의 연동에서는 이러한 값을 생략할 수 있습니다. 두 개의 필터 클래스를 사용하는 경우 필터 클래스당 하나의 객체를 지정하십시오.
{"excludeFilters": \[ \
{ \
"catalogId": "76df36b4-45a2-46a5-9308-3dd14861d76e", \
"filter": "category:chocolate" \
}, \
{ \
"catalogId": "76df36b4-45a2-46a5-9308-3dd14861d76e", \
"filter": "location:florida" \
} \
] \
}
|
| `targeting.includeFilters` | 캠페인에서 타겟팅할 명시적 필터입니다. 표준 연동의 경우 이 항목을 생략하십시오. 권장되는 경우 또는 고정 게재 캠페인을 생성할 때만 이 필드를 채우십시오.
{"includeFilters": \[ \
{ \
"catalogId": "76df36b4-45a2-46a5-9308-3dd14861d76e", \
"filter": "category:flavoured-milk" \
} \
] \
}
|
| `targeting.negativeSearchTerms` | 음수 검색어는 캠페인에서 특정 단어나 문구를 제외하여 관련 없는 검색에 광고가 표시되지 않도록 합니다. 이 전략은 타겟 고객을 구체화하고 비용을 절감하며 캠페인 효율성을 높입니다. 예를 들어, `used` 를 새 차 광고의 음수 검색어로 추가하면 중고차를 찾는 사람들에게 광고가 표시되는 것을 방지할 수 있습니다. |
| `targeting.crossSell` | 크로스셀 지면의 타겟팅을 지정합니다. |
| `targeting.crossSell.
targetProductsByKey` | 타겟팅할 명시적 카탈로그 제품 쌍을 지정합니다.
\[{"catalogId": "14edbbc5-a7be-4c54-9f35-767b4ee29fd3","productCode": "ABC123"}]
- 타겟 제품 카탈로그는 캠페인 카탈로그와 일치해야 합니다.
- 각 제품-카탈로그 쌍에 대해 제품이 존재해야 합니다.
- 타겟 제품은 광고 대상 제품에 포함될 수 없습니다.
- 타겟 제품과 광고 대상 제품은 일치하는 카테고리를 공유해야 합니다.
|
| `targeting.upSell.
targetProductsByKey` | 타겟팅할 명시적 카탈로그 제품 쌍을 지정합니다.
\[{"catalogId": "14edbbc5-a7be-4c54-9f35-767b4ee29fd3","productCode": "ABC123"}]
|
| `strategy.auction.maxBid` | 캠페인의 최대 클릭당 비용(CPC) 입찰가입니다. 예를 들어 2.99입니다.
- 유효한 BigDecimal이어야 합니다.
- 최소 입찰가보다 커야 합니다.
},
"strategy": {
"auction": {
"maxBid": "string",
"spendLimit": {
"daily": "string",
"total": "string"
}
},
|
| `strategy.auction.spendLimit` | 캠페인의 일일 또는 총 최대 지출을 지정합니다.
이 항목은 always on 캠페인의 경우 생략하십시오. 해당 캠페인은 지갑에 잔액이 있는 한 지출을 계속합니다. 예: "daily": "1000". 지출 한도가 0보다 큰 BigDecimal 값인지 확인하십시오.
},
"strategy": {
"auction": {
"maxBid": "string",
"spendLimit": {
"daily": "string",
"total": "string"
}
},
|
| `strategy.fixedTenancy.cost` | 캠페인의 총비용을 나타내며, 보고 목적으로만 사용되고 지갑에서 차감되지 않습니다. 리테일러가 전체 패키지 또는 수주서(IO)에 대해 최적화하는 경우 이 값을 업데이트할 수 있습니다. 예: 1000.99.
"fixedTenancy": {
"cost": "1000.99",
"positions": \[
0
],
"catalogCosts": \[
{
"catalogId": "string",
"catalogCostPercentage": 0
}
]
}
|
| `strategy.fixedTenancy.
catalogCostPercentage` | 각 카탈로그에 할당된 비용의 비율을 나타내는 0과 1 사이의 값입니다. 여러 카탈로그를 사용하는 경우 비율(예: 0.5)을 할당합니다. 단일 카탈로그의 경우 값 1을 사용합니다.
"fixedTenancy": {
"cost": "string",
"positions": \[
0
],
"catalogCosts": \[
{
"catalogId": "string",
"catalogCostPercentage": 0.5
}
]
}
|
| `strategy.fixedTenancy.
fixedCosts` | 캠페인과 관련된 외부 데이터, 크리에이티브 작업 또는 기타 서비스에 대한 추가 비용을 지정합니다. 이 요금은 캠페인이 승인될 때 적용되며 수정할 수 없습니다. 광고주에게 추가 비용이 적용되지 않는 한 이 항목을 생략하세요.
{
"dataCost": "150",
"creativeCost": "200",
"otherCost": "400"
}
|
| `fixedCosts.dataCost` | 캠페인의 데이터와 관련된 비용입니다. 예: $100.00. |
| `fixedCosts.creativeCost` | 캠페인의 크리에이티브 제작과 관련된 비용입니다. 예: $200.00. |
| `fixedCosts.otherCost` | 캠페인의 기타 경비와 관련된 비용입니다. 예: $50.00. |
| `customFields.customFieldId` | 구성 중인 고유한 customFieldId를 지정합니다. 맞춤 필드는 표준 연동에 필요하지 않으며 고객 연동 엔지니어(CIE)의 안내가 없는 한 이 필드를 사용하지 않을 가능성이 높습니다.
{
"customFieldId": "3e31d3e4-bf15-411b-a18e-5553f08a6122",
"content": "PO-12345"
}
|
| `customFields.content` | 캠페인의 맞춤 필드 내용입니다.
{
"customFieldId": "3e31d3e4-bf15-411b-a18e-5553f08a6122",
"content": "PO-12345"
}
|
| `customQuestions.customQuestionId` | 구성 중인 고유한 맞춤 타겟팅 질문을 지정합니다. 맞춤 질문은 표준 연동에 필요하지 않으며 고객 연동 엔지니어(CIE)의 안내가 없는 한 이 필드를 사용하지 않을 가능성이 높습니다.
{
"answers": \[
"preference:delivery",
"preference:online"
],"customQuestionId": "593a9860-5ce4-4dcc-b6c4-15cf6fb08426"
}
|
| `customQuestions.answers` | 고객 타겟팅을 위해 광고주가 선택한 답변을 지정합니다. customer targetingData values와 일치해야 합니다.
{
"answers": \[
"preference:delivery",
"preference:online"
],"customQuestionId": "593a9860-5ce4-4dcc-b6c4-15cf6fb08426"
}
|
## Banner X 캠페인 필드
| 필드 | 목적 및 예시 |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `contentStandardId` | 콘텐츠 표준의 고유 식별자입니다. 콘텐츠 표준은 웹사이트 또는 디지털 플랫폼의 지정된 공간 내에 배너 광고가 표시되는 방식을 규정하는 지침 및 기술 매개변수입니다.
이 식별자는 생성된 배너 X 에셋이 리테일러의 콘텐츠 표준을 준수하는지 확인하는 데 필요합니다.
|
| `slotId` | 'homepage\_banner\_slot\_1'과 같은 구성 내 슬롯의 고유 식별자입니다. 이 식별자는 배너가 싱글 타일, 더블 타일 또는 배너와 같이 리테일러가 정의한 올바른 슬롯을 사용하도록 보장합니다. |
| `slotType` | 이미지가 배치될 콘텐츠 표준 내의 고유한 슬롯입니다. 이미지가 사전 정의된 슬롯 요구 사항 및 검증을 준수하도록 보장합니다. 예로는 left\_ribbon, top\_banner 또는 side\_panel 등이 있습니다. |
| `headingText` | 배너의 제목 텍스트입니다. |
| `bannerText` | 배너 텍스트는 배너 광고에 표시되는 텍스트입니다. |
| `bannerTextColourHex` | 16진수 형식의 배너 텍스트 색상입니다. |
| `ctaFlag` | 배너에 행동 유도(CTA)가 활성화되어 있는지 여부를 나타내는 플래그입니다. |
| `ctaText` | 배너의 행동 유도 텍스트입니다. 행동 유도(CTA)는 사용자가 구매를 하거나 다른 페이지를 방문하는 등의 행동을 취하도록 유도하는 클릭 가능한 텍스트 또는 버튼입니다. 예: "Shop Now". |
| `ctaTextAccessibility` | 접근성 목적의 행동 유도 텍스트입니다. |
| `ctaLink` | 행동 유도 링크의 URL입니다. |
| `backgroundColourHex` | 16진수 형식의 배너 X 기본 배경 이미지 색상입니다. |
| `backgroundImageId` | 기본 배경 이미지의 고유 식별자입니다. |
| `backgroundImagePosition` | 컨테이너 내 기본 배경 이미지의 정렬 또는 위치입니다. |
| `secondaryBackgroundImageId` | 보조 배경 이미지의 고유 식별자입니다. |
| `secondaryBackgroundImagePosition` | 컨테이너 내 보조 배경 이미지의 정렬 또는 위치입니다. |
| `heroImageId` | 히어로 이미지의 고유 식별자입니다. 히어로 이미지는 일반적으로 제품이나 로고를 표시하는 데 사용되는 주요 프로모션 이미지입니다. |
| `heroImageAltText` | 접근성을 돕는 히어로 이미지의 대체 텍스트입니다. |
| `heroMode` | 히어로 섹션의 디스플레이 모드 또는 스타일입니다. |
| `secondaryHeroImageId` | 보조 히어로 이미지의 고유 식별자입니다. |
| `secondaryHeroImageAltText` | 접근성을 돕는 보조 히어로 이미지의 대체 텍스트입니다. |
| `secondaryHeroMode` | 보조 히어로 섹션의 디스플레이 모드 또는 스타일입니다. |
| `trackingTags` | 배너 X 캠페인의 성과를 모니터링하고 분석하기 위해 추적 제공업체 및 관련 태그를 지정하는 데 사용되는 필수 객체 배열입니다. |
| `additionalFields` | 배너 X에 대한 추가 구성 옵션을 제공하는 필수 객체 배열입니다. |
## 배너 캠페인 필드
| 필드 | 목적 및 예시 |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `contentStandardId` | 콘텐츠 표준의 고유 식별자입니다. 콘텐츠 표준은 웹사이트 또는 디지털 플랫폼의 지정된 공간 내에 배너 광고가 표시되는 방식을 규정하는 지침 및 기술 매개변수입니다.
이 식별자는 생성된 배너 에셋이 리테일러의 콘텐츠 표준을 준수하는지 확인하는 데 필요합니다.
|
| `slotId` | 'homepage\_banner\_slot\_1'과 같은 구성 내 슬롯의 고유 식별자입니다. 이 식별자는 배너가 싱글 타일, 더블 타일 또는 배너와 같이 리테일러가 정의한 올바른 슬롯을 사용하도록 보장합니다. |
| `artworkImageId` | 배너용으로 업로드된 아트워크 이미지의 고유 식별자입니다. 이 ID(fileId)는 Upload the creative assets API에 의해 반환됩니다. |
| `link` | 이것은 배너 슬롯에 연결된 URL로, 사용자가 광고를 클릭할 때 대상 페이지로 이동시킵니다. 예: |
| `altText` | 접근성 목적의 아트워크 이미지를 설명하는 대체 텍스트입니다. 예: 'Promotional banner for summer sale'. |
| `text` | 배너의 디스플레이 텍스트입니다. 추가 정보나 메시지를 제공하는 슬롯의 디스플레이 텍스트입니다. 예: 'Get 20% off your first purchase!' |
| `trackingTags` | 슬롯과의 상호작용을 모니터링하는 데 사용되는 제공업체의 추적 태그 목록입니다. 예: \[ { provider: 'Google Analytics', tag: 'promo\_click' }, { provider: 'Adobe Analytics', tag: 'banner\_view' } ]. 이러한 태그는 제3자 검증을 위해 광고에 포함됩니다. |
---
# 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/partner/ko/partner-api-overview/campaign-field-definitions.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.