MOBI TESTER API 연동 가이드

1. 개요

이 가이드는 CBT(또는 FGT) 게임과 MOBI를 연동하기 위한 가이드 문서입니다.
개발사는 이 가이드 문서를 이용하여 가입된 유저가 MOBI를 통해 모집된 테스터인지 판별하고, 테스트 진행 상태를 조회할 수 있으며, 유저가 특정 미션 완료시에 MOBI내에서 설문조사 참여 및 테스트 보상을 받을 수 있는 상태로 전환시킬 수 있습니다.



2. 테스터 모집 Flow Chart

테스터 모집 진행 흐름을 정리한 테스터 모집 Flow Chart입니다.
API 연동 전 아래 테스터 모집 Flow Chart를 참고해주시기 바라며 API 연동에 관한 자세한 내용은 3. API 연동 안내를 참고해주시기 바랍니다.







3. API 연동 안내

API 연동에는 MOBI에서 발급한 API Key, 회원의 구글 광고 아이디가 필요합니다.
(※ 4. API Key 발급 방법, 9. 구글 광고 아이디 수집 참고)

테스터 모집을 진행하기 위해 필요한 API 연동은 2가지 입니다.
- 해당 회원이 MOBI 테스터인지 확인
- MOBI 테스터가 미션을 완료

개발사 서버에 API 연동 가능 여부에 따라 연동 방법을 선택하여 진행해주시기 바랍니다.
[서버] : 개발사 자체 서버 페이지(JSP, PHP, ASP 등)에 연동되어야 합니다.
[안드로이드] : 개발사가 테스트를 진행할 게임 어플 내에 연동되어야 합니다.

개발사 서버에 API 연동이 가능한 경우
[서버] 5. 테스터 목록 불러오기
    - MOBI 서버에 JSON 형태로 테스터 목록 조회 후 개발사 서버에 테스터 목록 저장(이후 가입한 회원이 MOBI 테스터인지 개발사 서버에서 조회)
[안드로이드] 7. 테스터 미션 완료
    - 미션 완료한 회원의 구글 광고 아이디를 MOBI 서버에 전송하여 미션 완료 처리


개발사 서버에 API 연동이 제한되는 경우
[안드로이드] 6. 테스터 조회
    - 가입한 회원이 MOBI 테스터인지 MOBI 서버에서 실시간으로 조회
[안드로이드] 7. 테스터 미션 완료
    - 미션 완료한 회원의 구글 광고 아이디를 MOBI 서버에 전송하여 미션 완료 처리





4. API Key 발급 방법

MOBI TESTER API 연동 시에는 필수적으로 API Key가 필요합니다.
API Key를 발급받으시려면 연락처, 업체명, 담당자명을 작성하셔서 아래의 메일 주소로 보내주시면 빠른 시일내에 회신하도록 하겠습니다.

헝그리앱 운영팀 팀장 조영
cyoung@monawa.com





5. 테스터 목록 불러오기

MOBI에서 선출된 테스터 목록을 불러옵니다.
※ 테스터 모집 기간 종료(테스터 선출) 전에 서비스 URL에서 조회되는 테스터들(약 15명)은 APK 검수 인원이므로 개발사 서버에 저장 부탁드립니다.
※ 테스터 모집 기간 종료(테스터 선출) 후에 테스터 목록을 불러와 개발사 서버에 저장해주시기 바랍니다.
※ API 연동 테스트를 위해 구글 광고 아이디 등록이 필요한 경우 8. 테스트용 구글 광고 아이디 등록 API를 이용바랍니다.


- 아래 API 를 필수 파라미터와 함께 호출하여 테스터 목록을 불러옵니다.

URL

방식 URL
GET 또는 POST http://www.mobi.co.kr/TesterList.php
(기본적으로 APK 검수 인원 목록(약 15명)을 불러옵니다.)
(테스터 모집 기간 종료(테스터 선출) 후에 APK 검수 인원 목록과 실제 선출된 MOBI 테스터들의 목록을 함께 불러옵니다.)

파라메터(*=필수항목)

*key - MOBI에서 발급받은 API Key
page - 테스터 목록을 페이지 별로 가져옵니다.
- 페이지당 테스터 데이터 개수는 100개입니다.



- 테스터 목록 API 호출에 대한 응답으로 아래와 같이 Json 형태로 테스터 목록이 리턴됩니다.

결과

