퍼블리셔 실시간 S2S API

Owned by Joel Lim (Unlicensed)
Last updated: Jul 25, 2024 by Mason Yun
9 min read

목차

광고 할당 요청

항목

내용

항목

내용

1

요청 방향

매체사 → Buzzvil

2

HTTP Request method

GET

3

HTTP Request URL

https://screen.buzzvil.com/api/s2s/ads

4

HTTP Request parameters

아래 '1) HTTP Request parameters' 참고

5

Response

  • JSON 형식

  • Field 설명은 아래 ‘5) Response Fields' 표 참고

 

1) HTTP Request parameters

필드

유형

설명

필드

유형

설명

필수app_id

Integer
(MAX 20)

매체 앱 아이디

필수unit_id

Integer
(MAX 20)

매체 지면 아이디

필수ifa

String
(MAX 64)

사용자의 광고식별자. 광고 타게팅 및 어뷰징 필터링, CS 처리를 위해 필요합니다. 광고식별자 수집이 불가능할 경우 uuid 포맷을 모두 0으로 채워 요청해야 합니다.

예제) ab4ade35-1c8a-4405-acda-10ca1ad1abe1

광고식별자 수집이 불가능할 경우 전달 값) 00000000-0000-0000-0000-000000000000

필수user_id

String
(MAX 255)

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

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

필수client_ip

String
(MAX 45)

광고에 참여한 유저의 ip

실제 유저의 ip 값을 전달해 주어야 합니다. 그러지 않을 경우 CPA 유형의 광고 송출이 불가합니다.

예제) 123.123.123.123

권장ifv

string
(MAX 64)

iOS 앱 벤더식별자(IDFV). iOS에서 유저가 앱 추적 허용을 하지 않아 광고식별자 수집이 불가능할 경우엔 필수로 전달해주어야 하는 값입니다. 사용자 식별을 위한 대체식별자로 사용됩니다.

예제) ab4ade35-1c8a-4405-acda-10ca1ad1abe1

권장birthday

String
(MAX 10)

유저의 생년월일

생년월일 정보가 없을 경우 일부 광고가 할당에서 제외됩니다.

예제) 1993-01-09 ( O ) 19930109 ( X )

권장gender

String
(MAX 20)

성별 타게팅을 위한 정보.

성별 정보가 없을 경우 일부 광고가 할당에서 제외됩니다.

  • M: 남자

  • F: 여자

권장revenue_types

String
(MAX 255)

할당 받을 광고 상품 타입. 값이 비어있을 경우, 노출형 광고(cpm, cpc)만 할당됩니다.

할당을 원하지 않는 상품타입이 있다면, 상품타입값 앞에 음수기호(-)를 추가하면 됩니다.

예제) [“cpc”, “cpm”, “cpq”, “cpinsta”, “cpa”, “cpk”, “cpl”, “cpcquiz”]

인코딩 주의 %5B%22cpm%22%2C%22cpa%22%2C%22cpq%22%2C%22cpinsta%22%2C%22cpk%22%2C%22cpl%22%2C%22cpc%22%5D

액션형 광고만 할당받는 예제) [“-cpc”, “-cpm”]

권장platform

String

기기의 OS 정보

  • A: Android

  • I: iOS

권장country

String

요청 IP의 국가 정보.

현재는 국내 광고만 송출되고 있기 때문에 KR로 고정해서 호출해 주세요.

권장carrier

String
(MAX 20)

통신사 정보.

통신사 정보가 없을 경우 일부 광고가 할당에서 제외됩니다.

  • kt: KT 통신사

  • skt: SKT 통신사

  • lgt: LGT 통신사

권장device_name

String
(MAX 255)

디바이스 모델명

디바이스 모델명이 없을 경우 일부 광고가 할당에서 제외됩니다.


예제) SHV-E250S,SHV-E275K,SM-G928L → SHV-E250S 또는 SHV-E275K 또는 SM-G928L 인 유저에게 타게팅

권장latitude

Float
(MAX 32)

위도 와 경도. 지역별 광고 타게팅에 사용됩니다.

정보가 없을 경우 일부 광고가 할당에서 제외됩니다.

권장longitude

Float
(MAX 32)

권장user_agent

String
(MAX 255)

User Agent.

