Valuepotion Web SDK

Changelog

기존에 vp-v12 혹은 그 이하 버전을 사용하시다가 v13 혹은 그 이상으로 업데이트 하는 경우

VP.init({...}) 으로 초기화를 할 때 넣던 noAd, adDisplayed, hideIframeDuringLoad 모두 삭제되어 더 이상 사용이 불가능합니다. 대신에 VP.ad(...) 함수의 opts 를 통해 사용하세요.

기존에 vp-v11 혹은 그 이하 버전을 사용하시다가 v12 혹은 그 이상으로 업데이트 하는 경우

VP.init({...}) 으로 초기화를 할 때 광고 노출 성공/실패에 대해 제공하던 noAd, adDisplayed 파라메터가 deprecated 되었습니다. 대신에 VP.ad(...) 함수의 콜백을 사용하세요.

기본 연동

SDK 스크립트 삽입

<script type="text/javascript" src="https://campaigns-assets-vp.daumcdn.net/websdk/vp-latest.min.js"></script>

초기화

https://www.valuepotion.com/apps 에 가서 앱을 생성하면, clientId 가 발급됩니다. 그 값을 초기화 하는데 사용합니다.

VP.init({clientId: "xxx"});

init 의 params

key	value	type	required
clientId	앱의 clientId	string	true

VP.init({
    clientId: "xxx"
  }
});

광고 연동하기

광고 연동을 했는데, 광고가 노출되지 않는 경우 [email protected] 로 문의 바랍니다.

배너 광고

VP.ad(divId, placement, placementWidth, placementHeight, opts);

divId

빈 element (ex> div) 를 만드시고, 그 element 의 id 값을 넣어주시면 그 안에 광고가 삽입됩니다.
광고는 iframe element 로 만들어져 주어진 element 의 child 로서 삽입됩니다.

placement

광고를 요청할 위치를 구분짓는 문자열입니다. 어떤 플레이스먼트에 최초로 광고 요청을 하고 나면, 밸류포션 대시보드에 최대 10분 안에 자동으로 해당 플레이스먼트가 등록됩니다. 그러면 https://www.valuepotion.com/publishers/ad_network_settings/placements 페이지에 가서 가서 해당 플레이스먼스의 광고 설정을 켜주시면 됩니다. 비결제 유저, 결제 유저 모두에게 광고를 노출하시려면 Non paying user, Paying user 두 항목 모두 체크를 켜주시면 됩니다. 그러면 3분 정도 지난 후 부터 광고가 노출되기 시작합니다.

placementWidth, placementHeight

노출시킬 광고의 사이즈를 의미합니다. IAB 에서 가이드하는 표준의 일부를 포함하여 아래 사이즈를 지원합니다.

size
120x600
160x600
200x200
300x250
300x600
320x50
320x100
336x280
468x60
728x90
970x90

광고를 노출시킬 영역의 사이즈가 가변적이라면, 다음 함수를 통해 영역에 가장 알맞는 광고 사이즈를 고를 수 있습니다.

var wrapperElement = document.getElementById("xxxxx");

var size = VP.getRecommendedAdSize(wrapperElement);
// 혹은
var size = VP.getRecommendedAdSize(wrapperElement, {maxWidth: 350});
// 혹은
var size = VP.getRecommendedAdSize(wrapperElement, {maxHeight: 100});
// 혹은
var size = VP.getRecommendedAdSize(wrapperElement, {maxWidth: 350, maxHeight: 100});

VP.ad(divId, placement, size.width, size.height, opts);

그 외에 앱에 특화된 사이즈의 네이티브 광고 노출을 원하시면, [email protected] 으로 문의하시어 협의 바랍니다.

opts

opts 는 생략하고

VP.ad(divId, placement, placementWidth, placementHeight);

형태로도 사용하실 수 있습니다.

opts 에 들어갈 수 있는 값은 forceWidth, hideIframeDuringLoad, callback 입니다. 320x100 으로 광고를 요청했는데, 배너로 화면 가로를 꽉 채우고 싶은 경우에는

VP.ad(divId, placement, placementWidth, placementHeight, {forceWidth: "100%"});

위와 같이 요청을 하시면, iframe 의 width 가 100% 가 되면서 가로로 꽉 차게 되고, 320px 외의 남는 좌우 여백은 광고 이미지의 (1, 1) 위치 픽셀의 색깔로 채워지게 됩니다.

hideIframeDuringLoad 를 true 로 지정하면, 광고가 로딩되는 동안에는 iframe 이 자리를 차지 하지 않고 숨어 있게 됩니다. (default: false)

callback에 함수를 담으시면 광고가 노출되는 시점 혹은 광고가 없다고 판단되는 시점에 해당 콜백이 호출됩니다.

