매체사 포인트 적립 포스트백 API 연동
사용자에게 보상을 지급하기 위해서 포스트백(Postback) 연동이 필요합니다. 포스트백 요청은 보안을 위해 서버 간 통신(Server-to-Server) 형태로 진행됩니다.
절차 요약
버즈빌의 포인트 적립 요청을 받을 수 있는 서버 endpoint 구축 (해당 endpoint 의 URL을
postback url
로 지칭)본 가이드에 따라 Server-to-Server 연동
버즈빌 기술지원 매니저에게 postback url 전달
Index
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)를 바탕으로 적립 성공 여부를 판단합니다.
body에 오류 내용을 담더라도 응답 코드가 200인 경우 재시도하지 않으므로 주의해 주세요. |
HTTP Request Parameters
기능에 따라서 두 종류의 포스트백이 존재합니다. 각 타입에 관한 포스트백 파라미터 정보는 아래의 표를 참고하세요.
String 타입의 파라미터 필드 값이 한국어일 경우에는 유니코드로 인코딩되어 전달됩니다.
파라미터 필드(Field) | 타입 | 설명 |
---|---|---|
REQUIRED | String | 매체사에서 정의한 유저의 식별값 |
REQUIRED | String | 보상에 발급되는 ID. 각 보상을 식별하고 포인트 중복 지급을 방지하기 위해 사용
|
REQUIRED | Integer | 유저에게 지급해야하는 포인트 |
REQUIRED | Long | 광고가 노출된 지면의 ID 값 |
REQUIRED | String | 포인트가 지급된 방식에 설정된 이름
|
REQUIRED | String | 포인트를 지급 받기 위해 유저가 취한 액션 타입
|
REQUIRED | Long (timestamp) | 포인트 지급 시점 (UNIX Timestamp 초단위)
|
REQUIRED | String | 파라미터를 추가해야할 경우, 해당 파라미터(JSON serialize 된 문자열 값)를 활용
|
OPTIONAL | String | 유저가 참여한 광고의 광고 유형
|
OPTIONAL | Long | 유저가 참여한 캠페인(광고, 컨텐츠, 프로모션) 의 ID입니다. |
OPTIONAL | String | HTTP request parameter를 암호화 해서 전송하는 경우 사용되는 파라미터 |
OPTIONAL | String | HTTP request parameter에 Checksum을 전송하는 경우 사용되는 파라미터 |
OPTIONAL | String | 퍼블리셔 실시간 S2S API 제품 연동 매체사에서 지정하는 커스텀 파라미터
|
OPTIONAL | String | 퍼블리셔 실시간 S2S API 제품 연동 매체사에서 지정하는 커스텀 파라미터
|
OPTIONAL | String | 퍼블리셔 실시간 S2S API 제품 연동 매체사에서 지정하는 커스텀 파라미터
|
HTTP Request Parameter 포스트백 예제
다음은 HTTP Request Parameter의 포스트백 예제입니다.
{
"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 방화벽 예외 처리를 부탁 드립니다.
18.179.158.39
52.68.114.43
요청 파라미터 검증 OPTIONAL
버즈빌 서버에서 전달되는 포인트 적립 요청(포스트백)을 암호화 할 수 있습니다. 이 과정은 필수 적용 항목은 아니며, 필요한 경우 아래의 두 가지 방법을 제공합니다.
1. HTTP Request Parameter Encryption/Decryption
버즈빌 서버에서 매체사로 보내는 HTTP Request parameter를 암호화 하고 싶은 경우 사용합니다. 제공하는 암호화 방식은 고급 암호화 표준, AES(Advanded Encryption Standard)입니다. 제공되는 블록 암호화는 AES-256
이고, 사용하는 블록 암호화 모드(Block Cipher)는 CBC(Cipher Block Chaning) Mode와 PKCS7을 사용합니다.
각 언어별로 제공되는 예시는 아래와 같습니다.
2. Add Checksum Parameter
포스트백 데이터 검증을 위해 Request Parameter에 Checksum parameter를 추가하고자 하는 경우 사용합니다. 제공하는 데이터 검증 방식은 HMAC 인증이고, SHA-256
알고리즘을 사용합니다.