캠페인 참여 등, 유저가 리워드 지급 조건을 충족하면 Webhook 방식으로 어드민에서 등록한 URL 로 특정 request body 로 buzzbooster server 가 POST 요청을 보냅니다. 자체 포인트시스템을 버즈부스터와 연동하여 사용하고 싶은 경우 아래 단계를 수행하세요.
Step 1. URL 등록
dashboard > reward manager > settings > integration > SDK 탭에서 아래와 같이 포인트 지급을 처리할 URL 을 등록해주세요.
포인트 지급 API URL 은 환경별(dev, prod)로 세팅할 수 있습니다.
입력 후 “저장” 버튼을 클릭하여 등록을 완료합니다.
Step 2. 도메인 등록 요청, 방화벽 설정
등록한 URL에 대해 buzzbooster 자체적으로 해당 URL 에 대해 도메인 등록 작업이 필요하기 때문에 도메인 공유 절차가 필요합니다? 또한, 방화벽 설정을 위해 버즈빌의 고정 아이피 주소를 화이트리스팅 처리해주세요.
Step 3. API 구현
buzzbooster 내에서 포인트 지급이 발생한 경우, 버즈부스터는 아래의 spec 으로 Step 1 에서 등록한 URL에 POST요청을 전송합니다. 요청 수신 후, 포인트 지급을 처리할 수 있도록 아래 spec을 구현해주세요.
[POST] {registered_url}
BuzzBooster Request
Request Body
파라미터명 | 타입 | 설명 |
transaction_id | string | 포인트 지급/차감에 발급되는 id입니다. 포인트 중복 지급/차감을 방지하기 위해 사용합니다.
같은 transaction_id로 요청이 온 경우에는 반드시 포인트 중복 적립/차감이 되지 않도록 처리해야 합니다. |
user_id | string | 고객사 유저 아이디 |
app_id | integer | 유저의 앱 아이디(=app_key) |
reward | object | 적립/차감 해야되는 포인트 정보
type: 리워드 종류(POINT)
amount: 지급액. 0 미만인 경우 차감 요청 |
trigger | object | (하단 설명 참조) |
trigger 필드 상세 설명
•
trigger 필드에는 포인트 지급/차감 사유(reason)가 포함됩니다.
•
지급 사유가 PROMOTION 인 경우 유저가 참여한 캠페인 ID(promotion_id)와 이름(promotion_name) 및 미션명(mission_name)이 포함됩니다.
•
그 외의 경우 상세 이유(reason) 가 포함됩니다.
trigger.type: 지급/차감 사유 종류 (NAVERPAY 타입은 네이버페이 플러그인 사용시에만 발생합니다.)
•
PROMOTION: 캠페인 참여
•
MANUAL: 수동지급
•
NAVERPAY_CONVERT: 네이버페이 전환으로 인한 차감
•
NAVERPAY_CONVERT_CANCEL: 네이버페이 전환 취소로 인한 재지급
•
NAVERPAY_CONVERT_FAIL: 네이버페이 전환 실패로 인한 재지급
지급 사유가 PROMOTION 인 경우 custom field
•
trigger.promotion_id(optional): 참여한 캠페인 아이디
•
trigger.promotion_name(optional): 참여한 캠페인 이름
•
trigger.mission_name(optional): 유저가 완료한 미션명
그 외 지급 사유의 경우 custom field
•
trigger.reason: 상세 지급 사유
// 캠페인 참여 리워드 지급 요청 request body
{
"transaction_id": "2195ffb0-8f64-44b2-8c85-4723b9ecb18a",
"user_id": "USER_123456789",
"app_id": 1234567890,
"reward": {
"type": "POINT",
"amount": 10
},
"trigger": {
"type": "PROMOTION",
"promotion_id": "string",
"promotion_name": "대시보드에서 설정한 캠페인 이름",
"mission_name": "유저가 완료한 미션명"
}
}
// 리워드 수동차감 요청 request body
{
"transaction_id": "2195ffb0-8f64-44b2-8c85-4723b9ecb18a",
"user_id": "USER_123456789",
"app_id": 1234567890,
"reward": {
"type": "POINT",
"amount": -10
},
"trigger": {
"type": "MANUAL"
}
}
JSON
복사
Retry Policy
적립/차감에 실패 시 응답 코드가 500번대(501 Not Implemented 제외) 또는 429 Too Many Requests라면, 200 OK, 201 Created 혹은 409 Conflict 를 응답받을 때까지 BuzzBooster 서버에서 동일한 request body로 최대 4회 재시도합니다.
Partner Response
200, 201 - 포인트 적립/차감이 성공한 경우
4xx - 올바르지 않은 요청으로 인하여 포인트 적립/차감이 실패한 경우
409 - 이미 정상 처리된 트랜잭션이 중복 요청된 경우
5xx - 예상치 못한 문제로 인하여 포인트 적립/차감이 실패한 경우
Step 3. 연동 테스트
dashboard > reward manager > settings > integration > SDK 탭 의 각 환경별 “적립 테스트” 버튼을 클릭하여 연동이 완료되었는지 테스트할 수 있습니다. 테스트 결과는 dashboard > reward manager > reward admin > 포인트 지급 내역 에서 확인할 수 있습니다.