사용자에게 보상을 지급하기 위해서 포스트백(Postback) 연동이 필요합니다. 포스트백 요청은 보안을 위해 서버 간 통신(Server-to-Server) 형태로 진행됩니다.
...
버즈빌을 통해 유저가 포인트를 지급받은 경우, 매체사에게 이 사실을 전달하여 적립 요청을 보내기 위한 API입니다.
| 항목 | 내용 |
---|
1 | 요청 방향 | 버즈빌 → 매체사 |
2 | HTTP Request method | POST - application/x-www-form-urlencoded |
3 | HTTP Request URL | 매체사 서버의 endpoint |
4 | HTTP Request Parameters | 아래 Http Request Parameters 테이블을 참고합니다. |
5 | HTTP Response Code | 버즈빌 서버는 매체사 서버로 부터 전달받은 응답 코드(Response Code)를 바탕으로 적립 성공 여부를 판단합니다. |
(ok 요청을 제대로 처리한 경우 () Note |
---|
body에 오류 내용을 담더라도 응답 코드가 200인 경우 재시도하지 않으므로 주의해 주세요. |
|
HTTP Request Parameters
기능에 따라서 두 종류의 포스트백이 존재합니다. 각 타입에 관한 포스트백 파라미터 정보는 아래의 표를 참고하세요.
Info |
---|
String 타입의 파라미터 필드 값이 한국어일 경우에는 유니코드로 인코딩되어 전달됩니다. |
파라미터 필드(Field) | 타입 (Type) | 설명 |
---|
user_id
| String (max |
25565) | 매체사에서 정의한 유저의 식별값 최대 65자까지만 전달 가능합니다. |
transaction_id
| String (max 32) | 보상에 발급되는 ID. 각 보상을 식별하고 포인트 중복 지급을 방지하기 위해 사용 Panel |
---|
panelIconId | atlassian-warning |
---|
panelIcon | :warning: |
---|
bgColor | #FFEBE6 |
---|
| 재적립 시도 시 동일한 transaction_id 로 포스트백을 요청합니다. 같은 transaction_id 로 요청이 온 경우에 포인트가 중복 적립되지는 않는지 필수적으로 유의해서 처리해야 합니다. |
|
point
| Integer |
사용자에게 유저에게 지급해야하는 포인트 |
unit_id
| Long | 광고가 노출된 지면의 ID 값 Note |
---|
현재 주로 사용하는 값은 15자리의 숫자입니다. |
|
title
| String (max 255) | 포인트가 지급된 방식에 설정된 이름 광고 (참여한 광고의 이름) 그 외는 모두 빈값
Info |
---|
최대 한글 255자까지 전달될 수 있으므로 연동 시 DB별 String 사이즈를 참조해 주세요. |
|
actiontypeStringmax 32포인트를 지급 받기 위해 사용자가 event_at
| Long (timestamp) | 포인트 지급 시점 (UNIX Timestamp 초단위)
대부분 API 호출시점과 동일하지만 API 호출이 재시도인 경우 다를 포인트 지급 시점 (UNIX Timestamp 초단위) 대부분 API 호출시점과 동일하지만 API 호출이 재시도인 경우 다를 수 있습니다. |
action_type
| String (max 32) | 포인트를 지급 받기 위해 유저가 취한 액션 타입 opened : Feed 지면 진입 (지면을 방문하기만 해도 기본 리워드 적립)
u : 잠금 해제
l : 랜딩
a : 액션 (해당 광고의 요구 액션을 완료했을 때)
p : 컨텐츠 참여
won : Potto에서 당첨번호에 당첨되었을 시 포인트 적립을 요청
manual : 담당자 수기 적립 요청
spinned : 룰렛 미션 참여 시 지급되는 포인트
daily : Feed 출석체크(데일리 리워드 이벤트) 참여 보상
|
benefit_luckybox : 럭키박스 참여 보상
benefit_missionpack : 미션팩 특별 보상
benefit_missionpack_task : 미션팩 미션별 보상
Expand |
---|
| booster_attended : 버즈부스터 출석체크 보상
booster_hiddendone : 버즈부스터 비노출 캠페인 보상
booster_optedin : 버즈부스터 마케팅 수신동의 캠페인 보상
booster_spinned : 버즈부스터 룰렛 캠페인 보상
booster_scratched : 버즈부스터 긁는 복권 캠페인 보상
booster_stamped : 버즈부스터 스템프 캠페인 보상
booster_inviting : 친구 초대 캠페인 보상 (초대 한 사람)
booster_invited : 친구 초대 캠페인 보상 (초대 받은 사람)
|
Note |
---|
추후 다양한 action_type 이 타입이 추가될 수 있습니다. 따라서 포스트백 요청을 받을 때 정의된 값만 받도록 하는 것이 아닌, 값에 구애받지 않고 요청을 처리할 수 있도록 유의 바랍니다. |
|
revenue_type
| String (max 32) | 유저가 참여한 광고의 광고 유형 |
extra
|
GreenREQUIRED | String (max 1024) | 파라미터를 추가해야할 경우, 해당 파라미터(JSON serialize 된 문자열 값)를 활용 |
매체사가 지정한 캠페인 데이터 (대시보드에서 캠페인을 생성할 때 지정할 수 있습니다)
e.g {"sub_type": "A", "source":"external"}
Info |
---|
파라미터를 추가하고 싶으시다면 help@buzzvil.com으로 문의 부탁드립니다. |
|
campaign_id
| Long | 유저가 참여한 캠페인(광고, 컨텐츠, 프로모션) 의 ID입니다. |
data
| String | HTTP request parameter를 암호화 해서 전송하는 경우 사용되는 파라미터 Info |
---|
자세한 내용은 아래 HTTP Request Parameter Encryption/Decryption을 참조하세요. |
|
c
| String | HTTP request parameter에 Checksum을 전송하는 경우 사용되는 파라미터 Info |
---|
자세한 내용은 아래 Add Checksum Parameter를 참조하세요. |
|
custom2
| String (max 255) | 퍼블리셔 실시간 S2S API 제품 연동 매체사에서 지정하는 커스텀 파라미터 |
custom3
| String (max 255) | 퍼블리셔 실시간 S2S API 제품 연동 매체사에서 지정하는 커스텀 파라미터 |
custom4
| String (max 255) | 퍼블리셔 실시간 S2S API 제품 연동 매체사에서 지정하는 커스텀 파라미터 |
HTTP Request Parameter 포스트백 예제
...
Code Block |
---|
{
"user_id": "12345",
"point": 1,
"transaction_id": "126905422_10000001",
"event_at": 1641452397,
"unit_id": 5539189976900000,
"action_type": "l",
"title": "\uad11\uace0\u0020\ud2b9\uac00타이틀",
"extra": "{}"
} |
IP Whitelist 추가
버즈빌 서버에서 보내는 포인트 적립 요청을 받을 수 있도록 아래 IP에 대한 inbound 방화벽 예외 처리를 부탁 드립니다.
5418.179.
64158.39
.245
52.68.114.43
13.113.136.11
52.194.132.196
13.114.88.146
요청 파라미터 검증
...
Expand |
---|
|
준비물 버즈빌 매니저 통해 AES-256 암호화에 필요한 아래 값들 값 발급: AES Key (길이 32) AES IV (길이 16)
발급된 AES Key와 IV를 매체에 전달할때 값을 암호화해서 전달하기 위해 매체에서 public key를 발급하여 (RSA-1024) 버즈빌 매니저에게 버즈빌 → 매체사로 AES Key, IV 값을 전달하기 전, 매체사에서 RSA-1024 로 private key와 public key를 발급하고 public key를 버즈빌 매니저에게 전달
진행 절차 버즈빌 서버에서 HTTP Request parameter를 암호화 JSON serialized parameters(string)에 해당 string을 UTF-8 인코딩 적용 해당 string에 PKCS7 패딩 적용 및 AES 암호화 진행 암호화된 값을 base64 encoding을 진행
암호화 된 데이터를 HTTP POST request에 파라미터 data 라는 이름으로 추가하여 전송 e.g Code Block |
---|
| {
"data": "cg087LiIp30jCWpc3MVLfxPL4F05OFGGCkQwwpS6pRVMZhkumzfTFxc8iBoZ8unI15uk0cmY+CbSeOaLHsd7PaxsbyKISiJ31WJJ1OwfaYttoMwFysKNfL7pSz2HB9ULWZicG8MSPxCPKr9RDqgOXpuEoVm9YR3I4yNE5M0LNltpCTdXRBjTrOcjp+RtEZ1VENtHqTICK18nDqO+91BUt3AJsf4VmzogJ8UpA0izEbY="
} |
수신 측 (매체사) 에서는 HTTP POST request에서 data 파라미터를 가져와 아래와 같은 순서로 복호화 암호화된 값을 base64 decoding 진행 해당 decoding된 string을 복호화 진행 이후 PKCS7 패딩 제거 해당 string을 UTF-8 디코딩
예제 Code Block |
---|
| {
"unit_id":"12345",
"transaction_id":"10000000_1",
"user_id":"buzzvil",
"point": 1,
"action_type":"won",
"event_at": 1599622182,
"title":"title",
"extra": "{}"
} |
|
...