로딩중입니다
애드팝콘 오퍼월 : 안드로이드
4/18/2017 11:28:56 AM

애드팝콘 오퍼월 연동하기 : 안드로이드 네이티브


본 가이드는 안드로이드 네이티브 프로젝트에서 애드팝콘 오퍼월을 연동하기 위한 문서입니다.

애드팝콘에 대한 서비스 소개나 이용방법 안내는 아래 아티클에서 확인하실 수 있습니다.

[애드팝콘 서비스 안내]


서비스 이용 중 도움이 필요한 경우에는 아래 메일 주소로 연락 부탁 드립니다.

1. 서비스 이용 및 제휴 문의 - 애드팝콘 사업팀 (media@igaworks.com)

2. 기술문의 : 기술지원팀(tech_support@igaworks.com)



SDK 다운로드 및 설치


[SDK 다운로드 센터] 에서 최신 안드로이드 SDK 패키지를 다운로드 합니다.

다운로드 받은 .zip 파일을 압축해제하여 IgawCommon~*.jar 파일과 IgawAdpopcorn~*.jar 파일을 안드로이드 스튜디오 프로젝트로 복사합니다.

gradle 을 업데이트합니다.



매니페스트 설정


오퍼월을 이용하기 위한 내용을 AndroidManifest.xml 파일에 추가합니다.


앱키 & 해시키 추가

Igaworks 홈페이지에서 애드팝콘 앱 등록 후 발급받은 앱키, 해시키를 <application></application> 태그 안에 추가합니다.

<application>
...
    <meta-data android:name="igaworks_app_key" android:value="이곳에_앱키를_입력하세요" />
    <meta-data android:name="igaworks_hash_key" android:value="이곳에_해시키를_입력하세요" />
...
</application>


퍼미션 추가

<manifest></manifest> 태그 안에 필수 퍼미션을 추가합니다.

<manifest>
...
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.GET_ACCOUNTS" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
...
</manifest>

CAUTION!!!  GET_ACCOUNTS, WRITE_EXTERNAL_STORAGE 퍼미션은 어뷰징 방지를 위해 반드시 필요하며 적용되지 않을 시에는 검수 반려 대상입니다.


액티비티 추가

<application></application> 태그 안에 필수 액티비티를 추가합니다.

<application>
...
    <activity android:name="com.igaworks.adpopcorn.activity.ApOfferWallActivity_NT"
        android:theme="@android:style/Theme.NoTitleBar"/>

    <activity android:name="com.igaworks.adpopcorn.activity.ApVideoAdActivity"
        android:theme="@android:style/Theme.NoTitleBar"/>

...
</application>


리워드서버 연동방식 추가

<application></application> 태그 안에 리워드서버 연동방식을 추가합니다. 애드팝콘 어드민에서 자체서버를 선택한 경우에는 "server" 로 설정합니다. (권장)

<application>
...
    <meta-data android:name="igaworks_reward_server_type" android:value="server" />

...
</application>

CAUTION!!!  애드팝콘 어드민에서 리워드서버 연동방식을 igaworks 서버로 선택한 경우에는 "client"로 설정하여야 하며 리워드지급처리를 위한 추가 api를 연동하여야 합니다. [APPENDIX : 클라이언트 리워드 연동]


프로가드 설정

안드로이드 스튜디오의 app/proguard-rules.pro 파일에 애드팝콘 SDK에 대한 난독화 예외설정을 추가합니다.

##---------------Begin: proguard configuration for Igaworks Common  ----------
-keep class com.igaworks.** { *; }
-dontwarn com.igaworks.**
##---------------End: proguard configuration for Igaworks Common   ----------

##---------------Begin: proguard configuration for Gson  ----------
# Gson uses generic type information stored in a class file when working with fields. Proguard
# removes such information by default, so configure it to keep all of it.
-keepattributes Signature

# For using GSON @Expose annotation
-keepattributes *Annotation*

# Gson specific classes
-keep class sun.misc.Unsafe { *; }
-keep class com.igaworks.gson.stream.** { *; }

