8. 퍼블리셔 노출형 광고 S2S API

Owned by Kaila Kong (Unlicensed)
Last updated: Feb 10, 2023 by jua.song
5 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

매체 앱 아이디

필수unit_id

Integer

매체 지면 아이디

필수ifa

String

유저 개인 식별 정보. 어뷰징 필터링 및 CS 처리를 위해 필요합니다.

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

필수user_id

String

유저의 매체 아이디

필수client_ip

String

클라이언트 아이피. 어뷰징 필터링을 위해 사용됩니다.

예제) 123.123.123.123

권장birthday

String

유저의 생년월일

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

예제) 1993-01-09

권장gender

String

성별 타게팅을 위한 정보.

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

  • M: 남자

  • F: 여자

권장carrier

String

통신사 정보.

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

  • kt: KT 통신사

  • skt: SKT 통신사

  • lgt: LGT 통신사

권장device_name

String

디바이스 모델명

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

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

권장latitude

Float

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

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

권장longitude

Float

권장user_agent

String

User Agent.

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

 

2) Response parameter

필드

유형

설명

필드

유형

설명

code

Integer

처리결과 코드

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

msg

String

처리결과 메세지

ads

List<Object>

광고 목록

 

ads 세부 항목 (Response Fields - ads)

필드

유형

설명

필드

유형

설명

id

Integer

광고 아이디

name

String

광고 설명

impression_urls

List<String>

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

reward

Integer

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

type

String

광고 타입

  • cpc: 클릭형 광고

  • cpm: 노출형 광고

creative

Object

광고 소재

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

 

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

필드

유형

설명

필드

유형

설명

title

String

광고 소재 제목

description

String

광고에 대한 상세 설명

click_url

String

광고 클릭 시 호출되는 URL

call_to_action

String

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

예제) 참여하기

width

Integer

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

height

Integer

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

icon_url

String

광고주 아이콘 이미지

image_url

String

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

is_deeplink

Boolean

리다이렉팅된 최종 URL의 Deeplink 여부

 

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", // '광고 유형'을 나타내는 문자열이 내려옵니다. 내려올 수 있는 값은 다음과 같습니다: "cpc", "cpm", "creative": { "title": "광고 제목", "description": "광고 설명 문구", "click_url": "https://bar.foo", "call_to_action": "더 알아보기", "width": 1200, "height": 627, "icon_url": "https://foo.bar/icon.png", "image_url": "https://foo.bar/image.png", "is_deeplink": true } }, ... ], "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 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

  • Zx786y9pnCkUYZfeL1PHHodk8Ae80CPEw%3D%3D는 암호화된 payload 파라미터 예시입니다.

  • %7B%22clickId%22%3A%20%22sample-clickId%22%7D는 인코딩된 custom 파라미터 예시입니다.

Click API Request Parameter

필드

유형

설명

필드

유형

설명

필수 payload

string

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

payload 파라미터를 임의로 제거하거나 수정하지 마세요.

옵션 custom

json (url-encoded)

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

포인트 적립 포스트백 예제

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

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

 

FAQ

퍼블리셔 노출형 광고 S2S API는 광고 할당 수를 조정하는 size() 설정 방법이 존재하지 않습니다. 다만, 버즈빌 담당자에게 요청해주시기 바랍니다. 버즈빌 어드민에서 Unit 별 targetfill을 설정하여 광고 할당 수를 조정할 수 있습니다.

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

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

  • click_url은 사용자가 해당 주소로 이동하는데 그 목적이 있습니다. 따라서 HTML에서 a tag의 href를 사용해도 되고, javascript에서 location.href를 사용해도 됩니다. 현재 click_url의 구체적 호출 방법에 대해 별도 제약 사항은 없습니다. HTTP Request method 중 GET 방식으로만 호출해주시면 됩니다.

  • click_url 에도 유저의 광고 참여 정보가 담겨 암호화된 상태입니다. 반환 url 전체를 유저가 클릭하는 시점에 호출해주시면 됩니다.

 

가이드 변경 이력