result 조회 결과
- '0' : 실패
- '1' : 성공
error_code 조회 실패시 에러코드
- '-100' : key가 전송되지 않음
- '-101' : MOBI에서 발급하지 않은 API Key
- '-400' : 테스터가 아직 선출되지 않음
error_msg 에러 메시지
user_count 조회된 테스터수
user_data
(Array)
테스터 목록
- adid : 구글 광고 아이디
(구글 광고 아이디 수집 방법은 9. 구글 광고 아이디 수집을 참고해주세요.)
- device : 기기명
- android_version : 안드로이드 버전
- state : 테스트 진행 상태
  - '0' : 미션 진행 중
  - '1' : 미션 완료
  - '2' : 설문조사 완료
total_count - 전체 테스터수
※ 'page' 파라미터를 통해 페이지 별로 테스트 목록을 불러올 때에만 리턴됩니다.

예시

URL 요청 http://www.mobi.co.kr/TesterList.php?key=123456
응답 {"result":1,
"user_count":3,
"user_data":
        [{"adid":"0ca4d8ff-9a87-4d7c-883e-c033247704ce",
        "device":"PANTECH IM-A890L",
        "android_version":"4.4.4",
        "state":"0"},

        {"adid":"f313949e-cc43-4b76-8135-90f4273b3d2b",
        "device":"Samsung SM-N910S",
        "android_version":"5.1.1",
        "state":"0"},

        {"adid":"fb85aa5d-ff9b-4e1b-a0a8-b81ff6bb942c",
        "device":"LGE Nexus 5",
        "android_version":"5.0",
        "state":"0"}]}





6. 테스터 조회

MOBI에서 선출된 정상적인 테스터인지 조회합니다.
MOBI내에서 테스터의 진행 상태를 조회합니다.
※ API 연동 테스트를 위해 구글 광고 아이디 등록이 필요한 경우 8. 테스트용 구글 광고 아이디 등록 API를 이용바랍니다.

- 아래 API 를 필수 파라미터와 함께 호출하여 테스터를 조회합니다.

URL

방식 URL
GET 또는 POST http://www.mobi.co.kr/Tester.php

파라메터(*=필수항목)

*key - MOBI에서 발급받은 API Key
*adid - 테스터의 구글 광고 아이디
(구글 광고 아이디 수집 방법은 9. 구글 광고 아이디 수집을 참고해주세요.)



- 테스터 조회 API 호출에 대한 응답으로 아래와 같이 Json 형태로 응답이 리턴됩니다.

결과

result 조회 결과
- '0' : 실패
- '1' : 성공
error_code 조회 실패시 에러코드
- '-100' : key가 전송되지 않음
- '-101' : MOBI에서 발급하지 않은 API Key
- '-200' : adid가 전송되지 않음
- '-201' : 존재하지 않는 테스터
- '-202' : 선출되지 않은 테스터
- '-400' : 테스터가 아직 선출되지 않음
error_msg 에러 메시지
state 테스터 진행 상태
- '0' : 미션 진행 중
- '1' : 미션 완료
- '2' : 설문조사 완료

예시

URL 요청 http://www.mobi.co.kr/Tester.php?key=123456&adid=0ca4d8ff-9a87-4d7c-883e-c033247704ce
응답 {"result":1,"state":"0"}





7. 테스터 미션 완료

테스터를 미션 완료 처리하여 MOBI내에서 설문조사 참여가 가능한 상태로 전환합니다.
특정 미션(ex.레벨 10 달성, 7-1 스테이지 클리어 등)을 모두 완료시에 호출해주세요.


- 아래 API 를 필수 파라미터와 함께 호출하여 테스터의 미션을 완료 처리합니다.

URL

방식 URL
GET 또는 POST http://www.mobi.co.kr/MissionComplete.php

파라메터(*=필수항목)

*key - MOBI에서 발급받은 API Key
*adid - 테스터의 구글 광고 아이디
(구글 광고 아이디 수집 방법은 9. 구글 광고 아이디 수집을 참고해주세요.)



- 미션 완료 API 호출에 대한 응답으로 아래와 같이 Json 형태로 응답이 리턴됩니다.

결과

result 조회 결과
- '0' : 실패
- '1' : 성공
error_code 조회 실패시 에러코드
- '-100' : key가 전송되지 않음
- '-101' : MOBI에서 발급하지 않은 API Key
- '-200' : adid가 전송되지 않음
- '-201' : 존재하지 않는 테스터
- '-202' : 선출되지 않은 테스터
- '-300' : 테스트 진행 기간이 지났음
- '-999' : 미션 완료 처리 중 에러 발생 (MOBI에 문의바랍니다.)
error_msg 에러 메시지

예시

URL 요청 http://www.mobi.co.kr/MissionComplete.php
파라메터
key : 123456
adid : 0ca4d8ff-9a87-4d7c-883e-c033247704ce
응답 {"result":1}





8. 테스트용 구글 광고 아이디 등록

API 연동 테스트를 위해 구글 광고 아이디를 MOBI 서버에 등록합니다.
(구글 광고 아이디 수집 방법은 9. 구글 광고 아이디 수집을 참고해주세요.)

