> For the complete documentation index, see [llms.txt](https://adpopcornssp.gitbook.io/offerwall/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://adpopcornssp.gitbook.io/offerwall/publisher/common-settings/callback.md).

# 리워드 콜백 서버 연동

애드팝콘 리워드 서버에서 리워드 지급에 필요한 정보를 매체사 콜백 서버로 전달해요. 

이 가이드에 따라 콜백 서버를 구성해 주세요.

***

### 전체 흐름 <a href="#full-flow" id="full-flow"></a>

<table><thead><tr><th width="128">단계</th><th>내용</th><th>소요 시간</th></tr></thead><tbody><tr><td>Step 1</td><td>기본 정보 설정</td><td>약 5분</td></tr><tr><td>Step 2</td><td>콜백 응답 처리</td><td>약 10분</td></tr><tr><td>Step 3</td><td>프로토콜 테스트</td><td>약 5분</td></tr></tbody></table>

***

### Step 1. 기본 정보 설정 <a href="#step1" id="step1"></a>

파트너스 페이지에서 콜백을 수신하기 위한 서버 기본 정보를 입력해 주세요.

경로: 파트너스 페이지 상단 메뉴 → 리워드 설정 → 리워드 시스템 설정

<table><thead><tr><th width="195">항목</th><th>설명</th></tr></thead><tbody><tr><td>콜백 URL</td><td>리워드 지급 정보를 수신하는 콜백 서버의 라이브 URL</td></tr><tr><td>테스트 콜백 URL</td><td>리워드 지급 정보를 수신하는 콜백 서버의 테스트 URL</td></tr><tr><td>HTTP 통신 방식</td><td>콜백 송신 방식</td></tr></tbody></table>

#### 리워드 파라미터

애드팝콘 리워드 서버가 전달하는 각 리워드 파라미터를 수신할 파라미터 키 값을 등록할 수 있어요.&#x20;

기본 파라미터 외에 추가로 전달받고 싶은 정보를 추가할 수 있어요.

> 요청 방식이 POST일 경우 content-type은 application/x-www-form-urlencoded에요

<table><thead><tr><th width="170">파라미터</th><th width="102">필수 여부</th><th width="303">설명</th><th>자료형</th></tr></thead><tbody><tr><td>{usn}</td><td>필수</td><td>리워드를 지급받을 유저의 아이디</td><td>varchar(128)</td></tr><tr><td>{reward_key}</td><td>필수</td><td>캠페인 완료 시마다 발급되는 유니크한 리워드 트랜잭션 식별값</td><td>varchar(256)</td></tr><tr><td>{campaign_key}</td><td>필수</td><td>참여 완료한 캠페인 키</td><td>varchar(50)</td></tr><tr><td>{quantity}</td><td>필수</td><td>리워드 수량</td><td>long</td></tr><tr><td>{signed_value}</td><td>필수</td><td>리워드 검증 암호화 값</td><td>varchar(256)</td></tr><tr><td>{campaign_name}</td><td>선택</td><td>유저가 참여 완료한 캠페인의 이름</td><td>varchar(256)</td></tr><tr><td>{campaign_type}</td><td>선택</td><td>유저가 참여 완료한 캠페인의 타입</td><td>int</td></tr><tr><td>{app_key}</td><td>선택</td><td>애드팝콘 앱 키</td><td>int</td></tr><tr><td>{app_name}</td><td>선택</td><td>애드팝콘 앱 이름</td><td>varchar(50)</td></tr><tr><td>{time_stamp}</td><td>선택</td><td>캠페인 참여 완료 시각</td><td>varchar(20)</td></tr><tr><td>{adid}</td><td>선택</td><td>유저가 참여 완료한 디바이스의 구글 광고 아이디</td><td>varchar(128)</td></tr><tr><td>{idfa}</td><td>선택</td><td>유저가 참여 완료한 디바이스의 IDFA</td><td>varchar(128)</td></tr></tbody></table>

***

### Step 2. campaign\_type 상세 <a href="#step2" id="step2"></a>

<table><thead><tr><th width="97">No</th><th>캠페인</th><th>설명</th></tr></thead><tbody><tr><td>0</td><td>CPI 설치형</td><td>광고주 앱을 설치하여 완료</td></tr><tr><td>1</td><td>CPE 실행형</td><td>광고주 앱을 설치 후 실행하여 완료 (신규 실행)</td></tr><tr><td>2</td><td>회원가입형(웹 페이지 랜딩)</td><td>광고주 서비스 페이지로 이동 후
<br>회원가입을 하거나 개인정보를 입력하여 완료</td></tr><tr><td>3</td><td>클릭형</td><td>광고주 서비스 페이지로 이동하여 완료</td></tr><tr><td>4</td><td>좋아요형</td><td>페이스북 좋아요 캠페인</td></tr><tr><td>5</td><td>팔로우형</td><td>인스타그램 팔로우 캠페인</td></tr><tr><td>8</td><td>액션형</td><td>광고주 앱을 설치 후 특정 액션을 완료
<br>(로그인, 레벨 달성 등)</td></tr><tr><td>10</td><td>구매형</td><td>광고주 상품 구매 캠페인</td></tr><tr><td>11</td><td>유튜브 구독형</td><td>유튜브 구독형 캠페인</td></tr><tr><td>12</td><td>사전예약형</td><td>사전예약 캠페인</td></tr><tr><td>14</td><td>네이버 구독형</td><td>네이버 구독형 캠페인</td></tr><tr><td>15</td><td>카카오채널 구독형</td><td>카카오채널 구독 캠페인</td></tr><tr><td>16</td><td>네이터 카페 가입형</td><td>네이버 카페 가입 캠페인</td></tr><tr><td>17</td><td>네이버스토어 구독형</td><td>네이버 스토어 구독 캠페인</td></tr><tr><td>18</td><td>네이버 쇼핑 라이브 알람 받기</td><td>네이버 쇼핑 라이브 알람 받기 캠페인</td></tr><tr><td>19</td><td>네이버 TV 구독형</td><td>네이버 TV 구독형 캠페인</td></tr><tr><td>21</td><td>간편적립</td><td>간편적립 캠페인</td></tr><tr><td>22</td><td>틱톡 팔로우</td><td>틱톡 팔로우 캠페인</td></tr><tr><td>23</td><td>유튜브 시청형</td><td>유튜브 시청 완료 캠페인</td></tr><tr><td>25</td><td>다음 뉴스 구독형</td><td>다음 뉴스 구독 캠페인</td></tr><tr><td>26</td><td>네이버 플레이스</td><td>네이버 플레이스 저장하기</td></tr><tr><td>27</td><td>퀴즈 적립</td><td>퀴즈 풀기</td></tr><tr><td>29</td><td>컨텐츠 클릭형</td><td>컨텐츠 클릭하기</td></tr><tr><td>30</td><td>룰렛</td><td>룰렛 참여하기</td></tr><tr><td>31</td><td>멀티리워드 서브형</td><td>멀티리워드 서브캠페인 완료하기</td></tr><tr><td>32</td><td>멀티리워드 메인형</td><td>멀티리워드 메인캠페인 완료하기</td></tr></tbody></table>

***

### Step 3. 콜백 응답 처리 <a href="#step2" id="step2"></a>

애드팝콘 리워드 서버에서 전달하는 리워드 지급 정보를 수신하여 처리한 후, 처리 결과를 JSON 타입으로 회신해야 해요.

#### 응답 포맷

<table><thead><tr><th width="180">케이스</th><th width="130">Result</th><th width="130">ResultCode</th><th>ResultMsg</th></tr></thead><tbody><tr><td>리워드 지급 성공</td><td>true</td><td>1</td><td>success</td></tr><tr><td>보안성 검증 실패</td><td>false</td><td>1100</td><td>invalid signed value</td></tr><tr><td>리워드 중복 지급</td><td>false</td><td>3100</td><td>duplicate transaction</td></tr><tr><td>유저 검증 실패</td><td>false</td><td>3200</td><td>invalid user</td></tr><tr><td>예외 사항 발생</td><td>false</td><td>4000</td><td>custom error message</td></tr></tbody></table>

#### 케이스 상세

**1. 보안성 검증**

애드팝콘 리워드 서버에서 HMAC-MD5 방식으로 암호화하여 전달한 SignedValue 값과 매체사 서버에서 생성한 SignedValue 값을 비교하여 일치하는 경우에만 보안성이 검증된 통신으로 판단해요.

> SignedValue는 기본 콜백 파라미터(usn, rewardkey, quantity, campaignkey)를 plainText로 하여 애드팝콘 해시 키를 이용해 HMAC-MD5 방식으로 암호화한 값이에요.

**2. 리워드 중복 지급 방지**

유저가 동일한 reward\_key에 대해 리워드를 여러 번 받는 것을 방지하기 위한 과정이에요. reward\_key는 모든 캠페인에 대해 유일한 값이에요. 전달받은 reward\_key가 이미 지급 처리한 것이라면 리워드를 지급하면 안 돼요.

**3. 유저 검증**

리워드 지급 정보 중 유저 정보에 해당하는 유저가 존재하는지 확인하는 과정이에요. 올바르지 않은 유저 정보가 전달됐다면 리워드를 지급하면 안 돼요.

**4. 예외 사항 발생**

위에 정의된 에러 외의 상황에 대해 처리할 때 사용해요. ResultMsg에는 각 상황에 맞는 메시지를 직접 설정할 수 있어요. (반드시 영어로 설정)

**5. 리워드 지급 성공**

위 에러 사항을 모두 통과한 리워드 지급 정보에 대해 지급 처리를 완료한 뒤 결과를 회신해요.

#### 샘플 코드

콜백 서버 구성을 위해 C#, PHP 샘플 코드를 제공하고 있어요.

→ [리워드 서버 샘플 코드 다운로드](https://s3-ap-northeast-1.amazonaws.com/static.adbrix.igaworks.com/library/doc/rewardServer/IGAWorks_Reward_Server_Sample_Code.pdf)

***

### Step 4. 프로토콜 테스트 <a href="#step3" id="step3"></a>

리워드 서버 연동 편의를 위해 파트너스 페이지에서 프로토콜 테스트를 진행할 수 있어요.

1. 테스트를 진행할 유저식별값을 입력해 주세요.
2. 3가지 프로토콜 테스트의 \[진행하기] 버튼을 눌러주세요.
3. 샘플 리워드 정보가 테스트 콜백 URL로 전달돼요.

***

### 관련 가이드 <a href="#related-guides" id="related-guides"></a>

* 리워드 시스템 설정 → [**\[리워드 시스템 설정\]**](/offerwall/publisher/partners-page/system-settings.md)
* 리워드 시스템 테스트 → [**\[리워드 시스템 테스트\]**](/offerwall/publisher/partners-page/system-test.md)