문맥 타겟팅 API - Ad Control Help Center

문맥 타겟팅 API를 사용하면 서버에서 문맥 타겟팅을 관리할 수 있습니다. CMS의 섹션, 게시판, 태그를 타겟팅 옵션과 컨텍스트 ID에 대응시켜 두면, 콘텐츠가 바뀔 때마다 콘솔에서 일일이 수정하지 않고 자동으로 갱신할 수 있습니다. API는 콘솔의 문맥 타겟팅과 같은 데이터를 다룹니다. API로 만든 타겟팅은 콘솔에 표시되고, 콘솔에서 만든 타겟팅도 API로 조회할 수 있습니다.

사전 준비

context-targeting:read와 context-targeting:write 권한(scope)이 모두 있는 API 키가 필요합니다. 키는 프로젝트 소유자가 [관리] > [연동] 메뉴에서 발급하며, 이때 두 권한을 모두 선택합니다. 키 발급 방법은 연동 & API 키를 참고하세요.
이미 발급한 키의 권한은 바꿀 수 없습니다. 지금 쓰는 키에 두 권한 중 하나라도 없다면 새 키를 발급하고, 기존 키가 더 이상 필요 없으면 폐기하세요.

주로 쓰기 요청만 보내더라도 두 권한을 모두 부여하세요. 엔드포인트마다 확인하는 권한은 하나뿐이며, context-targeting:write에는 context-targeting:read가 포함되지 않습니다. 쓰기 권한만 있는 키는 모든 GET 요청에서 403을 받으므로 ID를 찾거나, 현재 컨텍스트 ID를 읽거나, 변경 사항이 로드됐는지 확인할 수 없습니다.

API는 서버에서만 호출하세요. 앱이나 웹 페이지에 API 키를 넣지 마세요.

기본 정보

항목	값
Base URL	`https://lake.adrop.io`
인증	`x-api-key` 헤더에 API 키를 넣습니다. 키로 프로젝트가 정해지므로 경로에는 프로젝트 ID가 들어가지 않습니다.
Content-Type	`application/json`
요청 본문 최대 크기	8 MB. 이보다 큰 요청은 `413`을 반환합니다.
ID 형식	서버가 발급하는 26자 ULID입니다(예: `01JAB3XK5Q8V7M2N4P6R9T0W1Y`). 올바른 ULID가 아닌 ID를 보내면 `400`을 반환합니다.
쓰기 처리	API는 프로젝트별로 쓰기 요청을 한 번에 하나씩 처리합니다. 다른 쓰기 요청이 처리되는 동안 보낸 요청은 `409 CONTEXT_TARGETING_WRITE_IN_PROGRESS`로 실패할 수 있으니, 쓰기 요청은 병렬로 보내지 말고 하나씩 차례로 보내세요. 읽기 요청은 영향을 받지 않습니다. 동시 쓰기를 참고하세요.

요청 한도 전체는 한도를 참고하세요.

용어

API 경로와 필드 중 일부는 콘솔과 다른 이름을 씁니다. 이 문서는 콘솔의 용어를 씁니다.

API	콘솔 용어	설명
`targeting`	타겟팅	”News Sections” 같은 문맥 타겟팅입니다. 이 API는 문맥 타겟팅만 다룹니다.
`category`	타겟팅 옵션(옵션)	“Sports”처럼 타겟팅에 속한 옵션입니다.
`contexts`	컨텍스트 ID	`sport`처럼 옵션에 등록된 ID입니다. 앱이나 웹사이트는 광고 요청에 이 ID를 `contextId`로 보냅니다.
`type: "collection"`	옵션 그룹	하위 옵션을 묶는 옵션입니다. 자신의 컨텍스트 ID와 하위 옵션의 컨텍스트 ID에 모두 매칭됩니다. 일반 옵션은 `type: "atomic"`입니다.
`children`, `parent`	하위 옵션	옵션 그룹 안에 있는 옵션입니다. 옵션 그룹의 `children`에는 하위 옵션 목록이, 하위 옵션의 `parent`에는 소속 옵션 그룹이 들어 있습니다.
`exposeChildren`	하위 옵션을 광고주에게 노출	광고주가 옵션 그룹의 하위 옵션을 하나씩 따로 선택할 수 있는지 여부입니다. 광고 송출에는 영향을 주지 않습니다.

엔드포인트

경로는 Base URL 기준입니다. 각 엔드포인트를 호출하려면 표에 적힌 권한이 필요합니다.