- 아래 API 를 필수 파라미터와 함께 호출하여 테스트용 구글 광고 아이디를 등록합니다.

URL

방식 URL
GET 또는 POST http://www.mobi.co.kr/AddTester.php

파라메터(*=필수항목)

*key - MOBI에서 발급받은 API Key
*adid - 추가할 구글 광고 아이디
(구글 광고 아이디 수집 방법은 9. 구글 광고 아이디 수집을 참고해주세요.)



- 테스터 추가 API 호출에 대한 응답으로 아래와 같이 Json 형태로 응답이 리턴됩니다.

결과

result 조회 결과
- '0' : 실패
- '1' : 성공
error_code 조회 실패시 에러코드
- '-100' : key가 전송되지 않음
- '-101' : MOBI에서 발급하지 않은 API Key
- '-200' : adid가 전송되지 않음
- '-500' : 테스터가 이미 등록되어 있음
- '-999' : 구글 광고아이디 추가 중 에러 발생 (MOBI에 문의바랍니다.)
error_msg 에러 메시지

예시

URL 요청 http://www.mobi.co.kr/AddTester.php?key=123456&adid=0ca4d8ff-9a87-4d7c-883e-c033247704ce
응답 {"result":1}





9. 구글 광고 아이디 수집

구글 광고 아이디를 수집하기 위해선 google-play-service 라이브러리가 필요합니다.

google-play-service 라이브러리 연동 안내는 아래 링크를 참조해주시기 바랍니다.
링크 : https://developers.google.com/android/guides/setup

google-play-service 라이브러리 연동 후 아래의 코드를 사용하여 구글 광고 아이디를 수집해주시기 바랍니다.
구글 광고 아이디 수집 시 시간이 다소 소요되므로 백그라운드에서 불러오시는 걸 권장해드립니다.

public String getGoogleAdId(Context mContext) {
    Info adInfo = null;
     try {
        adInfo = AdvertisingIdClient.getAdvertisingIdInfo(getApplicationContext());
    } catch (IOException e) {
        e.printStackTrace();
    } catch (GooglePlayServicesNotAvailableException e) {
        e.printStackTrace();
    } catch (IllegalStateException e) {
        // TODO Auto-generated catch block
        e.printStackTrace();
    } catch (GooglePlayServicesRepairableException e) {
        // TODO Auto-generated catch block
        e.printStackTrace();
    }
}

기타 구글 광고 아이디 관련 자세한 사항은 구글 개발자 가이드 'Advertising ID' 페이지를 참고해주시기 바랍니다.
링크 : http://developer.android.com/intl/ko/google/play-services/id.html





10. 안드로이드 API 연동 예제

안드로이드에서 API 연동을 위한 예제입니다.

