애드박스 참여하기 SDK 연동 가이드

1. 개요

이 가이드는 애드박스 참여하기 SDK 연동 방법을 기술한 가이드 문서입니다.


2. SDK 공통 연동

SDK 공통 연동 가이드를 참고하여 SDK 공통 연동을 진행해주시기 바랍니다.
SDK 공통 연동 가이드 : http://www.adbox.co.kr/guide/sdk.php


3. 참여하기 설정

아래의 항목들을 커스터마이징 가능하며 별도의 코드 수정 없이 실시간으로 적용이 가능합니다.
설정 요청은 메일로 부탁드립니다.

테마 색상 : 전체적인 테마 색상입니다. RGB Code로 전달 부탁드립니다. (ex. #123456)
상단 제목 표시 설정 : 상단 제목 표시 여부입니다. (ex. 표시, 미표시)
상단 제목 텍스트 : 상단 제목 텍스트를 설정하실 수 있습니다. (ex. 참여하기)
보상 단위명 : 지급되는 보상의 단위입니다. (ex. Point)
보상 비율 : 단가 대비 보상 비율입니다. 참여하기 단가가 300원일 경우 10%로 설정 시 회원에게 30원이 지급됩니다.
보상 버림 단위 : 보상 비율 적용 후 버림될 단위 입니다. 캠페인의 보상이 123이라면 10의 자리 설정시 캠페인 보상이 100으로 노출됩니다.(ex. 미설정, 10의 자리, 100의 자리)
상단 배너 : 상단 제목과 참여하기 리스트 사이에 배너 삽입이 가능합니다. (ex. 첨부파일 또는 URL)
콜백 URL : 참여하기 1~3Day 미션 완료 시에 호출되는 콜백 URL입니다. 하단의 '7. Callback URL' 확인 후 작성 부탁드립니다.

[담당자 연락처]
애드박스 운영 담당 황태경 매니저
hwangtg@monawa.com


4. 게임 플레이 리시버 추가

AndroidManifest.xml 의 <application></application> 태그 안에 ADBoxAppPlayReceiver를 추가합니다.
<receiver
   android:name="com.ha.adbox.sdk.receiver.ADBoxAppPlayReceiver">
   <intent-filter>
      <action android:name="com.ha.adbox.sdk.action.APP_PLAY" />
   </intent-filter>
</receiver>


5. 회원 아이디 설정

참여하기 광고 노출 전에 ADBoxAd.setUserId(context, userid) 메소드를 호출하여 회원 아이디를 SDK에 설정합니다.
userid에 회원의 고유 아이디값을 입력해주세요.
※ 회원마다 중복되지 않는 고유값이여야 하며, 아이디의 길이는 150자 내외로 설정해주시기 바랍니다.
 ※ SDK 초기화 후, 광고 노출 전에 회원 아이디가 설정되어야 합니다.
ADBoxAd.setUserId(this, userid);


6. 참여하기 노출

ADBoxAd.show(context, spotKey) 메소드를 호출합니다.
spotKey에 발급받으신 스팟 키를 입력해주세요.
ADBoxAd.show(this, spotKey);


7. Callback URL

회원이 참여하기 미션 완료 시 설정된 Callback URL을 호출하여 회원에게 보상이 지급될 수 있도록 합니다.
- 아래는 Callback URL 설정 요청시 사용 가능한 Callback Macro입니다.
- 각 Macro는 Callback URL 호출 시에 실제 값으로 치환됩니다.
* Callback URL에 {result} 매크로가 설정되어 있지 않다면 미션 실패 시에 Callback URL을 호출하지 않습니다.
* Callback URL에 {result} 매크로가 설정되어 있을 경우 미션 실패 시에도 Callback URL을 호출합니다.

매크로 형태 설명
*{userid} string * 필수 매크로입니다.
'2. 캠페인 조회 API' 를 호출 시에 추가한 '회원 ID' 입니다.
해당 회원에게 리워드를 지급해야 하므로 필수적으로 설정 부탁드립니다.
*{reward} int * 필수 매크로입니다.
미션 완료 리워드입니다.
해당 회원에게 리워드를 지급해야 하므로 필수적으로 설정 부탁드립니다.
※ {reward} 데이터와 다른 리워드를 임의 지급할 경우 광고 정산시 문제가 발생할 수 있습니다.
※ {reward} 데이터와 동일한 리워드가 지급되도록 구현 부탁드립니다.
{result} int 미션 참여 결과값입니다.
※ 해당 매크로 설정 시 미션 실패시에도 Callback URL이 호출됩니다.
미션 참여 결과값에 대한 상세 내용은 아래의 '미션 참여 결과값 안내'를 참고해주십시오.
{day} int(1) 완료된 미션이 ?Day 미션인지 전달됩니다.(1, 2, 3Day)
{api_key} string(16) 연동된 API 키
{campaign_key} string(16) 캠페인 키입니다.
{title} string 캠페인명입니다.

미션 참여 결과값(result) 안내

1 미션 완료
-200, -201, -202, -203, -206, -207 캠페인 종료
-250 이미 완료된 미션
-299 미션 참여 내역 없음
-300 동일 IP에서 동일 캠페인 3회 이상 참여
-400 블랙리스트에 등록된 IP
-401 블랙리스트에 등록된 구글 광고아이디
-402 블랙리스트에 등록된 안드로이드 아이디
-403 블랙리스트에 등록된 회원
-404 해외 아이피
-405 데일리캡 초과
(모든 캠페인 데일리캡 1,500으로 동일)

예시

설정 요청한 Callback URL http://server.com/callback?uid={userid}&coin={reward}&ck={campaign_key}&play_day={day}&subject={title}
실제 호출되는 Callback URL http://server.com/callback?uid=test_user_1234&coin=100&ck=432143214321&play_day=1&subject=WING%2B%25EC%25A0%2584%25EC%259E%25A5%25EC%259D%2598%25EB%2582%25A0%25EA%25B0%259C

8. 참여 내역 API

참여하기 참여 내역을 조회합니다.

- 아래의 API를 호출하여 참여하기 참여 내역을 조회합니다.

API URL http://m.adbox.co.kr/api/play/report.php

* 파라미터

*api_key * 필수 파라미터 입니다.
발급받은 API Key 입니다.
start_date 조회 시작일 (yyyy-mm-dd)
end_date 조회 종료일 (yyyy-mm-dd)


- 리포트 API 호출에 대한 응답으로 아래와 같이 JSON 형태로 캠페인 목록이 리턴됩니다.

결과

result 조회 결과
- '1' : 성공
- 그 외 : 조회 실패
error_msg 에러 메시지
report
(Array) 		참여 현황
- date : 날짜
- 1day : 1Day 완료수
- 2day : 2Day 완료수
- 3day : 3Day 완료수

예시

API 요청 http://m.adbox.co.kr/api/play/report.php?api_key=1234123412341234&start_date=2018-01-01&end_date=2018-01-03
응답


9. 회원 참여 내역 API

특정 회원의 참여하기 참여 내역을 조회합니다.

- 아래의 API를 호출하여 회원의 참여하기 참여 내역을 조회합니다.

API URL http://m.adbox.co.kr/api/play/member.php

* 파라미터

*api_key * 필수 파라미터 입니다.
발급받은 API Key 입니다.
*userid * 필수 파라미터 입니다.
회원의 아이디입니다.


- 리포트 API 호출에 대한 응답으로 아래와 같이 JSON 형태로 캠페인 목록이 리턴됩니다.

결과

result 조회 결과
- '1' : 성공
- 그 외 : 조회 실패
error_msg 에러 메시지
report
(Array) 		참여 현황
- campaign_key : 캠페인 키
- title : 캠페인 제목
- 1day : 1Day 완료일시
- 2day : 2Day 완료일시
- 3day : 3Day 완료일시

예시

API 요청 http://m.adbox.co.kr/api/play/member.php?api_key=1234123412341234&userid=test
응답