정보가 없을 경우 일부 광고가 할당에서 제외됩니다.

권장 target_fill

Int
(MAX 4)

할당받을 광고갯수. 한번에 할당 가능한 최대 target_fill은 20 입니다.

권장 cursor

String

(MAX 3000)

할당에서 제외할 광고 데이터

할당 요청에 대한 response에 cursor가 포함되어 있습니다. 이후의 request parameter에 포함하면 기존에 할당받은 광고가 제외된 광고 목록을 받을 수 있습니다.

예제) EvTIfLfbEUk7O_ylo5_rVBaEmt0jvIZvbI4o47azTNLDwGwbz2OoO522T4-9AzrlDwxo4ucwZ7pFg6LD-ReBNI8Yi9TKxWurSDIPvAhkqWuzY07jI_ej4Lngk_YeehlipFFV0ZfL8dnAY00xs6ydXTllkP_g_UOhHoyxxgyr3Qldp53TLXwTiv-7asYPa5H8

 

2) Response parameter

필드

유형

설명

필드

유형

설명

code

Integer

처리결과 코드

  • 200인 경우에만 참여 가능: 자세한 내용은 아래 상태코드 참고

msg

String

처리결과 메세지

ads

List<Object>

광고 목록 : 가변 길이입니다.

아래의 Ads 필드 값에 따라 결정됩니다.

cursor

String

할당받은 광고 데이터

 

ads 세부 항목 (Response Fields - ads)

필드

유형

설명

필드

유형

설명

id

Integer

광고 아이디

예제) 10075328

name

String

광고 설명

예제) "11번가 신선밥상"

impression_urls

List<String>

사용자에게 광고를 노출시 호출되는 URL

예제) https://ad-staging.buzzvil.com/api/impression?data=ReOJjkH6mus-sxbys_1F2Bg9EHwkoGAAfb86yWB

reward

Integer

광고 참여 시 적립되는 포인트 금액

예제) 100

reward_condition

String

리워드 지급을 위한 조건

  • 클릭시 적립: click

  • 특정 액션 수행시 적립: action

예제)

노출형 광고상품: “click”

액션형 광고상품: “action”

노출형 광고상품이지만 특정 액션을 수행해야 적립되는 광고: “action”

check_participation_url

String

reward_condition이 “action”일 때, 캠페인 참여 여부를 확인하는 API URL 주소. check_participation_url을 호출해 사용자에게 참여완료 여부를 알려줄 수 있습니다. 사용자가 광고를 참여한 후 지면에 복귀했을 때, 호출합니다.

 

예제)

reward_condition이 "click"일 때: ""

reward_condition이 "action"일 때: “https://ad.buzzvil.com/api/check_conversion?data=ReOJjkH6mus"

type

String

광고 타입

노출형 상품

  • cpc: 클릭형 상품

  • cpm: 노출형 상품

액션형 상품

  • cpa: 일반 참여형 상품

  • cpk: 카카오톡 채널 추가 상품

  • cpq: 퀴즈 상품

  • cpqlite: 퀴즈 상품

  • cpl: 페이스북 좋아요 상품

  • cpyoutube: 유튜브 구독 상품

  • cps: 쇼핑형 상품

  • cptiktok: 틱톡 팔로우 상품

  • cpnstore: 네이버 스토어 알림설정 상품

  • cpe: 앱내 이벤트 참여 상품

  • cpylike: 유튜브 구독+좋아요 상품

  • cpinsta: 인스타그램 팔로우 상품

  • cpcquiz : 퀴즈 적립 컨텐츠

예제) “cpc”

creative

Object

광고 소재

  • 자세한 사항은 하단 'creative 세부 항목' 표 참고

payload

String

액션형 광고 참여시 필요한 콜백 파라미터를 인코딩한 문자열

노출형 광고 예제) ““

액션형 광고 예제) “zh8qPfFDUycs3d_p_4kIv_8P1Q8etYu1xDtf4VDmTYyxzwqSdiPGXPXeVQGPD"

external_browser

Boolean

광고 클릭 시 랜딩 페이지가 외부 브라우저에서 열려야하는지 여부

예제) true, false

external_browser = false 일때는 외부 브라우저로 랜딩이 되면 안 되나요?

external_browser = false일때 외부 브라우저로 랜딩되어도 광고 참여엔 전혀 문제가 없습니다.

