Page Comparison

...

본 연동 가이드는 이러한 BuzzAd-Benefit Web SDK를 웹페이지에 적용하는 방법에 대해 설명합니다.최소 지원 버전: 1.2.0

Android와 iOS에서 추가로 해야 하는 작업은 아래의 링크를 참고하시기 바랍니다.

Child pages (Children Display)

※ 주의사항

BuzzAd-Benefit Web SDK는 현재 데스크탑/ 모바일의 일반 브라우저에서는 동작하지 않으며, 안드로이드/ 아이폰 앱에 포함된 웹뷰를 통해서 웹페이지를 보여주는 경우에 동작합니다. 이때, 안드로이드/아이폰 앱에는 BuzzAd-Benefit SDK가 적용되어 있어야 합니다.
안드로이드의 경우 TLS 1.2가 지원되지 않는 OS 4.4.2 미만의 버전에서는 Web SDK가 작동하지 않으며, 아이폰의 경우 WKWebView만 지원합니다.

Index목차

Table of Contents

exclude	.*(주의사항)

...

광고가 표시될 웹페이지를 웹뷰를 통해 보여주는 매체사의 안드로이드/ 아이폰 앱
BD 매니저를 통해 전달받은 OS 별 APP_ID 및 UNIT_ID
매체사의 안드로이드/ 아이폰 앱에 웹 SDK 지원을 위한 연동
- 안드로이드 앱 연동 가이드
- 아이폰 앱 연동 가이드
Buzzvil 서버로부터 포인트 적립 요청을 받을 수 있는 매체사 API 서버 - 포인트 postback API 연동문서 포스트백 연동 가이드
- Postback 수신 url 세팅 후 Buzzvil BD 매니저에게 전달

...

https://buzz-js.buzzvil.com/buzzad-benefit-sdk/연동하려는 버전1.3.1/buzzad-benefit-sdk.js을 입력해 주세요입력하세요.

Code Block

language	html

<script src="https://buzz-js.buzzvil.com/buzzad-benefit-sdk/1.23.31/buzzad-benefit-sdk.js">
</script>

...

Code Block

language	js

(function() {
  if (window.BuzzAdBenefit) {
    // SDK 설정
  }
})();

SDK 초기화

광고를 요청하기 전, SDK를 초기화하는 코드를 호출해야 합니다.

...

초기화 과정에는 OS 별 앱을 구분하기 위해 APP_ID를 설정합니다. 이 코드는 광고 요청 전, 반드시 1회만 호출해야 합니다. 이후 모든 광고 요청 및 동작은 지정된 APP_ID 로 이루어지게 됩니다.

자바 스크립트는 페이지가 바뀌거나 새롭게 로드되는 경우와 같은, 페이지 전환 시 이전 환경이 유지되지 않습니다. 따라서 광고가 연동된 각각의 모든 웹페이지에서 초기화 코드를 호출해야 합니다.

`BuzzAdBenefit` 초기화

Application Class의 onCreate에 아래 코드를 추가할 것을 권장합니다. 단, 최초 광고 요청 전에만 불린다면 자유롭게 코드 위치를 결정할 수 있습니다. 광고를 요청하기 전, SDK를 초기화하는 코드를 호출해야 합니다. 아래의 예제 코드를 이용하여 플랫폼 별로 다른 APP ID를 적용할 수 있습니다.

YOUR_OS_APP_ID (ANDROID_APP_ID, IOS_APP_ID 부분에 ) 부분에 위 단계에서 준비한 APP_ID를 삽입

Code Block

language	js

function getAppId() {
  var ANDROID_APP_ID = '0123456789';
  var IOS_APP_ID = '9876543210';
  
  switch(BuzzAdBenefit.platform) {
    case 'android':
      return ANDROID_APP_ID;
    case 'ios':
      return IOS_APP_ID;
    default:
      // not supported platform
  }
}
BuzzAdBenefit.init({
  appId: getAppId()
});

...

Code Block

language	js

BuzzAdBenefit.ensureAuthenticated
// 
  .then(function() => {
    	return BuzzAdBenefit.loadAd({
      		unitId: {
  	      android: 'YOUR_ANDROID_UNIT_ID', // 안드로이드 앱에서는 광고를 요청하지 않는 경우 생략 가능
  	      ios: 'YOUR_IOS_UNIT_ID', // 아이폰 앱에서는 광고를 요청하지 않는 경우 생략 가능
		}
     }
  }	});
}).then(function(nativeAd) => {
    	console.log('An ad is loaded!');
    	populateAd(nativeAd); // 광고 표시
 			
}, function).catch((e) => {
    	if (e.message === 'EMPTY_RESPONSE') {
      console.log('NO FILL');
    } else {
      console.error('An error is detected while loading ad: ' + e.message);
    }
    	hideAd();
// 광고 영역 숨김
  });

