옵션 그룹 - Ad Control Help Center

옵션 그룹은 다른 옵션을 묶는 타겟팅 옵션이며, 옵션 그룹에 묶인 옵션을 하위 옵션이라고 합니다. API로 옵션 그룹을 만들고, 하위 옵션을 추가하거나 옮기고, 광고주가 하위 옵션을 하나씩 선택할 수 있게 할지 정할 수 있습니다. 이 페이지의 요청에는 context-targeting:write 권한이 있는 API 키가 필요합니다. 옵션 그룹을 조회하려면 context-targeting:read 권한이 필요합니다. 사전 준비를 참고하세요. 예시에서는 News Sections 타겟팅(01JAB3XK5Q8V7M2N4P6R9T0W1Y)에 Sports 옵션 그룹을 만들고, 하위 옵션으로 Baseball과 Soccer를 둡니다. 옵션 이름은 타겟팅 안에서 고유해야 하므로, 이 타겟팅에 Sports라는 이름의 다른 옵션은 없다고 가정합니다.

옵션 그룹이란

옵션 그룹은 자체 컨텍스트 ID와 하위 옵션의 컨텍스트 ID에 모두 매칭됩니다. 아래 구조에서 Sports를 포함한 캠페인은 컨텍스트 ID가 sport, baseball, soccer 중 하나인 광고 요청에 매칭됩니다.

옵션	유형	자체 컨텍스트 ID	매칭되는 컨텍스트 ID
Sports	옵션 그룹	`sport`	`sport`, `baseball`, `soccer`
Baseball	Sports의 하위 옵션	`baseball`	`baseball`
Soccer	Sports의 하위 옵션	`soccer`	`soccer`

한 단계 구조: 하위 옵션은 항상 일반 옵션(type: "atomic")입니다. 옵션 그룹은 항상 최상위 옵션이며, 옵션 그룹 안에 다른 옵션 그룹을 넣을 수 없습니다.
비워 둘 수 없음: 옵션 그룹에는 하위 옵션이나 자체 컨텍스트 ID가 하나 이상 있어야 합니다.
자체 컨텍스트 ID는 고유: 옵션 그룹의 자체 컨텍스트 ID는 프로젝트 안의 다른 옵션 그룹의 자체 컨텍스트 ID와 겹칠 수 없습니다. 제약 사항을 참고하세요.
이름: 옵션 그룹과 하위 옵션의 이름은 이름 규칙을 따르며, 옵션 그룹과 하위 옵션을 포함한 타겟팅 안의 모든 옵션 사이에서 고유해야 합니다. 이름이 겹치면 409 TARGETING_CATEGORY_NAME_DUPLICATE로 실패합니다.

옵션 객체에서 옵션 그룹과 하위 옵션에는 다음 필드가 있습니다.

필드	타입	설명
`type`	string	옵션 그룹은 `collection`입니다. 하위 옵션은 `atomic`입니다.
`contextCount`	number	옵션 그룹의 경우 매칭되는 컨텍스트 ID 수(자체 컨텍스트 ID와 하위 옵션의 컨텍스트 ID, 중복 제외)
`ownContextCount`	number	옵션 그룹 전용. 자체 컨텍스트 ID 수
`exposeChildren`	boolean	옵션 그룹 전용. 하위 옵션을 광고주에게 노출하는지 여부. 설정한 적이 없으면 `false`
`children`	string[]	옵션 그룹 전용. 처음 50개 하위 옵션의 ID
`childCount`	number	옵션 그룹 전용. 전체 하위 옵션 수
`parent`	string	하위 옵션 전용. 속한 옵션 그룹의 ID

옵션 그룹을 조회할 때는 다음을 참고하세요.

옵션 조회는 contexts에 옵션 그룹의 자체 컨텍스트 ID만 반환하며, offset과 limit으로 페이지를 나눠 읽습니다(전체 개수는 ownContextCount). 하위 옵션의 컨텍스트 ID는 각 하위 옵션을 조회해 확인하세요.
childCount가 50보다 크면 옵션 목록 조회에서 parent 쿼리 파라미터에 옵션 그룹 ID를 지정해 하위 옵션 전체를 조회하세요.

