1 개요 이가이드는 Cocos2d-x 엔진을사용하는안드로이드어플리케이션프로젝트에서아이지에이웍스의서비스를 이용하기위한플러그인가이드입니다. 기능 IGAWorks Cocos2d-x 플러그인이지원하는 IGAW 서비스는아래와같습니다. - 애드브릭스 - 애드팝콘 - 디스플레이애드

Cocos2d-x 플러그인가이드 Ver 1.0.0 2014.11. IGAWorks 연동지원팀 Property of IGAWorks, Inc. All Right Reserved.

1 개요 이가이드는 Cocos2d-x 엔진을사용하는안드로이드어플리케이션프로젝트에서아이지에이웍스의서비스를 이용하기위한플러그인가이드입니다. 기능 IGAWorks Cocos2d-x 플러그인이지원하는 IGAW 서비스는아래와같습니다. - 애드브릭스 - 애드팝콘 - 디스플레이애드 (DA) 2 기본설정 플러그인구성 최신 Cocos2d-x 플러그인을다운로드합니다. [ 최신플러그인다운로드 ] 다운로드받은 Igaworks_cocos2dx_plugin.zip 파일을압축해제하면다음과같은폴더구조와파일을확인할수 있습니다. - Classes : Cocos2d-x 용 cpp 파일. Plugin 사용을위해서 Cocos2d-x 프로젝트에복사해야합니다. - Proj.android : 안드로이드용플러그인파일과 Igaworks 서비스별애드온 jar 라이브러리파일. IgaworksCocos2dxPlugin.jar, IgawCommon_v0.0.0.jar, android-support-v4.jar 파일은반드시프로젝트에추가해야합니다. 기타서비스애드온 jar 라이브러리파일은연동하고자하는서비스에따라서추가합니다.

Cocos2d-x 안드로이드프로젝트설정 다운로드받은 Cocos2d-x 플러그인을안드로이드프로젝트에서사용하기위해다음과같은설정을진행합니다. 1. IgaworksPlugin.cpp, IgaworksPlugin.h 파일을 Cocos2d-x 프로젝트의 Classes 폴더에복사 2. jni/android.mk 수정 다음과같이 Classes 폴더안에있는 cpp 파일이자동으로빌드에포함되도록설정합니다. 참고. 필요한 cpp 파일만포함되길원하실때에는 LOCAL_SRC_FILES 에해당파일을명시합니다. AndroidManifest.xml 설정 아이지에이웍스의서비스를사용하기위한설정을 AndroidManifest.xml 파일에추가합니다. 1. 기본정보등록 - 아이지에이웍스앱키, 해시키를등록합니다.( 홈페이지에서앱생성후확인가능 ) - 앱이출시되는마켓정보를입력합니다. (google, naver, tstore 와같이 1 개만영문으로입력 ) - 리워드서버방식을설정합니다.( 자체서버이용 :server, SDK 이용 :client) 2. 액티비티등록 애드팝콘오퍼월 / DA 를이용하기위한필수액티비티를추가합니다. 3. 리시버등록 애드팝콘광고기능을이용하기위한필수리시버를추가합니다. 4. 퍼미션등록 플러그인을사용하기위한필수퍼미션을추가합니다.

<manifest> <!-- IGAWorks DA 최초요구 SDK ver : 8 --> <uses-sdk android:minsdkversion="8" android:targetsdkversion="21" /> <!-- 필수퍼미션추가 --> <uses-permission android:name="android.permission.internet" /> <uses-permission android:name="android.permission.access_network_state" /> <uses-permission android:name="android.permission.access_wifi_state" /> <uses-permission android:name="android.permission.read_phone_state" /> <uses-permission android:name="android.permission.read_external_storage" /> <uses-permission android:name="android.permission.write_external_storage" /> <application <!-- 생략 --> <!-- 애드팝콘오퍼월필수액티비티추가 --> <activity android:name="com.igaworks.adpopcorn.activity.apofferwallactivity_nt" android:theme="@android:style/theme.translucent.notitlebar"/> <!-- 애드팝콘오퍼월 CS 액티비티추가 --> <activity android:name="com.igaworks.adpopcorn.activity.apcsactivity_nt" android:theme="@android:style/theme.notitlebar"/> <!-- IgawAdpopcorn 3.4.0 부터추가됨 --> <activity android:name="com.igaworks.adpopcorn.activity.apvideoadactivity" android:theme="@android:style/theme.notitlebar" android:hardwareaccelerated="true" /> <!-- DA 필수액티비티추가 --> <activity android:name="com.igaworks.displayad.activity.interstitialactivity" android:configchanges="keyboardhidden orientation screensize" android:theme="@android:style/theme.notitlebar" /> <!-- 리시버등록 --> <receiver android:name="com.igaworks.igawreceiver" android:exported="true" > <intent-filter> <action android:name="com.android.vending.install_referrer" /> </intent-filter> </receiver> <!-- 기본정보등록 --> <meta-data android:name="igaworks_app_key" android:value=" 아이지에이웍스앱키 "/> <meta-data android:name="igaworks_hash_key" android:value=" 아이지에이웍스해시키 "/> <meta-data android:name="igaworks_market_info" android:value="google"/> <meta-data android:name="igaworks_reward_server_type" android:value="server"/> </application> </manifest>