발생 가능한 에러에 대해서는 Benefit JS SDK 에러 처리 가이드 를 참고

...

nativeAd: 앞으로 사용하는 NativeAd 객체
placementView: 광고를 표시할 영역의 문서 객체 모델(DOM)
adListener: 광고의 여러 상태에 맞게 정의된 콜백들의 객체 (. 콜백의 자세한 정의 및 동작은 문서 참조)
- onImpressed(placementView, nativeAd): 광고가 화면에 표시되면 호출됨
- onClicked(placementView, nativeAd): 광고가 클릭되면 호출됨
- onRewardRequested(placementView, nativeAd): 리워드 지급 요청 API가 불릴 때 호출됨
- onRewarded(placementView, nativeAd, result): 리워드 지급 요청의 결과를 받았을 때 호출됨
- onParticipated(placementView, nativeAd): 광고의 상태가 참여 완료로 전환될 때 호출됨
- onVideoError(placementView, nativeAd, errorCode, errorMessage): 비디오 광고 재생시 발생한 에러 정보를 얻을 수 있음

위 API를 사용하기 위한 파라미터 등은 아래의 코드에서 확인할 수 있습니다.

...

language	js

...

광고 이벤트 콜백 & 기타 API 가이드를 참고하세요.

위 API를 사용하기 위한 파라미터 등은 아래의 코드에서 확인할 수 있습니다.

Code Block

language	js

function populateAd(nativeAd) {
  const adListener = {
    onImpressed: function(placementView, nativeAd) {
      console.log('ON IMPRESSED: The ad is impressed.');
    },
    onClicked: function(placementView, nativeAd) {
      console.log('ON CLICKED: The ad is clicked.');
    },
    onRewardRequested: function(placementView, nativeAd) {
      console.log('ON REWARD IMPRESSEDREQUESTED: The adReward is impressedrequested.');
    },
    onClickedonRewarded: function(placementView, nativeAd, result) {
      console.log('ON CLICKEDREWARDED: The result adof isReward: clicked.' + result);
    },
    onRewardRequestedonParticipated: function(placementView, nativeAd) {
      console.log('ON REWARDPARTICIPATED: REQUESTED:The Rewardad is set requestedto particiated.');
      updateCtaView(element.getElementsByClassName('cta')[0], nativeAd);  // 아래에서 설명
    },
    onRewardedonVideoError: function(placementView, nativeAd, resulterrorCode, errorMessage) {
      console.logerror('ON VIDEO REWARDEDERROR: TheAn resulterror ofis Rewarddetected: ' + result);errorCode + '\n' + errorMessage);
    },
  };
 onParticipated: function(placementView,
nativeAd) { const placementView = document.getElementById('placement1');
  consoleBuzzAdBenefit.logregisterNativeAd('ON PARTICIPATED: The ad is set to particiated.'nativeAd, placementView, adListener);
  renderAd(placementView, nativeAd);  // 광고 구성요소를 DOM에  updateCtaView(element.getElementsByClassName('cta')[0], nativeAd);  // 아래에서 설명
    },
    onVideoError: function(placementView, nativeAd, errorCode, errorMessage) {
      console.error('ON VIDEO ERROR: An error is detected: ' + errorCode + '\n' + errorMessage);
    },
  };
  
  const placementView = document.getElementById('placement1');
  BuzzAdBenefit.registerNativeAd(nativeAd, placementView, adListener);
  renderAd(placementView, nativeAd);  // 광고 구성요소를 DOM에 추가하여 화면에 표시
}

발생 가능한 에러에 대해서는 Benefit JS SDK 에러 처리 가이드 를 참고

Expand

title	PlacementDOM에 대한 추가 설명

PlacementView의 자식 중에 clickable 클래스를 가진 모든 문서 객체 모델은 클릭 시 랜딩 페이지를 열도록 설정됩니다.
PlacementView의 자식 중에 buzz-mediaview 클래스를 가진 첫 번째 문서 객체 모델은 이미지와 비디오 플레이어를 표시하는 영역인 MediaView로 설정됩니다.
registerNativeAd()에 넘긴 PlacementView가 이미 광고를 표시하고 있었던 경우에는 이전의 설정을 모두 초기화하고 새로운 광고에 맞도록 설정됩니다.

...

광고 객체(NativeAd)는 다음의 하위 구성요소를 가지고 있습니다. 아래 표에서 각 구성요소에 대한 정보와 요구 사항을 확인할 수 있습니다.

...

구성 요소

...

설명

...

크기

...

요구사항

...

필수 여부

...

MediaView

...

이미지, 동영상 등 광고 소재

...

1200x627 px

...

Aspect ratio 유지 권장
주위에 패딩 추가 가능

