Index
Table of Contents | ||||
---|---|---|---|---|
|
...
퍼블리셔가 받아볼 수 있는 광고 목록을 조회합니다.
항목 | 내용 | |
---|---|---|
1 | 요청 방향 | 매체사 → BuzzAd |
2 | HTTP Request method | GET |
3 | HTTP Request URL | |
4 | HTTP Request parameters | Field 설명
|
5 | Response |
|
5) Response Fields
Field | Type | Description |
---|---|---|
| list | 광고 목록
|
| String | 처리 결과 코드
|
| String | 처리 결과 메세지 |
ads
세부 항목 (Response Fields - ads)
Field | Type | Description |
---|---|---|
| Integer | 광고 아이디 (식별값) |
| String | 광고 제목 |
| String | 광고 설명 |
| String | 광고 적립방법 설명 |
| String | 아이콘 이미지 주소 |
| String | 매체사 단가 |
| String | 광고 타입. 추후 새로운 타입이 추가될 수 있으므로 연동시 이를 고려해야 합니다.
|
package_name
String
안드로이드 package_name
예제) “cpc” | ||||
| String | 안드로이드 package_name | ||
| String | 아이폰 url scheme | ||
| String | 광고가 지원되는 플랫폼
| ||
| Integer | 나이 하한 타게팅. 타게팅이 없는 경우 | ||
| Integer | 나이 상한 타게팅. 타게팅이 없는 경우 |
sex
|
JSON |
다 구간 나이 타게팅. age_ranges를 사용하는 경우 age_from, age_to 값은 무시해도 된다.
|
null
M
: 남자
F
:
| ||
| String | 성별 타게팅. 타게팅이 없는 경우
|
| String | 결혼 유무 타게팅. 타게팅이 없는 경우
|
| String | 통신사 타게팅. 타게팅이 없는 경우
|
| Bool |
|
| String | 디바이스 모델 타게팅
|
| String | 앱 타게팅 (안드로이드만 지원)
|
| String | 지역 타게팅
|
| list | creative 목록
|
creative
세부 항목 (Response Fields - ads - creative)
Field | Type | Description |
---|---|---|
| Integer | creative ID |
| String | 짧은 참여방법/주의사항 기재 |
| integer | native creative 가 세팅 되어 있는 경우 627 (고정값), 없는 경우 0 |
| integer | native creative 가 세팅 되어 있는 경우 1200 (고정값), 없는 경우 0 |
| String | 참여방법 및 주의사항이 기재 |
| String | ex) 팔로워 누르러 가기 |
| String | Native creative가 세팅되어 있을 경우에만 native 타입의 이미지 파일 url이 담김 |
| String | 오퍼월 리스트내에 볼수 있는 아이콘 이미지 |
Info |
---|
...
광고 |
...
광고에 참여하기 위해서는 참여 요청 API를 호출하여 참여 가능 여부를 확인해야 합니다.
...
항목
...
내용
...
요청 방향
...
매체사 → BuzzAd
...
HTTP Request method
...
POST
...
HTTP Request URL
...
https://ad.buzzvil.com/api/v1/participate
...
HTTP Request parameters
...
Field 설명은 아래 ‘4) HTTP Request parameters’ 표 참고
Note | ||||||
---|---|---|---|---|---|---|
|
...
Response
...
JSON 형식으로 반환
Field 설명은 아래 ‘5) Response’ 표 참고
4) HTTP Request parameters
...
Field
...
Type
...
Description
...
unit_id
...
Integer
...
매체 아이디
...
campaign_id
...
Integer
...
광고 아이디
...
ifa
...
String
...
안드로이드 광고 아이디(GAID)
또는 iOS Identifier for Advertiser(IDFA)
...
custom
...
String
...
매체사에서 정의한 파라미터
postback으로 다시 전달됨
최대 길이는 255
...
client_ip
...
String
...
광고 참여한 유저의 ip ex) 123.123.123.123
...
udid
Status | ||||
---|---|---|---|---|
|
...
String
...
안드로이드 IMEI
Note |
---|
udid는 안드로이드 Q 버전부터 수집 불가 항목입니다. |
...
android_id
Status | ||||
---|---|---|---|---|
|
...
String
...
android id
...
udid_sha1
Status | ||||
---|---|---|---|---|
|
...
String
...
sha1 적용한 안드로이드 IMEI
Note |
---|
udid는 안드로이드 Q 버전부터 수집 불가 항목입니다. |
...
android_id_sha1
Status | ||||
---|---|---|---|---|
|
...
String
...
sha1 적용한 android id
...
user_id
...
String
...
매체사 유저 아이디
...
sub_publisher_id
Status | ||
---|---|---|
|
...
String
...
매체사의 하위 매체사 아이디
...
sub_publisher_user_id
Status | ||
---|---|---|
|
...
String
...
매체사의 하위 매체사의 유저 아이디
...
device_name
Status | ||||
---|---|---|---|---|
|
...
String
...
디바이스 모델 이름
...
carrier
Status | ||||
---|---|---|---|---|
|
...
String
...
통신사 ex) SKT, UPlus
...
google_account_sha1
Status | ||||
---|---|---|---|---|
|
...
String
...
안드로이드 기기에 등록된 google account sha1 적용 값
복수 개인 경우 가장 첫 번째 account만 전달합니다.
getAccountsByType(”com.google”)
함수를 이용해 가져올 수 있습니다.부록 3) “Google account 가져오기 예제” 참고
5) Response
...
Field
...
Type
...
Description
...
code
...
Integer
...
처리결과 코드
200인 경우에만 참여 가능: 자세한 내용은 부록 참고
...
msg
...
String
...
처리결과 메세지
...
landing_url
...
String
...
광고주 페이지 랜딩 URL
3. 광고 참여 완료
Info |
---|
본 항목은 CPI 광고만 해당됩니다. |
...
목록 조회 요청 시, Native creative 가 세팅되어 있는 광고만을 선별하여 반환 받을 수 있습니다. Request parameters 내 아래의 key & value를 포함해주시기 바랍니다.
|
Expand | ||
---|---|---|
|
2. 광고 참여 요청
광고에 참여하기 위해서는 참여 요청 API를 호출하여 참여 가능 여부를 확인해야 합니다.
항목 | 내용 | |||||||||
---|---|---|---|---|---|---|---|---|---|---|
1 | 요청 방향 | 매체사 → BuzzAd | ||||||||
2 | HTTP Request method | POST | ||||||||
3 | HTTP Request URL | |||||||||
4 | HTTP Request parameters |
| ||||||||
5 | Response |
|
4) HTTP Request parameters
Field | Type | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|---|
| Integer | 매체 아이디 | ||||||||
| Integer | 광고 아이디 | ||||||||
| String |
| ||||||||
| String | 사용자 고유 식별자입니다. 서비스 도중 변하지 않는 고정 값이며, 광고 할당을 위한 필수 정보입니다.
| ||||||||
| String | 광고 참여한 유저의 ip ex) 123.123.123.123 | ||||||||
| String | 안드로이드 IMEI
| ||||||||
| String | android id | ||||||||
| String | sha1 적용한 안드로이드 IMEI
| ||||||||
| String | sha1 적용한 android id | ||||||||
| String | 매체사의 하위 매체사 아이디 | ||||||||
| String | 매체사의 하위 매체사의 유저 아이디 | ||||||||
| String | 디바이스 모델 이름 | ||||||||
| String | 통신사 ex) SKT, UPlus | ||||||||
| String | 안드로이드 기기에 등록된 google account sha1 적용 값
| ||||||||
| String | 매체사에서 지정하는 커스텀 파라미터
| ||||||||
| String | 매체사에서 지정하는 커스텀 파라미터
| ||||||||
| String | 매체사에서 지정하는 파라미터
|
5) Response
Field | Type | Description |
---|---|---|
| Integer | 처리결과 코드
|
| String | 처리결과 메세지 |
| String | 광고주 페이지 랜딩 URL |
3. 광고 참여 완료
Info |
---|
본 항목은 CPI 광고만 해당됩니다. |
CPI 광고는 매체사 측에서 사용자가 앱을 설치했는지 여부를 판단하고 BuzzAd으로 API를 통해서 설치 완료 요청을 해야합니다. 성공시 BuzzAd에서 매체사로 리워드 적립 postback가 호출됩니다.
Expand | ||
---|---|---|
| ||
패키지명 확인이 가능하면, 해당 api를 요청합니다.
|
항목 | 내용 | |
---|---|---|
1 | 요청 방향 | 매체사 → BuzzAd |
2 | HTTP Request method | POST |
3 | HTTP Request URL | |
4 | HTTP Request parameters |
|
5 | Response | JSON 형식으로 반환
|
4) HTTP Request parameters
Field | Type | Description | ||||||
---|---|---|---|---|---|---|---|---|
| Integer | 매체 아이디 | ||||||
| Integer | 광고 아이디 | ||||||
| String |
| ||||||
| String | 광고 참여한 유저의 아이피 ex) 123.123.123.123 | ||||||
| String | 안드로이드 IMEI
|
5) Response
Field | Type | Description |
---|---|---|
| Integer | 처리결과 코드
|
| String | 처리결과 메세지 |
4. 포인트 적립 포스트백 API 연동
BuzzAd에서 유저가 목표한 액션을 수행 시 매체사로 보내주는 리퀘스트입니다.
버즈애드에서 포인트 적립이 발생했을 때 버즈애드에서 직접 매체사 유저들에게 포인트를 지급하는 것이 아닙니다. 버즈애드 서버에서 매체사 서버로 포인트 적립 요청을 보낼 뿐이고, 실제 지급은 매체사 서버에서 처리합니다.
Info |
---|
매체사 포인트 적립 포스트백 API 연동 문서를 참고하여 API 연동 후, endpoint url을 버즈빌 매니저에게 전달해주세요. |
...
Note |
---|
아래 표에 명시되지 않은 Code가 추가될 수 있으므로 주의해야 합니다. |
코드 |
---|
설명 | |
---|---|
200 | 정상 |
401 | 블랙리스트 유저 |
402 | 잘못된 ip 주소 형식 |
1000 | 시스템 에러 |
9001 | 존재하지 않는 unit_id |
파라미터 에러
9004 | 유효하지 않은 파라미터 ( |
요청에 required field가 누락됐을 경우 발생) | |
9008 | 존재하지 않는 |
campaign_id
캠페인 | |
9011 | 요청 unit이 inactive 상태인 경우 |
9013 |
비활성화된 캠페인 |
9014 |
종료된 광고 (라이브 중인 시간이 아님)
9015
현재 캠페인이 라이브 중이 아니거나, 해당 매체에 타게팅되어 있지 않은 경우 | |
9020 | 이미 캠페인에 참여한 |
경우 |
9021 |
캠페인이 모두 소진된 |
경우 |
9022 |
ifa
파라미터 없음
Info |
---|
GAID 또는 IDFA 트래킹을 허용 받지 못한 유저의 경우에 9022 에러코드가 리턴됩니다. |
9025
클릭 로그 찾을 수 없음
9031
광고식별자 수집이 불가한 사용자가 광고식별자 필수 캠페인을 클릭한 경우 | |
9031 | 알 수 없는 애드네트워크 캠페인 에러 |
9037 | 클릭한 사용자가 타게팅 조건에 맞지 않아 참여가 불가능한 경우 |
9040 | 광고식별자 형식이 잘못됐거나, 추적이 불가한 식별유형일 경우(e.g. 0000…) |
2) 앱 설치 트래킹
iOS/안드로이드에서 앱 설치여부를 트래킹 하는 방법에 대한 간략한 예제입니다. OS에 맞는 항목을 선택하여 자세한 내용을 확인해주세요.
...
Expand | ||
---|---|---|
| ||
타게팅 값이 있는 광고를 받는 절차
|
Expand | ||
---|---|---|
| ||
iOS14 버전에서 IDFA 수집에 대한 정책 변경으로 인해 사용자의 IDFA 값을 얻기 위해서는 먼저 사용자에게 App Tracking Transparency 팝업을 노출하여 권한을 획득해야 합니다. 이로인해 ifa 파라미터 값이 없을 경우 발생하는 9022 에러가 많은 유저에게서 발생할 수 있습니다. 기존에도 유저가 opt-out 할 경우 ifa 파라미터 값이 없어서 동일한 에러코드를 리턴했을텐데 iOS14 이후 버전을 사용하는 유저들의 경우 opt-in을 하지 않으면 모두 이 에러가 발생하며 액션형 광고 참여가 불가능한 상황이라 좀 더 적극적인 opt-in 안내를 할 필요가 있습니다. 아래 문구는 버즈빌 허니스크린에서 해당 에러에 대해 유저에게 안내하고 있는 문구입니다. 아래 안내문구를 참고하여 9022 에러가 리턴되었을때 유저에게 보여줄 안내 메세지 적용 작업이 필요합니다.
|
...
가이드 변경 이력
Expand | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Google account 가져오기 예제 추가 서주은
2017/02/07 cpy 유튜브 시청 → 동영상 시청 서주은
2018/05/16 FAQ #1 추가 윤진
2018/07/11 “3. 부록의 (1) 처리 결과 코드” 에 9004 에러 추가 윤진
2019/01/04 “2-(1) 광고 목록 조회” 하단에 “타게팅 값이 있는 광고를 받는 절차” 설명 추가 윤진 1. 20 2020/05/26
공지연 1.21 2020/08/18 CPS = 결제형 광고 → 쇼핑 적립형 광고 로 수정 공지연 1.22 2020/10/13 | 이태규IDFA 트래킹 허용 받지 못한 경우 가이드 추가
|