[DEPRECATED] 포인트 적립 포스트백 API 연동

Owned by Jen Yoon (Unlicensed)
Last updated: Mar 05, 2021 by Ricky Lee (Unlicensed)
5 min read

유저가 버즈빌 프로덕트를 통해 적립받은 포인트가 실제 퍼블리셔의 포인트로 적립되기 위해서는 버즈빌 서버와 퍼블리셔의 서버 간 연동이 필요합니다.

퍼블리셔의 상황에 따른 연동 방법

아래의 절차에 따라 진행합니다.

  1. 버즈빌의 포인트 적립 요청을 받을 수 있는 서버 endpoint 구축 (해당 endpoint 의 url을 "postback url"으로 지칭)

  2. 본 가이드에 따라 Server-To-Sever 연동

  3. 버즈빌 BD 매니저에게 postback url 전달

퍼블리셔 앱을 미국 혹은 다국가에서 운영하는 경우, 반드시 BD 매니저와 사전 논의 부탁드립니다.

퍼블리셔 앱에 버즈빌의 포인트 시스템 (BuzzStore) 을 연동합니다. 해당 문서의 연동 가이드에 따라 진행해주세요.

Index

Introduction

BuzzScreen SDK, BuzzAd SDK, Offerwall SDK 또는 Offerwall API를 통해 유저가 포인트를 지급받은 경우, 매체사에게 이 사실을 전달하여 적립 요청을 보내기 위한 API입니다.

 

항목

내용

항목

내용

1

요청 방향

버즈빌 → 매체사

2

HTTP Request method

POST - application/x-www-form-urlencoded

3

HTTP Request URL

매체사에서 정의

4

HTTP Request Parameters

아래 표 참고

5

HTTP Response Code

매체사로부터 받은 응답 코드에 따라 해당 Postback 요청의 성공 여부를 결정

  • 200 (ok): 성공 처리

    • 매체 서버에서 요청을 제대로 처리한 경우의 응답 코드

  • 200 이외의 응답 코드: 최대 5회까지 해당 Postback 요청을 재시도

    • Exponential하게 1분, 10분, 1시간, 3시간, 24시간의 간격을 두고 수행

body에 오류 내용을 담더라도 응답 코드가 200인 경우 재시도하지 않으므로 주의해 주세요.

HTTP Request Parameters

포인트 적립 포스트백은 포인트를 적립받은 상황에 따라 아래 두 가지 유형으로 나뉘어 전송됩니다. 각 유형 별로 포스트백에 포함되는 필드 값들은 아래 표를 참고해주세요.

  • 노출형

    • 버즈스크린 지면에서 기본포인트를 적립한 경우

    • 또는 CPC, CPM 타입의 광고 포인트를 적립한 경우

  • 액션형

    • CPC, CPM 외의 광고 포인트를 적립한 경우 (아래 파라미터 중 action_type 이 a 인 경우에 해당)

필드

타입

노출형

액션형

설명

필드

타입

노출형

액션형

설명

unit_id

Integer

O

O

app_key 와 같은 정의

현재 주로 전달하는 값은 15자리의 숫자입니다.

transaction_id

String
(max 32)

O

O

포인트 중복 적립을 막기 위한 id

  • 최대 32자까지 전달될 수 있으므로, 연동 시 확인이 필요합니다.

★ 같은 transaction_id로 요청이 온 경우에는 반드시 포인트 중복 적립이 되지 않도록 처리해주어야 합니다.

user_id

String
(max 255)

O

O

매체사에서 정의한 유저의 식별값

  • BuzzScreen SDK에서 setUserId 호출 시 전달했던 userId

  • BuzzAd SDK에서 BuzzAd.showOfferWall 호출 시 전달했던 userId

  • BuzzAd Benefit SDK에서 UserProfile 빌드 시 세팅한 userId

campaign_id

Long

O

O

포인트가 지급된 캠페인의 id

  • action_type 이 u인 경우 (잠금해제): 해당 시점의 광고/컨텐츠의 id

  • action_type 이 l or a인 경우 (광고 랜딩 또는 참여): 참여한 광고의 id