3 기본코드연동 SDK 초기화 Cocos2d-x 플러그인을사용하기위해서는 Cocos2dxActivity 에서플러그인초기화를해야합니다. - IgaworksCocos2dxPlugin.setCococs2dxActivity(this); @Override protected void oncreate(bundle savedinstancestate) { // TODO Auto-generated method stub super.oncreate(savedinstancestate); // Init Plugin IgaworksCocos2dxPlugin.setCocos2dxActivity(this); } 기본연동 IGAWorks 서비스를이용하기위한기본코드연동을진행합니다. 연동되는코드를통해서기본분석지표가제공되며, 애드팝콘실행형캠페인을진행할수있습니다. * 주의. C++ 플러그인 api 를사용하기위해서는 IgaworksPlugin.h 를 include 해야합니다. - IgaworksPlugin::startApplication(); 앱이실행되는시점에서 1 번만호출합니다. ( 어플리케이션의시작을의미합니다.) - IgaworksPlugin::startSession(); 앱이 foreground 로전환되는시점에서호출합니다. 앱이활성화되는시점을의미하며 Android 에서는 onresume() 에설정합니다. - IgaworksPlugin::endSession(); 앱이 background 로전환되는시점에서호출합니다. 앱이비활성화되는시점을의미하며 Android 에서는 onpause() 에설정합니다. ( 비활성화 : 홈버튼, 백버튼, 전원버튼을통해앱을이탈, 혹은앱종료 ) - IgaworksPlugin::setUserId(const char* userid); 유저식별값을입력합니다. 이정보는유저에게리워드를지급하기위해필요한정보이며, 입력된정보를 이용하여리워드정보가전달됩니다. - IgaworksPlugin::setCallbackListener(this); 리스너를사용하기위해설정합니다. [7. 이벤트리스너참고 ] * 주의. 입력되는유저식별값정보에는개인정보가포함되어서는안됩니다. 부득이하게사용하셔야하는경우에는 반드시암호화처리를한값을사용하셔야합니다. ( 반려사유에해당 )

4 애드브릭스연동 제공된플러그인을이용하여아이지에이웍스의분석 / 통계서비스인애드브릭스를이용할수있습니다. 애드브릭스는다음과같은기능을제공합니다. - 유저분석 A. 나이 B. 성별 - 유저활동분석 A. 최초이용활동분석 B. 유저활동분석 C. 유저구매활동분석 - 아이지에이웍스실행형캠페인 - 아이지에이웍스친구초대캠페인 - 아이지에이웍스액션형캠페인 유저분석연동 어플리케이션을이용하는유저의정보를알수있는경우, 유저정보를분석할수있습니다. 애드브릭스에서제공하는유저정보카테고리는성별과나이입니다. - IgaworksPlugin::setAge(int age); - IgaworksPlugin::setGender(int gender); 유저활동분석연동 어플리케이션을이용하는유저의행동패턴을분석할수있습니다. 애드브릭스에서제공하는패턴의카테고리는아래와같습니다. - 최초이용활동 : 앱을설치하고최초로실행한날의자정까지의행동을집계합니다. - 앱유지활동 : 앱내에서유저가하는모든행동에대해서집계합니다. - 앱내구매활동 : 앱내에서유저가하는구매행동에대해서집계합니다.

최초이용활동 (FirstTimeExperience) 유저가앱을설치하고최초로실행한첫날의자정까지의행동을집계합니다. 집계된데이터는애드브릭스의 [Advanced Analytics -> New User Funnel Analysis] 에서확인가능합니다. - IgaworksPlugin::firstTimeExperience(const char* activityname); * 아래예시는연동되는앱을카카오톡게임으로가정하여작성된것입니다. IgaworksPlugin::firstTimeExperience( app_start ); IgaworksPlugin::firstTimeExperience( content_loading ); IgaworksPlugin::firstTimeExperience( kakao_talk_connect ); IgaworksPlugin::firstTimeExperience( terms_agree ); IgaworksPlugin::firstTimeExperience( tutorial_start ); IgaworksPlugin::firstTimeExperience( tutorial_complete ); IgaworksPlugin::firstTimeExperience( level_1 ); IgaworksPlugin::firstTimeExperience( level_2 ) 앱유지활동 (Retention) 유저가앱내에서행하는모든행동들에대해서집계합니다. 분석하기원하시는액션이발생했을때, retention api 를통해집계합니다. 집계된데이터는애드브릭스의 [Advanced Analytics -> In-app Activities ] 에서확인가능합니다. - IgaworksPlugin::retention(const char* activityname); * 아래예시는연동되는앱을카카오톡게임으로가정하여작성된것입니다. IgaworksPlugin::retention( level_1 ); IgaworksPlugin::retention( level_2 ); IgaworksPlugin::retention( level_3 ); IgaworksPlugin::retention( level_4 ); IgaworksPlugin::retention( open_main_menu ); IgaworksPlugin::retention( invite_friend ); IgaworksPlugin::retention( open_item_store ); IgaworksPlugin::retention( kill_second_boss_monster ); 앱내구매활동 (Buy) 유저가앱내에서행하는모든구매행동들에대해서집계합니다. 구매액션이발생했을때, buy api 를통해집계합니다.

집계된데이터는애드브릭스의 [Advanced Analytics -> In-app Purchase ] 에서확인가능합니다. - IgaworksPlugin::buy(const char* activityname); IgaworksPlugin::buy( gold_100_package ); IgaworksPlugin::buy( gold_200_package ); IgaworksPlugin::buy( gold_500_package ); IgaworksPlugin::buy( gold_1000_package );

5 애드팝콘연동 제공된플러그인을이용하여아이지에이웍스의매체수익화서비스인애드팝콘을이용할수있습니다. 리워드지급서버설정 오퍼월을통해서캠페인을완료한유저에게는보상을지급해야합니다. 보상의지급을위해서리워드정보가 전달되어야합니다. 개발사자체서버를통해서리워드정보를수신하기를원하시면 AndroidManifest 설정의리워드지급방식을 server 로설정합니다. 자체서버없이 IGAWorks 서버를이용하고자하실때에는 client 로설정하셔야합니다. [ 추가클라이언트연동필요 ] <!-- server : 자체서버로정보수신, client : sdk 를이용하여정보수신 --> <meta-data android:name="igaworks_reward_server_type" android:value="server"/> 유저식별값입력 캠페인에참여한유저를식별하기위해서유저식별값을입력하여야합니다. * 주의. 유저식별값은오퍼월이노출되기전에설정되어야하며, 입력값에는개인정보가포함되어서는안됩니다. 불가피하게개인정보를사용하셔야하는경우에는별도의암호화를거쳐서입력하셔야합니다. - IgaworksPlugin::setUserId(const char* userid); IgaworksPlugin::setUserId( user12345 ); 오퍼월노출 유저에게오퍼월을노출합니다. 오퍼월을통해서유저는캠페인을확인, 참여하여보상을얻을수있고참여완료한광고의상태확인과 CS 문의도할 수있습니다. - IgaworksPlugin::openOfferwall();

리워드지급연동 : SDK 이용 광고를참여한유저에게리워드를지급하기위해필요한정보를수신하는방식이개발사자체서버가아닌 SDK 를이용하는경우에는아래가이드를참고하여추가연동을진행해야합니다. * 주의. AndroidManifest.xml 파일의 igaworks_reward_server_type 을 client 라고설정하여야합니다. 리워드리스너등록 리워드정보를수신, 처리하기위한리스너를등록합니다. - IgaworksPlugin::setClientRewardEventListener(); 리워드정보조회 IGAW 리워드서버에있는리워드정보를조회합니다. 리워드지급처리가되지않은정보들이구현된리스너를 통해서리턴됩니다. - IgaworksPlugin::getClientPendingRewardItems(); 리워드정보확인및지급 getclientpendingrewarditems 의호출결과가아래구현된리스너로전달됩니다. 이곳에서리워드정보를 확인하고리워드의지급처리를진행합니다. - virtual void OnGetRewardInfo(const char* campaignkey, const char* campaignname, const char* quantity, const char* cv, const char* rewardkey); void HelloWorld::OnGetRewardInfo(const char* campaignkey, const char* campaignname, const char* quantity, const char* cv, const char* rewardkey){ // campaignkey : 캠페인식별키 // campaignname : 캠페인이름 // quantity : 지급해야할리워드수량 // cv : 인증토큰 // rewardkey : 유니크트랜잭션키 // quantity 만큼의리워드를유저에게지급합니다. 필요한경우 UI 를제작하여유저에게노티합니다. } 리워드지급처리결과전송 전달받은리워드정보를이용하여유저에게리워드지급처리를진행한뒤, IGAW 리워드서버에이사실을 전달합니다. 전달받은리워드정보에포함된 cv, rewardkey 값을이용하여아래 api 를호출합니다. - IgaworksPlugin::didGiveRewardItem(const char* cv, const char* rewardkey); void HelloWorld::OnGetRewardInfo(const char* campaignkey, const char* campaignname, const char* quantity, const char* cv, const char* rewardkey){ // campaignkey : 캠페인식별키 // campaignname : 캠페인이름

} // quantity : 지급해야할리워드수량 // cv : 인증토큰 // rewardkey : 유니크트랜잭션키 IgaworksPlugin::didGiveRewardItem(cv, rewardkey); 최종처리결과확인 didgiverewarditem 의호출결과가아래구현된리스너로전달됩니다. - virtual void OnDidGiveRewardItemResult(const char* resultmessage) {} void HelloWorld::OnDidGiveRewardItemResult(const char* resultmessage){ // rewardmessage : 최종처리결과, 참고용으로사용합니다. // 실패된건에대해서는 IGAW 리워드서버에남아있게되고 getpendingrewarditem 에서다시 return 됩니다. }

6 디스플레이광고 (DA) 연동 제공된플러그인을이용하여아이지에이웍스의매체수익화서비스인애드팝콘 DA 를이용할수있습니다. 플러그인에서는전면팝업광고 (interstitial), 부분팝업광고 (popup), 종료팝업광고 (ending), 네이티브광고 (native) 를 제공하며, 배너광고 (banner) 는 IgaworksDA Android native code 를이용하여연동하여야합니다. * 주의. 스마트스케쥴 ( 미디에이션 ) 기능을이용하기위해서는각광고제공업체의라이브러리를프로젝트에포함하고 설정해야합니다. DA 초기화 아래함수를호출하여 DA 애드온을초기화합니다. - IgaworksPlugin::initDisplayAd(); Memory / View 할당해제 DA 와관련된리소스를 release 하기위해사용합니다. * 주의. 리소스해제는앱이종료되는 Activity 의 ondestroy() 에서만호출되어야합니다. - System.exit(0); 혹은 android.os.process.killprocess(android.os.process.mypid()); @Override protected void ondestroy() { // TODO Auto-generated method stub super.ondestroy(); System.exit(0); } 네트워크광고전환주기설정 제공하는미디에이션네트워크별로수신한광고의새로고침주기를설정합니다. * 참고. 설정하지않으면기본값 (60 초 ) 으로유지됩니다. - IgaworksPlugin::setRefreshTime(int seconds); IgaworksPlugin::setRefreshTime(90); 위치타겟팅설정 위치정보를설정합니다. 설정된정보에일치하는위치타겟팅광고가존재할경우해당광고가노출됩니다. - IgaworksPlugin::setLocation(double latitude, double longitude); IgaworksPlugin::setLocation(37.566535, 126.977969);

전면팝업광고 (Interstitial) : 노출 전면광고를노출하고자하는시점에서아래 api 를호출합니다. * 참고. spotkey 는애드팝콘 DA 관리페이지에서확인할수있습니다. - IgaworksPlugin::showInterstitialAd(const char* spotkey); IgaworksPlugin::showInterstitialAd(INTERSTITIAL_SPOTKEY); 부분팝업광고 (Popup) : 노출 부분팝업광고를노출하고자하는시점에서아래 api 를호출합니다. - IgaworksPlugin::showPopupAd(const char* spotkey); IgaworksPlugin::showPopupAd(INTERSTITIAL_SPOTKEY); 종료팝업광고 (Ending) : 광고로드 엔딩광고의경우앱시작시점에서미리로드를해야합니다. 따라서앱이시작되는시점에서아래 api 를호출합니다. - IgaworksPlugin::loadEngingAd(const char* spotkey); IgaworksPlugin::loadEndingAd(INTERSTITIAL_SPOTKEY); 종료팝업광고 (Ending) : 광고노출 안드로이드뒤로가기버튼이나별도의종료이벤트에아래 api 를연결하여엔딩광고를노출합니다. - IgaworksPlugin::showEngingAd(const char* spotkey); IgaworksPlugin::showEndingAd(INTERSTITIAL_SPOTKEY); 네이티브광고 (Native) : 광고로드 네이티브광고를로드합니다. 로드에성공하면 NativeAdListener 로결과가전달됩니다. - IgaworksPlugin::loadNativeAd(const char* spotkey); IgaworksPlugin::loadNativeAd(INTERSTITIAL_SPOTKEY); 네이티브광고 (Native) : 노출추적 네이티브광고의노출을집계합니다. - IgaworksPlugin::impressionAction(); IgaworksPlugin::impressionAction();

네이티브광고 (Native) : 클릭추적 네이티브광고의클릭을집계합니다. - IgaworksPlugin::clickAction(); IgaworksPlugin::clickAction(); 네이티브광고 (Native) : 인스턴스해제 네이티브광고의인스턴스를해제합니다. - IgaworksPlugin::destroyAd(); IgaworksPlugin::destroyNativeAd(); 띠배너광고 (Banner) 플러그인을이용한배너광고연동은지원되지않습니다. 안드로이드프로젝트내에서직접 View 영역을생성, 할당하여연동을진행하여야합니다. 아래링크를통해서샘플 java 파일을다운로드하실수있습니다. [ 배너광고연동샘플 java 파일다운로드 ]

7 이벤트리스너설정 Cocos2d-x 플러그인에서는각서비스들에대해서이벤트리스너를지원합니다. 리스너를사용하기위해서는 IgaworksPlugin.h 와 IgaworksCocos2dxCallbackListener 를추가해야합니다. * 주의. 이벤트리스너를정상적으로이용하기위해서는 IgaworksPlugin::setCallbackListener(this); 를반드시 호출하여야합니다. 지원되는서비스별이벤트리스너는다음과같습니다. 애드팝콘오퍼월서비스 - 오퍼월이벤트리스너 A. OnClosedOfferWallPage : 오퍼월종료액션이벤트리스너. - 리워드처리델리게이트 (* SDK 이용하여처리시 ) A. OnGetRewardInfo : 오퍼월리워드정보조회이벤트리스너 B. OnDidGiveRewardItemResult : 오퍼월리워드처리결과이벤트리스너 애드팝콘 DA 서비스 - 전면팝업광고리스너 A. OnInterstitialReceiveSuccess : 전면팝업광고로드성공 B. OnInterstitialReceiveFail : 전면팝업광고로드실패 C. OnInterstitialClosed : 전면팝업광고종료 - 부분팝업광고리스너 A. OnPopupAdReceiveSuccess : 부분팝업광고로드성공 B. OnPopupAdReceiveFail : 부분팝업광고로드실패 C. OnPopupAdClosed : 부분팝업광고종료 - 네이티브광고리스너 A. OnNativeAdRequestSucceeded : 네이티브광고컨텐츠로드성공 B. OnNativeAdRequestFailed : 네이티브광고컨텐츠로드실패

8 검수 애드팝콘서비스를이용하시거나, 애드브릭스를이용한캠페인을진행하실경우에는반드시 IGAW 의검수를받아야 합니다. 애드팝콘서비스는애드팝콘관리페이지의검수메뉴를통해검수신청을진행하시면됩니다. 애드브릭스캠페인검수는아이지에이웍스의담당 AE 나 QA@igaworks.com 으로신청하시면됩니다. 검수를신청하실때에는 SDK 가연동된 apk 파일과앱키, 앱명을함께전달하셔야합니다. ( * 대용량의 apk 일경우다운로드가가능한링크로대체하셔도됩니다.) 9 문의 플러그인사용방법에대해서문의사항이있을경우에 IGAWorks 연동지원팀 (integration@igaworks.com) 으로 아래양식을채워서메일주시면최대한빠르게지원드리겠습니다. 앱명 사용엔진 앱키 SDK ver.