옵션 그룹이나 하위 옵션의 이름 또는 컨텍스트 ID를 바꿀 때는 다른 옵션과 마찬가지로 옵션 수정을 사용합니다. 옵션 그룹에 contexts를 보내면 자체 컨텍스트 ID만 바뀝니다. 변경 사항은 잠시 후 광고 송출에 반영됩니다. 변경 반영 시점을 참고하세요.

옵션 그룹 만들기

옵션 추가와 같은 엔드포인트에 type: "collection"이나 children, 또는 둘 다를 보냅니다. children의 각 항목은 옵션 그룹과 함께 새 하위 옵션으로 생성됩니다.

요청

POST /context-targeting/{targetingId}/category

경로 파라미터

파라미터	타입	필수	설명
`targetingId`	string	O	옵션 그룹을 추가할 타겟팅의 ID

요청 본문

필드	타입	필수	설명
`name`	string	O	옵션 그룹 이름
`type`	string	-	`collection`. `children`을 보내면 생략할 수 있습니다
`contexts`	string[]	-	옵션 그룹의 자체 컨텍스트 ID
`children`	object[]	-	옵션 그룹과 함께 만들 하위 옵션
`children[].name`	string	O	하위 옵션 이름
`children[].contexts`	string[]	-	하위 옵션의 컨텍스트 ID
`exposeChildren`	boolean	-	하위 옵션을 광고주에게 노출할지 여부. 기본값은 `false`. 하위 옵션을 광고주에게 노출을 참고하세요

children에 항목을 하나 이상 넣거나 contexts에 컨텍스트 ID를 하나 이상 넣어야 합니다. 둘 다 없는 옵션 그룹은 400 TARGETING_CATEGORY_NOT_SUPPORTED로 실패합니다. type: "atomic"과 children을 함께 보내도 같은 오류로 실패합니다.
children의 항목에는 name과 contexts만 넣을 수 있습니다. 하위 옵션은 자신의 하위 옵션을 가질 수 없습니다.
옵션 그룹의 자체 컨텍스트 ID 중 하나라도 프로젝트 안의 다른 옵션 그룹이 이미 자체 컨텍스트 ID로 가지고 있으면 400 TARGETING_COLLECTION_CONTEXT_DUPLICATED로 실패합니다. 제약 사항을 참고하세요.
새 옵션 그룹도 새 최상위 옵션이므로, 다른 새 옵션과 마찬가지로 광고 상품과 캠페인에 미치는 영향이 적용됩니다.

타겟팅 생성 시 categories의 각 항목에 같은 필드를 넣어 옵션 그룹을 만들 수도 있고, 옵션 일괄 추가로 만들 수도 있습니다.

요청 예시

curl -X POST https://lake.adrop.io/context-targeting/01JAB3XK5Q8V7M2N4P6R9T0W1Y/category \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sports",
    "type": "collection",
    "contexts": ["sport"],
    "children": [
      { "name": "Baseball", "contexts": ["baseball"] }
    ]
  }'

하위 옵션 없이 자체 컨텍스트 ID만으로 옵션 그룹을 만들려면 type: "collection"을 그대로 두고 children을 생략합니다.

{
  "name": "Sports",
  "type": "collection",
  "contexts": ["sport"]
}

응답 예시

201과 함께 새 옵션 그룹을 반환합니다.

{
  "_id": "01JAB3XK5SB1C2D3E4F5G6H7J8",
  "name": "Sports",
  "type": "collection",
  "contextCount": 2,
  "ownContextCount": 1,
  "exposeChildren": false,
  "children": ["01JAB3XK5TC1D2E3F4G5H6J7K8"],
  "childCount": 1,
  "createdAt": "2026-10-13T01:23:45.000Z",
  "updatedAt": "2026-10-13T01:23:45.000Z"
}

옵션 그룹에 옵션 추가

기존 옵션 그룹에 새 하위 옵션을 추가하려면 옵션 추가 엔드포인트에 parent로 옵션 그룹 ID를 보냅니다.

