Feed Native API

Feed Native

피드 네이티브 지면은 앱 화면과 자연스럽게 임베드 되는 앱 맞춤형 광고 지면입니다. 타이틀, 아이콘, 이미지 등 광고 지면 레이아웃을 자유롭게 구성할 수 있습니다. 리스트 및 캐러셀로 구현 가능합니다.

광고 할당 요청

항목

내용

1

요청 방향

Application -> Pointhome SDK -> Buzzvil

2

HTTP Request method

Pointhome SDK API

4

HTTP Request parameters

아래 '1) HTTP Request parameters' 참고하 각 OS 별로 PointHome SDK를 이용하여 구현구현

5

Response

  • 각 OS 별로 알맞는 데이터 형식 제공

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

1) HTTP Request parameters

NAM 광고를 HTML Element에 연결하여 즉시 송출합니다.

OS 별로 필드명이 동일하지 않으니 아래 참고 부탁드립니다.

  • [AOS] deviceName [iOS] device_name

  • [AOS] userAgent [iOS] user_agent

필드

유형

설명

deviceADID (AOS - 필수)

String (MAX 64)

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

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

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

IDFA(iOS - 필수)

String (MAX 64)

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

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

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

placementID (필수)

String (MAX 64)

매체 지면 아이디

userKey (필수)

String (MAX 64)

유저의 식별키

birthday (권장)

String (MAX 10)

유저의 생년월일

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

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

gender (권장)

String (MAX 20)

성별 타게팅을 위한 정보.

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

  • M: 남자

  • F: 여자

deviceName (권장)

String (MAX 255)

디바이스 모델명

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

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

latitude (권장)

String (MAX 32)

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

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

longitude (권장)

String (MAX 32)

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

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

userAgent (권장)

String (MAX 255)

User Agent.

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

targetFill (권장)

Int (MAX 4)

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

없을 경우 20으로 요청합니다.

cursor (권장)

String

(MAX 3000)

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

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

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

2) Response parameter

필드

유형

설명

cursor

String

할당받은 광고 데이터의 고유 값

items

List<Object>

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

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

items-object 세부 항목 (Response Fields - items - object)

Android의 필드 네임은 카멜 케이스(camelCase)로 이루어져 있습니다.

iOS, Web의 필드 네임은 스네이크 케이스(snake_case)로 이루어져 있습니다.

주의사항

매 광고마다 광고가 노출 되었을 때, impressionUrls 값으로 내려오는 Url을 전부 GET method로 요청을 해야합니다.

호출되지 않을 경우 광고 매출정산이 맞지 않을 수 있습니다.

필드

유형

설명

id

Integer

광고 아이디

예제) 10075328

name

String

광고 설명

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

impressionUrls (모든 URL을 GET method로 요청 필수)

List<String>

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

reward

Integer

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

예제) 100

rewardCondition

String

리워드 지급을 위한 조건

  • 클릭시 적립: click

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

예제)

노출형 광고상품: “click”

액션형 광고상품: “action”

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

checkParticipationUrl

String

reward_condition이 “action”일 때, 캠페인 참여 여부를 확인하는 API URL 주소. check_participation_url을 호출해 사용자에게 참여완료 여부를 알려줄 수 있습니다.

예제)

reward_condition이 "click"일 때: ""

type

String

광고 타입

노출형 상품

  • cpc: 클릭형 상품

  • cpm: 노출형 상품

액션형 상품

  • cpa: 일반 참여형 상품

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

  • cpq: 퀴즈 상품

  • cpqlite: 퀴즈 상품

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

  • cpyoutube: 유튜브 구독 상품

  • cps: 쇼핑형 상품

  • cptiktok: 틱톡 팔로우 상품

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

  • cpi: 설치형 상품

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

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

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

  • cpcquiz : 퀴즈 적립 컨텐츠

예제) “cpc”

creative

Object

광고 소재 (Object)

payload

String

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

노출형 광고 예제) ““

액션형 광고 예제) “zh8qPfFDUycs3d_p_4kIv_8P1Q8etYu1xDtf4VDmTYyxzwqSdiPGXPXeVQGPD"

creative세부 항목 (Response Fields - items - Object - creative)

Android의 필드 네임은 카멜 케이스(camelCase)로 이루어져 있습니다.

iOS, Web의 필드 네임은 스네이크 케이스(snake_case)로 이루어져 있습니다.

필드

유형

설명

title

String

광고 소재 제목

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

description

String

광고에 대한 상세 설명

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

clickUrl

String

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

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

액션형 광고 예제) ““

callToAction

String

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

예제) 참여하기

width

Integer

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

예제) 1200

height

Integer

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

예제) 627

iconUrl

String

광고주 아이콘 이미지 URL

imageUrl

String

광고소재 이미지 URL

isDeeplink

Boolean

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

예제) true

Response Parameter로 구현하기

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

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

필드

유형

설명

비고

title(필수)

String

광고 소재 제목

  • 최대 10자

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

imageUrl(필수)

String

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

  • 종횡비 유지 필수

  • 여백 추가 가능

  • 이미지 너비: width (1200px)

  • 이미지 높이: height (627px)

description(필수)

String

광고에 대한 상세 설명

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

  • 최대 40자

iconUrl(필수)

String

광고주 아이콘 이미지

  • 종횡비 유지 필수

callToAction(필수)

String

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

  • 최대 7자

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

reward(필수)

Integer

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

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

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

ImpressionUrls

사용자에게 광고가 노출되면 Response Data - items impressionUrls을 모두 다 호출해야 합니다.

상세 내용은 아래 가이드를 참고해주세요.

ClickUrls

  • 사용자가 광고를 클릭하면 Response Data - creative clickUrl을 처리해야 합니다.

  • 각 광고 객체(FeedItemsData)는 액션형광고와 노출형 광고 타입으로 구분 할 수 있습니다. 각 광고 타입마다 clickUrl을 처리하는 방식이 달라집니다.

    • 액션형 광고 : 클릭 하고 나서 설치 및 미션 수행등의 동작을 요구하는 광고

    필드

    유형

    설명

    description (필수)

    String (MAX 64)

    광고에 대한 상세 설명

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

    landingUrl (필수)

    String (MAX 64)

    매체 지면 아이디

    • 노출형 광고 : 클릭 하고 나서 광고 업체의 사이트로 이동하는 광고

  • Android 구현 코드 가이드

CheckParticipate - 광고 참여 확인

PreviousWebNextAndroid Native

Last updated