external_browser = true 일때 인앱 브라우저로 랜딩되지 않도록만 유의해 주세요!

 

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

필드

유형

설명

필드

유형

설명

title

String

광고 소재 제목

예제) “LG전자 베스트샵 카카오톡 채널추가”

description

String

광고에 대한 상세 설명

예제) “LG전자 베스트샵 이벤트, 풍성한 혜택 정보까지! 가장 먼저 만나보세요!”

click_url

String

광고 클릭 시 호출되는 URL. cpc, cpm 광고만 값이 채워짐.

노출형 광고 예제) “https://screen.buzzvil.com/api/s2s/click_redirect/?payload=eytY9sky7fy45qys84KAzTqBAQeSDSKtvTolx1-Zy9Y8ND9t1hE1Mn”

액션형 광고 예제) ““

call_to_action

String

광고의 참여를 유도하는 CTA 버튼의 UI 텍스트

예제) 참여하기

width

Integer

광고 소재의 가로 길이. 값은 1200으로 고정

예제) 1200

height

Integer

광고 소재의 세로 길이. 값은 627으로 고정

예제) 627

icon_url

String

광고주 아이콘 이미지 URL

예제) https://d3aulf22blzf9p.cloudfront.net/uploads/1662458645-S98R6.png

image_url

String

광고소재 이미지 URL

예제) https://d3aulf22blzf9p.cloudfront.net/uploads/1677571904-JZ8YB.jpg

is_deeplink

Boolean

리다이렉트 될 최종 URL의 Deeplink 여부

예제) true, false

 

Response Parameter로 구현하기

다음은 API를 호출한 결과로 얻는 Response parameter를 사용하여 광고 소재를 구성하고 사용자의 광고 참여 단계별로 필요한 구현을 하는 예시입니다.

1. Response parameter로 전달받은 필드를 사용하여 광고 레이아웃을 구성하세요.

 필드

유형

설명

비고

 필드

유형

설명

비고

필수 title

String

광고 소재 제목

  • 최대 10자

  • 생략 부호로 일정 길이 이상은 생략 가능

필수image_url

String

URL 형태로 전달받는 광고 이미지

  • 종횡비 유지 필수

  • 여백 추가 가능

  • 이미지 너비: width / 이미지 높이: height

필수 description

String

광고에 대한 상세 설명

  • 생략 부호로 일정 길이 이상은 생략 가능

  • 최대 40자

필수 icon_url

String

광고주 아이콘 이미지

  • 종횡비 유지 필수

필수 call_to_action

String

광고의 참여를 유도하는 CTA 버튼의 UI 텍스트

  • 최대 7자

  • 생략 부호로 일정 길이 이상은 생략 가능

필수 reward

Integer

광고 참여 시 적립되는 포인트 금액

 

2. 사용자에게 광고가 노출되면 impression_urls로 전달한 URL을 호출합니다.

3. 사용자가 광고를 클릭하면 click_url로 전달한 URL을 호출합니다.

4. 사용자가 정상적으로 광고 참여를 완료하면, 버즈빌 서버에서 매체사의 포스트백 URL으로 포인트 적립 요청을 시도합니다. 자세한 내용은 매체사 포인트 적립 포스트백 API 연동 가이드를 참고하세요.

 