parent는 같은 타겟팅에 있는 최상위 옵션 그룹이어야 합니다. 타겟팅에 해당 ID의 옵션이 없으면 404 TARGETING_CATEGORY_NOT_FOUND로 실패합니다. 그 옵션이 옵션 그룹이 아니면 400 TARGETING_CATEGORY_NOT_SUPPORTED로 실패합니다.
새 옵션은 일반 옵션입니다. parent와 함께 type: "collection", children, exposeChildren 중 하나라도 보내면 400 TARGETING_CATEGORY_NOT_SUPPORTED로 실패합니다.
옵션 그룹은 새 옵션의 컨텍스트 ID에도 매칭되기 시작합니다. 옵션 그룹을 포함한 캠페인은 이 컨텍스트 ID도 타겟팅하고, 옵션 그룹을 제외한 캠페인은 이 컨텍스트 ID도 제외합니다. 광고 상품 설정은 바뀌지 않습니다.

기존 옵션을 옵션 그룹에 넣으려면 옵션 이동과 분리를 참고하세요.

요청

POST /context-targeting/{targetingId}/category

경로 파라미터

파라미터	타입	필수	설명
`targetingId`	string	O	옵션 그룹이 있는 타겟팅의 ID

요청 본문

필드	타입	필수	설명
`name`	string	O	하위 옵션 이름
`contexts`	string[]	-	하위 옵션의 컨텍스트 ID
`parent`	string	O	옵션을 추가할 옵션 그룹의 ID

요청 예시

curl -X POST https://lake.adrop.io/context-targeting/01JAB3XK5Q8V7M2N4P6R9T0W1Y/category \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Soccer",
    "contexts": ["soccer"],
    "parent": "01JAB3XK5SB1C2D3E4F5G6H7J8"
  }'

응답 예시

201과 함께 새 하위 옵션을 반환합니다.

{
  "_id": "01JAB3XK5TC1D2E3F4G5H6J7K9",
  "name": "Soccer",
  "type": "atomic",
  "contextCount": 1,
  "parent": "01JAB3XK5SB1C2D3E4F5G6H7J8",
  "createdAt": "2026-10-13T01:25:10.000Z",
  "updatedAt": "2026-10-13T01:25:10.000Z"
}

옵션 이동과 분리

옵션의 위치를 바꾸려면 옵션 수정에 parent를 보냅니다.

옵션 그룹 ID를 보내면 옵션이 최상위나 다른 옵션 그룹에서 그 옵션 그룹 아래로 이동합니다.
null을 보내면 하위 옵션이 옵션 그룹에서 분리되어 최상위로 이동합니다.

이동	광고 상품과 캠페인에 미치는 영향
최상위 → 옵션 그룹	광고 상품에 있던 이 옵션 자체의 설정이 삭제됩니다. 광고 상품에서 이 옵션을 필수 포함 또는 필수 제외로 설정했거나, 종료되지 않은 캠페인이 이 옵션을 포함하거나 제외하고 있으면 `400 TARGETING_CATEGORY_LOCKED`로 이동이 실패합니다(삭제·취소된 캠페인과 광고주가 임시 저장한 캠페인은 해당하지 않습니다). 먼저 이 설정을 해제하세요.
옵션 그룹 → 최상위	옵션이 광고 상품과 캠페인에 있던 옵션 그룹의 설정을 이어받으므로, 옵션 그룹을 포함하거나 제외한 캠페인은 계속 이 옵션의 컨텍스트 ID를 포함하거나 제외합니다. 이로 인해 광고 상품에서 필수 포함 또는 필수 제외로 설정된 옵션이 500개를 넘게 되면 `400 AD_PRODUCT_TARGETING_POLICY_LIMIT_EXCEEDED`로 실패합니다.
옵션 그룹 → 다른 옵션 그룹	광고 상품과 캠페인은 바뀌지 않습니다.

옵션이 들어온 옵션 그룹은 그 옵션의 컨텍스트 ID에 매칭되기 시작하고, 옵션이 빠져나간 옵션 그룹은 더 이상 매칭되지 않습니다.

