# Feed Native API

## Feed Native <a href="#id-android-feednative" id="id-android-feednative"></a>

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

## 광고 할당 요청 <a href="#undefined" id="undefined"></a>

<table data-header-hidden><thead><tr><th width="84"></th><th></th><th></th></tr></thead><tbody><tr><td><strong>항목</strong></td><td><strong>내용</strong></td><td></td></tr><tr><td>1</td><td>요청 방향</td><td>Application -> Pointhome SDK -> Buzzvil</td></tr><tr><td>2</td><td>HTTP Request method</td><td>Pointhome SDK API</td></tr><tr><td>4</td><td>HTTP Request parameters</td><td>아래 '1) HTTP Request parameters' 참고하 각 OS 별로 PointHome SDK를 이용하여 구현구현</td></tr><tr><td>5</td><td>Response</td><td><ul><li>각 OS 별로 알맞는 데이터 형식 제공</li><li>Field 설명은 아래 ‘5) Response Fields' 표 참고</li></ul></td></tr></tbody></table>

## 1) HTTP Request parameters <a href="#undefined" id="undefined"></a>

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

{% hint style="warning" %}
OS 별로 필드명이 동일하지 않으니 아래 참고 부탁드립니다.

* \[AOS] deviceName \[iOS] device\_name
* \[AOS] userAgent \[iOS] user\_agent
  {% endhint %}

<table data-full-width="false"><thead><tr><th width="159"></th><th width="109"></th><th></th></tr></thead><tbody><tr><td><strong>필드</strong></td><td><strong>유형</strong></td><td><strong>설명</strong></td></tr><tr><td><code>deviceADID</code><br><mark style="color:red;">(AOS - 필수)</mark></td><td>String<br>(MAX 64)</td><td><p>사용자의 광고식별자. 광고 타게팅 및 어뷰징 필터링, CS 처리를 위해 필요합니다. <strong>광고식별자 수집이 불가능할 경우 uuid 포맷을 모두 0으로 채워 요청해야 합니다.</strong></p><p></p><p><mark style="color:blue;">예제) ab4ade35-1c8a-4405-acda-10ca1ad1abe1</mark></p><p></p><p><mark style="color:red;"><strong>광고식별자 수집이 불가능할 경우 전달 값) 00000000-0000-0000-0000-000000000000</strong></mark></p></td></tr><tr><td><code>IDFA</code><mark style="color:red;">(iOS - 필수)</mark></td><td>String<br>(MAX 64)</td><td><p>사용자의 광고식별자. 광고 타게팅 및 어뷰징 필터링, CS 처리를 위해 필요합니다. <strong>광고식별자 수집이 불가능할 경우 uuid 포맷을 모두 0으로 채워 요청해야 합니다.</strong></p><p></p><p><mark style="color:blue;">예제) ab4ade35-1c8a-4405-acda-10ca1ad1abe1</mark></p><p></p><p><mark style="color:red;"><strong>광고식별자 수집이 불가능할 경우 전달 값) 00000000-0000-0000-0000-000000000000</strong></mark></p></td></tr><tr><td><code>placementID</code><br><mark style="color:red;">(필수)</mark></td><td>String<br>(MAX 64)</td><td>매체 지면 아이디</td></tr><tr><td><code>userKey</code><br><mark style="color:red;">(필수)</mark></td><td>String<br>(MAX 64)</td><td>유저의 식별키</td></tr><tr><td><code>birthday</code><br><mark style="color:green;">(권장)</mark></td><td>String<br>(MAX 10)</td><td><p>유저의 생년월일</p><p>생년월일 정보가 없을 경우 일부 광고가 할당에서 제외됩니다.</p><p></p><p><mark style="color:red;"><strong>예제) 1993-01-09 ( O )</strong></mark> <mark style="color:blue;">19930109 ( X )</mark></p></td></tr><tr><td><code>gender</code><br><mark style="color:green;">(권장)</mark></td><td>String<br>(MAX 20)</td><td><p>성별 타게팅을 위한 정보.</p><p>성별 정보가 없을 경우 일부 광고가 할당에서 제외됩니다.</p><ul><li><code>M</code>: 남자</li><li><code>F</code>: 여자</li></ul></td></tr><tr><td><code>deviceName</code><br><mark style="color:green;">(권장)</mark></td><td>String<br>(MAX 255)</td><td><p>디바이스 모델명</p><p>디바이스 모델명이 없을 경우 일부 광고가 할당에서 제외됩니다.</p><p></p><p><mark style="color:blue;">예제) SHV-E250S,SHV-E275K,SM-G928L → SHV-E250S 또는 SHV-E275K 또는 SM-G928L 인 유저에게 타게팅</mark></p></td></tr><tr><td><code>latitude</code><br><mark style="color:green;">(권장)</mark></td><td>String<br>(MAX 32)</td><td><p>위도 와 경도. 지역별 광고 타게팅에 사용됩니다.</p><p>정보가 없을 경우 일부 광고가 할당에서 제외됩니다.</p></td></tr><tr><td><code>longitude</code><br><mark style="color:green;">(권장)</mark></td><td>String<br>(MAX 32)</td><td><p>위도 와 경도. 지역별 광고 타게팅에 사용됩니다.</p><p>정보가 없을 경우 일부 광고가 할당에서 제외됩니다.</p></td></tr><tr><td><code>userAgent</code><br><mark style="color:green;">(권장)</mark></td><td>String<br>(MAX 255)</td><td><p>User Agent.</p><p>정보가 없을 경우 일부 광고가 할당에서 제외됩니다.</p></td></tr><tr><td><code>targetFill</code><br><mark style="color:green;">(권장)</mark></td><td>Int<br>(MAX 4)</td><td><p>할당받을 광고갯 수. 한번에 할당 가능한 최대 targetFill은 20 입니다.</p><p>없을 경우 20으로 요청합니다.</p></td></tr><tr><td><code>cursor</code><br><mark style="color:green;">(권장)</mark></td><td><p>String</p><p>(MAX 3000)</p></td><td><p>할당에서 제외할 광고 데이터</p><p>할당 요청에 대한 <code>response</code>에 <code>cursor</code>가 포함되어 있습니다. 이후의 request parameter에 포함하면 기존에 할당받은 광고가 제외된 광고 목록을 받을 수 있습니다.</p><p></p><p><mark style="color:blue;">예제) EvTIfLfbEUk7O_ylo5_rVBaEmt0jvIZvbI4o47azTNLDwGwbz2OoO522T4-9AzrlDwxo4ucwZ7pFg6LD-ReBNI8Yi9TKxWurSDIPvAhkqWuzY07jI_ej4Lngk_YeehlipFFV0ZfL8dnAY00xs6ydXTllkP_g_UOhHoyxxgyr3Qldp53TLXwTiv-7asYPa5H8</mark></p></td></tr></tbody></table>

