3. 광고주 CPS Web 연동

Introduction

BuzzAd 의 인벤토리를 통해 들어온 유저가 광고주의 웹페이지에서 광고하는 상품에 대한 구매 여부를 트래킹합니다.

1) 광고 참여 및 포인트 지급 Flow


  1. BuzzAd의 인벤토리를 통해서 유저가 광고주의 광고로 랜딩하여 들어올 때, BuzzAd 서버에서는 유저의 액션을 트래킹하기 위한 id인 bz_tracking_id 를 원래의 랜딩 url에 파라미터로 붙여서 전달합니다.

  2. 광고주 페이지에서 유저의 상품 구매가 완료되면, Javascript 연동 코드를 통해 또는 광고주 서버로부터 API 호출을 통해bz_tracking_id, transaction_id, count 값을 전달합니다.

  3. BuzzAd 서버에서는 전달받은 bz_tracking_id, transaction_id, count (또는 order_list) 값을 이용해 광고에 참여 완료한 유저 정보를 찾아서 해당 유저에게 구매한 상품 및 개수에 맞는 포인트를 지급합니다.

bz_tracking_id 는 광고마다 부여되는 고정된 값이 아니라, 유저의 클릭 때마다 매번 달라지는 값입니다.
transaction_id 는 유저의 상품 구매 시 마다 생성되는 고유한 값입니다.
counttransaction_id 생성될 때 함께 발생하는 값으로 유저가 구매하는 상품의 개수를 의미합니다.
order_list는 버즈빌과 자동으로 상품목록을 받아오는 API 연동을 진행하셨을 경우 유저의 결제 정보(상품 번호, 수량, 상품 단가 등)를 담고 있습니다.

2) 연동 방식 선택

위 Flow chart 의 “Action Complete” 신호를 전달하는 방식 (파란색 화살표) 에 따라 Javascript 를 이용한 연동과 Server to Server API 연동이 있습니다.

두 가지 방식 중 상황에 맞게 하나를 선택해서 연동 작업을 진행해주세요.


 

1. Server to Server 연동 - 액션 달성 API

JavaScript 방식으로 연동을 완료했을 경우 본 항목은 불필요합니다.

사용자가 광고상품 구매를 완료하면 BuzzAd 서버로 액션이 수행 되었음을 알려주어야 합니다. 연동은 다음과 같이 진행합니다.

항목

내용

항목

내용

1

요청 방향

광고주 → 버즈빌

2

HTTP Request method

POST or GET

3

HTTP Request URL

https://track.buzzvil.com/action/pb/cps/default/

광고 상품을 자동으로 받아오는 연동을 진행한 경우 Request URL 주소를 새로 발급하여 사용해야합니다. 연동 진행시 운영자에게 주소 발급을 요청 해주세요.
ex. https://track.buzzvil.com/network/pb/{광고주명}

4

HTTP Request parameters

Field 설명

  • bz_tracking_id (String)

    • 광고와 유저 트래킹을 위한 아이디

    • BuzzAd에서 광고와 연결된 URL로 전환 시 함께 전달되는 값으로, 광고주 웹 사이트는 이 값을 보관하였다가 액션 달성 API 호출 시 다시 전달해주어야 합니다.

  • transaction_id (String) - CPS에서만 사용

    • 유저가 상품 구매 이벤트를 트래킹 하기 위한 고유한 아이디

    • 유저가 광고 페이지에서 상품 구매를 하였을 때 해당 파라미터에 값이 인입되며, 광고 페이지 방문만으로는 생성되지 않습니다. 웹 사이트는 이 값이 발생되면 보관하였다가 액션 달성 API 호출 시 전달해 줍니다.

  • count (Integer) - CPS에서만 사용, 버즈빌과 자동으로 상품목록을 받아오는 API 연동을 진행하지 않으셨을 경우에만 사용

    • 유저가 구매한 상품의 개수

    • transaction_id 값이 생성시 같이 생성되는 값으로 액션 달성 API 호출 시 전달되는 값입니다.

  • order_list(String) - CPS에서만 사용, 버즈빌과 자동으로 상품목록을 받아오는 API 연동을 진행하셨을 경우에만 사용

    • 유저가 구매한 상품의 리스트. 여러개의 order 객체가 담길 수 있는 json format의 String입니다.

    • 상품 목록을 자동을 받아오는 연동을 진행하지 않으셨을 경우 order_list 대신 위의 count를 보내주게끔 연동을 진행하셔서 햡니다.

    • order 객체는 유저가 주문완료한 각각의 상품을 나타내고 다음과 같이 구성됩니다.

      • id(Integer) - 상품의 고유 ID.

      • count(Integer) - 유저가 구매한 해당 상품의 수량

      • price(Integer) - 해당 상품의 단가

    • (예시1) [{“count”: 1, “price”: 11900, “id”: “100144”}]
      - 상품 ID가 100144인 단가 11900 짜리 상품을 1개 구매한 경우

    • (예시1) [{“count”: 2, “price”: 11900, “id”: “100144”},{“count”: 3, “price”: 2500, “id”: “100145”}]
      - 상품 ID가 100144인 단가 11900 짜리 상품 2개와 상품 ID가 100145인 단가 2500 짜리 상품을 3개 구매한 경우