옵션 그룹은 이동할 수 없습니다. 옵션 그룹에 parent를 보내면 400 TARGETING_CATEGORY_NOT_SUPPORTED로 실패합니다.
옮길 위치는 같은 타겟팅에 있는 최상위 옵션 그룹이어야 합니다. 그렇지 않으면 404 TARGETING_CATEGORY_NOT_FOUND 또는 400 TARGETING_CATEGORY_NOT_SUPPORTED로 실패합니다.
자체 컨텍스트 ID가 없는 옵션 그룹의 마지막 하위 옵션은 이동하거나 분리할 수 없습니다. 이 요청은 400 TARGETING_CATEGORY_NOT_SUPPORTED로 실패합니다.

이 이동 제한은 필수 포함, 필수 제외 설정이나 캠페인의 포함·제외 설정이 자동으로 생긴 경우에도 적용됩니다(예: 옵션을 옵션 그룹에서 분리하거나 옵션 그룹을 삭제할 때 옵션 그룹의 설정을 이어받은 경우). 이 설정을 해제하기 전에는 API로 이 옵션을 다시 옵션 그룹 아래로 옮길 수 없습니다. 옵션을 옵션 그룹 안에 두려면 처음부터 parent나 children으로 만드세요.

요청

PATCH /context-targeting/category/{categoryId}

경로 파라미터

파라미터	타입	필수	설명
`categoryId`	string	O	옮길 옵션의 ID

요청 본문

필드	타입	필수	설명
`parent`	string 또는 null	O	옵션을 옮길 옵션 그룹의 ID, 또는 최상위로 분리하려면 `null`
`name`	string	-	새 이름. 이동과 함께 적용되며, 이동이 실패하면 이름도 바뀌지 않습니다

parent는 contexts와 함께 보낼 수 없습니다. 컨텍스트 ID는 별도 요청으로 변경하세요.

요청 예시

Soccer를 최상위로 분리합니다.

curl -X PATCH https://lake.adrop.io/context-targeting/category/01JAB3XK5TC1D2E3F4G5H6J7K9 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "parent": null }'

다시 Sports 아래로 옮기려면 대신 옵션 그룹 ID를 보냅니다.

{
  "parent": "01JAB3XK5SB1C2D3E4F5G6H7J8"
}

응답 예시

200과 함께 수정된 옵션을 반환합니다. 분리된 옵션에는 parent가 없습니다.

{
  "_id": "01JAB3XK5TC1D2E3F4G5H6J7K9",
  "name": "Soccer",
  "type": "atomic",
  "contextCount": 1,
  "createdAt": "2026-10-13T01:25:10.000Z",
  "updatedAt": "2026-10-13T01:30:00.000Z"
}

하위 옵션을 광고주에게 노출

기본적으로 광고주는 옵션 그룹을 통째로만 선택할 수 있습니다. exposeChildren을 true로 설정하면 광고주가 캠페인을 예약할 때 하위 옵션을 하나씩 포함하거나 제외할 수 있습니다.

광고 상품에서 옵션 그룹을 자유 선택으로 제공할 때만 광고주가 하위 옵션을 선택할 수 있습니다. 타겟팅 판매하기를 참고하세요.
exposeChildren은 옵션 그룹이 매칭되는 컨텍스트 ID를 바꾸지 않습니다. 이 값을 바꿔도 기존 광고 상품과 캠페인은 변경되지 않습니다.
exposeChildren은 옵션 그룹에만 보낼 수 있습니다. 다른 옵션에 보내면 400 TARGETING_CATEGORY_NOT_SUPPORTED로 실패합니다. 값은 true 또는 false로 보내야 하며, null은 400으로 실패합니다.
옵션 그룹을 만들 때 함께 설정할 수도 있습니다.

요청

PATCH /context-targeting/category/{categoryId}

경로 파라미터

파라미터	타입	필수	설명
`categoryId`	string	O	옵션 그룹 ID

요청 본문

필드	타입	필수	설명
`exposeChildren`	boolean	O	`true`이면 하위 옵션을 광고주에게 노출하고, `false`이면 숨깁니다

같은 요청에 name과 contexts를 함께 보낼 수 있습니다.

요청 예시

curl -X PATCH https://lake.adrop.io/context-targeting/category/01JAB3XK5SB1C2D3E4F5G6H7J8 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "exposeChildren": true }'

