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
| list | 광고 목록
|
| String | 처리 결과 코드
|
| String | 처리 결과 메세지 |
ads
세부 항목 (Response Fields - ads)
| Integer | 광고 아이디 (식별값) |
| String | 광고 제목 |
| String | 광고 설명 |
| String | 광고 적립방법 설명 |
| String | 아이콘 이미지 주소 |
| String | 매체사 단가 |
| String | 광고 타입. 추후 새로운 타입이 추가될 수 있으므로 연동시 이를 고려해야 합니다.
|
| String | 안드로이드 package_name |
| String | 아이폰 url scheme |
| String | 광고가 지원되는 플랫폼
해당 파라미터는 광고운영단에서 세팅되는 값이며 W로 내려가는 값을 매체사 측에서 다시 필터링 하여 내리는 경우 올바른 유닛에 광고가 내려가지 않을 수 있음 |
| Integer | 나이 하한 타게팅. 타게팅이 없는 경우 |
| Integer | 나이 상한 타게팅. 타게팅이 없는 경우 |
| JSON | 다 구간 나이 타게팅. age_ranges를 사용하는 경우 age_from, age_to 값은 무시해도 된다.
|
| String | 성별 타게팅. 타게팅이 없는 경우
|
| String | 결혼 유무 타게팅. 타게팅이 없는 경우
|
| String | 통신사 타게팅. 타게팅이 없는 경우
|
| Bool |
|
| String | 디바이스 모델 타게팅
|
| String | 앱 타게팅 (안드로이드만 지원)
|
| String | 지역 타게팅
|
| list | creative 목록
|
creative
세부 항목 (Response Fields - ads - creative)
| Integer | creative ID |
| String | 짧은 참여방법/주의사항 기재 |
| integer | native creative 가 세팅 되어 있는 경우 627 (고정값), 없는 경우 0 |
| integer | native creative 가 세팅 되어 있는 경우 1200 (고정값), 없는 경우 0 |
| String | 참여방법 및 주의사항이 기재 |
| String | ex) 팔로워 누르러 가기 |
| String | Native creative가 세팅되어 있을 경우에만 native 타입의 이미지 파일 url이 담김 |
| String | 오퍼월 리스트내에 볼수 있는 아이콘 이미지 |
2. 광고 참여 요청
광고에 참여하기 위해서는 참여 요청 API를 호출하여 참여 가능 여부를 확인해야 합니다.
1 | 요청 방향 | 매체사 → BuzzAd |
2 | HTTP Request method | POST |
3 | HTTP Request URL | |
4 | HTTP Request parameters |
권장 파라미터를 주지 않는 경우 어뷰징 체크를 더 엄격하게 하므로 가능하다면 전달해주는 것이 좋습니다. |
5 | Response |
|
4) HTTP Request parameters
| Integer | 매체 아이디 |
| Integer | 광고 아이디 |
| String |
|
| String | 매체사에서 정의한 파라미터
|
| String | 광고 참여한 유저의 ip ex) 123.123.123.123 |
| String | 안드로이드 IMEI udid는 안드로이드 Q 버전부터 수집 불가 항목입니다. |
| String | android id |
| String | sha1 적용한 안드로이드 IMEI udid는 안드로이드 Q 버전부터 수집 불가 항목입니다. |
| String | sha1 적용한 android id |
| String | 매체사 유저 아이디 |
| String | 매체사의 하위 매체사 아이디 |
| String | 매체사의 하위 매체사의 유저 아이디 |
| String | 디바이스 모델 이름 |
| String | 통신사 ex) SKT, UPlus |
| String | 안드로이드 기기에 등록된 google account sha1 적용 값
|
5) Response
| Integer | 처리결과 코드
|
| String | 처리결과 메세지 |
| 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
| Integer | 매체 아이디 |
| Integer | 광고 아이디 |
| String |
|
| String | 광고 참여한 유저의 아이피 ex) 123.123.123.123 |
| String | 안드로이드 IMEI udid는 안드로이드 Q 버전부터 수집 불가 항목입니다. |
5) Response
| Integer | 처리결과 코드
|
| String | 처리결과 메세지 |
4. 포인트 적립 포스트백 API 연동
BuzzAd에서 유저가 목표한 액션을 수행 시 매체사로 보내주는 리퀘스트입니다.
버즈애드에서 포인트 적립이 발생했을 때 버즈애드에서 직접 매체사 유저들에게 포인트를 지급하는 것이 아닙니다. 버즈애드 서버에서 매체사 서버로 포인트 적립 요청을 보낼 뿐이고, 실제 지급은 매체사 서버에서 처리합니다.
https://buzzvil.atlassian.net/wiki/spaces/BDG/pages/1756004654 문서를 참고하여 API 연동 후, endpoint url을 버즈빌 매니저에게 전달해주세요.
부록
1) 처리 결과 코드
아래 표에 명시되지 않은 Code가 추가될 수 있으므로 주의해야 합니다.
200 | 정상 |
1000 | 시스템 에러 |
9001 | 존재하지 않는 |
9003 | 파라미터 에러 |
9004 | 유효하지 않은 파라미터 (어드민에서 유닛의 광고 그룹 설정 확인) |
9008 | 존재하지 않는 |
9013 | 종료된 광고 (disabled) |
9014 | 종료된 광고 (라이브 중인 시간이 아님) |
9015 | postback url 이 등록되어 있지 않음 |
9020 | 이미 참여한 광고 |
9021 | 이미 소진된 광고 |
9022 |
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