메서드	경로	권한	설명
`GET`	`/context-targeting`	`context-targeting:read`	타겟팅 목록 조회
`GET`	`/context-targeting/{targetingId}`	`context-targeting:read`	타겟팅 조회(옵션 포함)
`POST`	`/context-targeting`	`context-targeting:write`	타겟팅 생성(옵션도 함께 생성 가능)
`PATCH`	`/context-targeting/{targetingId}`	`context-targeting:write`	타겟팅 이름 변경
`DELETE`	`/context-targeting/{targetingId}`	`context-targeting:write`	타겟팅 삭제(모든 옵션 함께 삭제)
`POST`	`/context-targeting/bulk/create`	`context-targeting:write`	타겟팅 일괄 생성(요청당 최대 100개)
`POST`	`/context-targeting/bulk/update`	`context-targeting:write`	타겟팅 이름 일괄 변경(요청당 최대 100개)
`POST`	`/context-targeting/bulk/delete`	`context-targeting:write`	타겟팅 일괄 삭제(요청당 최대 100개)
`GET`	`/context-targeting/{targetingId}/categories`	`context-targeting:read`	타겟팅의 옵션 목록 조회(페이지 단위)
`GET`	`/context-targeting/category/{categoryId}`	`context-targeting:read`	옵션 조회(컨텍스트 ID 포함)
`POST`	`/context-targeting/{targetingId}/category`	`context-targeting:write`	타겟팅에 옵션 추가
`PATCH`	`/context-targeting/category/{categoryId}`	`context-targeting:write`	옵션 수정: 이름 변경, 컨텍스트 ID 변경, 이동, `exposeChildren` 설정
`DELETE`	`/context-targeting/category/{categoryId}`	`context-targeting:write`	옵션 삭제
`POST`	`/context-targeting/category/bulk/create`	`context-targeting:write`	옵션 일괄 추가(요청당 최대 5,000개)
`POST`	`/context-targeting/category/bulk/update`	`context-targeting:write`	옵션 일괄 수정(요청당 최대 5,000개)
`POST`	`/context-targeting/category/bulk/delete`	`context-targeting:write`	옵션 일괄 삭제(요청당 최대 5,000개)

일괄 작업 엔드포인트는 항목별 결과를 반환합니다. 일괄 작업 응답을 참고하세요.

빠른 시작

이 예시에서는 “News Sections” 타겟팅을 만들고, 옵션 하나의 컨텍스트 ID를 바꾼 뒤, 변경 사항이 로드됐는지 확인합니다.

타겟팅과 옵션 생성

요청 한 번으로 타겟팅과 옵션을 함께 만듭니다.

curl -X POST https://lake.adrop.io/context-targeting \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "News Sections",
    "categories": [
      { "name": "Sports", "contexts": ["sport", "baseball", "soccer"] },
      { "name": "Tech", "contexts": ["tech", "ai", "mobile"] }
    ]
  }'

201 응답으로 새 타겟팅이 반환됩니다. 타겟팅과 각 옵션의 _id를 저장해 두세요. 나중에 타겟팅을 변경할 때 필요합니다.

{
  "_id": "01JAB3XK5Q8V7M2N4P6R9T0W1Y",
  "name": "News Sections",
  "categories": [
    {
      "_id": "01JAB3XK5RA1B2C3D4E5F6G7H8",
      "name": "Sports",
      "type": "atomic",
      "contextCount": 3,
      "createdAt": "2026-10-13T01:23:45.000Z",
      "updatedAt": "2026-10-13T01:23:45.000Z"
    },
    {
      "_id": "01JAB3XK5RA1B2C3D4E5F6G7H9",
      "name": "Tech",
      "type": "atomic",
      "contextCount": 3,
      "createdAt": "2026-10-13T01:23:45.000Z",
      "updatedAt": "2026-10-13T01:23:45.000Z"
    }
  ],
  "categoryCount": 2,
  "createdAt": "2026-10-13T01:23:45.000Z",
  "updatedAt": "2026-10-13T01:23:45.000Z"
}

생성 요청은 멱등(idempotent)하지 않습니다. 요청이 타임아웃되어 다시 보내야 한다면 먼저 재시도와 중복 요청을 확인하세요.

컨텍스트 ID 추가·제거

섹션이 바뀌면 옵션의 컨텍스트 ID를 갱신합니다. add와 remove는 요청에 적은 ID만 바꿉니다.

curl -X PATCH https://lake.adrop.io/context-targeting/category/01JAB3XK5RA1B2C3D4E5F6G7H8 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contexts": {
      "add": ["basketball", "golf"],
      "remove": ["soccer"]
    }
  }'

200 응답으로 수정된 옵션이 반환됩니다.

{
  "_id": "01JAB3XK5RA1B2C3D4E5F6G7H8",
  "name": "Sports",
  "type": "atomic",
  "contextCount": 4,
  "createdAt": "2026-10-13T01:23:45.000Z",
  "updatedAt": "2026-10-13T01:30:00.000Z"
}