예제 apk 다운로드
예제 프로젝트 다운로드
위 예제를 다운로드하시거나 아래의 코드를 참고해서 기능 구현해주시기 바랍니다.

    private static final String TAG = "MOBI_TESTER_API";

    // 모비에서 발급받은 API KEY 입니다.
    public static final String MOBI_API_KEY = "mobi_tester_api_key";



    /*************************
     * 해당 광고 아이디의 회원이 모비 테스터인지 확인합니다.
     *************************/
    public void checkMobiTester(String adid) {
        /*
         * 테스터 조회 API에 key, adid를 전송하여 조회합니다.
         * http 통신 라이브러리 사용 시 그에 맞게 수정하여 구현 부탁드립니다.
         */
        HttpUriRequest request = new HttpGet("http://www.mobi.co.kr/Tester.php?key=" + MOBI_API_KEY + "&adid=" + adid);
        String apiResult = executeHttp(request);

        if (TextUtils.isEmpty(apiResult)) {
            Log.e(TAG, TAG + " : getMobiTesterJson : TextUtils.isEmpty(apiResult)");
            return;
        }

        JSONObject json = null;
        try {
            json = new JSONObject(apiResult);
        } catch (JSONException e) {
            // TODO Auto-generated catch block
            e.printStackTrace();
        }

        if (json == null) {
            Log.e(TAG, TAG + " : getMobiTesterJson : JSONException");
            return;
        }

        boolean result = json.optInt("result", 0) == 1;
        int errorCode = json.optInt("error_code", 0);
        String errorMsg = json.optString("error_msg", "");
        int state = json.optInt("state", 0);

        Log.i(TAG, TAG + " : result : " + result);

        /*
         * 조회 실패시(result == 0) 에러 코드
         * - '-100' : key가 전송되지 않음
         * - '-101' : MOBI에서 발급하지 않은 API Key
         * - '-200' : adid가 전송되지 않음
         * - '-201' : 존재하지 않는 테스터
         * - '-202' : 선출되지 않은 테스터
         * - '-400' : 테스터가 아직 선출되지 않음
         */
        Log.i(TAG, TAG + " : errorCode : " + errorCode);
        Log.i(TAG, TAG + " : errorMsg : " + errorMsg);

        /*
         * 테스터 진행 상태 0 : 미션 진행 중 1 : 미션 완료 2 : 설문 완료
         */
        Log.i(TAG, TAG + " : state : " + state);
    }



    /*************************
     * 해당 광고 아이디의 회원을 미션 완료 처리합니다.
     *************************/
    public void mission_complete(String adid) {
        /*
         * 미션 완료 API에 key, adid를 전송하여 조회합니다.
         * http 통신 라이브러리 사용 시 그에 맞게 수정하여 구현 부탁드립니다.
         */
        HttpUriRequest request = new HttpGet(
                "http://www.mobi.co.kr/MissionComplete.php?key=" + MOBI_API_KEY + "&adid=" + adid);
        String apiResult = executeHttp(request);

        if (TextUtils.isEmpty(apiResult)) {
            Log.e(TAG, TAG + " : mission_complete : TextUtils.isEmpty(apiResult)");
            return;
        }

        JSONObject json = null;
        try {
            json = new JSONObject(apiResult);
        } catch (JSONException e) {
            // TODO Auto-generated catch block
            e.printStackTrace();
        }

        if (json == null) {
            Log.e(TAG, TAG + " : mission_complete : JSONException");
            return;
        }

        boolean result = json.optInt("result", 0) == 1;
        int errorCode = json.optInt("error_code", 0);
        String errorMsg = json.optString("error_msg", "");

        Log.i(TAG, TAG + " : result : " + result);

        /*
         * 미션 완료 처리 실패시(result == 0) 에러 코드
         * - '-100' : key가 전송되지 않음
         * - '-101' : MOBI에서 발급하지 않은 API Key
         * - '-200' : adid가 전송되지 않음
         * - '-201' : 존재하지 않는 테스터
         * - '-202' : 선출되지 않은 테스터
         * - '-300' : 테스트 진행 기간이 지났음
         * - '-999' : 미션 완료 처리 중 에러 발생 (MOBI에 문의바랍니다.)
         */
        Log.i(TAG, TAG + " : errorCode : " + errorCode);
        Log.i(TAG, TAG + " : errorMsg : " + errorMsg);

    }



    /***************
     * http 통신으로 URL에 데이터를 전송하는 메소드입니다.
     ***************/
    private String executeHttp(HttpUriRequest request) {
        if (request == null) {
            Log.d("executeHttppost", "request is null ");
            return "";
        }

        HttpParams params = new BasicHttpParams();
        params.setParameter(CoreProtocolPNames.PROTOCOL_VERSION, HttpVersion.HTTP_1_1);
        params.setBooleanParameter(CoreProtocolPNames.USE_EXPECT_CONTINUE, false);
        HttpConnectionParams.setConnectionTimeout(params, 15000);
        HttpConnectionParams.setSoTimeout(params, 15000);
        HttpConnectionParams.setTcpNoDelay(params, true);

        HttpClient client = new DefaultHttpClient(params);

        HttpResponse response = null;
        try {
            response = client.execute(request);
        } catch (ClientProtocolException e) {
            // TODO Auto-generated catch block
            e.printStackTrace();
        } catch (IOException e) {
            // TODO Auto-generated catch block
            e.printStackTrace();
        }

        if (response == null)
            return "";

        StatusLine statusLine = response.getStatusLine();
        int responseCode = statusLine.getStatusCode();

        HttpEntity entity = response.getEntity();
        InputStream content = null;
        try {
            content = entity.getContent();
        } catch (IllegalStateException e1) {
            // TODO Auto-generated catch block
            e1.printStackTrace();
        } catch (IOException e1) {
            // TODO Auto-generated catch block
            e1.printStackTrace();
        }

        if (content == null)
            return "";

        BufferedReader reader = new BufferedReader(new InputStreamReader(content));
        String line;
        StringBuilder builder = new StringBuilder();
        try {
            while ((line = reader.readLine()) != null) {
                builder.append(line);
            }
        } catch (IOException e) {
            // TODO Auto-generated catch block
            e.printStackTrace();
        }

        if (reader != null)
            try {
                reader.close();
            } catch (IOException e) {
                // TODO Auto-generated catch block
                e.printStackTrace();
            }

        if (response.getEntity() != null)
            try {
                response.getEntity().consumeContent();
            } catch (IOException e1) {
                // TODO Auto-generated catch block
                e1.printStackTrace();
            }

        return builder.toString();

    }