[DEPRECATED] Potto/만보기 포스트백 API 연동

Owned by Diane Rha (Unlicensed)
Last updated: Mar 05, 2021 by Ricky Lee (Unlicensed)
7 min read

다음 연동은 포인트 시스템을 보유한 매체사가 적용해야 합니다.

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

 Index

Introduction

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

항목

내용

항목

내용

1

요청 방향

버즈빌 → 매체사

2

HTTP Request method

POST - application/x-www-form-urlencoded

3

HTTP Request URL

매체사 서버의 endpoint (i.e postback_url )

4

HTTP Request Parameters

아래 Http Request Parameters 테이블을 참고합니다.

5

HTTP Response Code

버즈빌 서버는 매체사 서버로 부터 전달받은 응답 코드(Response Code)를 바탕으로 성공 여부를 판단합니다.

  • 200 (ok): 성공 처리

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

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

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

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

HTTP Request Parameters

기능에 따라서 두 종류의 포스트백이 존재합니다. 각 타입에 관한 포스트백 파라미터 정보는 아래 테이블을 참고합니다.

파라미터 필드(Field)

타입
(Type)

Potto

만보기

설명

파라미터 필드(Field)

타입
(Type)

Potto

만보기

설명

unit_id

Long

O

O

광고가 노출된 지면의 ID 값입니다

  • Potto: 포또 번호 뽑기를 하는 fragment에서의 광고 유닛

  • 만보기: 만보기 리워드 적립을 하는 fragment에서의 광고 유닛

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

transaction_id

String 
(max 32)

O

O

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

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

user_id

String 
(max 255)

O

O

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

  • Web Feed 연동 시 전달 받은 값

point

Integer

O

O

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

action_type

String
(max 32)

O

O

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

  • won: Potto에서 당첨번호에 당첨됨

  • walked: 만보기에서 목표 걸음수를 달성하고 포인트 적립을 요청함

event_at

Long (timestamp)

O

O

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

data

String

OPTIONAL

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

c

String

OPTIONAL

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

 

요청 파라미터 검증 OPTIONAL

버즈빌 서버에서 전달되는 포인트 적립 요청(포스트백)을 암호화 할 수 있습니다. 이 과정은 필수 적용 항목은 아니고, 필요한 경우, 아래의 두 가지 방법을 제공합니다.

1. HTTP Request Parameter Encryption/Decryption

버즈빌 서버에서 매체사로 보내는 HTTP Request parameter를 암호화 하고 싶은 경우 사용합니다. 제공하는 암호화 방식은 고급 암호화 표준, AES(Advanded Encryption Standard)입니다. 제공되는 블록 암호화는 AES-256 이고, 사용하는 블록 암호화 모드(Block Cipher)는 CBC(Cipher Block Chaning) Mode와 PKCS7을 사용합니다.

준비물

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

    • AES Key (길이 64)

    • AES IV (길이 16)

진행 절차

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

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

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

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

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

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

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

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

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

 

예제

  • 예제에서는 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 을 거치지 않아도 같은 결과가 나옵니다.

각 언어별로 제공되는 예시는 아래와 같습니다.

Python 2.7+

 

Python 3.6+

 

2. Add Checksum Parameter

포스트백 데이터 검증을 위해 Request Parameters 에 Checksum parameter를 추가하고자 하는 경우 사용합니다. 제공하는 데이터 검증 방식은 HMAC 인증이고, SHA-256 알고리즘을 사용합니다.

준비물

  • 버즈빌 매니저 통해 HMAC 인증에 필요한 아래 값들 발급:

    • HMAC KEY (최대 길이 64)

진행 절차

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

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

       

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

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

    • data: 2번에서 생성한 msg

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

    • 결과값 길이: 64자

예제

  • hmac_key = 12345678abcdefgh12345678abcdefgh12345678abcdefgh12345678abcdefgh

     

  • msg = 429482977:testuserid76301:3467:2