View Source

Index

1. 광고 목록 조회

퍼블리셔가 받아볼 수 있는 광고 목록을 조회합니다.

	항목	내용
1	요청 방향	매체사 → BuzzAd
2	HTTP Request method	GET
3	HTTP Request URL	https://ad.buzzvil.com/api/v1/list
4	HTTP Request parameters	Field 설명 `unit_id` (Integer) : 매체사 식별을 위한 아이디
5	Response	JSON 형식으로 반환 Field 설명은 아래 ‘5) Response Fields' 표 참고

2) Response Fields

Field

Type

Description

ads

list

광고 목록

자세한 아이템은 아래 'ads 세부 항목' 표 참고

code

String

처리 결과 코드

200인 경우에만 정상

msg

String

처리 결과 메세지

`ads` 세부 항목 (Response Fields - ads)

Field

Type

Description

id

Integer

광고 아이디 (식별값)

title

String

광고 제목

description

String

광고 설명

action_description

String

광고 적립방법 설명

icon

String

아이콘 이미지 주소

revenue

Decimal

매체사 단가

revenue_type

String

광고 타입. 추후 새로운 타입이 추가될 수 있으므로 연동시 이를 고려해야 합니다.

cpi: 앱 설치형
cpe: 앱 실행형 또는 앱 실행후 액션형
cpa: 액션형
cpl: 페이스북 좋아요
cpinsta: 인스타그램 팔로우
cps: 쇼핑 적립형 광고
cpyoutube: 유튜브 광고
cpq: 퀴즈형
cpk: 카카오톡 채널 참여하기
cpylike: 유튜브 구독 + 영상 좋아요 광고
cptiktok: 틱톡 팔로우
cpnstore : 네이버 스마트스토어 찜
cpqlite : 퀴즈형
cpcquiz : 퀴즈 적립 컨텐츠

예제) “cpc”

package_name

String

안드로이드 package_name

url_scheme

String

아이폰 url scheme

platform

String

광고가 지원되는 플랫폼

A: 안드로이드
I: 아이폰
W: 안드로이드/아이폰 둘 다 지원

해당 파라미터는 광고운영단에서 세팅되는 값이며 W로 내려가는 값을 매체사 측에서 다시 필터링 하여 내리는 경우 올바른 유닛에 광고가 내려가지 않을 수 있음

age_from

Integer

나이 하한 타게팅. 타게팅이 없는 경우 null

age_to

Integer

나이 상한 타게팅. 타게팅이 없는 경우 null

age_ranges

JSON

다 구간 나이 타게팅. age_ranges를 사용하는 경우 age_from, age_to 값은 무시해도 된다.

타게팅이 없는 경우

[]

타게팅이 있는 경우

[{"from":10, "to":20}, {"from":30, "to":40}]

sex

String

성별 타게팅. 타게팅이 없는 경우 null

M: 남자
F: 여자

relationship

String

결혼 유무 타게팅. 타게팅이 없는 경우 null

S: 미혼
M: 기혼

carrier

String

통신사 타게팅. 타게팅이 없는 경우 null

kt: KT 통신사
skt: SKT 통신사
lgt: LGT 통신사

udid_required

Bool

true: 광고 참여/참여완료 요청시 udid 파라미터 필수
false: 광고 참여/참여완료 요청시 udid 파라미터 필수 아님

device_name

String

디바이스 모델 타게팅

콤마(,)로 구분된 디바이스 모델명
OR 조건
ex) SHV-E250S,SHV-E275K,SM-G928L → SHV-E250S 또는 SHV-E275K 또는 SM-G928L 인 유저에게 타게팅

target_app

String

앱 타게팅 (안드로이드만 지원)

콤마(,)로 구분된 패키지 네임으로, 해당 앱이 설치된 유저에게 타게팅
패키지 네임 앞에 ‘-’ 기호가 있는 경우 설치되지 않은 유저에게 타게팅
OR 조건
ex1) Pl.idreams.skyforcehd,com.imangi.templerun2 → Pl.idreams.skyforcehd 또는 com.imangi.templerun2 가 설치된 유저에게 타게팅
ex2) com.thinkreals.couponmoa,-com.supercell.clashofclans → com.thinkreals.couponmoa가 설치되어 있거나 com.supercell.clashofclans가 설치되어 있지 않은 유저에게 타게팅