...

O

...

title

...

광고의 제목

...

최대 25자

...

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

...

O

...

description

...

광고에 대한 상세 설명

...

최대 100자

...

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

...

O

...

CTA view

...

광고의 액션 시 지급되는 포인트와 액션을 유도하는 문구

...

최대 15자

...

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

...

O

...

iconUrl

...

광고주 아이콘 이미지

...

80x80 px

...

Aspect ratio 유지 권장

...

X

...

추가하여 화면에 표시
}

발생 가능한 에러에 대해서는 Benefit JS SDK 에러 처리 가이드 를 참고

Expand

title	PlacementDOM에 대한 추가 설명

PlacementView의 자식 중에 clickable 클래스를 가진 모든 문서 객체 모델은 클릭 시 랜딩 페이지를 열도록 설정됩니다.
PlacementView의 자식 중에 buzz-mediaview 클래스를 가진 첫 번째 문서 객체 모델은 이미지와 비디오 플레이어를 표시하는 영역인 MediaView로 설정됩니다.
registerNativeAd()에 넘긴 PlacementView가 이미 광고를 표시하고 있었던 경우에는 이전의 설정을 모두 초기화하고 새로운 광고에 맞도록 설정됩니다.

Step 5: 광고 레이아웃 구성하기

광고 레이아웃을 구성하는 정보와 UI에 대해서는 아래의 표를 참고하세요.

구성 요소

설명

MediaView

Status

colour	Green
title	필수

광고 소재의 종류에 따라 이미지나 동영상 플레이어가 삽입되는 영역입니다.
사이즈: 1200 x 627 (px) (광고 소재의 종횡비는 방드시 유지해야 합니다.)
여백을 추가할 수 있습니다. 자세한 내용은 버즈빌 매니저에게 문의하세요.
SDK는 PlacementView의 자식 중에서 buzz-mediaview 클래스를 가진 첫 번째 문서 객체 모델을 찾아 MediaView로 설정합니다.
MediaView에 설정한 아래의 CSS 속성은, 편의를 위해 이미지나 비디오 플레이어가 자동으로 상속 받아 적용합니다.
- border-radius
- height
- max-width
- width

title

Status

colour	Green
title	필수

광고의 제목입니다. 최대 10자까지 권장하며, 필요에 따라 글자 수에 상관 없이 일정 부분은 생략 부호도 대체할 수 있습니다.

description

Status

colour	Green
title	필수

광고에 대한 상세 설명입니다. 최대 40자까지 권장하며, 필요에 따라 글자 수에 상관 없이 일정 부분은 생략 부호도 대체할 수 있습니다.

CTA view

Status

colour	Green
title	필수

광고의 액션 시 지급되는 포인트와 액션을 유도하는 문구입니다. 최대 7자까지 권장하며, 필요에 따라 글자 수에 상관 없이 일정 부분은 생략 부호도 대체할 수 있습니다.

iconUrl

Status

colour	Blue
title	권장

광고주 아이콘 이미지입니다. 아이콘의 종횡비는 반드시 유지해야 합니다.
사이즈: 80 x 80 (px)

광고 객체(NativeAd)는 native-ad를 클래스로 지정한 태그의 하위에 아래 구조에 맞게 구성해야 합니다.

다음은 PlacementView DOM의 예시입니다.

Code Block

language	html

<li class="post native-ad" id="placement1" style="display: none">
  <div class="buzz-mediaview clickable">
  </div>
  <div class="info">
    <div class="icon-wrapper clickable">
      <img class="icon">
    </div>
    <h5 class="title clickable"></h5>
  </div>
  <div class="description">
  </div>
  <div class="button-wrapper">
    <button class="cta clickable"></button>
  </div>
</li>

다음은 광고를 화면에 표시하거나 숨기는

...

JavaScript 코드

...

예시입니다.

Code Block

language	js

function renderAd(placementView, nativeAd) {
  placementView.style.display = '';
  placementView.getElementsByClassName('icon')[0].setAttribute('src', nativeAd.iconUrl);
  placementView.getElementsByClassName('title')[0].innerHTML = nativeAd.title;
  placementView.getElementsByClassName('description')[0].innerHTML = nativeAd.description;
 
  updateCtaView(rootViewplacementView.getElementsByClassName('cta')[0], nativeAd);
}

function hideAd() {
  const placementView = document.getElementById('placement1');
  placementView.style.display
= 'none';
}

MediaView

광고의 종류에 따라 이미지나 비디오 플레이어가 삽입되는 영역입니다.
SDK는 PlacementView의 자식 중에서 buzz-mediaview 클래스를 가진 첫 번째 문서 객체 모델을 찾아 MediaView로 설정합니다.
MediaView에 설정한 아래의 CSS 속성은, 편의를 위해 이미지나 비디오 플레이어가 자동으로 상속 받아 적용합니다.
- border-radius
- height
- max-width
- width