5

Request Example

상품 목록 연동 미진행 시:

https://track.buzzvil.com/action/pb/cps/default/?bz_tracking_id=10023_71ffbffd-ccf1-4edf-9c4c&transaction_id=2012282210547253&count=2

상품 목록 연동 진행 시:

https://track.buzzvil.com/network/pb/sample?bz_tracking_id=10023_71ffbffd-ccf1-4edf-9c4c&transaction_id=2012282210547253&order_list=[{“count”:2,“price”:11900,“id”: “100144”},{“count”:3,“price”:2500,“id”:“100145”}]

6

Response

  • JSON 형식으로 반환

  • Field 설명

    • code (Integer) : 처리 결과 코드

      • 200 : 정상

      • 9020 : 중복 요청

      • 그 외 : 에러

    • msg (String) : 처리결과 메세지

 

 


2. Javascript 연동

반드시 제공되는 연동 테스트까지 완료한 후에 버즈빌 담당자에게 연동 완료 회신을 해주시기 바랍니다.

1) 요약

제공되는 두 종류의 Javascript 코드를 두 단계에 걸쳐 추가함으로써 연동할 수 있습니다. 첫번째 단계(초기화)는 광고의 첫 페이지(랜딩 페이지)가 로드될 때, 두번째 단계(액션 달성 전송)는 액션이 완료 되었을 때에 호출하도록 합니다.

Javascript 연동은 localStorage를 이용하기 때문에 랜딩 페이지와 액션 완료 페이지의 도메인이 반드시 동일해야 합니다. 불가능할 경우 Server to Server 연동을 진행해야 합니다.

광고 포인트 지급 Flow

  1. Step1 '초기화' 단계 연동을 통해 광고주 랜딩 url 에 붙어온 bz_tracking_id 파라미터를 유저의 웹브라우저 내에 광고주 도메인의 localStorage에 저장합니다.

  2. Step2 '액션 달성 전송' 단계의 연동을 통해 액션 완료 시 BuzzAd 서버로 신호를 보낼 때 localStorage에 저장해 둔 bz_tracking_id를 꺼내어 구매 액션으로 인해 값이 추가된 transaction_idcount 값을 함께 전달합니다.

  3. BuzzAd 서버에서는 전달받은 bz_tracking_id, transaction_id, count 값을 이용해 해당 광고 상품을 구매한 유저 정보를 찾아 구매한 상품 내역에 맞는 포인트를 지급합니다.

2) 메소드 호출

항목

코드 및 내용

항목

코드 및 내용

Step1. 초기화

1 2 3 <script> if (/bz_tracking_id/.test(location.search)) { localStorage.BuzzAd = location.search } </script>

코드에 ‘test’가 들어있는 것은 테스트용 예시 코드가 아니라 정규표현식 중 하나입니다. 스크립트 전체를 그대로 사용해 주세요.

  • BuzzAd를 통해 랜딩되는 광고의 첫 페이지에서 아래의 자바스크립트 코드를 실행합니다.

  • 해당 코드는 bz_tracking_id 라는 파라미터가 현재 url의 검색 쿼리 부분에 있다면 이를 localStorage 에 “BuzzAd”라는 이름으로 저장합니다.

Step2. 액션 달성 전송