# Application classes that will be serialized/deserialized over Gson
-keep class com.igaworks.adbrix.model.** { *; }

##---------------End: proguard configuration for Gson  ----------

CAUTION!!!  이클립스 프로젝트의 경우에는 Project/proguard-project.txt 파일을 수정합니다.



오퍼월 광고 코드 연동


SDK 초기화

앱이 시작되는 액티비티의 onResume(), onPause() 에서 startSessionendSession api를 호출하여 SDK를 초기화 합니다. 

초기화가 진행되지 않으면 애드팝콘 SDK가 정상 동작하지 않습니다.

@Override
protected void onResume() {
    super.onResume();
    IgawCommon.startSession(ActivityContext);

}

@Override
protected void onPause() {
    super.onPause();
    IgawCommon.endSession();

}


유저식별값 입력

유저식별값은 캠페인을 완료한 유저를 식별하여 리워드를 지급하기 위해 사용되는 정보입니다.


주의 사항


  1. 1명의 유저는 1개의 고유한 유저식별값을 가져야하며, 가변적인 값을 사용해서는 안됩니다.
  2. 개인정보(이메일, 이름, 전화번호, 식별가능한 유저아이디 등)이 포함되어서는 안됩니다.
  3. 한글, 특수문자, 공백 등이 포함된 경우에는 반드시 URL 인코딩 처리를 하여 사용하여야 합니다.
  4. 유저가 오퍼월에 진입하기 전에 설정되어야 합니다.

위 주의사항에 유의하여 유저 식별값을 입력합니다.

IgawCommon.setUserId(ActivityContext,"bXlBY2NvdW50X25hbWU=");


오퍼월 광고 노출

openOfferwall api 를 호출하여 오퍼월 광고를 노출합니다. 

offerwallBtn.setOnClickListener(new View.OnClickListener() {

    @Override
    public void onClick(View v) {
        //오퍼월을 노출합니다.
        IgawAdpopcorn.openOfferWall(MainActivity.this);
    }
});


다이얼로그 타입 오퍼월 광고 노출

openDialogTypeOfferwall api 를 호출하여 오퍼월 광고를 노출합니다. 

offerwallBtn.setOnClickListener(new View.OnClickListener() {

    @Override
    public void onClick(View v) {
        //오퍼월을 노출합니다.
        IgawAdpopcorn.openDialogTypeOfferwall(MainActivity.this);
    }
});


잠금화면에서의 오퍼월 광고 노출

오퍼월을 잠금 화면에서 접근 가능하도록 할 경우 아래의 api를 추가 하여야 합니다.

IgawAdpopcornExtension.useFlagShowWhenLocked(Context context, boolean flag)


오퍼월 종료 이벤트 리스너

오퍼월 종료에 대한 이벤트 리스너를 제공합니다.

IgawAdpopcorn.setEventListener(ActivityContext, new IAdPOPcornEventListener() {
    @Override
    public void OnClosedOfferWallPage() {
        // Offerwall Closed
    }
});


오퍼월 참여 가능 포인트 조회 API

오퍼월에서 참여 가능한 광고의 포인트를 조회하는 API 입니다.

IgawAdpopcornExtension.getEarnableTotalRewardInfo(context, new IAPRewardInfoCallbackListener(){
    @Override
    public void OnEarnableTotalRewardInfo(boolean queryResult, int totalCount, String totalReward) {
        // TODO Auto-generated method stub
        Toast.makeText(context, "Total reward : " + totalReward, Toast.LENGTH_SHORT).show();
    }
});


팝업 광고 코드 연동


애드팝콘에서 제공하는 광고를 전면 팝업 형태의 UI로 제공하는 광고 타입입니다.


애드팝콘 필수 권한 체크

팝업 광고 API를 사용하기 전에 애드팝콘 이용 시 필요한 필수 권한이 추가 되어 있는지 확인을 하기 위해 아래 API를 반드시 호출합니다.

IgawAdpopcorn.checkRequiredPermission(Activity activity)

CAUTION!!!  권한이 없을 경우 , 권한 요청 다이얼로그를 띄우기 위해 파라미터로 반드시 activity context를 넘겨 주어야 합니다.


