7. 퍼블리셔 오퍼월 S2S API
Index
1. 광고 목록 조회
퍼블리셔가 받아볼 수 있는 광고 목록을 조회합니다.
항목 | 내용 | |
|---|---|---|
| 1 | 요청 방향 | 매체사 → BuzzAd |
| 2 | HTTP Request method | GET |
| 3 | HTTP Request URL | |
| 4 | HTTP Request parameters | Field 설명
|
| 5 | Response |
|
5) Response Fields
Field | Type | Description |
|---|---|---|
ads | list | 광고 목록
|
code | String | 처리 결과 코드
|
msg | String | 처리 결과 메세지 |
ads 세부 항목 (Response Fields - ads)
Field | Type | Description |
|---|---|---|
id | Integer | 광고 아이디 (식별값) |
title | String | 광고 제목 |
description | String | 광고 설명 |
action_description | String | 광고 적립방법 설명 |
icon | String | 아이콘 이미지 주소 |
revenue | String | 매체사 단가 |
revenue_type | String | 광고 타입. 추후 새로운 타입이 추가될 수 있으므로 연동시 이를 고려해야 합니다.
|
package_name | String | 안드로이드 package_name |
url_scheme | String | 아이폰 url scheme |
platform | String | 광고가 지원되는 플랫폼
해당 파라미터는 광고운영단에서 세팅되는 값이며 W로 내려가는 값을 매체사 측에서 다시 필터링 하여 내리는 경우 올바른 유닛에 광고가 내려가지 않을 수 있음 |
age_from | Integer | 나이 하한 타게팅. 타게팅이 없는 경우 null |
age_to | Integer | 나이 상한 타게팅. 타게팅이 없는 경우 null |
sex | String | 성별 타게팅. 타게팅이 없는 경우 null
|
relationship | String | 결혼 유무 타게팅. 타게팅이 없는 경우 null
|
carrier | String | 통신사 타게팅. 타게팅이 없는 경우 null
|
udid_required | Bool |
|
device_name | String | 디바이스 모델 타게팅
|
target_app | String | 앱 타게팅 (안드로이드만 지원)
|
region | String | 지역 타게팅
|
creative | list | creative 목록
|
creative 세부 항목 (Response Fields - ads - creative)
Field | Type | Description |
|---|---|---|
ID | Integer | creative ID |
short_action_description | String | 짧은 참여방법/주의사항 기재 |
height | integer | native creative 가 세팅 되어 있는 경우 627 (고정값), 없는 경우 0 |
width | integer | native creative 가 세팅 되어 있는 경우 1200 (고정값), 없는 경우 0 |
action_description | String | 참여방법 및 주의사항이 기재 |
call_to_action | String | ex) 팔로워 누르러 가기 |
image_url | String | Native creative가 세팅되어 있을 경우에만 native 타입의 이미지 파일 url이 담김 |
icon | String | 오퍼월 리스트내에 볼수 있는 아이콘 이미지 |
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 |
|---|---|---|
unit_id | Integer | 매체 아이디 |
campaign_id | Integer | 광고 아이디 |
ifa | String |
|
custom | String | 매체사에서 정의한 파라미터
|
client_ip | String | 광고 참여한 유저의 ip ex) 123.123.123.123 |
udid 권장 | String | 안드로이드 IMEI udid는 안드로이드 Q 버전부터 수집 불가 항목입니다. |
android_id 권장 | String | android id |
udid_sha1 권장 | String | sha1 적용한 안드로이드 IMEI udid는 안드로이드 Q 버전부터 수집 불가 항목입니다. |
android_id_sha1 권장 | String | sha1 적용한 android id |
user_id | String | 매체사 유저 아이디 |
sub_publisher_id 선택 | String | 매체사의 하위 매체사 아이디 |
sub_publisher_user_id 선택 | String | 매체사의 하위 매체사의 유저 아이디 |
device_name 권장 | String | 디바이스 모델 이름 |
carrier 권장 | String | 통신사 ex) SKT, UPlus |
google_account_sha1 권장 | String | 안드로이드 기기에 등록된 google account sha1 적용 값
|
5) Response
Field | Type | Description |
|---|---|---|
code | Integer | 처리결과 코드
|
msg | String | 처리결과 메세지 |
landing_url | String | 광고주 페이지 랜딩 URL |
3. 광고 참여 완료
본 항목은 CPI 광고만 해당됩니다.
CPI 광고는 매체사 측에서 사용자가 앱을 설치했는지 여부를 판단하고 BuzzAd으로 API를 통해서 설치 완료 요청을 해야합니다. 성공시 BuzzAd에서 매체사로 리워드 적립 postback가 호출됩니다.
항목 | 내용 | |
|---|---|---|
| 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 |
|---|---|---|
unit_id | Integer | 매체 아이디 |
campaign_id | Integer | 광고 아이디 |
ifa | String |
|
client_ip | String | 광고 참여한 유저의 아이피 ex) 123.123.123.123 |
udid 선택 | String | 안드로이드 IMEI udid는 안드로이드 Q 버전부터 수집 불가 항목입니다. |
5) Response
Field | Type | Description |
|---|---|---|
code | Integer | 처리결과 코드
|
msg | String | 처리결과 메세지 |
4. 포인트 적립 포스트백 API 연동
BuzzAd에서 유저가 목표한 액션을 수행 시 매체사로 보내주는 리퀘스트입니다.
버즈애드에서 포인트 적립이 발생했을 때 버즈애드에서 직접 매체사 유저들에게 포인트를 지급하는 것이 아닙니다. 버즈애드 서버에서 매체사 서버로 포인트 적립 요청을 보낼 뿐이고, 실제 지급은 매체사 서버에서 처리합니다.
https://buzzvil.atlassian.net/wiki/spaces/BDG/pages/384696503 문서를 참고하여 API 연동 후, endpoint url을 버즈빌 매니저에게 전달해주세요.
부록
1) 처리 결과 코드
아래 표에 명시되지 않은 Code가 추가될 수 있으므로 주의해야 합니다.
Code | Description |
|---|---|
200 | 정상 |
1000 | 시스템 에러 |
9001 | 존재하지 않는 unit_id |
9003 | 파라미터 에러 |
9004 | 유효하지 않은 파라미터 (어드민에서 유닛의 광고 그룹 설정 확인) |
9008 | 존재하지 않는 campaign_id |
9013 | 종료된 광고 (disabled) |
9014 | 종료된 광고 (라이브 중인 시간이 아님) |
9015 | postback url 이 등록되어 있지 않음 |
9020 | 이미 참여한 광고 |
9021 | 이미 소진된 광고 |
9022 | ifa 파라미터 없음 GAID 또는 IDFA 트래킹을 허용 받지 못한 유저의 경우에 9022 에러코드가 리턴됩니다. |
9025 | 클릭 로그 찾을 수 없음 |
9031 | 내부 API 에러 |
2) 앱 설치 트래킹
iOS/안드로이드에서 앱 설치여부를 트래킹 하는 방법에 대한 간략한 예제입니다. OS에 맞는 항목을 선택하여 자세한 내용을 확인해주세요.
3) Google account 가져오기 예제
1
2
3
4
5
6
7
8
9
String getGoogleAccount(Context context) {
// need permission : android.permission.GET_ACCOUNTS
AccountManager accountManager = AccountManager.get(context);
Account[] accounts = accountManager.getAccountsByType("com.google");
if (accounts.length > 0) {
return accounts[0].name;
}
return "";
}
FAQ