응답 예시

200과 함께 수정된 옵션 그룹을 반환합니다.

{
  "_id": "01JAB3XK5SB1C2D3E4F5G6H7J8",
  "name": "Sports",
  "type": "collection",
  "contextCount": 3,
  "ownContextCount": 1,
  "exposeChildren": true,
  "children": ["01JAB3XK5TC1D2E3F4G5H6J7K8", "01JAB3XK5TC1D2E3F4G5H6J7K9"],
  "childCount": 2,
  "createdAt": "2026-10-13T01:23:45.000Z",
  "updatedAt": "2026-10-13T01:35:00.000Z"
}

옵션 그룹 삭제

옵션 그룹은 옵션 삭제로 삭제합니다. 하위 옵션은 삭제되지 않습니다.

하위 옵션은 최상위로 이동하고, 광고 상품과 캠페인에 있던 옵션 그룹의 설정을 이어받습니다. 예를 들어 광고 상품에서 Sports를 필수 포함으로 설정했다면 Baseball과 Soccer가 필수 포함이 되고, Sports를 포함했던 캠페인은 Baseball과 Soccer를 포함하게 됩니다.
옵션 그룹의 자체 컨텍스트 ID는 삭제되어 더 이상 매칭되지 않습니다. 위 예시에서 Sports를 포함했던 캠페인은 더 이상 sport에 매칭되지 않습니다.
설정을 이어받은 결과 광고 상품에서 필수 포함 또는 필수 제외로 설정된 옵션이 500개를 넘게 되면 400 AD_PRODUCT_TARGETING_POLICY_LIMIT_EXCEEDED로 실패하고, 아무것도 삭제되지 않습니다.

캠페인이 옵션 그룹을 사용하고 있어도 삭제는 막히지 않습니다. 하위 옵션이 없는 옵션 그룹이라면, 이 옵션 그룹을 포함했던 캠페인에서는 그 조건이 사라집니다. 광고 상품과 캠페인에 미치는 영향을 참고하세요.

콘솔에서 그룹을 삭제하면 하위 옵션도 함께 삭제됩니다. API로 옵션 그룹을 삭제하면 콘솔의 그룹 해제처럼 하위 옵션이 최상위 옵션으로 남습니다.

요청

DELETE /context-targeting/category/{categoryId}

경로 파라미터

파라미터	타입	필수	설명
`categoryId`	string	O	옵션 그룹 ID

요청 예시

curl -X DELETE https://lake.adrop.io/context-targeting/category/01JAB3XK5SB1C2D3E4F5G6H7J8 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

응답 예시

200과 함께 삭제된 옵션 그룹의 ID를 반환합니다.

{
  "_id": "01JAB3XK5SB1C2D3E4F5G6H7J8"
}

제약 사항

구조

옵션 그룹은 이동할 수 없고, 옵션의 유형은 만든 뒤에 바꿀 수 없습니다. 기존 옵션을 묶으려면 옵션 그룹을 만든 뒤 옵션을 그 아래로 옮기세요. 새 옵션 그룹은 비워 둘 수 없으므로 자체 컨텍스트 ID나 새 하위 옵션을 넣어 만드세요.
children으로 만든 하위 옵션도 요청당·타겟팅당 옵션 수 한도에 포함됩니다. 한도를 참고하세요.

옵션 그룹의 자체 컨텍스트 ID는 옵션 그룹 사이에서 고유

옵션 그룹의 자체 컨텍스트 ID는 프로젝트 안의 다른 옵션 그룹의 자체 컨텍스트 ID와 겹칠 수 없으며, 다른 옵션 그룹이 어느 문맥 타겟팅에 있든 마찬가지입니다. 일반 옵션과 하위 옵션은 어떤 옵션과도 컨텍스트 ID가 겹쳐도 됩니다.
이 규칙은 옵션 그룹을 만들 때와 add나 set으로 옵션 그룹에 자체 컨텍스트 ID를 추가할 때 적용됩니다. 겹치면 400 TARGETING_COLLECTION_CONTEXT_DUPLICATED로 실패하며, detail.conflicts에는 겹치는 컨텍스트 ID가 최대 20개까지, 각 컨텍스트 ID를 이미 가진 옵션 그룹과 함께 담깁니다. 오류 코드를 참고하세요.