안드로이드 6.0 이상의 디바이스 대응을 위한 추가 연동

안드로이드 6.0 이상부터는 구글 계정 수집을 위해 GET_ACCOUNTS 권한 추가뿐만 아니라 권한을 허용할 계정도 직접 선택 해야 하기 때문에 아래 API를 추가 연동 하셔야 합니다.

@Override 

public void onRequestPermissionsResult(int requestCode, String[] permissions, int[] grantResults) { 
    super.onRequestPermissionsResult(requestCode, permissions, grantResults);

    IgawAdpopcorn.onRequestPermissionsResult(this,requestCode, permissions, grantResults);
}


팝업 광고 요청

유저식별값 설정 , 필수 권한 허용 , 구글 계정 수집이 정상적으로 이루어진 경우 아래 API를 통해 광고를 요청 하면 팝업 광고가 노출 됩니다.

IgawAdpopcorn.loadPopupAd(MainActivity.this,new IAPPopupAdEventListener() { @Override public void OnLoadPopupAdSuccess() { //

팝업 광고 로딩 성공 시 : loadPopupAd API 호출에 대한 결과 } @Override public void OnLoadPopupAdFailure (APPopupAdError apPopupAdError) { // 팝업 광고 로딩 실패 시 : loadPopupAd API 호출에 대한 결과 } @Override public void OnShowPopupAdSuccess() { // 팝업 광고 노출 성공 시 : showPopupAd API 호출에 대한 결과 } @Override public void OnShowPopupAdFailure(APPopupAdError apPopupAdError) { // 팝업 광고 노출 실패 시 : showPopupAd API 호출에 대한 결과 } @Override public void OnPopupAdClose() { // 팝업 광고 닫힐 때 } });


팝업 광고 노출

loadPopupAd API 호출에 대한 결과로 OnLoadPopupAdSuccess 이벤트를 받은 경우 노출을 할 광고가 있는 경우이기 때문에

showPopupAd API를 호출하여 광고 노출이 가능합니다.

IgawAdpopcorn.showPopupAd(Activity activity);

CAUTION!!!  팝업 형태로 노출이 이루어지기전에 반드시 파라미터로 activity context를 넘겨 주어야 합니다.



비디오 광고 코드 연동


애드팝콘에서 제공하는 광고를 비디오 타입 UI로 제공하는 광고 타입입니다.

loadVideoAd api를 이용하여 라이브 중인 비디오 광고 정보를 로드합니다.

IgawAdpopcorn.loadVideoAd(this, new IAPLoadVideoAdEventListener() {
    @Override
    public void OnLoadVideoAdSuccess() {
        // Video Loading Succeeded
    }

    @Override
    public void OnLoadVideoAdFailure(APVideoError apVideoError) {
        // Video Loading Failed.
        // apVideoError errorCode
        //    EXCEPTION = 200
        //    ADID_ABUSING = 500
        //    CAN_NOT_FIND_AVAILABLE_CAMPAIGN = 1000
        //    INVALID_MEDIA_KEY = 1400
        //    USER_IDENTIFIER_MISSING = 2250
    }
});


showVideoAd api를 이용하요 로드된 비디오 광고 정보를 노출합니다.

IgawAdpopcorn.showVideoAd(this, new IAPShowVideoAdEventListener() {
    @Override
    public void OnShowVideoAdSuccess() {
        // Video Showing Succeeded
    }

    @Override
    public void OnShowVideoAdFailure(APVideoError apVideoError) {
        // Video Showing Failed
        // ErrorCode
        //      TERMINATED_OR_INVALID_CAMPAIGN =  980;
        //      TERMINATED_OR_INVALID_CAMPAIGN =  999;
        //      ALREADY_COMPLETED_CAMPAIGN =  2000;
    }

    @Override
    public void OnVideoAdClose() {
        // VideoAd Closed
    }
});



오퍼월 스타일 설정


오퍼월 스타일 설정

스타일 api를 이용하여 오퍼월의 색상 및 테마를 변경할 수 있습니다.

프리셋에 정의된 것 외에 직접 색상코드를 입력하는 것도 가능합니다.

[안드로이드 애드팝콘 오퍼월 커스텀 API 가이드]


디바이스 회전 설정

앱이 가로모드를 지원하는 경우 디바이스의 상하 회전에 따라 오퍼월도 회전되도록 설정할 수 있습니다.

//true:회전모드, false:고정모드
IgawAdpopcorn.setSensorLandscapeEnable(ActivityContext, true);

CAUTION!!!  회전모드가 기본값으로 설정되어 있습니다.



IGAW 리워드 서버 연동


유저가 애드팝콘 광고의 완료 조건(앱설치, 신규실행 등)을 달성했을 때, 리워드를 지급하기 위한 연동이 필요합니다.

리워드를 지급하기 위한 정보를 콜백서버에서 처리하는 방식과 클라이언트에서 처리하는 방식이 있습니다.


  • 콜백서버 방식 (권장)
    콜백서버를 구성하여 리워드정보를 수신하는 방식으로 보안성이나 유저CS 처리 등의 유지보수에 용이합니다.
    [IGAW 리워드서버 연동 : 리워드서버 방식]

  • 클라이언트 방식
    자체서버를 구축하기 어려운 경우에 리워드정보를 클라이언트에서 처리하는 방식을 사용합니다.
    클라이언트에서 처리하기 위한 추가 api를 연동해야 합니다.
    [APPENDIX : 클라이언트 리워드 연동]



APPENDIX : 클라이언트 리워드 연동


IGAW 리워드서버에서 전달하는 콜백을 수신할 자체서버 구축이 어려운 경우에

추가 연동을 통해서 리워드 지급을 처리할 수 있습니다.


AndroidManifest.xml

리워드 콜백을 클라이언트에서 처리하기 위해 리워드서버 연동 방식을 수정합니다.

<application></application> 태그 안에 다음과 같이 리워드서버 연동 방식을 client로 설정합니다.

<meta-data android:name="igaworks_reward_server_type" android:value="client"/>


리워드 이벤트 리스너 등록&구현

IGAW리워드 서버로부터 전달되는 리워드 정보를 수신하기 위한 이벤트 리스너를 등록 & 구현 합니다.


리스너 상세 설명

1. onGetRewardInfo(boolean isSuccess, String resultMsg, APClientRewardItem[] rewardItems)

IGAW 리워드서버에 있는 처리되지 않은 리워드 정보가 전달 됩니다. 

리워드 정보는 APClientRewardItem 타입의 rewardItem[i] 배열로 전달되며, 배열에 포함된 정보는 다음과 같습니다.

  1. rewardItem[i].getCampaignKey() : 유저가 완료한 캠페인의 캠페인 키
  2. rewardItem[i].getCampaignTitle() : 유저가 완료한 캠페인의 이름
  3. rewardItem[i].getRTID() : 완료 트랜잭션 아이디
  4. rewardItem[i].getRewardQauntity() : 유저에게 지급해야 할 가상화폐의 양
  5. rewardItem[i].didGiveRewardItem() : 리워드 지급 처리 완료 정보를 IGAW서버에 전달하기 위한 api


IGAW리워드 서버에 해당 사실을 전달하기 위해 5번 항목에 있는 didGiveRewardItem api를 호출하여 정상적으로 결과를 수신한 경우에 1~4까지의 정보를 이용하여 유저에게 리워드 지급 처리를 합니다.


2. onDidGiveRewardItemResult(boolean isSuccess, String resultMsg, int resultCode, String completedRewardKey)

위에서 호출한 didGiveRewardItem api의 호출 결과가 전달 됩니다. 전달되는 completedRewardKey를 이용하여 리워드 중복지급 방지처리 등을 처리하시면 됩니다.

결과가 성공으로 리턴되는 경우에만 유저에게 리워드를 지급처리하여야 합니다.

IgawAdpopcornExtension.setClientRewardCallbackListener(context, new IAPClientRewardCallbackListener(){
@Override public void onGetRewardInfo(boolean isSuccess, String resultMsg, APClientRewardItem[] rewardItems) {
for (APClientRewardItem rewardItem : rewardItems) {
//아래 정보를 이용하여 유저에게 리워드를 지급합니다. rewardItem.getCampaignKey(); rewardItem.getCampaignTitle(); rewardItem.getRTID(); rewardItem.getRewardQuantity(); // didGiveRewardItem api를 이용하여 유효한 rewardkey 인지 확인합니다.
        // 확인결과는 onDidGiveRewardItemResult로 전달됩니다. rewardItem.didGiveRewardItem(); } } @Override public void onDidGiveRewardItemResult(boolean isSuccess, String resultMsg, int resultCode, String completedRewardKey) { // TODO Auto-generated method stub                 // 본 이벤트리스너의 수신 결과가 성공일 때에만 유저에게 리워드 지급 처리를 합니다.                 // 한번 지급 처리한 completedRewardKey 에 대해서는 다시 리워드 지급을 하면 안됩니다. } });

리워드 정보 수동 조회

리워드 이벤트 리스너는 오퍼월이 시작되거나 종료될 때 호출되며 IGAW리워드 서버에 처리되지 않은 리워드 정보가 있을 때, 정보가 전달 됩니다.

위 시점 외에 리워드 정보를 조회하고자 할 경우에는 getClientPendingRewardItems api를 호출하여 원하는 시점에 리워드정보를 조회할 수 있습니다.

조회된 정보는 위에서 구현한 리워드 이벤트 리스너로 전달됩니다.

IgawAdpopcornExtension.getClientPendingRewardItems(MainActivity.this);



APPENDIX : 애드팝콘 오퍼월 View 타입


애드팝콘 오퍼월 View 타입은 별도의 레이아웃을 이용해 애드팝콘 오퍼월을 구현할 수 있는 서비스입니다.

View 타입 으로 연동을 진행하면 아래 스크린샷과 같이 하나의 레이아웃에 앱의 UI 에 맞게 오퍼월을 구현하는 것이 가능합니다.



안드로이드 6.0 이상의 디바이스 대응을 위한 추가 연동

안드로이드 6.0 이상부터는 구글 계정 수집을 위해 GET_ACCOUNTS 권한 추가뿐만 아니라 권한을 허용할 계정도 직접 선택 해야 하기 때문에 아래 API를 모두 추가 연동 하셔야 합니다.

@Override 

public void onRequestPermissionsResult(int requestCode, String[] permissions, int[] grantResults) { 
    super.onRequestPermissionsResult(requestCode, permissions, grantResults);

    IgawAdpopcorn.onRequestPermissionsResult(this,requestCode, permissions, grantResults);
}


@Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {        
        try{
            offerwallLayout.onActivityResult(requestCode, resultCode, data);
        }catch(Exception e){}
    }

오퍼월 Layout 생성

오퍼월 Layout 생성 후, 추가하고자 하는 Layout 에 추가합니다.

activityLayout = (LinearLayout)findViewById(R.id.custom_parent_layout);
offerwallLayout = new ApOfferWallLayout(context);
activityLayout.addView(offerwallLayout);

CAUTION!!!  setCustomOfferwallLayout api가 호출되기 전에 반드시 setUserId api를 이용하여

유저식별값이 설정되어야 합니다.


오퍼월 액티비티 레이아웃 오리엔테이션 설정

activity orientation 이 landscape 인 경우에는 setApOfferWallOrientation(Boolean landscape) 를 호출하여 설정합니다.

offerwallLayout.setApOfferWallOrientation(true);
// default 는 portrait 이므로 landscape 일 경우 true 로 설정합니다.


오퍼월 Layout 세팅

IgawAdpopcornExtension.setCustomOfferwallLayout api를 호출하여 생성한 오퍼월 Layout을 SDK에 세팅합니다.

IgawAdpopcornExtension.setCustomOfferwallLayout(context.offerwallLayout,true);
// 타이틀바 숨김 : true
// 타이틀바 노출 : false


오퍼월 노출 카운트 수집 설정

오퍼월 노출 횟수 수집을 위해서는 setOfferwallImpressions api호출하고 오퍼월을 노출 시킵니다.

IgawAdpopcornExtension.setOfferwallImpressions(context);

igawBtn.setOnClickListener(new View.OnClickListener() {
    @Override
        public void onClick(View v) {
            offerwallLayout.setVisibility(View.VISIBLE);
            offerwallLayout.resume();
            showAdpopcornOfferwall = true;
        }
});

CAUTION!!!  setOfferwallImpressions api 는 애드팝콘 오퍼월의 노출 횟수를 집계하는 만큼

반드시 오퍼월 노출과 함께 호출되어야 합니다.

※ 오퍼월 연동이 모두 완료 되었으나 테스트 광고가 노출 되지 않을 경우? [FAQ 애드팝콘 오퍼월 D/A 확인하기]


오퍼월 레이아웃 컨트롤

Activity 생명 주기에 맞춰, offerwallLayout control api를 추가합니다.

@Override
protected void onResume() {
    // TODO Auto-generated method stub
    super.onResume();
    // offerwallLayout 노출 상태인 경우, activity resume 시, 광고 리스트 갱신.
    if(offerwallLayout != null && showAdpopcornOfferwall)
        offerwallLayout.resume(false);
}
 
@Override
protected void onDestroy() {
    // TODO Auto-generated method stub
    super.onDestroy();
    // offerwallLayout 해제.
    if(offerwallLayout != null)
        offerwallLayout.destroy();
}



현금성 리워드 매체 필수 연동 안내

필수 애드온 설치

현금성 리워드 앱의 경우, 반드시 IgawAdPopcornAddOn.jar 파일이 포함되어져 있어야 합니다.
다운로드 받으신 .zip 파일안에 포함된 IgawAdPopcornAddOn.jar 파일을 프로젝트에 추가합니다.
[IgawAdPopcornAddOn SDK 다운로드]

CAUTION!!! 현금성 리워드 매체에 대한 필수 애드온 관련 내용은 2017년 11월 1일부터 적용 됩니다.

애드팝콘 PUID 수집 API

현금성 리워드 앱의 경우 추가적으로 SDK(IgawAdPopcornAddOn.jar) 탑재 후
아래 API를 오퍼월 진입 전 호출하여 IMEI를 수집하도록 연동이 이루어져야 합니다.
// IgawAdpopcornExtension.setCashRewardAppFlag(Context context, boolean flag)
IgawAdpopcornExtension.setCashRewardAppFlag(context,true);

현금성 리워드 앱 필수 퍼미션 추가

현금성 리워드 앱의 경우, 기존 퍼미션 외에 아래와 같이 READ_PHONE_STATE  퍼미션이 추가로 포함 되어야 합니다.
<manifest>
...
    <user-permission android:name="android.permission.READ_PHONE_STATE" />
...
</manifest>


광고테스트 및 검증 신청


연동 작업을 마무리 한 뒤에 광고 테스트를 진행하고 검증을 신청합니다.


테스트 디바이스 등록 


애드팝콘 어드민에서 테스트 디바이스를 등록합니다.

테스트 디바이스의 구글광고아이디, 애플광고식별자를 그대로 사용합니다.

  • 구글광고아이디 샘플 : 7073c288-69ba-4a0b-a28c-e688fd3557ef
  • 애플광고식별자 샘플 : 31C7AE39-68A9-4281-8647-3C6F0A573E79



광고 노출 및 리워드 테스트

등록한 테스트 디바이스에서 오퍼월을 호출하여 테스트광고를 확인합니다.

테스트광고를 참여하여 정상적으로 리워드가 지급되는지를 확인합니다.


검증신청

모든 개발이 완료되면 애드팝콘 어드민을 통해 검증을 신청합니다. 

검증에 대한 자세한 안내는 다음의 아티클을 참고해주세요.

[IGAWorks 검수 안내]


광고 라이브 및 정산 절차

검증이 통과되면 별도의 요청이 없어도 가용한 모든 광고가 라이브 처리 됩니다.

광고 라이브 및 정산에 대한 문의는 애드팝콘 사업팀 (media@igaworks.com)으로 연락 부탁 드립니다.