1 2 3 4 5 6 7 8 9 10 11 12 13 14 <script> (function (img) { img.onload = function () { if(localStorage.BuzzAd.indexOf('10023_71ffbffd-ccf1-4edf-9c4c') != -1){ alert("[Success] Action Completed!"); }; //*필요시 여기서 리다이렉트 수행* }; var queryString; if (localStorage.BuzzAd == null) { queryString = ""; } else { queryString = localStorage.BuzzAd + "&count={{COUNT}}" + "&transaction_id={{TRANSACTION_ID}}"; } img.src = "//track.buzzvil.com/action/pb/cps/default/pixel.gif" + queryString; }) (new Image()) </script> // postback 요청시마다 COUNT에는 유저가 구매한 수량 값을 TRANSTACTION_ID 에는 고유한 구매 ID 값을 넣어서 해당 스크립트를 호출해야함.
  • 광고 페이지를 방문한 사용자가 광고 상품을 구매 시 상단의 JavaScript 코드를 실행합니다.

    • 앞서 저장한 “BuzzAd” 라는 이름의 변수에 count 값과 transaction_id 값을 붙여 서버로 전송합니다. 이 값을 통해 유저가 광고를 통해 상품 구매를 완료했음을 BuzzAd 서버로 전달하여 구매한 내역에 맞는 리워드를 지급할 수 있게 됩니다.

(필수) count와 transaction_id 파라미터는 사용자의 구매 이벤트 발생 시 마다 해당 값들을 받아올 수 있도록 연동 진행 중 광고주 측에서 별도로 작업이 필요합니다.

액션 달성 후 리다이렉트를 수행하는 경우

  • 반드시 BuzzAd 서버에 액션 전송이 완료된 후 리다이렉트를 수행하여야 합니다.

    • 위의 코드 내 주석이 위치한 부분은 액션 전송이 완료되면 호출되는 함수 내부로서 이 부분에서 리다이렉트를 수행하면 안전하게 리다이렉트를 처리할 수 있습니다.

  • 코드의 함수는 BuzzAd를 통해서 광고에 참여하였는지 여부에 상관없이 언제나 호출되므로 별도의 위치에서 리다이렉트를 처리할 필요는 없습니다.

    • 오히려 임의로 별도의 위치에서 리다이렉트를 수행할 경우 BuzzAd 서버로 액션 달성 전송이 아예 오지 않을 수 있으므로 주의해야 합니다.

기존 alert를 사용하실 경우 꼭 모바일에서 테스트 진행 부탁드립니다. 특정 모바일 브라우저에서 alert이 동작하지 않는 문제가 발생할 수 있습니다.

3) Javascript 연동 테스트

아래 링크된 페이지에서 Buzzad integration test 링크를 북마크로 추가하여 테스트를 진행해주세요. 자세한 테스트 진행 방식은 해당 페이지를 참고합니다.

Javascript Integration Test Page

  1.  

     

  2.  

  • 연동 테스트가 실패했을 경우, 아래 FAQ를 참고합니다.

  • 연동 테스트는 Step1을 성공한 후에 Step2를 진행해야 합니다.

FAQ

코드 작업을 진행하신 페이지의 URL이 광고용으로 전달하신 URL과 동일한지 다시 확인해 주세요.

  • 광고용으로 전달 받은 랜딩 페이지에서 곧바로 리다이렉트가 일어날 경우 의도치 않게 전달받은 URL이 아닌 다른 페이지에서 코드 작업을 진행하실 가능성이 있습니다.

  • bz_tracking_id 는 첫 랜딩 페이지에만 붙어서 전달되기 때문에 주어진 스크립트 코드는 반드시 랜딩 페이지에서 실행되어야 하며, 그렇지 않을 경우 트래킹 아이디 자체가 아예 생성되지 않은 것 처럼 보여서 연동이 실패하였다고 뜰 수 있습니다.

  • 만일 첫 랜딩 페이지와 작업하신 페이지가 다를 경우, 처음에 전달받은 URL 페이지에서 다시 코드 작업을 하시거나 광고에 등록될 URL을 변경하도록 버즈빌 광고 담당자에게 알려주세요.

해당 alert는 테스트를 하실 때만 보이게 되어 있습니다. 코드를 수정하지 않으셔도 일반 유저들에게는 보이지 않습니다.

  1. 우선, 액션 완료 페이지와 랜딩 페이지 간에 도메인이 달라지지 않았는지 확인해주세요.

    • 버즈빌에 전달한 랜딩 페이지에서 바로 리다이렉트가 일어나는 경우

    • 버즈빌에는 http 주소를 전달하였으나 작업한 페이지는 https 인 경우 등

  2. 도메인이 동일하다면, 액션 완료 후 리다이렉트 또는 자동으로 창을 닫는 코드가 Step2 코드의 주석 부분에 삽입되어 있는지 확인해주세요. 리다이렉트나 자동 창 닫기 코드는 반드시 Step2 코드의 주석 처리된 부분에서 이뤄져야 합니다.

 

테스트용 bz_tracking_id

 

연동 과정에서 기술적인 문제가 발생하는 경우 기술 지원팀으로 문의주시기 바랍니다.

버즈빌 기술지원팀: tech-support@buzzvil.com

 

버전

변경일자

변경내용

담당자

버전

변경일자

변경내용

담당자

1.0

2020/08/14

CPS 가이드 작성

공지연

1.1

2020/08/18

스크립트 가이드 부분 내용 추가

공지연