Skip to main content
광고 유닛 API를 사용하면 서버에서 광고 유닛을 만들고 관리할 수 있습니다. API로 만든 유닛은 콘솔에 바로 표시되며, 유닛 ID는 SDK 연동과 광고 상품 API의 소재 세트에 사용합니다. API는 콘솔의 광고 유닛과 같은 데이터를 다룹니다. 콘솔에서 만든 유닛도 API로 조회하고 수정할 수 있습니다.

사전 준비

  • ad-unit:read와 ad-unit:write 권한(scope)이 있는 API 키가 필요합니다. 이 두 권한은 콘솔 [관리] > [연동] 메뉴에서 선택할 수 없습니다. 에이드랍에 요청하면 권한을 넣은 키를 발급해 드리며, 앱 API와 광고 상품 API 권한도 같은 키에 함께 받을 수 있습니다.
  • 두 권한은 따로 확인합니다. ad-unit:write만 있는 키는 조회(GET) 요청에서 403을 받습니다. 만들기·수정 응답에는 유닛 전체가 담기지만, 유닛을 따로 조회하려면 ad-unit:read도 필요합니다.
  • 유닛을 만들 앱의 ID는 앱 API로 조회합니다.
API는 서버에서만 호출하세요. 앱이나 웹 페이지에 API 키를 넣지 마세요.

기본 정보

429를 받으면 Retry-After 헤더에 적힌 시간(초)만큼 기다린 뒤 다시 보내세요. 서버가 바쁠 때는 요청을 하나씩 보내도 429를 받을 수 있습니다.

엔드포인트

경로는 Base URL 기준입니다.

유닛 만들기

새 광고 유닛을 만듭니다.

요청

ad-unit:write 권한이 필요합니다.

요청 본문

  • 생략한 값은 콘솔 유닛 만들기 화면과 같은 포맷별 기본값으로 채워집니다.
  • 설정을 켜고 딸린 값을 보내지 않으면 콘솔과 같은 기본값이 들어갑니다. 예를 들어 carouselActivated를 켜면 carouselShowIndicator와 carouselRollingInterval이 기본값으로 채워집니다.
  • 웹 앱에는 배너와 네이티브 유닛만 만들 수 있습니다.
  • 응답에만 있는 필드(_id, connected, archived, createdAt, updatedAt)와 여기에 없는 필드를 보내면 400 VALIDATION_FAILED를 반환합니다.

요청 예시

응답 예시

201 응답으로 만든 유닛을 유닛 객체로 반환합니다.
생성 요청은 멱등(idempotent)하지 않습니다. 응답을 받지 못해 같은 요청을 다시 보내면 유닛이 중복으로 만들어질 수 있으니, 다시 보내기 전에 유닛 목록에서 유닛이 만들어졌는지 확인하세요.

오류

  • 400 AD_UNIT_VALIDATION_FAILED: 사이즈, 포맷별 설정의 범위, 설정 사이의 조건 같은 유닛 규칙을 어겼습니다.
  • 400 AD_UNIT_NATIVE_SLOTS_NOT_ACCEPTABLE: nativeSlots가 규칙에 맞지 않습니다.
  • 404 PROJECT_APP_NOT_FOUND: app이 이 프로젝트의 앱이 아닙니다.

유닛 객체

조회, 생성, 수정 엔드포인트는 다음 형식으로 유닛을 반환합니다. features는 저장되지 않은 설정을 기본값으로 채워 반환하지 않습니다.

포맷과 사이즈

format에는 다음 값을 대소문자까지 정확히 넣습니다.
  • 배너, 네이티브, 팝업은 프리셋 외에 사이즈를 직접 지정할 수 있습니다. 가로와 세로는 각각 110,000 사이의 정수이고, 팝업은 가로:세로 비율이 2:33:2여야 합니다.
  • 동영상 사이즈(320x180, 180x320)를 쓰면 video.dimensions에 같은 비율(16:9, 9:16)을 넣습니다.
  • 보상형 유닛의 소재는 항상 9:16 동영상입니다.
각 포맷의 특징은 광고 포맷을 참고하세요.

포맷별 설정

features에는 포맷이 쓰는 설정만 넣을 수 있습니다. 다른 포맷의 설정을 넣으면 400을 반환합니다. 숫자는 JSON 숫자로 보내고("1000" 같은 문자열은 받지 않습니다), 시간 값의 단위는 밀리초입니다.

모든 포맷

전면, 보상형, 스플래시는 동영상 설정(videoSupported, videoController, videoSkipDelayMs)이 항상 꺼져 있습니다.

배너

네이티브

팝업 (하단·중앙)

전면

스플래시

보상형은 모든 포맷에 공통인 설정만 씁니다.

