사용자에게 보상을 지급하기 위해서 포스트백(Postback) 연동이 필요합니다. 포스트백 요청은 보안을 위해 서버 간 통신(Server-to-Server) 형태로 진행됩니다사용자에게 보상을 지급하기 위해서 포스트백(Postback) 연동이 필요합니다. 포스트백 요청은 보안을 위해 서버 간 통신(Server-to-Server) 형태로 진행됩니다.
Panel | ||||||
---|---|---|---|---|---|---|
| ||||||
절차 요약
|
Index
Table of Contents | ||
---|---|---|
|
...
Introduction
버즈빌을 통해 유저가 포인트를 지급받은 경우, 매체사에게 이 사실을 전달하여 적립 요청을 보내기 위한 API입니다.
항목 | 내용 | |||
---|---|---|---|---|
1 | 요청 방향 | 버즈빌 → 매체사 | ||
2 | HTTP Request method | POST - application/x-www-form-urlencoded | ||
3 | HTTP Request URL | 매체사 서버의 endpoint | ||
4 | HTTP Request Parameters | 아래 | ||
5 | HTTP Response Code | 버즈빌 서버는 매체사 서버로 부터 전달받은 응답 코드(Response Code)를 바탕으로 적립 성공 여부를 판단합니다.
|
HTTP Request Parameters
기능에 따라서 두 종류의 포스트백이 존재합니다. 각 타입에 관한 포스트백 파라미터 정보는 아래의 표를 참고하세요.
Info |
---|
String 타입의 파라미터 필드 값이 한국어일 경우에는 유니코드로 인코딩되어 전달됩니다. |
파라미터 필드(Field) | 타입 | 설명 | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
| String | 매체사에서 정의한 유저의 식별값 최대 65자까지만 전달 가능합니다. | ||||||||||
| String | 보상에 발급되는 ID. 각 보상을 식별하고 포인트 중복 지급을 방지하기 위해 사용
|
...
|
...
Index
Table of Contents | ||
---|---|---|
|
Introduction
버즈빌을 통해 유저가 포인트를 지급받은 경우, 매체사에게 이 사실을 전달하여 적립 요청을 보내기 위한 API입니다.
...
항목
...
내용
...
요청 방향
...
버즈빌 → 매체사
...
HTTP Request method
...
POST - application/x-www-form-urlencoded
...
HTTP Request URL
...
매체사 서버의 endpoint
...
HTTP Request Parameters
...
아래 Http Request Parameters
테이블을 참고합니다.
...
HTTP Response Code
...
버즈빌 서버는 매체사 서버로 부터 전달받은 응답 코드(Response Code)를 바탕으로 성공 여부를 판단합니다.
200 (ok): 성공 처리
매체 서버에서 요청을 제대로 처리한 경우의 응답 코드
200 이외의 응답 코드: 최대 5회까지 해당 Postback 요청을 재시도
Exponential하게 1분, 10분, 1시간, 3시간, 24시간의 간격을 두고 수행
Note |
---|
body에 오류 내용을 담더라도 응답 코드가 200인 경우 재시도하지 않으므로 주의해 주세요. |
HTTP Request Parameters
기능에 따라서 두 종류의 포스트백이 존재합니다. 각 타입에 관한 포스트백 파라미터 정보는 아래의 표를 참고하세요.
Info |
---|
String 타입의 파라미터 필드 값이 한국어일 경우에는 유니코드로 인코딩되어 전달됩니다. |
파라미터 필드(Field)
타입
(Type)
설명
user_id
|
...
절차 요약
버즈빌의 포인트 적립 요청을 받을 수 있는 서버 endpoint 구축 (해당 endpoint 의 URL을
postback url
로 지칭)본 가이드에 따라 Server-to-Server 연동
버즈빌 기술지원 매니저에게 postback url 전달
transaction_id
| ||||||||||
| Integer | 유저에게 지급해야하는 포인트 | ||||||||
| Long | 광고가 노출된 지면의 ID 값
| ||||||||
| String | 포인트가 지급된 방식에 설정된 이름
| ||||||||
|
String
(max 255)
매체사에서 정의한 유저의 식별값
Long (timestamp) | 포인트 지급 시점 (UNIX Timestamp 초단위)
대부분 API 호출시점과 동일하지만 API 호출이 재시도인 경우 다를 수 있습니다. | ||
|
|
|
point
Status | ||||
---|---|---|---|---|
|
Integer
사용자에게 지급해야하는 포인트
unit_id
Status | ||||
---|---|---|---|---|
|
Long
광고가 노출된 지면의 ID 값
Note |
---|
현재 주로 사용하는 값은 15자리의 숫자입니다. |
title
Status | ||||
---|---|---|---|---|
|
String
(max 255)
포인트가 지급된 방식에 설정된 이름
광고 (참여한 광고의 이름)
e.g
출시 임박! 해당 CPS 상품을 먼저 만나보세요! 😁 #Buzzvil #환상적
그 외는 모두 빈값
ex. 만보기/뽀또
Info |
---|
최대 한글 255자까지 전달될 수 있으므로 연동 시 DB별 String 사이즈를 참조해 주세요. |
String |
보상에 발급되는 ID, 이는 포인트 중복 지급을 방지하기 위해 사용
최대 32자까지 전달될 수 있으므로, 연동 시 확인이 필요합니다.
Note |
---|
같은 |
포인트를 지급 받기 위해 유저가 취한 액션 타입
| |||||||
|
|
| String |
(max 32)
포인트를 지급 받기 위해 사용자가 취한 액션 타입
opened
: Feed 지면 진입 (지면을 방문하기만 해도 기본 리워드 적립)u
: 잠금 해제l
: 랜딩a
: 액션 (해당 광고의 요구 액션을 완료했을 때)won
: Potto에서 당첨번호에 당첨되었을 시 포인트 적립을 요청spinned
: 룰렛 미션 참여 시 지급되는 포인트daily
: FEED 진입 시 이벤트 보상
추후 다양한 타입이 추가될 수 있습니다.
event_at
Status | ||||
---|---|---|---|---|
|
Long (timestamp)
포인트 지급 시점 (UNIX Timestamp 초단위)
Timestamp 조회: https://www.epochconverter.com/
(max 32) | 유저가 참여한 광고의 광고 유형
추후 다양한 타입이 추가될 수 있습니다. | |||||
|
|
| String | 파라미터를 추가해야할 경우, 해당 파라미터(JSON serialize 된 문자열 값) |
매체사가 지정한 캠페인 데이터 (대시보드에서 캠페인을 생성할 때 지정할 수 있습니다)
e.g{"sub_type": "A", "source":"external"}
를 활용
| ||||||||||
| Long | 유저가 참여한 캠페인(광고, 컨텐츠, 프로모션) 의 ID입니다. | ||||||||
| String | HTTP request parameter를 암호화 해서 전송하는 경우 사용되는 파라미터
| ||||||||
| String | HTTP request parameter에 Checksum을 전송하는 경우 사용되는 파라미터
| ||||||||
| String | 퍼블리셔 실시간 S2S API 제품 연동 매체사에서 지정하는 커스텀 파라미터
| ||||||||
| String | 퍼블리셔 실시간 S2S API 제품 연동 매체사에서 지정하는 커스텀 파라미터
| ||||||||
| String | 퍼블리셔 실시간 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": "{}" }"타이틀", "extra": "{}" } |
IP Whitelist 추가
버즈빌 서버에서 보내는 포인트 적립 요청을 받을 수 있도록 아래 IP에 대한 inbound 방화벽 예외 처리를 부탁 드립니다.
18.179.158.39
52.68.114.43
요청 파라미터 검증
Status | ||||
---|---|---|---|---|
|
버즈빌 서버에서 전달되는 포인트 적립 요청(포스트백)을 암호화 할 수 있습니다. 이 과정은 필수 적용 항목은 아니고아니며, 필요한 경우 , 아래의 두 가지 방법을 제공합니다.
1. HTTP Request Parameter Encryption/Decryption
...
Expand | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||
준비물
진행 절차
예제
|
...
2. Add Checksum Parameter
포스트백 데이터 검증을 위해 Request Parameters 에 Parameter에 Checksum parameter를 추가하고자 하는 경우 사용합니다. 제공하는 데이터 검증 방식은 HMAC 인증이고, SHA-256
알고리즘을 사용합니다.
...