...

 placementView.style.display = 'none';
}

CTA View 주의 사항

CTA View는 참여를 유도하기 위한 버튼입니다. 현재 리워드 상태와 참여 유도 문구를 표시할 수 있습니다. 여러 조건에 따라 디자인을 변경할 수 있습니다.

또한 디자인 커스터마이즈는 커스터마이징은 SDK에서 제공하지 않으며, 않으므로 직접 구현해야 합니다. 아래 경우에 따라 디자인을 변경할 수 있습니다디자인을 자체 구현할 수 있는 경우는 다음과 같습니다.

광고 자체에 리워드가 없는 경우
- 유저가 적립을 받았으나 재적립 주기가 돌아오지 않은 상태로 광고가 노출된 경우 (리워드가 부여되지 않은 경우)
- 원래 리워드가 없는 광고인 경우
현재 지급 가능한 리워드가 있는 경우
사용자가 광고에 참여하여 참여 완료 상태인

...

경우

Info

1번, 2번의 경우, 광고를 처음 화면에 표시할 때 nativeAd.reward > 0인지 확인하여 표시합니다.
3번의 경우 onParticipated 이벤트를 받았을 때 nativeAd.particiated가 참인지 여부를 체크하여 CtaView를 업데이트 해야 합니다. (아래 샘플 코드의 updateCtaView라는 함수의 구현을 참고) 이 함수는 처음 광고를 보여줄 때, 그리고 onParticipated 이벤트를 받았을 때 실행됩니다.

Code Block

language	js

function updateCtaView(ctaView, nativeAd) {
  var ctaTextHeader = '';
  if (nativeAd.reward) {
    if (nativeAd.participated) {
      // CtaView의 디자인을 '이미 참여하여 리워드 지급 불가능 상태'로 표시
    } else {
      // CtaView의 디자인을 '참여 시 리워드 지급 가능 상태'로 표시
      ctaTextHeader = '+' + nativeAd.reward + ' ';
    }
  } else {
    // CtaView의 디자인을 '지급 가능한 리워드 없음' 상태로 표시
  }
  ctaView.innerText = ctaTextHeader + nativeAd.callToAction;
}

...

Code Block

language	js

BuzzAdBenefit.ensureAuthenticated
  .then(function() => {
    	return BuzzAdBenefit.loadAds({
      		unitId: {
  	      android: 'YOUR_UNIT_ID_ANDROID', // 안드로이드 앱에서는 광고를 요청하지 않는 경우 생략 가능
	      ios: 'YOUR_UNIT_ID_IOS', // 아이폰 앱에서는 광고를 요청하지 않는 },경우 생략 가능
     		},
		count: 3
 	});
}).then(function(nativeAds) => {
    	console.log(nativeAds.length + ' ads are loaded!');			
  }).catch(function(e) => {
	if (e.message === 'EMPTY_RESPONSE') {
      console.log('NO FILL');
    } else {
      console.error('An error is detected while loading ad: ' + e.message);
    }
});

SDK가 감지한 플랫폼 정보 체크하기

웹 SDK는 자동으로 현재 실행되고 있는 환경이 안드로이드 또는 아이폰 웹뷰를 통한 것인지, 아니면 순수 웹 브라우저를 통해 접속한 것인지 체크합니다. 이 정보를 얻고 싶은 경우 다음과 같이 사용할 수 있습니다.

...

registerNativeAd(nativeAd, placementView, adListener)의 두번째 인자로 전달한 Placement View의 SDK는 다음과 같은 추가적인 작업을 합니다.

광고가 화면에 보이는지 여부를 자동으로 체크합니다.
clickable을 클래스로 등록한 자식 문서 객체 모델이 있는 경우, 클릭하여 랜딩 페이지를 열 수 있도록 설정합니다.

Placement View로 전달한 문서 객체 모델에서 더 이상 광고를 표시하고 싶지 않은 경우, 위의 추가된 작업을 해제해야 합니다. 해제를 위해 다음의 코드를 호출합니다.

...

Versions Compared

Old Version 22

New Version Current

Key

※ 주의사항

SDK 초기화

`BuzzAdBenefit` 초기화

Step 5: 광고 레이아웃 구성하기

MediaView

CTA View 주의 사항

SDK가 감지한 플랫폼 정보 체크하기

Page Comparison

Versions Compared

Old Version 22

New Version Current

Key

※ 주의사항

SDK 초기화

BuzzAdBenefit 초기화

Step 5: 광고 레이아웃 구성하기

MediaView

CTA View 주의 사항

SDK가 감지한 플랫폼 정보 체크하기

`BuzzAdBenefit` 초기화