로딩중입니다
애드팝콘 오퍼월 : 유니티 안드로이드
4/26/2017 4:17:48 PM

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

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

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

[애드팝콘 서비스 안내]


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

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

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



SDK 다운로드 및 설치


[SDK 다운로드 센터] 에서 최신 유니티 안드로이드 플러그인 패키지를 다운로드 합니다.

다운로드 받은 .zip 파일을 압축해제하여 IgawUnityPlugin_aos_ver~*.unitypackage 파일을 유니티 프로젝트로 드래그하여 설치합니다.

Importing package 팝업창에서 애드팝콘 오퍼월에 필요한 아래 항목만을 선택하여 import 합니다.




매니페스트 설정


오퍼월을 이용하기 위한 내용을 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 : 클라이언트 리워드 연동]



코드연동

SDK 초기화

어플리케이션 실행 후 유니티 엔진이 구동 될 때, initPluginstartSessionendSession api를 호출하여 SDK를 초기화합니다.
using IgaworksUnityAOS;

public class MySampleScene : MonoBehavior {

    void Awake() {        
        IgaworksUnityPluginAOS.InitPlugin ();
    }

    void Start()
    {
        #if UNITY_5_3_OR_NEWER
            Debug.Log("Current Unity version is UNITY_5_3_OR_NEWER");
        #else            
            IgaworksUnityPluginAOS.Common.startSession();
        #endif
    }

    void OnApplicationPause(bool pauseStatus){
        
        if (pauseStatus) {
        Debug.Log ("go to Background");
        IgaworksUnityPluginAOS.Common.endSession();
    } else {
        Debug.Log ("go to Foreground");
        IgaworksUnityPluginAOS.Common.startSession();
    }

}

유저식별값 입력

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


주의 사항


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

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

IgaworksUnityPluginAOS.Common.setUserId("bXlBY2NvdW50X25hbWU=");


오퍼월 광고 노출

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

public class MySampleScene : MonoBehavior {         
    Rect openOfferwallBtn = new Rect(100, 100, 200, 200);

    void OnGUI() {
        if (GUI.Button(openOfferwallBtn, "AdpopcornOfferwall")) {
            IgaworksUnityPluginAOS.Adpopcorn.openOfferwall();
        }
    }
} 


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

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

public class MySampleScene : MonoBehavior {         
    Rect openOfferwallBtn = new Rect(100, 100, 200, 200);

    void OnGUI() {
        if (GUI.Button(openOfferwallBtn, "AdpopcornOfferwall")) {
            IgaworksUnityPluginAOS.Adpopcorn.openDialogTypeOfferwall();
        }
    }
} 

비디오 광고(리워드) 로드 및 노출

애드팝콘에서 제공하는 리워드 비디오 광고를 이용하기 위해 loadVideoAd api를 이용하여 라이브 중인 광고 정보를 로드합니다.

함께 제공되는 델리게이트를 이용하여 api 호출 결과를 확인할 수 있습니다.

using IgaworksUnityAOS;

public class MySampleScene : MonoBehaviour {
	
	void LoadAdPopcornRewardedVideoAdInfo () {
	
		IgaworksUnityPluginAOS.OnLoadVideoAdSuccess = mOnLoadVideoAdSuccess;
		IgaworksUnityPluginAOS.OnLoadVideoAdFailure = mOnLoadVideoAdFailure;

		IgaworksUnityPluginAOS.Adpopcorn.loadVideoAd ();	
	}

	void mOnLoadVideoAdSuccess() { }
	void mOnLoadVideoAdFailure(string apErrorMessage) {
		// Adpopcorn Rewarded Video Info Loading Failed
		// errorCode
		//		200 : Exception
		//		500 : Abusing
		//		1000 : Can not fild available campaign
		//		1400 : invalid app key
		//		2250 : user identifier missing
	}
}


showVideoAd api를 이용하여 로드된 비디오 광고를 원하는 시점에 노출합니다.

함께 제공되는 델리게이트를 이용하여 api 호출 결과를 확인할 수 있습니다.

using IgaworksUnityAOS;

public class MySampleScene : MonoBehaviour {
	
	void ShowAdPopcornRewardedVideoAd () { 
		IgaworksUnityPluginAOS.OnShowVideoAdSuccess = mOnShowVideoAdSuccess;
		IgaworksUnityPluginAOS.OnShowVideoAdFailure = mOnShowVideoAdFailure;
		IgaworksUnityPluginAOS.onVideoAdClose = mOnVideoAdClose;

		IgaworksUnityPluginAOS.Adpopcorn.showVideoAd ();	
	}

	void mOnVideoAdClose () {}
	void mOnShowVideoAdSuccess () {}
	void mOnShowVideoAdFailure (string apErrorMessage) {
		// Adpopcorn Rewarded Video Showing Failed
		// errorCode
		//		980 : Terminated or invalid campaign
		//		999 : Terminated or invalid campaign
		//		2000 : Already completed campaign
	}
}


이벤트 델리게이트 및 기타 설정


오퍼월 종료 이벤트 델리게이트

오퍼월 종료되는 이벤트에 대한 이벤트 델리게이트를 제공합니다.
setAdpopcornOfferwallEventListener api를 호출하여 리스너를 등록하고 구현하여 사용합니다.

using IgaworksUnityAOS;

public class MySampleScene : MonoBehaviour {