노출된 광고가 텍스트 배너 광고인 경우, 폰트를 커스터마이징 하기 위해서 textAdStyle 에 스타일을 선언할 수 있습니다.

var opts = {
    callback: function (filled) {
        if (filled) {
            console.log("ad loaded");
        } else {
            console.log("no ad");
        }
    },
    textAdStyle: {
        "color": "red",
        "font-size": "28px",
        "font-weight": "bold"
    }
}
VP.ad(divId, placement, placementWidth, placementHeight, opts);

동영상(In-stream) 광고

동영상 컨텐츠를 제공하는 매체에서, 컨텐츠 영상에 pre-roll, mid-roll 혹은 post-roll 으로써 동영상 광고(In-stream Video Ad)를 연동하려는 경우 이 부분을 참고하시면 됩니다.

videojs 를 통해 동영상 컨텐츠를 제공하는 경우에만 이 기능을 사용할 수 있습니다.

VP.videoAd(videoElementId, placement, opts);

위와 같이 실행하면 기존의 video element 에 광고 영상이 덧붙게 됩니다.

opts 에 사용할 수 있는 값은 아래와 같습니다.

전면형 광고

배너 형태가 아니라 화면 전체를 덮는 형태의 광고를 사용하고 싶으시면

VP.interstitial(placement, opts);

형태로 광고를 요청할 수 있습니다.

opts 는 역시나 생략 가능하여

VP.interstitial(placement);

와 같이 광고를 요청하실 수 있습니다.

opts 에 들어갈 수 있는 값은 background 와 callback 이 있습니다.

background : 전면형 광고는 320x480 사이즈로 화면 정중앙에 뜨게 되는데, 그 주변의 남는 여백을 채우는 색깔을 지정합니다. 기본으로는 "rgba(0, 0, 0, 0.7)" 이라는 값이 쓰이고 있으며 "#000000" 혹은 "rgba(x, x, x, x)" 형태로 값을 넣을 수 있습니다.
callback : 광고가 뜨고 나서 실행될 콜백을 지정합니다.

opts = {
    background: "rgba(0, 0, 0, 0.8)",
    callback: function (filled) {
        if (filled) {
            console.log("ad loaded");
        } else {
            console.log("no ad");
        }
    }
}
VP.interstitial(placement, opts);

이벤트 트래킹

VP.track(params);

또는

VP.track(params, callback);

callback 은 track api의 서버 응답이 완료된 후에 호출됩니다.

비결제 이벤트

VP.track({action: "click_share_button"});

또는

VP.track({
    category: "ui",
    action: "click_share_button",
    label: "viewer"
})

또는

VP.track({
    category: "ui",
    action: "vote",
    label: "article-03",
    value: 4
})

결제 이벤트

VP.track({
    action: "purchase_with_coupon",
    revenueAmount: 1000,
    currency: "KRW",
    orderId: "xxxxxx",
    productId: "xxxxxx"
});

콜백을 붙이면

VP.track({
    action: "purchase_with_coupon",
    revenueAmount: 1000,
    currency: "KRW",
    orderId: "xxxxxx",
    productId: "xxxxxx"
}, function () {
    console.log("purchase done!");
});

유저 정보 세팅

코호트 분석 및 타겟팅을 위해 유저 정보를 설정합니다. 모든 값은 옵션이며, 얻을 수 없는 값은 설정하지 않아도 됩니다.

  VP.setUserAccountType("xxx");
  
  VP.setUserBirth("yyyyMMdd");
  
  VP.setUserFriends(32);
  
  VP.setUserGender("M" or "F");
  
  VP.setUserId("xxx");
  
  VP.setUserLevel(12);
  
  VP.setUserServerId("xxx");

고급

하이브리드 앱에서 사용하는 경우

안드로이드 앱에 웹뷰를 놓고, 그 웹뷰 안에 웹페이지를 로딩하는 방식의 하이브리드 앱에서 밸류포션 SDK 를 사용하시려는 경우에는

https://gist.github.com/ValuepotionSDK/f3316d05d0182fe420b77cb7747da0bf 를 참조하세요.

광고 테스트 시 도메인 관련 이슈

localhost 나 *.herokuapp.com 등의 도메인에서 광고 노출 여부를 테스트하는 경우 광고가 노출되지 않는 경우가 있습니다.

이럴 때는

VP.init({
    clientId: "xxx",
    pageUrl: "http://abc.com"
});

위의 코드와 같이 pageUrl 이라는 속성으로 서비스 도메인을 지정해주시면 테스트 하고 있는 환경과 상관없이 광고가 정상적으로 노출됩니다.

하지만 보다 효율 높은 광고 노출을 위해서, 실제 배포 때는 저 속성을 꼭 삭제해야 합니다.

ValuepotionSDK/README.md