Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

사용자에게 보상을 지급하기 위해서 포스트백(Postback) 연동이 필요합니다. 포스트백 요청은 보안을 위해 서버 간 통신(Server-to-Server) 형태로 진행됩니다.

...

파라미터 필드(Field)

타입
(Type)

설명

user_id

Status
colourGreen
titleREQUIRED

String 
(max 255)

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

transaction_id

Status
colourGreen
titleREQUIRED

String 
(max 32)

보상에 발급되는 ID, 이는 포인트 중복 지급을 방지하기 위해 사용

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

Panel
panelIconIdatlassian-warning
panelIcon:warning:
bgColor#FFEBE6

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

point

Status
colourGreen
titleREQUIRED

Integer

사용자에게 지급해야하는 포인트

unit_id

Status
colourGreen
titleREQUIRED

Long

광고가 노출된 지면의 ID 값

Note

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

title

Status
colourGreen
titleREQUIRED

String
(max 255)

포인트가 지급된 방식에 설정된 이름

  • 광고 (참여한 광고의 이름)

    • e.g 출시 임박! 해당 CPS 상품을 먼저 만나보세요! 😁 #Buzzvil #환상적

  • 그 외는 모두 빈값

    • ex. 만보기/뽀또

Info

최대 한글 255자까지 전달될 수 있으므로 연동 시 DB별 String 사이즈를 참조해 주세요.

action_type

Status
colourGreen
titleREQUIRED

String
(max 32)

포인트를 지급 받기 위해 사용자가 취한 액션 타입

  • opened: Feed 지면 진입 (지면을 방문하기만 해도 기본 리워드 적립)

  • u: 잠금 해제

  • l: 랜딩

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

  • won: Potto에서 당첨번호에 당첨되었을 시 포인트 적립을 요청

  • manual: 담당자 수기 적립 요청

  • spinned : 룰렛 미션 참여 시 지급되는 포인트

  • daily : Feed 출석체크(데일리 리워드 이벤트) 참여 보상

추후 다양한 타입이 추가될 수 있습니다.

event_at

Status
colourGreen
titleREQUIRED

Long (timestamp)

포인트 지급 시점 (UNIX Timestamp 초단위)

대부분 API 호출시점과 동일하지만 API 호출이 재시도인 경우 다를 수 있습니다.

extra

Status
colourGreen
titleREQUIRED

String
(max 1024)

파라미터를 추가해야할 경우, 해당 파라미터(JSON serialize 된 문자열 값)을 활용

  • 매체사가 지정한 캠페인 데이터 (대시보드에서 캠페인을 생성할 때 지정할 수 있습니다)

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

data

Status
colourRed
titleOPTIONAL

String

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

Info

자세한 내용은 아래 HTTP Request Parameter Encryption/Decryption을 참조하세요.

c

Status
colourRed
titleOPTIONAL

String

HTTP request parameter에 Checksum을 전송하는 경우 사용되는 파라미터

Info

자세한 내용은 아래 Add Checksum Parameter를 참조하세요.

custom2

Status
colourRed
titleOPTIONAL

String
(max 255)

퍼블리셔 실시간 S2S API 제품 연동 매체사에서 지정하는 커스텀 파라미터

  • 버즈빌에서 매체사로 포스트백 request 시 전달 되는 값

  • custom2~4까지 전달 가능

custom3

Status
colourRed
titleOPTIONAL

String
(max 255)

퍼블리셔 실시간 S2S API 제품 연동 매체사에서 지정하는 커스텀 파라미터

  • 버즈빌에서 매체사 로 포스트백 request 시 전달 되는 값

  • custom2~4까지 전달 가능

custom4

Status
colourRed
titleOPTIONAL

String
(max 255)

퍼블리셔 실시간 S2S API 제품 연동 매체사에서 지정하는 커스텀 파라미터

  • 버즈빌에서 매체사로 포스트백 request 시 전달 되는 값

  • custom2~4까지 전달 가능

...

Expand
title진행 과정

준비물

  • 버즈빌 매니저 통해 AES-256 암호화에 필요한 아래 값들 발급:

    • AES Key (길이 32)

    • AES IV (길이 16)

  • 발급된 AES Key와 IV를 매체에 전달할때 값을 암호화해서 전달하기 위해 매체에서 public - key를 발급하여 (RSA-1024) 버즈빌 매니저에게 전달