{ "ads": [ { "id": 1234567, // camapign_id를 의미합니다. 이해를 돕기 위한 임의의 숫자입니다. "name": "광고 이름", "impression_urls": ["https://foo.bar"], "reward": 1, "type": "cpm", // '광고 유형'을 나타내는 문자열이 내려옵니다. "reward_condition": "click", "creative": { "title": "광고 제목", "description": "광고 설명 문구", "action_description": "" "click_url": ""https://screen.buzzvil.com/api/s2s/click_redirect/?payload=eytY9sky7SYO8lJNNzj96XXQhleloUrzNMUyYmMM2F9Z0SXg_zgExsarhdQKkukI7TfAsG_E5EPR5n9gXS3y7xnQUCOSYpRIuASNuPm3jJCGTw9aRVqGvYj__iCgiVvkzVRf7s5Y2wHepxRNBUu7IZbipADjB0Cj1Q8_etS1fyk7-fweLmgIcsVnfS4P5S8SX1K7MC65M0I7F-SJj2sRrLk-28Vz2ggyfly-iiYeoJpzHPP42A5D3q6XOhInDuJeVaZXLtmTeHxQikQA2zIoaEK3t9jkrVYCf5IpTuOtx366x_jjxGupIR9eUkJwX5guomcfpKMkVR_MoFGzJOU7M7hS6NpWZsWXrNnl_heB7uuU-0qvhhsNxKB1rq0cX0nwhD2khUsuwNdSLERG6CL2Oo6xXgGh5n24LykHyMA1XDNEwpgayx6cIz6nIrO16EZlzneEo4tCqbOkOlLRKHYGWo_hVuw7AWNp8L-aFQd3FU16C_JZXElBUfaai2nErAJHEMGetGZCYKPBwAeSD3wUv__qDUE-6NBIkhWYAE_8M0bO421p0HJLk_9h9I2bbC-aSilDsWrFa1fj2aCsQiVjGNjZdNLBqNK88rhoouu0wjluSAPNZKQVDw9xhTGVr6jpFWneb8r5EEcFRz2cccVFKekWJ1EOodOwN-a7u0O1Y1ut_i2uPoc-0wb-9SUSEaqkk3mHKOoDonQEJmRwhq8uK5oGJol1GLn_ojmfyDztR1HDVmwPydA-QpYEQ_DBJv0fKflTo_QlOB2KfB5zs8uKLp0FDvMGS_5dp9NK1k-s0kv_oKPeEz8nIcaXvSHMR4mvbZuBi7Vid6bpk8dg85_Jaf-72Ral0Ssr_yTXcaZsJx6_eJPLRyNlFiu-5HDyuMhl7q-CIKkf-BQwny6T6t3eXxADDbFvzynQ-XIOj4WD3aX2uLc9CeiAQlq9Z7jwkiuP5jEAPUmpB3pcN7EABQMfr2dor7Ner8XjNTdADnfTDkkPKx6joxz42rkNA21lerqXgyND6Cm6ui_iwqOYjDRWKUQ1gDHYt4C0_shC-EOgMBwa151C32T__8KyoTPB8Au60efJTmw9bjkqGslcZOy-VdFfuiN1uQG0SYdzgSCYq-z7tWmIqMq2b6eJGclDLAXIKpwEbi3ZntmPrR_5g3vnN6DgI3c-JfzHkB6rL_n9nX6PIL_wQHitLkbFpzVvdMbENM5WFkYSYz1GpFHUE19iw5nLv5H8S_mgUPGaSpcgiSvk0y4RI2t--bJSy_BwG8aITE8jFYfoBmrUnBahrIJC4e6R-RHpg-ZJ2O2MLCU4kXVJDbV_614U0M0uVv1WT4X9N6oHylgYUU8vjvHi5mVshEcqSy4aCBBmhJ2UAkYgP4lyhdNmtpwkGC1wOSbBwJxcbP5m7a9uEyxw9YeW8uaB-9XSuavTBcH4cTTZod1bzZEyZ6FBmsXPbX0GTKseOoNukZ9Q6jC4Zlvl7I-gV18dkakzpsWzGvgYtlFE_dR7DiHG--1zVVjAEGXGbVhl5k9_HBbXwg_J3b6XoA1D-8AAfDP5QXqWV8f4MlqUJaPKKnDGqPaUGcICklJKJB7fvOlFtuGvdCR5EcJkvPfj0QUUYKYcSqZuXdg5FzIDTpJ7sEJEq6Zf-I2F5Rds1iv4QvHY2w_Pv96CMxueasNlwxxHkT9n6B4xSo72RTlhsBuCs6q29lXMLoU7Od-AiDvVLBws2I-4zS6E_FOcRWWnvOIeE-ZXVmBCcRKbiH75BbHR9ZRJSGSW4-SGBhr1lzRWqZxLJgImYnjoo5Z5rBC4ng4kRK6J3vv6ZHJdEcEhLN1_QvP-OXfv5en7YqAhjEtVKObARW5lI53LetHhkVn7vrdpC6Mw0rwXN-gb-tROHqobSJGrtfpHYinpKe7sPAnayv-tv8kvrsv4OzbYptNNKfpb15BlTpueNCLds6STnd8nv-9kwhmjc-wK-sKVsac", "call_to_action": "더 알아보기", "width": 1200, "height": 627, "icon_url": "https://foo.bar/icon.png", "image_url": "https://foo.bar/image.png", "is_deeplink": true }, "check_participation_url": "", "payload": "zh8qPfFDUycs3d_p_4kIv_8P1Q8etYu1xDtf4VDmTYyxzwqSdiPGXPXeVQGPD" }, ... ], "code": 200, "msg": "allocate successfully" }

3) Status code

  • 아래 상태코드는 http status와 별개로, Response parameter 안에 code 라는 필드를 통해 내려갑니다.

코드

설명

코드

설명

200

정상

1000

시스템 에러

9001

존재하지 않는 unit_id

9004

유효하지 않은 파라미터 (요청에 required field가 누락됐을 경우 발생)

9011

요청 unit이 inactive 상태인 경우

 

4) Custom parameter

노출형 광고를 S2S API로 연동한 상태에서 커스텀 파라미터(Custom parameter)를 추가할 수 있습니다. 커스텀 파라미터를 추가하면 원하는 정보를 버즈빌로부터 포스트백 콜백(요청)과 함께 수신할 수 있습니다.

커스텀 파라미터를 추가하려면 사용자가 광고 클릭 시 호출되는 click_url에 custom 파라미터를 추가하고 원하는 값을 설정하세요.

click_url에 custom 파라미터를 추가해서 호출하는 경우, reward_condition이 action, click인지는 신경쓰지 않고 항상 custom 파라미터를 함께 호출해 주세요.

 

노출형(cpm, cpc) 광고이더라도 실제 적립 요건은 액션(페이지 스크롤, 운세 보기 등)을 요구할 수 있습니다. 따라서 아래의 상황에서도 custom 값을 호출해 주어야 합니다.

  • revenue_type = cpm or cpc

  • reward_condition = action

Click API 호출 방식

다음은 payload 값이 부여된 요청 URL에 가상의 clickID key 값을 custom 파라미터로 추가한 예제입니다.

메서드

요청 URL

메서드

요청 URL

GET

https://screen.buzzvil.com/api/s2s/click_redirect/?payload=Zx786y9pnCkUYZfeL1PHHodk8Ae80CPEw%3D%3D&custom=%7B%22clickId%22%3A%20%22sample-clickId%22%7D

Click API Request Parameter

필드

유형

설명

필드

유형

설명

필수 payload

string

광고 할당 시 버즈빌 서버에서 부여하는 암호화된 파라미터입니다. 사용자에게 포인트를 지급하기 위해 필요한 광고 정보가 들어 있습니다.

옵션 custom

json (url-encoded)

포스트백 콜백 시 받고자 하는 추가 정보를 설정하기 위한 인코딩된 파라미터입니다.

포인트 적립 포스트백 예제

커스텀 파라미터를 추가하면 버즈빌이 요청하는 포스트백에 custom이 포함됩니다. 다음의 예제를 참고하세요.

{ ... "extra": { "custom": {"YOUR_KEY": "YOUR_VALUE"} }, ... }

 

광고 참여 요청

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

호출시점: 사용자가 할당받은 광고소재를 클릭했을 때, 호출합니다.

항목

내용

항목

내용

1

요청 방향

매체사 → Buzzvil

2

HTTP Request method

POST

3

Content-Type

application/x-www-form-urlencoded

4

HTTP Request URL

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

5

HTTP Request parameters

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

6

Response

  • JSON 형식으로 반환

  • Field 설명은 아래 ‘5) Response’ 표 참고