	// Use this for initialization
	void Start () {
		IgaworksUnityPluginAOS.Adpopcorn.setAdpopcornOfferwallEventListener ();
		IgaworksUnityPluginAOS.OnClosedOfferwallPage = mOnClosedOfferwall;
	}

	void mOnClosedOfferwall () { }	
}


디바이스 회전 설정

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

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

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


오퍼월 스타일 설정

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

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

// 오퍼월 테마 프리셋 
//	RED_THEME = "ff9d261c";
//	BLUE_THEME = "ff3d7caf";
//	YELLOW_THEME = "ffffba03";	


// 오퍼월 타이틀

IgaworksUnityPluginAOS.Adpopcorn.setOfferwallTitle(“커스텀 타이틀”); // 오퍼월 테마 색상 변경 IgaworksUnityPluginAOS.Adpopcorn.setOfferwallThemeColor(IgaworksUnityPluginAOS.OfferwallThemeStyle.BLUE_THEME);

// 오퍼월 타이틀 색상 변경 IgaworksUnityPluginAOS.Adpopcorn.setOfferwallTitleColor(IgaworksUnityPluginAOS.OfferwallThemeStyle.BLUE_THEME); // 오퍼월 타이틀 백그라운드 색상 변경 IgaworksUnityPluginAOS.Adpopcorn.setOfferwallTitleBackgroundColor(IgaworksUnityPluginAOS.OfferwallThemeStyle.BLUE_THEME);
*유니티에서는 로고 이미지 설정 시 api 지원을 하지 않고 있습니다.



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(string campaignkey, string campaignname, string quantity, string cv, string rewardkey)

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


  1. campaignkey : 유저가 완료한 캠페인의 캠페인 키
  2. campaignname : 유저가 완료한 캠페인의 이름
  3. quantity : 유저에게 지급해야 할 가상화폐의 양
  4. cv : 리워드 지급 처리 완료 정보를 IGAW서버에 전달하기 위한 api
  5. rewardkey : 완료 트랜잭션 아이디

1~3까지의 정보를 이용하여 유저에게 리워드 지급 처리를 한 뒤, IGAW리워드 서버에 해당 사실을 전달하기 위해 4, 5번 항목을 포함해 didGiveRewardItem api를 호출합니다.


2. OnDidGiveRewardItemRequestResult (bool isSuccess, string rewardkey)

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

void setAdpopcornRewardDelegate() {
        IgaworksUnityPluginAOS.Adpopcorn.setClientRewardEventListener();
	IgaworksUnityPluginAOS.OnGetRewardInfo = mOnGetRewardInfo;
	IgaworksUnityPluginAOS.OnDidGiveRewardItemRequestResult = mOnDidGiveRewardItemRequestResult;   
}

void mOnGetRewardInfo(string campaignkey, string campaignname, string quantity, string cv, string rewardkey){    
	// 아래 정보를 이용하여 유저에게 리워드를 지급합니다.
	string ck = campaignkey;
	string cn = campaignname;
	string qt = quantity;

	// didGiveRewardItem api를 이용하여 유효한 rewardkey 인지 확인합니다.
	// 확인결과는 mOnDidGiveRewardItemRequestResult로 전달됩니다.
	IgaworksUnityPluginAOS.Adpopcorn.didGiveRewardItem (cv, rewardkey);
}

void mOnDidGiveRewardItemRequestResult (bool isSuccess, string rewardkey) {
	// 본 델리게이트의 수신 결과가 성공일 때에만 유저에게 리워드 지급 처리를 합니다.
	// 한번 지급 처리한 completedRewardKey 에 대해서는 다시 리워드 지급을 하면 안됩니다.
}
CAUTION!!!  리워드 델리게이트는 getClientPendingRewardItems api를 호출하여 리워드 정보를 조회한 경우에 호출됩니다.


리워드 정보 조회

getClientPendingRewardItems api를 호출하여 리워드정보를 조회합니다. 

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

IgaworksUnityPluginAOS.Adpopcorn.getClientPendingRewardItems();

CAUTION!!!  클라이언트에서는 유저의 광고참여완료 여부를 알 수 없기 때문에 오퍼월이 닫히는 시점이나 앱이 최초 실행되는 시점에 위 api를 호출하는 것을 권장합니다.



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

필수 애드온 설치

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


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

애드팝콘 PUID 수집 API

현금성 리워드 앱의 경우 추가적으로 SDK(IgawAdPopcornAddOn.jar) 탑재 후
아래 API를 오퍼월 진입 전 호출하여 IMEI를 수집하도록 연동이 이루어져야 합니다.
IgaworksUnityPluginAOS.Adpopcorn.setCashRewardAppFlag (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)으로 연락 부탁 드립니다.