[광고주] CPE/CPA (Web - S2S 연동)

Owned by sophie jang (Unlicensed)
Last updated: Jul 13, 2023 by Toy Yu
3 min read

Abstract: S2S 연동이란?

광고주 웹사이트 및 서버 상 스크립트를 직접 개발해 연동하는 방식입니다.
광고주 서버에서 버즈빌 서버로 직접 통신을 하기 때문에 Server-to-Server 라는 명칭을 사용하고 있습니다.

S2S 연동에서 주요 페이지는 다음 2가지 입니다.

  1. 랜딩 페이지: 사용자가 광고 클릭 후 처음 도착하는 페이지

  2. 전환 페이지: 사용자가 광고주가 기대하는 전환 행위(ex. 회원가입)을 완료하고 처음 도착하는 페이지

 

S2S 연동을 위해서는 다음 2가지 스크립트 직접 개발해야 합니다.

  1. 초기화 스크립트: 랜딩 페이지에서 실행되어 bz_tracking_id 값을 저장

  2. 전환 스크립트: 광고주 서버에서 실행되어 저장해둔 bz_tracking_id 값을 사용해, 버즈빌로 전환 포스트백을 송신

 

BuzzAd 의 인벤토리(=광고 지면)를 통해 들어온 유저가 광고주의 웹 페이지에서 특정 동작을 수행했는지 여부를 트래킹하는 상품입니다.

광고 참여 및 포인트 지급 Flow

  1. [광고 클릭]
    BuzzAd의 인벤토리를 통해서 유저가 광고를 클릭하면, BuzzAd 서버에서는 유저의 액션을 트래킹하기 위한 id(식별자)인 bz_tracking_id 를 랜딩 url의 파라미터로 붙여서 전달합니다.

  2. [초기화 스크립트 실행]
    유저는 해당 url을 통해 광고주 웹 사이트 상 랜딩 페이지에 랜딩하고, 동시에 랜딩 페이지에 삽입된 초기화 스크립트가 실행되며 bz_tracking_id 라는 파라미터가 현재 url의 검색 쿼리 부분에 있는 경우 전환 스크립트 실행 시 호출 가능한 공간에 저장합니다.

  3. [전환 스크립트 실행]
    유저가 전환 행위(ex. 회원가입)를 완료하면, 광고주 서버에서 전환 스크립트가 실행되며 저장해 둔 bz_tracking_id 를 BuzzAd 서버로 전달합니다.

  4. [포인트 지급]
    BuzzAd 서버는 전달받은 bz_tracking_id 값을 이용해 광고에 참여 완료한 유저를 식별하고, 해당 유저에게 포인트를 지급합니다.

Process: S2S 연동 방법

다음 요건이 충족되면 연동이 완료됩니다!

STEP 1. 준비

광고주 웹사이트 상 랜딩 페이지의 소스코드를 편집할 수 있게 준비해주세요
광고주 웹사이트의 서버(BE)의 소스코드를 편집할 수 있게 준비해주세요

 

STEP 2. 초기화 스크립트 개발

다음 조건에 맞는 초기화 스크립트를 개발해주세요.
랜딩 페이지 URL query string에 “bz_tracking_id” 라는 파라미터가 있는 경우 그 값을 저장함
저장된 값은 추후 전환 페이지에서 사용할 수 있는 공간에 저장되어야 함

 

STEP3. 전환 스크립트 개발

아래 API 명세를 참고해서 다음 조건에 맞는 전환 스크립트를 개발해주세요.
사용자가 전환 행위를 완료할 경우 아래 API를 통해 버즈빌 서버로 전환 요청 (http request)를 송신함
회원 가입과 같이 여러 경로로 (ex. 소셜 회원가입) 전환 행위가 가능한 경우 모든 경우를 포함해 전환 스크립트가 올바르게 동작하도록 개발해주세요.
다음 curl 명령어 상 S2S 연동용 토큰 부분을 실제 토큰 값으로 치환하고 올바르게 동작에 하는 지 확인해 주세요.
(주의: 중괄호 “{}” 생략)
curl -H "Authorization: Bearer {S2S 연동용 토큰을 여기에 넣어주세요}" https://track.buzzvil.com/action/pb/s2s/\?bz_tracking_id\=10023_71ffbffd-ccf1-4edf-9c4c

 

POST https://track.buzzvil.com/action/pb/s2s/

분류

Key

Type

Description

분류

Key

Type

Description

Header

Authorization

 

string

  • 버즈빌 담당자가 별도로 발급해 온보딩 시트를 통해 전달한 토큰의 값

  • 다음 형식으로 전달

    • Bearer S2S 연동용 토큰

Content-Type

string

  • 전달하는 형식

  • 다음 문자열을 값으로 지정

    • "application/x-www-form-urlencoded"

Body

bz_tracking_id

string

  • 초기화 스크립트로 저장해둔 bz_tracking_id의 값

Response (msg)

Code

Name

Msg

발생하는 경우

해결 방법

Code

Name

Msg

발생하는 경우

해결 방법

200

RESLUT_OK

ok

  • 올바른 요청인 경우

 

401

TOO_MANY_REQUEST

too many requests

  • 잘못된 S2S 연동용 토큰을 사용한 경우

  • 입력한 S2S 연동용 토큰 값 주변에 중괄호가 있는 경우 제거

  • 온보딩 시트 상 발급 된 S2S 연동용 토큰의 값과 동일한지 재확인

9020

IS_ALREADY_PARTCIPATED

Already participated.

  • 동일한 정보로 1회 이상 요청한 경우

  • 해결된 것으로 판단하고 다음 단계로 속행

9026

POSTBACK_PARAMETER_NOT_FOUND

POSTBACK_PARAMETER_NOT_FOUND

  • body에 bz_tracking_id값을 비워둔 상태로 포스트백을 송신한 경우

  • 포스트백 header에
    Content-Type을 "application/x-www-form-urlencoded"로 지정했는지 확인

  • 포스트백 body에 bz_tracking_id 값을 채워주는 로직 디버깅

9028

TRACKING_ID_NOT_FOUND

tracking_id not found

  • 잘못된 bz_tracking_id을 사용한 경우
    (ex. Step 4 상 테스트 도구에서 발급되는 가짜 bz_tracking_id)

  • curl 기반 API 테스트 전용 bz_tracking_id 사용

    • 10023_71ffbffd-ccf1-4edf-9c4c

 

STEP4. 연동 테스트 진행

테스트 도구를 사용해 연동 테스트를 진행해주세요.

 

FAQ

 

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

버즈빌 기술지원팀: csm@buzzvil.com