설정 조건

  • 템플릿만 허용(useTemplate)은 프리셋 사이즈를 쓰고 동영상이 없는 배너만 켤 수 있습니다.
  • canSupportThemeDark는 템플릿만 허용을 켜지 않은 배너, 이미지·동영상이 있는 네이티브, 팝업, 스플래시에서만 켤 수 있습니다.
  • 이미지·동영상이 없는 네이티브는 AD 마크 표시(useWatermark), CTA 버튼, 동영상 소재 받기를 켤 수 없습니다.
  • 범위는 해당 설정이 켜져 있을 때만 검사합니다. 예를 들어 carouselRollingInterval은 carouselActivated가 켜져 있을 때 검사합니다.

네이티브 텍스트와 미디어

  • nativeTexts 항목은 id(영문 소문자, 숫자, _), label, maxLength(0보다 큰 최대 글자 수), optional(선택 항목 여부)로 이루어집니다. 최대 50개까지 넣을 수 있습니다.
  • headline(광고 제목)과 body(광고 설명)는 nativeTexts의 첫 번째나 두 번째 자리에만 둘 수 있습니다.
  • nativeSlots 항목은 id, label(선택), w, h로 이루어지며, 이미지·동영상이 있는 네이티브에서만 쓸 수 있습니다. 첫 번째 미디어의 id는 m1이고 사이즈는 유닛의 size와 같아야 합니다. 최대 3개까지 넣을 수 있으며, 미디어가 하나뿐이면 []로 저장됩니다.
  • nativeTexts와 nativeSlots의 id는 모두 합쳐 겹칠 수 없습니다.
nativeSlots 규칙을 어기면 400 AD_UNIT_NATIVE_SLOTS_NOT_ACCEPTABLE을 반환하고 detail.reason에 이유를 알려 줍니다. 다중 미디어는 네이티브 다중 미디어를 참고하세요.

유닛 목록 조회

프로젝트의 유닛을 최신 순으로 페이지 단위로 반환합니다. 기본으로 삭제된 유닛은 빠집니다.

요청

ad-unit:read 권한이 필요합니다.

쿼리 파라미터

요청 예시

응답 예시

200 응답으로 items(유닛 목록)와 next(다음 페이지 커서)를 반환합니다. next가 없으면 마지막 페이지입니다.
정렬 순서는 대체로 만든 순서의 역순이지만, 오래된 유닛은 순서가 다를 수 있습니다. 순서에 기대지 말고 next로 이어서 읽으세요.

유닛 조회

유닛 하나를 반환합니다. 삭제된 유닛도 ID로 조회할 수 있으며, 이때 archived는 true입니다.

요청

ad-unit:read 권한이 필요합니다.

요청 예시

응답

200 응답으로 유닛 객체를 반환합니다.

오류

  • 404 AD_UNIT_NOT_FOUND: 유닛이 없거나 다른 프로젝트의 유닛입니다.

유닛 수정

보낸 필드만 바꿉니다.

요청

ad-unit:write 권한이 필요합니다. 요청 본문은 유닛 만들기의 필드에서 app을 뺀 것과 같습니다. 유닛의 앱은 바꿀 수 없습니다.

쿼리 파라미터

바뀌는 방식

  • 보내지 않은 필드는 그대로입니다. 빈 본문 {}을 보내면 아무것도 바뀌지 않습니다.
  • features는 보낸 설정만 바뀌고 나머지 설정은 그대로입니다. 단, carouselActivated, videoSupported, videoController를 켜거나 끄면 함께 보내지 않은 딸린 설정(carouselShowIndicator, carouselRollingInterval, videoController, videoSkipDelayMs)이 켤 때는 기본값으로, 끌 때는 꺼진 값으로 바뀝니다.
  • null은 desc(설명 지우기), size(이미지·동영상 없는 네이티브로 바꾸기), video(동영상 사이즈 해제), features.carouselCountLimit(팝업 캐러셀 개수 제한 끄기)에만 보낼 수 있습니다.
  • 포맷을 바꿀 때 지금 사이즈가 새 포맷의 프리셋이 아니면 size도 함께 보내야 합니다. 새 포맷에서 쓰지 않는 설정은 지워지고, 새 포맷의 설정은 기본값으로 채워집니다.
  • 삭제된 유닛은 수정할 수 없습니다(409 AD_UNIT_ARCHIVED).

바꿀 수 없는 필드

SDK에서 광고를 요청한 적이 있는 유닛(connected: true)과 광고 상품의 소재 세트에 들어 있는 유닛은 format, size, video, nativeSlots의 id를 바꿀 수 없습니다(409 AD_UNIT_FIELD_LOCKED). 이름, 설명, 그 밖의 설정은 바꿀 수 있습니다.