campaign_name

String
(max 255)

O

O

포인트가 지급된 캠페인의 이름

title

String
(max 255)

X

O

참여한 광고의 이름

point

Integer

O

O

유저에게 지급할 포인트의 전체 합

  • 유저의 액션에 의해 캠페인에서 지급되는 포인트와 기본포인트 (base_point)를 합친 값

base_point

Integer

O

X

유저에게 정해진 기본포인트 주기마다 제공해주는 포인트

  • 최근에 기본 포인트를 적립받은 시점으로부터 정해진 interval (기본포인트 주기) 이 지나지 않았으면 지급되지 않아야 하므로 0, 지났으면 기본 적립금 값이 전달됩니다.

is_media

Integer

O

O

  • 0: 버즈빌 측 캠페인

  • 1: 매체사 측 캠페인

revenue_type

String
(max 32)

O

O

포인트가 지급된 캠페인의 타입

  • 광고: cpi, cpe, cpa 등의 값이 올 수 있습니다.

  • 컨텐츠: 빈 값이 전달됩니다.

action_type

String
(max 32)

O

O

포인트를 지급 받기 위해 유저가 취한 액션 타입

  • u: 잠금해제

  • l: 랜딩

  • a: 액션 (해당 광고의 요구 액션을 완료했을 때)

event_at

Long (timestamp)

O

O

포인트 지급 시점

extra

String
(max 1024)

O

O

매체사가 자체 정의한 캠페인 데이터의 json serialize된 스트링

e.g. {"sub_type": "A", "source":"external"}

unit_price

decimal (18,9)

X

O

포인트가 지급된 캠페인의 매체사 단가

custom

String
(max 64)

X

O

user_id 와 같은 값 (액션형에서 사용하는 파라미터)

ifa

String
(max 64)

X

O

유저의 광고 id (AOS: Google Ad ID, iOS: IDFA)

reward

Integer

X

O

유저에게 지급할 포인트 금액 (액션형에서 사용하는 파라미터)

  • point 값과 동일합니다.
    CPS 상품을 노출하는 매체인 경우 리워드 값이 클 수 있기에 max 1,000,000까지 받을 수 있도록 세팅 권고드립니다.

allow_multiple_conversions

0 or 1

X

O

  • 0: 동일 광고에 최대 1회 참여 가능함

  • 1: 동일 광고에 여러 번 참여 가능함 (예: 일부 비디오 광고 등)

data

String

optional

HTTP request parameter를 암호화 해서 전송하는 경우 사용되는 파라미터

click_type
(deprecated)

String

O

X

랜딩/잠금해제 구분자

  • u: 잠금해제

  • l: 랜딩

 

 

Request Parameter Validation (Optional)

버즈빌서버에서 전달되는 포스트백을 암호화 할 수 있습니다. 이 과정은 필수 적용 항목은 아니고, 필요한 경우, 아래의 두 가지 방법 중 한 가지를 적용하면 됩니다.

1. HTTP Request Parameter Encryption/Decryption

BuzzScreen에서 매체사로 보내는 HTTP Request parameter를 암호화 하고 싶은 경우 사용합니다. 아래 과정에 따라 암호화를 진행할 수 있습니다.

진행 절차

  1. 암호화 키 발급

    1. 버즈빌 BD 매니저와 사전 협의

    2. 이메일(tech-support@buzzvil.com)을 통해 암호화 키를 요청하면 AES key, IV 값을 지급

  2. BuzzScreen 에서 아래 순서대로 파라미터를 암호화

    1. JSON serialized parameters with UTF-8 encoding

    2. AES(CBC mode, PKCS7 padding) encryption

    3. base64 encoding

  3. 암호화된 데이터를 HTTP POST request 파라미터에 data 라는 이름으로 추가하여 전송

  4. 수신 측 (매체사) 에서는 HTTP POST request에서 data 파라미터를 가져와 아래와 같은 순서로 복호화

    1. base64 decoding

    2. AES decoding

    3. JSON load

