Versions Compared

Old Version 4

changes.mady.by.user Ricky Lee

Saved on

compared with

New Version 5

changes.mady.by.user Olivia Kim

Saved on

Key

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

...

버즈빌을 통해 유저가 포인트를 지급받은 경우, 매체사에게 이 사실을 전달하여 적립 요청을 보내기 위한 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)를 바탕으로 성공 여부를 판단합니다.

  • 200 (ok): 성공 처리

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

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

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

Note

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

HTTP Request Parameters

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

Info

String 타입의 파라미터 필드 값이 한국어일 경우에는 유니코드로 인코딩되어 전달됩니다.

파라미터 필드(Field)

타입
(Type)

설명

user_id

Status
colourGreen
titleREQUIRED

String 
(max 255)

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

transaction_id

Status
colourGreen
titleREQUIRED

String 
(max 32)

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

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

Note

같은 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)

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

  • u: 잠금해제

  • l: 랜딩

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

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

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

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

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를 참조하세요.

HTTP Request Parameter 포스트백 예제

다음은 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": "{}"
}

요청 파라미터 검증 
Status
colourRed
titleOPTIONAL

...