옵션 그룹은 비워 둘 수 없음

요청	결과
자체 컨텍스트 ID가 없는 옵션 그룹의 마지막 하위 옵션을 삭제·이동·분리	`400 TARGETING_CATEGORY_NOT_SUPPORTED`. 대신 옵션 그룹을 삭제하세요. 하위 옵션은 최상위로 이동합니다.
하위 옵션이 없는 옵션 그룹의 마지막 자체 컨텍스트 ID를 `remove`나 `set: []`로 제거	`400 TARGETING_CATEGORY_NOT_SUPPORTED`

자체 컨텍스트 ID가 있는 옵션 그룹은 하위 옵션이 모두 없어져도 됩니다. 이때는 자체 컨텍스트 ID만 가진 옵션 그룹으로 남습니다. 일괄 요청당 옵션 그룹 관련 항목 수 옵션 일괄 요청 하나에 넣을 수 있는 옵션 그룹 관련 항목은 최대 150개입니다. 이보다 많으면 요청 전체가 400으로 실패하고 아무것도 적용되지 않습니다. 항목을 나눠 요청을 하나씩 차례로 보내세요.

일괄 요청	옵션 그룹 관련 항목
옵션 일괄 추가	옵션 그룹을 만드는 항목(`type: "collection"` 또는 `children`)과 `parent`가 있는 항목
옵션 일괄 수정	`parent`가 있는 항목(`null` 포함)
옵션 일괄 삭제	옵션 그룹과 하위 옵션의 ID

일괄 삭제에서는 오류 코드가 TARGETING_CATEGORY_TREE_ITEMS_LIMIT_EXCEEDED입니다. detail.limit은 한도이고, detail.count는 요청에 포함된 옵션 그룹과 하위 옵션의 수입니다.
옵션 그룹 이름 변경, 자체 컨텍스트 ID 변경, exposeChildren 설정은 옵션 그룹 관련 항목으로 세지 않습니다.

옵션 그룹과 그 하위 옵션을 같은 일괄 요청으로 삭제하지 마세요 결과가 ids 안의 순서에 따라 달라집니다.

옵션 그룹이 먼저인 경우: 하위 옵션이 최상위로 이동해 옵션 그룹의 설정을 이어받은 뒤, 최상위 옵션으로 삭제됩니다. 옵션 그룹을 포함했던 캠페인에서 그 조건이 사라질 수 있습니다.
하위 옵션이 먼저인 경우: 옵션 그룹에 자체 컨텍스트 ID가 없으면 마지막 하위 옵션의 삭제가 400 TARGETING_CATEGORY_NOT_SUPPORTED로 실패합니다. 이 옵션은 이후 옵션 그룹이 삭제될 때 최상위로 이동합니다.

​옵션 그룹이란

​옵션 그룹 만들기

​요청

​경로 파라미터

​요청 본문

​요청 예시

​응답 예시

​옵션 그룹에 옵션 추가

​요청

​경로 파라미터

​요청 본문

​요청 예시

​응답 예시

​옵션 이동과 분리

​요청

​경로 파라미터

​요청 본문

​요청 예시

​응답 예시

​하위 옵션을 광고주에게 노출

​요청

​경로 파라미터

​요청 본문

​요청 예시

​응답 예시

​옵션 그룹 삭제

​요청

​경로 파라미터

​요청 예시

​응답 예시

​제약 사항

옵션 그룹이란

옵션 그룹 만들기

요청

경로 파라미터

요청 본문

요청 예시

응답 예시

옵션 그룹에 옵션 추가

요청

경로 파라미터

요청 본문

요청 예시

응답 예시

옵션 이동과 분리

요청

경로 파라미터

요청 본문

요청 예시

응답 예시

하위 옵션을 광고주에게 노출

요청

경로 파라미터

요청 본문

요청 예시

응답 예시

옵션 그룹 삭제

요청

경로 파라미터

요청 예시

응답 예시

제약 사항