1) HTTP Request parameters

Field

Type

Description

Field

Type

Description

필수 unit_id

Integer

매체 아이디

필수 campaign_id

Integer

광고 아이디

필수 ifa

String

  • 안드로이드 광고 아이디(GAID)

  • 또는 iOS Identifier for Advertiser(IDFA)

예제) ab4ade35-1c8a-4405-acda-10ca1ad1abe1

광고식별자 수집이 불가능할 경우 예제) 00000000-0000-0000-0000-000000000000

필수 custom

String

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

필수 client_ip

String

광고에 참여한 유저의 ip

실제 유저의 ip 값을 전달해 주어야 합니다. 그러지 않을 경우 CPE, CPA 유형의 광고 송출이 불가합니다.

예제) 123.123.123.123

필수 payload

String

광고 할당 시 응답받았던 payload

예제) “zh8qPfFDUycs3d_p_4kIv_8P1Q8etYu1xDtf4VDmTYyxzwqSdiPGXPXeVQGPD"

권장 ifv

String

iOS 앱 벤더식별자(IDFV). iOS에서 유저가 앱 추적 허용을 하지 않아 광고식별자 수집이 불가능할 경우엔 필수로 전달해주어야 하는 값입니다. 사용자 식별을 위한 대체식별자로 사용됩니다.

