targetings에 넣을 타겟팅 ID와 옵션 ID를 찾거나, 옵션에 설정한 프로퍼티·이벤트 조건을 확인할 때 사용합니다.
이 API는 조회만 할 수 있습니다. 오디언스 타겟팅을 만들거나 수정하려면 콘솔을 사용하세요. 오디언스 타겟팅을 참고하세요. 문맥 타겟팅은 문맥 타겟팅 API로 다룹니다.
사전 준비
audience-targeting:read권한(scope)이 있는 API 키가 필요합니다. 이 권한은 콘솔 [관리] > [연동] 메뉴에서 선택할 수 없습니다. 에이드랍에 요청하면 권한을 넣은 키를 발급해 드리며, 광고 상품 API 권한도 같은 키에 함께 받을 수 있습니다.
기본 정보
429를 받으면 Retry-After 헤더에 적힌 시간(초)만큼 기다린 뒤 다시 보내세요. 서버가 바쁠 때는 요청을 하나씩 보내도 429를 받을 수 있습니다.
용어
API 경로와 필드 중 일부는 콘솔과 다른 이름을 씁니다. 이 문서는 콘솔의 용어를 씁니다.엔드포인트
경로는 Base URL 기준입니다. 모든 엔드포인트에audience-targeting:read 권한이 필요합니다.
타겟팅 객체
타겟팅 객체에는 옵션이 들어 있지 않습니다. 옵션은 옵션 목록 조회로 읽습니다.
타겟팅 목록 조회
프로젝트의 모든 오디언스 타겟팅을 콘솔에 보이는 순서대로, 페이지 나눔 없이 한 번에 반환합니다. 문맥 타겟팅은 포함되지 않습니다.요청
요청 예시
응답 예시
200 응답으로 타겟팅 객체 배열을 반환합니다.
타겟팅 조회
타겟팅 하나를 반환합니다.요청
요청 예시
응답
200 응답으로 타겟팅 객체를 반환합니다.
오류
404 TARGETING_NOT_FOUND: 타겟팅이 없거나, 다른 프로젝트의 타겟팅이거나, 문맥 타겟팅입니다.
옵션 객체
옵션 조회는 여기에
targeting(소속 타겟팅 ID), convertible, conditions를 더해 반환합니다.
옵션 목록 조회
타겟팅의 최상위 옵션을 콘솔에 보이는 순서대로 페이지 단위로 반환합니다. 옵션 그룹의 하위 옵션은parent로 따로 읽습니다.
요청
쿼리 파라미터
요청 예시
응답 예시
200 응답으로 items(옵션 객체 목록)와 next(다음 페이지 커서)를 반환합니다. next가 없으면 마지막 페이지입니다.
- 옵션 목록에는 조건이 없습니다. 조건은 옵션 조회로 읽습니다.
users가0이면 아직 사용자 통계가 쌓이지 않았거나 통계를 일시적으로 읽지 못한 것일 수 있습니다.0하나로 옵션을 판단하지 말고, 의심되면 잠시 뒤 다시 조회하세요.- 페이지를 읽는 도중 옵션이 추가·삭제·이동되면 결과가 실제와 달라질 수 있습니다.
next로 넣은 옵션이 그 사이 삭제되거나 옮겨지면404 TARGETING_CATEGORY_NOT_FOUND를 반환하니, 첫 페이지부터 다시 읽으세요.
오류
400 TARGETING_CATEGORY_NOT_SUPPORTED:parent가 옵션 그룹이 아닌 일반 옵션입니다.404 TARGETING_NOT_FOUND: 타겟팅이 없거나, 다른 프로젝트의 타겟팅이거나, 문맥 타겟팅입니다.404 TARGETING_CATEGORY_NOT_FOUND:next가 이 타겟팅의 최상위 옵션이 아니거나(삭제·이동됨),parent가 이 타겟팅의 옵션이 아닙니다.
옵션 조회
옵션 하나를 조건과 함께 반환합니다.요청
요청 예시
응답 예시
200 응답으로 옵션 객체에 다음 필드를 더해 반환합니다. users는 들어 있지 않습니다.
오류
404 TARGETING_CATEGORY_NOT_FOUND: 옵션이 없거나, 다른 프로젝트의 옵션이거나, 오디언스 타겟팅에 속한 옵션이 아닙니다.
조건
conditions는 옵션의 조건을 all(그리고)과 any(또는)로 묶은 트리입니다. 광고 송출에 실제로 쓰이는 조건과 같은 의미로 나타냅니다.
노드
- 가장 바깥은 항상
all또는any입니다. 조건이 하나뿐이면{ "all": [조건] }입니다. - 같은 종류의 노드를 겹쳐 쓰지 않습니다. 예를 들어
all안에all이 바로 오지 않습니다.
level이 10 이상이고, 최근 30일 안에 item_category가 book인 구매를 1회 이상 한 사용자) 또는 (성별이 F인 사용자)“입니다.
프로퍼티 조건
이벤트 조건
콘솔에서 이벤트 조건을 여러 개 이으면 광고 송출에서는 정해진 규칙으로 결합되므로, 콘솔에서 or로 이은 조건이 트리에서는
all로 나올 수 있습니다. 트리의 all과 any를 그대로 따르세요.
옵션 그룹의 조건
옵션 그룹은 자기 조건이 없고, 하위 옵션의 조건 중 하나를 만족하면 포함됩니다. 그래서 옵션 그룹의conditions는 하위 옵션 조건을 any로 합친 것입니다.
- 하위 옵션의 조건이
any로 시작하면 그 안의 조건이 바깥any에 바로 들어가므로, 갈래 수가 하위 옵션 수와 다를 수 있습니다. - 하위 옵션이 하나뿐이면
any로 감싸지 않고 그 하위 옵션의 조건을 그대로 반환합니다. - 조건이 없는 하위 옵션은 건너뜁니다.
조건을 읽을 수 없는 경우
두 값은 서로 관계없습니다.
convertible이 true이면서 operable이 false일 수도 있습니다.
오류 처리
오류 응답에는statusCode가 들어 있고, 아래 표에서 errorCode 칸이 -가 아닌 오류에는 errorCode도 들어 있습니다. 처리 방식은 errorCode로 나누고, errorCode가 없으면 statusCode로 나누세요. 요청 형식 오류(VALIDATION_FAILED)는 잘못된 위치를 detail.errors[]의 path로 알려 줍니다.