* [Android 구현 코드 가이드](https://avatye.gitbook.io/spc/android-native#id-android-feednative)
* [iOS 구현 코드 가이드](https://avatye.gitbook.io/spc/ios-native#id-ios-getfeed)
* [Web 구현 코드 가이드](https://avatye.gitbook.io/spc/web#undefined-1)

## 2) Response parameter <a href="#undefined" id="undefined"></a>

<table data-full-width="false"><thead><tr><th width="157.33333333333331"></th><th width="165"></th><th></th></tr></thead><tbody><tr><td><strong>필드</strong></td><td><strong>유형</strong></td><td><strong>설명</strong></td></tr><tr><td><code>cursor</code></td><td>String</td><td>할당받은 광고 데이터의 고유 값</td></tr><tr><td><code>items</code></td><td>List&#x3C;Object></td><td><p>광고 목록 : 가변길이 입니다.</p><p>아래의 items 필드 값에 따라 결정됩니다.</p></td></tr></tbody></table>

&#x20;

### `items-object` 세부 항목 (Response Fields - items - object) <a href="#id-android-responsesuccessobject" id="id-android-responsesuccessobject"></a>

{% hint style="warning" %}
Android의 필드 네임은 카멜 케이스(camelCase)로 이루어져 있습니다.&#x20;

iOS, Web의 필드 네임은 스네이크 케이스(snake\_case)로 이루어져 있습니다.
{% endhint %}

#### <mark style="color:red;">주의사항</mark> <a href="#id-ios" id="id-ios"></a>

매 광고마다 광고가 노출 되었을 때, <mark style="color:red;">impressionUrls 값으로 내려오는 Url을 전부 GET method</mark>로 요청을 해야합니다.

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

<table data-full-width="false"><thead><tr><th width="258.3333333333333"></th><th width="131"></th><th></th></tr></thead><tbody><tr><td><strong>필드</strong></td><td><strong>유형</strong></td><td><strong>설명</strong></td></tr><tr><td><code>id</code></td><td>Integer</td><td><p>광고 아이디</p><p><mark style="color:blue;">예제) 10075328</mark></p></td></tr><tr><td><code>name</code></td><td>String</td><td><p>광고 설명</p><p><mark style="color:blue;">예제) "11번가 신선밥상"</mark></p></td></tr><tr><td><mark style="color:red;"><code>impressionUrls</code></mark><br><mark style="color:red;">(모든 URL을 GET method로 요청 필수)</mark></td><td>List&#x3C;String></td><td><p><mark style="color:red;">사용자에게 광고 노출시 호출되는 URL</mark></p><p></p><p><mark style="color:blue;">예제)</mark> <a href="https://ad-staging.buzzvil.com/api/impression?data=ReOJjkH6mus-sxbys_1F2Bg9EHwkoGAAfb86yWB">https://ad-staging.buzzvil.com/api/impression?data=ReOJjkH6mus-sxbys_1F2Bg9EHwkoGAAfb86yWB</a></p></td></tr><tr><td><code>reward</code></td><td>Integer</td><td><p>광고 참여 시 적립되는 포인트 금액</p><p><mark style="color:blue;">예제) 100</mark></p></td></tr><tr><td><code>rewardCondition</code></td><td>String</td><td><p>리워드 지급을 위한 조건</p><ul><li>클릭시 적립: <code>click</code></li><li>특정 액션 수행시 적립: <code>action</code></li></ul><p><mark style="color:blue;">예제)</mark></p><p><mark style="color:blue;">노출형 광고상품: “click”</mark></p><p><mark style="color:blue;">액션형 광고상품: “action”</mark></p><p><mark style="color:blue;">노출형 광고상품이지만 특정 액션을 수행해야 적립되는 광고: “action”</mark></p></td></tr><tr><td><code>checkParticipationUrl</code></td><td>String</td><td><p><code>reward_condition</code>이 “action”일 때, 캠페인 참여 여부를 확인하는 API URL 주소. <code>check_participation_url</code>을 호출해 사용자에게 참여완료 여부를 알려줄 수 있습니다.</p><p> </p><p><mark style="color:blue;">예제)</mark></p><p><mark style="color:blue;">reward_condition이 "click"일 때: ""</mark></p><p><mark style="color:blue;">reward_condition이 "action"일 때:</mark> “<a href="https://ad.buzzvil.com/api/check_conversion?data=ReOJjkH6mus">https://ad.buzzvil.com/api/check_conversion?data=ReOJjkH6mus</a>"</p></td></tr><tr><td><code>type</code></td><td>String</td><td><p>광고 타입</p><p><strong>노출형 상품</strong></p><ul><li><code>cpc</code>: 클릭형 상품</li><li><code>cpm</code>: 노출형 상품</li></ul><p><strong>액션형 상품</strong></p><ul><li><code>cpa</code>: 일반 참여형 상품</li><li><code>cpk</code>: 카카오톡 채널 추가 상품</li><li><code>cpq</code>: 퀴즈 상품</li><li><code>cpqlite</code>: 퀴즈 상품</li><li><code>cpl</code>: 페이스북 좋아요 상품</li><li><code>cpyoutube</code>: 유튜브 구독 상품</li><li><code>cps</code>: 쇼핑형 상품</li><li><code>cptiktok</code>: 틱톡 팔로우 상품</li><li><code>cpnstore</code>: 네이버 스토어 알림설정 상품</li><li><code>cpi</code>: 설치형 상품</li><li><code>cpe</code>: 앱내 이벤트 참여 상품</li><li><code>cpylike</code>: 유튜브 구독+좋아요 상품</li><li><code>cpinsta</code>: 인스타그램 팔로우 상품</li><li><code>cpcquiz</code> : 퀴즈 적립 컨텐츠</li></ul><p>예제) “cpc”</p></td></tr><tr><td><code>creative</code></td><td>Object</td><td><p>광고 소재 (Object)</p><ul><li>자세한 사항은 하단 '<a href="#id-android-responsesuccessobject-2">Response Data - creative</a> ' 표 참고</li></ul></td></tr><tr><td><code>payload</code></td><td>String</td><td><p>액션형 광고 참여시 필요한 콜백 파라미터를 인코딩한 문자열</p><p><mark style="color:blue;">노출형 광고 예제) ““</mark></p><p><mark style="color:blue;">액션형 광고 예제) “zh8qPfFDUycs3d_p_4kIv_8P1Q8etYu1xDtf4VDmTYyxzwqSdiPGXPXeVQGPD"</mark></p></td></tr></tbody></table>

&#x20;

### `creative`세부 항목 (Response Fields -  items - Object - creative) <a href="#id-android-responsesuccessobject" id="id-android-responsesuccessobject"></a>

{% hint style="warning" %}
Android의 필드 네임은 카멜 케이스(camelCase)로 이루어져 있습니다.&#x20;

iOS, Web의 필드 네임은 스네이크 케이스(snake\_case)로 이루어져 있습니다.
{% endhint %}

<table data-header-hidden data-full-width="false"><thead><tr><th width="175"></th><th width="108"></th><th></th></tr></thead><tbody><tr><td><strong>필드</strong></td><td><strong>유형</strong></td><td><strong>설명</strong></td></tr><tr><td><code>title</code></td><td>String</td><td><p>광고 소재 제목</p><p><mark style="color:blue;">예제) “LG전자 베스트샵 카카오톡 채널추가”</mark></p></td></tr><tr><td><code>description</code></td><td>String</td><td><p>광고에 대한 상세 설명</p><p><mark style="color:blue;">예제) “LG전자 베스트샵 이벤트, 풍성한 혜택 정보까지! 가장 먼저 만나보세요!”</mark></p></td></tr><tr><td><code>clickUrl</code></td><td>String</td><td><p>광고 클릭 시 호출되는 URL. cpc, cpm 광고만 값이 채워짐.</p><p><mark style="color:blue;">노출형 광고 예제) “https://screen.buzzvil.com/api/s2s/click_redirect/?payload=eytY9sky7fy45qys84KAzTqBAQeSDSKtvTolx1-Zy9Y8ND9t1hE1Mn”</mark></p><p><mark style="color:blue;">액션형 광고 예제) ““</mark></p></td></tr><tr><td><code>callToAction</code></td><td>String</td><td><p>광고의 참여를 유도하는 CTA 버튼의 UI 텍스트</p><p><mark style="color:blue;">예제) 참여하기</mark></p></td></tr><tr><td><code>width</code></td><td>Integer</td><td><p>광고 소재의 가로 길이. 값은 1200으로 고정</p><p><mark style="color:blue;">예제) 1200</mark></p></td></tr><tr><td><code>height</code></td><td>Integer</td><td><p>광고 소재의 세로 길이. 값은 627으로 고정</p><p><mark style="color:blue;">예제) 627</mark></p></td></tr><tr><td><code>iconUrl</code></td><td>String</td><td><p>광고주 아이콘 이미지 URL</p><p><mark style="color:blue;">예제)</mark> <a href="https://d3aulf22blzf9p.cloudfront.net/uploads/1662458645-S98R6.png">https://d3aulf22blzf9p.cloudfront.net/uploads/1662458645-S98R6.png</a></p></td></tr><tr><td><code>imageUrl</code></td><td>String</td><td><p>광고소재 이미지 URL</p><p><mark style="color:blue;">예제)</mark> <a href="https://d3aulf22blzf9p.cloudfront.net/uploads/1677571904-JZ8YB.jpg">https://d3aulf22blzf9p.cloudfront.net/uploads/1677571904-JZ8YB.jpg</a></p></td></tr><tr><td><code>isDeeplink</code></td><td>Boolean</td><td><p>리다이렉트 될 최종 URL의 Deeplink 여부</p><p><mark style="color:blue;">예제) true</mark></p></td></tr></tbody></table>