region

String

지역 타게팅

콤마로 구분된 지역: 도/시 단위로 타게팅 가능
OR 조건
ex) 서울특별시 강남구,경상남도 → 서울특별시 강남구 또는 경상남도에 거주중인 유저에게 타게팅

creative

list

creative 목록

자세한 아이템은 아래 'creative 세부 항목' 표 참고

is_multi_mission

Bool

멀티 미션 포함 여부

(True: 멀티 미션 광고 / False: 일반 CPA 광고)

멀티 미션 캠페인은 광고에 단 한 번 참여해도 여러 개의 미션을 동시에 완료할 수 있는 구조입니다. 이처럼 보상을 여러 번 지급해야 하는 특성상 보상 횟수(프리퀀시)를 무제한으로 설정해야 정상적으로 동작합니다. 만약 보상 횟수에 제한이 있으면 멀티 미션 캠페인을 연동하기 어렵습니다.

missions

list

missions 목록

해당 필드는 revenue_type 이 CPA(액션형 광고)일 때 보여질 수 있는 optional한 필드입니다. 멀티 미션 광고를 연동하고자 할 적에는 이 필드 데이터를 참고해주세요.

`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	참여방법 및 주의사항이 기재 22자 권장, 최대 40자
`call_to_action`	String	ex) 팔로워 누르러 가기
`image_url`	String	Native creative가 세팅되어 있을 경우에만 native 타입의 이미지 파일 url이 담김
`icon`	String	오퍼월 리스트내에 볼수 있는 아이콘 이미지

`missions` 세부 항목 (Response Fields - ads - missions)

Field

Type

Description

mission_id

Integer

멀티 미션 광고 식별값(ID)

mission_type

String

멀티 미션 광고유형

현재는 multi_event 타입만 연동 가능. 추후, 다른 타입도 추가 예정.

"multi_event"
"screenshot"
"quiz"

title

String

멀티 미션 광고명

description

String

멀티 미션 광고 설명

revenue

Decimal

멀티 미션 광고 당 지급되는 매체 수수료

멀티 미션 완료 여부 상태는 포인트 적립 시 https://buzzvil.atlassian.net/wiki/spaces/BDG/pages/404684961/7.+S2S+API#4.-%ED%8F%AC%EC%9D%B8%ED%8A%B8-%EC%A0%81%EB%A6%BD-%ED%8F%AC%EC%8A%A4%ED%8A%B8%EB%B0%B1-API-%EC%97%B0%EB%8F%99 API 응답값에서 mission_id 필드로 미션 완료 상태 관리를 하시길 바랍니다. API 응답값에는 완료 여부 상태와 관계없이 멀티 미션 캠페인 정보를 전달합니다.

멀티 미션 노출 순서는 응답값으로 전달하는 리스트 객체 순서 그대로입니다. 참고 부탁드립니다.

2. 광고 참여 요청

광고에 참여하기 위해서는 참여 요청 API를 호출하여 참여 가능 여부를 확인해야 합니다.

항목

내용

1

요청 방향

매체사 → BuzzAd

2

HTTP Request method

POST

3

HTTP Request URL

https://ad.buzzvil.com/api/v1/participate

4

HTTP Request parameters

Field 설명은 아래 ‘4) HTTP Request parameters’ 표 참고

파라미터를 주지 않는 경우 어뷰징 체크를 더 엄격하게 하므로 가능하다면 전달해주는 것이 좋습니다.

5

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

사용자 고유 식별자입니다. 서비스 도중 변하지 않는 고정 값이며, 광고 할당을 위한 필수 정보입니다.

앱을 삭제 후 재설치하여 사용자의 ID 값이 변경되거나 다른 사유로 인해 고정 ID를 사용하지 못하는 경우, 어뷰징 발생 가능성으로 인해 액션형 광고 송출이 불가능합니다. 사용자 고유 식별자가 변동되는 경우 버즈빌 사업 담당자에게 문의하세요.

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

sub_publisher_id

String

매체사의 하위 매체사 아이디

sub_publisher_user_id

String

매체사의 하위 매체사의 유저 아이디

device_name

String

디바이스 모델 이름

carrier

String

통신사 ex) SKT, UPlus

google_account_sha1

String

안드로이드 기기에 등록된 google account sha1 적용 값

복수 개인 경우 가장 첫 번째 account만 전달합니다.
getAccountsByType(”com.google”) 함수를 이용해 가져올 수 있습니다.
- 부록 3) “Google account 가져오기 예제” 참고

custom2

String

매체사에서 지정하는 커스텀 파라미터

버즈빌에서 매체사로 포스트백 request 시 전달 되는 값
최대 길이는 255
custom2~4까지 전달 가능

custom3

String

매체사에서 지정하는 커스텀 파라미터

버즈빌에서 매체사 로 포스트백 request 시 전달 되는 값
최대 길이는 255
custom2~4까지 전달 가능

custom4

String

매체사에서 지정하는 파라미터

버즈빌에서 매체사로 포스트백 request 시 전달 되는 값
최대 길이는 255
custom2~4까지 전달 가능

5) Response

Field

Type

Description

code

Integer

처리결과 코드

200인 경우에만 참여 가능: 자세한 내용은 부록 참고

msg

String

처리결과 메세지

landing_url

String

광고주 페이지 랜딩 URL

3. 광고 참여 완료

본 항목은 CPI 광고만 해당됩니다.

CPI 광고는 매체사 측에서 사용자가 앱을 설치했는지 여부를 판단하고 BuzzAd으로 API를 통해서 설치 완료 요청을 해야합니다. 성공시 BuzzAd에서 매체사로 리워드 적립 postback가 호출됩니다.

패키지명 확인이 가능하면, 해당 api를 요청합니다.

private fun isInstalled(
        context: Context,
        packageName: String?
    ): Boolean {
        if (packageName == null) {
            return false
        }

        return try {
            context.packageManager.getPackageInfo(packageName!!, 0)
            true
        } catch (e: PackageManager.NameNotFoundException) {
            false
        }
    }

	항목	내용
1	요청 방향	매체사 → BuzzAd
2	HTTP Request method	POST
3	HTTP Request URL	https://ad.buzzvil.com/api/v1/complete
4	HTTP Request parameters	Field 설명은 아래 ‘4) HTTP Request parameters’ 표 참고
5	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)

client_ip

String

광고 참여한 유저의 아이피 ex) 123.123.123.123

udid

String

안드로이드 IMEI

udid는 안드로이드 Q 버전부터 수집 불가 항목입니다.

5) Response

Field

Type

Description

code

Integer

처리결과 코드

200인 경우에만 정상 처리: 부록 참고

msg

String

처리결과 메세지

4. 포인트 적립 포스트백 API 연동

BuzzAd에서 유저가 목표한 액션을 수행 시 매체사로 보내주는 리퀘스트입니다.

버즈애드에서 포인트 적립이 발생했을 때 버즈애드에서 직접 매체사 유저들에게 포인트를 지급하는 것이 아닙니다. 버즈애드 서버에서 매체사 서버로 포인트 적립 요청을 보낼 뿐이고, 실제 지급은 매체사 서버에서 처리합니다.

매체사 포인트 적립 포스트백 API 연동 문서를 참고하여 API 연동 후, endpoint url을 버즈빌 매니저에게 전달해주세요.

멀티 미션 광고일 경우 기존 포스트백 API에서 extra필드에 mission_id 데이터를 전송할 예정입니다. 포인트 적립 연동 시 해당 mission_id 필드로 특정 미션에 대한 적립을 핸들링하실 수 있습니다. 참고 부탁드려요.

{
  "user_id": "12345",
  "point": 1,
  "transaction_id": "126905422_10000001",
  "event_at": 1641452397,
  "unit_id": 5539189976900000,
  "action_type": "l",
  "title": "타이틀",
  "mission": "{\"id\": 1}"
}

Index

1. 광고 목록 조회

2) Response Fields

ads 세부 항목 (Response Fields - ads)

creative 세부 항목 (Response Fields - ads - creative)

missions 세부 항목 (Response Fields - ads - missions)

2. 광고 참여 요청

4) HTTP Request parameters

5) Response

3. 광고 참여 완료

4) HTTP Request parameters

5) Response

4. 포인트 적립 포스트백 API 연동

`ads` 세부 항목 (Response Fields - ads)

`creative` 세부 항목 (Response Fields - ads - creative)

`missions` 세부 항목 (Response Fields - ads - missions)