예제) ab4ade35-1c8a-4405-acda-10ca1ad1abe1

권장 user_id

String

사용자 고유 식별자

권장 device_name

String

디바이스 모델 이름

권장 carrier

String

해당하는 통신사

예제) kt , skt, lgt

custom2 선택

String

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

  • 버즈빌에서 매체사로 포스트백 request 시 전달 되는 값

  • 최대 길이는 255

  • custom2~4까지 전달 가능

custom3 선택

String

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

  • 버즈빌에서 매체사 로 포스트백 request 시 전달 되는 값

  • 최대 길이는 255

  • custom2~4까지 전달 가능

custom4 선택

String

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

  • 버즈빌에서 매체사로 포스트백 request 시 전달 되는 값

  • 최대 길이는 255

  • custom2~4까지 전달 가능

2) Response

Field

Type

Description

Field

Type

Description

code

Integer

처리결과 코드

  • 200이면 정상 참여 가능

  • 이 외 code는 아래 3) 'Status Code' 표 참고

msg

String

처리결과 메세지

action_description

String

액션형 광고 참여 안내 및 주의사항 문구

예제) "[참여방법]\n- '채널 추가' 후 대화창에 전송된 환영메시지를 복사해 입력해주세요.\n\n[주의사항]\n- 이미 추가한 카카오톡 채널은 포인트가 지급되지 않습니다.\n- 카카오톡 채널의 환영메시지를 정확히 입력 후 '환영메시지 제출하기' 버튼을 눌러야 포인트가 지급됩니다.\n- 동일인이 부정한 방법으로 여러번 참여를 시도할 경우, 포인트 지급 및 추후 광고 참여에 제재가 가해집니다.\n- 30일 이내 채널을 차단한 경우, 이후 캠페인 참여시 불이익을 받을수 있습니다."

landing_url

String

광고주 페이지 랜딩 URL

3) Status Code

  • 아래 상태코드는 http status와 별개로, Response parameter 안에 code 라는 필드를 통해 내려갑니다.

코드

설명

코드

설명

200

정상

401

블랙리스트 유저

402

잘못된 ip 주소 형식

1000

시스템 에러

9001

존재하지 않는 unit_id

9004

유효하지 않은 파라미터 (요청에 required field가 누락됐을 경우 발생)

9008

존재하지 않는 캠페인

9011

요청 unit이 inactive 상태인 경우

9013

비활성화된 캠페인

9014

현재 캠페인이 라이브 중이 아니거나, 해당 매체에 타게팅되어 있지 않은 경우

9020

이미 캠페인에 참여한 경우

9021

캠페인이 모두 소진된 경우

9022

광고식별자 수집이 불가한 사용자가 광고식별자 필수 캠페인을 클릭한 경우

9031

알 수 없는 애드네트워크 캠페인 에러

9037

클릭한 사용자가 타게팅 조건에 맞지 않아 참여가 불가능한 경우

9040

광고식별자 형식이 잘못됐거나, 추적이 불가한 식별유형일 경우(e.g. 0000…)

 

광고 참여 확인

리워드 지급조건이 “action”인 캠페인의 참여여부를 확인하는 API 입니다. 이 API를 사용해 사용자에게 참여완료 여부를 알려줄 수 있습니다.

호출시점: 캠페인 참여를 마치고 앱으로 복귀하는 시점

항목

내용

항목

내용

1

요청 방향

매체사 → Buzzvil

2

HTTP Request method

GET

3

HTTP Request URL

광고요청시 받은 check_participation_url

4

Response

  • Field 설명은 아래 ‘1) Response’ 표 참고

1) Response parameter

Field

Type

Description

Field

Type

Description

result

Boolean

사용자의 캠페인 참여 여부