&#x20;

### Response Parameter로 구현하기 <a href="#id-android-responsesuccessobject" id="id-android-responsesuccessobject"></a>

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

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

<figure><img src="https://283698080-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FF12VJfGFMBuW9L8L55dS%2Fuploads%2FnunFaR5dF05w07JSqjE9%2FFrame%2016-20240125-091000.png?alt=media&#x26;token=3c292d6a-849d-497c-90d1-5dc7879be8fc" alt=""><figcaption></figcaption></figure>

<table data-header-hidden data-full-width="false"><thead><tr><th width="173"></th><th width="87"></th><th width="176"></th><th></th></tr></thead><tbody><tr><td> <strong>필드</strong></td><td><strong>유형</strong></td><td><strong>설명</strong></td><td><strong>비고</strong></td></tr><tr><td><code>title</code><mark style="color:red;">(필수)</mark></td><td>String</td><td>광고 소재 제목</td><td><ul><li>최대 10자</li><li>생략 부호로 일정 길이 이상은 생략 가능</li></ul></td></tr><tr><td><code>imageUrl</code><mark style="color:red;">(필수)</mark></td><td>String</td><td>URL 형태로 전달받는 광고 이미지</td><td><ul><li>종횡비 유지 필수</li><li>여백 추가 가능</li><li>이미지 너비: width (1200px) </li><li>이미지 높이: height (627px)</li></ul></td></tr><tr><td><code>description</code><mark style="color:red;">(필수)</mark></td><td>String</td><td>광고에 대한 상세 설명</td><td><ul><li>생략 부호로 일정 길이 이상은 생략 가능</li><li>최대 40자</li></ul></td></tr><tr><td><code>iconUrl</code><mark style="color:red;">(필수)</mark></td><td>String</td><td>광고주 아이콘 이미지</td><td><ul><li>종횡비 유지 필수</li></ul></td></tr><tr><td><code>callToAction</code><mark style="color:red;">(필수)</mark></td><td>String</td><td>광고의 참여를 유도하는 CTA 버튼의 UI 텍스트</td><td><ul><li>최대 7자</li><li>생략 부호로 일정 길이 이상은 생략 가능</li></ul></td></tr><tr><td><code>reward</code><mark style="color:red;">(필수)</mark></td><td>Integer</td><td>광고 참여 시 적립되는 포인트 금액</td><td> </td></tr></tbody></table>

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

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