예제

  • 예제에서는 AES key, IV 값으로 모두 12341234asdfasdf를 사용

{ "event_at": 1442984268, "user_id": "testuserid76301", "action_type": "u", "extra": "{}", "is_media": 0, "base_point": 2, "point": 2, "campaign_name": "test campaign", "campaign_id": 3467, "transaction_id": 429482977 }

  • 암호화 결과

    • JSON (UTF-8encoding) → AES encryption → base64 encoding 순서로 진행

      sgfHOC5Z66tLmlokmQEaXY39u+64gMWhLnxQAZ9ivYsTvF1isjVfaRx2BNhOADwPR6KB55/7F7iXBm5FKU8mHmHnlR3wSomVAlcjtx77KluoYoXi/jRCvaFLGIo7vcK1GVHxS557u/XTo53/AzdPZpk/aXkvFZvWPgS+GWj1TWle0mBJ0xOgfmb8LwMfi4rvfayTph3bZeryLuphorBzMoIhf+kQLyjfIyouWVoCh6UICeRBgzTS9SlgdUA6M1PVlCsQch0zKVeTJZEFEn8478QbpEEhgHDhXkzdo8tXgkw=

 

  • 위의 암호화된 문장을 복호화하면,

    • base64 decoding)

      \xb2\x07\xc78.Y\xeb\xabK\x9aZ$\x99\x01\x1a]\x8d\xfd\xbb\xee\xb8\x80\xc5\xa1.|P\x01\x9fb\xbd\x8b\x13\xbc]b\xb25_i\x1cv\x04\xd8N\x00<\x0fG\xa2\x81\xe7\x9f\xfb\x17\xb8\x97\x06nE)O&\x1ea\xe7\x95\x1d\xf0J\x89\x95\x02W#\xb7\x1e\xfb*[\xa8b\x85\xe2\xfe4B\xbd\xa1K\x18\x8a;\xbd\xc2\xb5\x19Q\xf1K\x9e{\xbb\xf5\xd3\xa3\x9d\xff\x037Of\x99?iy/\x15\x9b\xd6>\x04\xbe\x19h\xf5Mi^\xd2`I\xd3\x13\xa0~f\xfc/\x03\x1f\x8b\x8a\xef}\xac\x93\xa6\x1d\xdbe\xea\xf2.\xeaa\xa2\xb0s2\x82!\x7f\xe9\x10/(\xdf#*.YZ\x02\x87\xa5\x08\t\xe4A\x834\xd2\xf5)`u@:3S\xd5\x94+\x10r\x1d3)W\x93%\x91\x05\x12\x7f8\xef\xc4\x1b\xa4A!\x80p\xe1^L\xdd\xa3\xcbW\x82L

       

    • AES decryption) Key, IV: 12341234asdfasdf

       

    • UTF-8 decoding

      (memo) 위의 예제에 한글이 없기 때문에 UTF-8 decoding 을 거치지 않아도 같은 결과가 나옵니다.

 

2. Add Checksum Parameter

포스트백 데이터 검증을 위해 Request Parameters 에 Checksum parameter를 추가하고자 하는 경우 사용합니다.

진행 절차

  1. BD 매니저에게 hmac_key 를 요청하여 키 값을 수령

  2. 전달받은 포스트백 파라미터 중 transaction_id, user_id, campaign_id, point 값으로 아래 형식대로 String을 생성 (이하 "msg")

    1. 주의사항 : msg 값은 인코딩되어야 하며, 각 파라미터 string 과 colon 사이에는 띄어쓰기가 없습니다.



  3. HMAC SHA-256 알고리즘을 사용하여 msg 값을 암호화

    • key: 1번에서 발급받은 hmac_key

    • data: 2번에서 생성한 msg

  4. 전달받은 포스트백 파라미터 중 c 필드의 값과 비교, 일치 여부를 확인

    • 결과값 길이: 64자

예제

  • hmac_key = 12345678abcdefgh12345678abcdefgh12345678abcdefgh12345678abcdefgh

     

  • msg = 429482977:testuserid76301:3467:2