옵션의 컨텍스트 ID 전체를 한 번에 교체하려면 컨텍스트 ID 갱신 방법을 참고하세요.

변경 사항 로드 확인

타겟팅을 조회해 syncedAt을 수정 요청이 성공한 시각과 비교합니다.

curl "https://lake.adrop.io/context-targeting/01JAB3XK5Q8V7M2N4P6R9T0W1Y?includeCategories=false" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "_id": "01JAB3XK5Q8V7M2N4P6R9T0W1Y",
  "name": "News Sections",
  "categoryCount": 2,
  "syncedAt": 1791855005000,
  "createdAt": "2026-10-13T01:23:45.000Z",
  "updatedAt": "2026-10-13T01:30:06.000Z"
}

이전 단계의 수정은 2026-10-13T01:30:00.000Z(1791855000000)에 성공했습니다. syncedAt이 이보다 늦으므로 변경 사항은 로드됐고, 이후 몇 분 안에 광고 송출에 반영됩니다. syncedAt이 없거나 이보다 이르면 잠시 후 타겟팅을 다시 조회하세요. 자세한 내용은 변경 반영 시점을 참고하세요.

광고 요청에 컨텍스트 ID 전달

광고를 요청할 때 사용자가 보고 있는 페이지의 컨텍스트 ID를 contextId로 보냅니다. 변경 사항이 반영되면 contextId가 basketball인 광고 요청은 “Sports” 옵션에 매칭됩니다.광고 요청에서 컨텍스트 ID가 어떻게 쓰이는지는 문맥 타겟팅 만들기를 참고하세요.

변경 반영 시점

성공한 쓰기 요청은 즉시 저장됩니다. 이어서 Adrop이 프로젝트의 문맥 타겟팅을 광고 송출용으로 로드하며, 변경 사항은 보통 몇 분 안에 광고 송출에 반영됩니다. 변경 사항이 로드됐는지는 타겟팅의 syncedAt 필드(epoch 밀리초)로 확인합니다.

syncedAt은 해당 타겟팅의 가장 최근 로드가 시작된 시각입니다. syncedAt과 같거나 그 이전에 성공한 변경은 로드된 것이며, 이후 몇 분 안에 광고 송출에 반영됩니다.
새로 만든 타겟팅에는 syncedAt이 없습니다. 컨텍스트 ID를 변경(add, remove, set)하거나, 옵션을 추가하거나, 옵션을 이동·분리한 뒤에도 빠집니다. 보통 다음 로드가 끝나면 다시 나타납니다.
변경 시점에 이미 진행 중이던 로드는 syncedAt을 자신의 시작 시각, 즉 변경보다 이른 시각으로 설정할 수 있습니다. 그 로드에는 변경 사항이 포함되지 않았을 수 있지만, 이후 로드에는 포함됩니다.
이름 변경이나 삭제로는 syncedAt이 지워지지 않습니다.

따라서 syncedAt이 있는지 없는지로 판단하지 마세요. 요청이 성공한 시각을 기록해 두었다가, 타겟팅 조회에 includeCategories=false를 붙이는 식으로 변경 사항이 포함된 타겟팅을 조회하세요. syncedAt이 기록한 시각과 같거나 그보다 늦으면 변경 사항이 로드된 것입니다. syncedAt은 Adrop 서버 시각을 기준으로 하므로, 사용하는 서버의 시각과 차이가 날 수 있다면 여유를 두고 비교하세요.

변경 사항이 반영되기 전까지 광고 요청은 이전 컨텍스트 ID를 기준으로 매칭됩니다. 새 컨텍스트 ID는 앱이나 웹사이트가 광고 요청에 그 ID를 보내기 시작하기 전에 미리 추가하세요.

타겟팅

타겟팅 조회, 생성, 이름 변경, 삭제

타겟팅 옵션

옵션을 추가하고 컨텍스트 ID를 최신 상태로 유지하는 방법

옵션 그룹

옵션을 옵션 그룹의 하위 옵션으로 묶는 방법

오류와 한도

오류 코드, 한도, 재시도 방법

연동 & API 키

API 키 발급과 관리

문맥 타겟팅 만들기

문맥 타겟팅과 컨텍스트 ID의 동작 방식

타겟팅 판매하기

타겟팅을 광고 상품에 연결해 광고주에게 판매하는 방법

​사전 준비

​기본 정보

​용어

​엔드포인트

​빠른 시작

​변경 반영 시점

​관련 문서

타겟팅

타겟팅 옵션

옵션 그룹

오류와 한도

연동 & API 키

문맥 타겟팅 만들기

타겟팅 판매하기

사전 준비

기본 정보

용어

엔드포인트

빠른 시작

변경 반영 시점

관련 문서