## ImpressionUrls <a href="#id-android-impressionurls" id="id-android-impressionurls"></a>

{% hint style="warning" %}
사용자에게 광고가 노출되면 [Response Data - items](#id-android-responsesuccessobject-1) `impressionUrls`을 모두 다 호출해야 합니다.
{% endhint %}

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

* [Android 구현 가이드](#id-android-impressionurls)
* [iOS 구현 가이드](https://avatye.gitbook.io/spc/ios-native#id-ios)
* [Web 구현 가이드](https://avatye.gitbook.io/spc/web#id-android-impressionurls-1)

## ClickUrls <a href="#id-android-clickurls" id="id-android-clickurls"></a>

* 사용자가 광고를 클릭하면 [Response Data - creative](#id-android-responsesuccessobject-2) `clickUrl`을 처리해야 합니다.
* 각 광고 객체(FeedItemsData)는 액션형광고와 노출형 광고 타입으로 구분 할 수 있습니다. 각 광고 타입마다 `clickUrl`을 처리하는 방식이 달라집니다.

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

  <table data-header-hidden data-full-width="false"><thead><tr><th width="164"></th><th width="189"></th><th></th></tr></thead><tbody><tr><td><strong>필드</strong></td><td><strong>유형</strong></td><td><strong>설명</strong></td></tr><tr><td><code>description</code><br><mark style="color:red;">(필수)</mark></td><td>String<br>(MAX 64)</td><td><p>광고에 대한 상세 설명</p><p></p><p><mark style="color:blue;">예제) “LG전자 베스트샵 이벤트, 풍성한 혜택 정보까지! 가장 먼저 만나보세요!”</mark></p></td></tr><tr><td><code>landingUrl</code><br><mark style="color:red;">(필수)</mark></td><td>String<br>(MAX 64)</td><td>매체 지면 아이디</td></tr></tbody></table>

  * 노출형 광고 : 클릭 하고 나서 광고 업체의 사이트로 이동하는 광고
* [Android 구현 코드 가이드](#id-android-clickurls)

## CheckParticipate - 광고 참여 확인 <a href="#id-android-checkparticipate" id="id-android-checkparticipate"></a>

* 리워드 지급조건이 액션형 광고의 참여여부를 사용자에게 알려줄 수 있습니다.
* [Android 구현 코드 가이드](#id-android-checkparticipate)