예제) true

 

문의하기 페이지

사용자가 문의를 등록할 수 있도록 버즈빌이 제공하는 CS 페이지 접근 API입니다. url 호출시 외부 브라우저로 이동하게 구현해야 합니다.

항목

내용

항목

내용

1

요청 방향

매체사 → Buzzvil

2

HTTP Request method

GET

3

HTTP Request URL

https://ad.buzzvil.com/offerwall/inquiry

4

HTTP Request parameters

아래 '1) HTTP Request parameters' 참고

5

Response

HTML

1) HTTP Request parameters

Field

Type

Description

Field

Type

Description

필수 app_id

Integer

버즈빌 매니저로부터 발급받은 App ID

필수 ifa

String

  • 안드로이드 광고 아이디(GAID)

  • 또는 iOS Identifier for Advertiser(IDFA)

예제) ab4ade35-1c8a-4405-acda-10ca1ad1abe1

광고식별자 수집이 불가능할 경우 예제) 00000000-0000-0000-0000-000000000000

필수 user_id

String

사용자 고유 식별자

필수 platform

String

플랫폼 구분을 위해 필요한 Enum 구분값.

  • iOS: I

  • Android: A

iOS 예제) I

Android 예제) A

권장 ifv

String

iOS 앱 벤더식별자(IDFV). iOS에서 유저가 앱 추적 허용을 하지 않아 광고식별자 수집이 불가능할 경우엔 필수로 전달해주어야 하는 값입니다. 사용자 식별을 위한 대체식별자로 사용됩니다.

예제) ab4ade35-1c8a-4405-acda-10ca1ad1abe1

Meta API

호출 시 유저가 최대로 적립 가능한 금액과 유저의 IFA 변경 여부를 확인할 수 있는 API입니다. HTTP Request Parameters는 할당 요청 API와 동일한 파라미터를 사용합니다.

항목

내용

항목

내용

1

요청 방향

매체사 → Buzzvil

2

HTTP Request Method

GET

3

HTTP Request URL

https://screen.buzzvil.com/api/s2s/ads/meta

4

HTTP Request Parameters

광고 할당 요청 API와 동일*

5

Response

  • JSON 형식

  • Field 설명은 아래 ‘1) Response Fields' 표 참고

Meta API의 target_fill로 전달되는 값은 유저가 최대로 적립 가능한 금액을 노출하기 위해 무시합니다.

1) Response Fields

Field

Type

Description

Field

Type

Description

code

Integer

처리결과 코드

  • 200이면 정상 응답

  • 이 외 code는 아래 3) 'Status Code' 표 참고

message

String

처리결과 메세지

result

JSONObject

총 적립 가능 금액과 ifa의 변경 여부를 나타냅니다.

  • 설명은 아래 3) "result Description” 표 참고

2) Status Code

코드

설명

코드

설명

200

정상

1000

시스템 에러

9001

존재하지 않는 unit_id

9004

유효하지 않은 파라미터 (요청에 required field가 누락됐을 경우 발생)

9011

요청 unit이 inactive 상태인 경우

3) result Description

Field

Type

Description

Field

Type

Description

total_reward

Integer

최대로 적립 받을 수 있는 리워드입니다.

예제) “total_reward”: 97215

is_modified_ifa

Boolean

ifa 변경 여부를 확인합니다.

  • true: ifa의 변경이 있었음

  • false: ifa의 변경이 없었음

FAQ

광고가 보이는 시점에 impression_urls을 호출합니다. 원칙적으로 광고 id 당 하나의 impression_urls가 반환됩니다. Impression_urls에는 Unit id, User ID, 그 외 포인트 적립에 필요한 parameters가 포함되어 있습니다. 따라서 impression_urls를 호출해주시면 유저가 어느 지면에서 어떤 광고에 참여했는지 등이 버즈빌 서버로 전달됩니다. (별도 파라미터를 추가하여 호출할 필요가 없습니다)

응답 중 impression_urls key로 반환되는 값의 타입은 string list 인 것이 맞습니다. 다만 대부분 list의 길이가 1입니다. 반대로 말씀드리면 항상 1인 것은 아니라서, 해당 list 내의 모든 url을 호출해주시는 방식으로 구현을 부탁드립니다.

 

가이드 변경 이력