광고 상품에 미치는 영향

광고 상품에 들어 있는 유닛의 useTemplate, useWatermark, features를 바꾸면 소재 세트 기준과 맞지 않게 될 수 있습니다. 그러면 그 유닛은 해당 상품에서 수정 필요 상태(fixRequired)가 되어 광고가 송출되지 않습니다. 자세한 내용은 광고 상품 API의 소재 세트를 참고하세요. 이 유닛을 쓰는 상품이 너무 많아 한 번에 다시 맞출 수 없으면 409 AD_UNIT_RECONCILE_LIMIT_EXCEEDED를 반환하고 아무것도 바꾸지 않습니다. detail.limit에는 걸린 한도의 이름이, detail.max에는 그 한도 값이 들어 있습니다.
유닛을 조회한 응답에서 응답에만 있는 필드(_id, app, connected, archived, createdAt, updatedAt)를 빼고 그대로 보내면 아무것도 바뀌지 않습니다. 오래전에 콘솔에서 만든 유닛은 features의 숫자가 문자열(예: "1000")로 저장돼 있을 수 있으니, 다시 보낼 때는 숫자로 바꿔 보내세요.

요청 예시

응답

200 응답으로 수정된 유닛 객체를 반환합니다.

오류

  • 404 AD_UNIT_NOT_FOUND: 유닛이 없거나 다른 프로젝트의 유닛입니다.
  • 409 AD_UNIT_ARCHIVED: 삭제된 유닛입니다.
  • 409 AD_UNIT_CONFLICT: ifUpdatedAt이 유닛의 updatedAt과 다릅니다. 유닛을 다시 조회한 뒤 수정하세요.
  • 409 AD_UNIT_FIELD_LOCKED: 바꿀 수 없는 필드를 바꾸려고 했습니다.
  • 409 AD_UNIT_RECONCILE_LIMIT_EXCEEDED: 이 유닛을 쓰는 상품이 너무 많습니다.

유닛 삭제

유닛을 삭제합니다. 삭제한 유닛은 되돌릴 수 없습니다.

요청

ad-unit:write 권한이 필요합니다.

요청 예시

응답 예시

200 응답으로 유닛 ID를 반환합니다.
  • 삭제한 유닛은 목록에서 빠지지만 ID로는 계속 조회할 수 있습니다(archived: true). 이미 삭제한 유닛을 다시 삭제해도 200을 반환합니다.
  • 삭제한 유닛은 이 유닛을 쓰는 모든 광고 상품의 소재 세트에서 빠집니다. 비게 된 소재 세트도 함께 없어지므로 유닛이 하나도 없는 상품이 남을 수 있습니다.
삭제하기 전에 광고 상품 API로 이 유닛을 쓰는 상품이 있는지 확인하세요. 상품 목록에는 유닛 ID가 없으므로 상품마다 조회해 unitGroups[].units를 확인합니다.

오류

  • 404 AD_UNIT_NOT_FOUND: 유닛이 없거나 다른 프로젝트의 유닛입니다.
  • 409 AD_UNIT_RECONCILE_LIMIT_EXCEEDED: 이 유닛을 쓰는 상품이 너무 많습니다. 먼저 상품에서 이 유닛을 빼세요.

오류 처리

오류 응답

오류 응답에는 statusCode가 들어 있고, 아래 표에서 errorCode 칸이 -가 아닌 오류에는 errorCode도 들어 있습니다. 요청의 어느 부분이 잘못됐는지 알려 주는 오류는 detail도 함께 반환합니다. 처리 방식은 errorCode로 나누고, errorCode가 없으면 statusCode로 나누세요.
detail.errors[]의 path는 잘못된 필드의 위치이고, value는 보낸 값입니다. detail.errors는 최대 100건까지 들어 있습니다. 요청 형식 오류(VALIDATION_FAILED)에는 message와 error 필드도 함께 들어 있는데, features의 오류는 message에 한 줄로 합쳐지므로 설정별 오류는 detail.errors[]로 확인하세요.

오류 코드

다시 보내기

  • 쓰기 요청(POST, PATCH, DELETE)이 502를 받거나 응답 없이 끊겼다면 요청이 반영됐을 수 있습니다. 다시 보내기 전에 유닛을 조회해 반영 여부를 확인하세요. 생성 요청은 멱등하지 않으므로 그대로 다시 보내면 유닛이 중복으로 만들어질 수 있습니다.
  • ifUpdatedAt을 붙인 수정 요청을 다시 보낼 때는, 앞선 요청이 반영됐다면 409 AD_UNIT_CONFLICT를 받을 수 있습니다. 유닛을 다시 조회해 확인하세요.

한도