진행 절차

  1. 버즈빌 서버에서 HTTP Request parameter를 암호화

    1. JSON serialized parameters(string)에 해당 string을 UTF-8 인코딩 적용

    2. 해당 string에 PKCS7 패딩 적용 및 AES 암호화 진행

    3. 암호화된 값을 base64 encoding을 진행

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

    1. e.g

      Code Block
      languagejson
      {
        "data": "cg087LiIp30jCWpc3MVLfxPL4F05OFGGCkQwwpS6pRVMZhkumzfTFxc8iBoZ8unI15uk0cmY+CbSeOaLHsd7PaxsbyKISiJ31WJJ1OwfaYttoMwFysKNfL7pSz2HB9ULWZicG8MSPxCPKr9RDqgOXpuEoVm9YR3I4yNE5M0LNltpCTdXRBjTrOcjp+RtEZ1VENtHqTICK18nDqO+91BUt3AJsf4VmzogJ8UpA0izEbY="
      }
  3. 수신 측 (매체사) 에서는 HTTP POST request에서 data 파라미터를 가져와 아래와 같은 순서로 복호화

    1. 암호화된 값을 base64 decoding 진행

    2. 해당 decoding된 string을 복호화 진행 이후 PKCS7 패딩 제거

    3. 해당 string을 UTF-8 디코딩

 

예제

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

Code Block
languagejson
{
  "unit_id":"12345",
  "transaction_id":"10000000_1",
  "user_id":"buzzvil",
  "point": 1,
  "action_type":"won",
  "event_at": 1599622182,
  "title":"title",
  "extra": "{}"
}
  • 암호화 결과

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

      Code Block
      cg087LiIp30jCWpc3MVLfxPL4F05OFGGCkQwwpS6pRVMZhkumzfTFxc8iBoZ8unI15uk0cmY+CbSeOaLHsd7PaxsbyKISiJ31WJJ1OwfaYttoMwFysKNfL7pSz2HB9ULWZicG8MSPxCPKr9RDqgOXpuEoVm9YR3I4yNE5M0LNltpCTdXRBjTrOcjp+RtEZ1VENtHqTICK18nDqO+91BUt3AJsf4VmzogJ8UpA0izEbY=

 

  • 위의 암호화된 문장을 복호화시, 다음과 같습니다.

    • base64 decoding

      Code Block
      r\r<\xec\xb8\x88\xa7}#\tj\\\xdc\xc5K\x7f\x13\xcb\xe0]98Q\x86\nD0\xc2\x94\xba\xa5\x15Lf\x19.\x9b7\xd3\x17\x17<\x88\x1a\x19\xf2\xe9\xc8\xd7\x9b\xa4\xd1\xc9\x98\xf8&\xd2x\xe6\x8b\x1e\xc7{=\xaclo"\x88J"w\xd5bI\xd4\xec\x1fi\x8bm\xa0\xcc\x05\xca\xc2\x8d|\xbe\xe9K=\x87\x07\xd5\x0bY\x98\x9c\x1b\xc3\x12?\x10\x8f*\xbfQ\x0e\xa8\x0e^\x9b\x84\xa1Y\xbda\x1d\xc8\xe3#D\xe4\xcd\x0b6[i\t7WD\x18\xd3\xac\xe7#\xa7\xe4m\x11\x9dU\x10\xdbG\xa92\x02+_\'\x0e\xa3\xbe\xf7PT\xb7p\t\xb1\xfe\x15\x9b: \'\xc5)\x03H\xb3\x11\xb6

       

    • AES decryption) Key, IV: buzzvil123456789

      Code Block
      {"unit_id": "12345", "transaction_id": "10000000_1", "user_id": "buzzvil", "point": 1, "action_type": "won", "event_at": 1599622182, "title": "title", "extra": "{}"}

       

    • UTF-8 decoding

      Code Block
      {"unit_id": "12345", "transaction_id": "10000000_1", "user_id": "buzzvil", "point": 1, "action_type": "won", "event_at": 1599622182, "title": "title", "extra": "{}"}

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

...