로딩중입니다
애드팝콘 오퍼월 : 유니티 안드로이드
4/12/2018 2:25:42 PM

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

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

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

[애드팝콘 서비스 안내]


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

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

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



SDK 다운로드 및 설치


아래 다운로드 링크를 통해 최신 애드팝콘 유니티 플러그인 패키지를 다운로드 합니다.

[안드로이드 유니티 애드팝콘 SDK 다운로드]


IgawAdPopcornUnityPlugin_aos_vX.X.X.unitypackage를 아래와 같이 import 진행 합니다.



매니페스트 설정


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


앱키 & 해시키 추가

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

<application>
...
    <meta-data android:name="adpopcorn_app_key" android:value="이곳에_앱키를_입력하세요" />
    <meta-data android:name="adpopcorn_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 : 클라이언트 리워드 연동]



필수 코드 연동


유저식별값 입력

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


주의 사항

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

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

IgawAdPopcornUnityPluginAOS.getInstance().setUserId("bXlBY2NvdW50X25hbWU=");



오퍼월 코드 연동


애드팝콘 오퍼월 광고를 노출하는 API는 일반 액티비티 타입과 다이얼로그 타입을 지원하는 두 가지 API가 제공 되고 있습니다.

두 가지 API를 참고 하여서 원하시는 오퍼월 형태로 연동을 진행 합니다.


일반 액티비티 오퍼월 광고 노출

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

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

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


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

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

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

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

오퍼월 종료 이벤트 리스너

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

using IgaworksUnityAOS;

public class MySampleScene : MonoBehaviour {

	// Use this for initialization
	void Start () {
		IgawAdPopcornUnityPluginAOS.getInstance().setAdpopcornOfferwallEventListener ();
		IgawAdPopcornUnityPluginAOS.OnClosedOfferWallPage += mOnClosedOfferwallPage;
	}

	void mOnClosedOfferwallPage (object sender, System.EventArgs args)
	{
		Debug.Log ("#################     mOnClosedOfferwallPage     ###################\n" );
	}
}


오퍼월 적립 가능 리워드 조회

애드팝콘 오퍼월에서 참여 가능한 캠페인 수와 적립 가능한 리워드 정보를 조회합니다.

getEarnableTotalRewardInfo API를 이용하여 적립 가능한 리워드 정보를 조회합니다.

public class MySampleScene : MonoBehaviour {


    // Use this for initialization


    void Start () {

        // 델리게이트 등록

        IgawAdPopcornUnityPluginAOS.getInstance().setAdPopcornTotalRewardInfoEventListener();

        IgawAdPopcornUnityPluginAOS.OnEarnableTotalRewardInfo += mOnEarnableTotalRewardInfo;


        // 적립 가능 리워드 조회

        IgawAdPopcornUnityPluginAOS.getInstance().getEarnableTotalRewardInfo();

    }

    void mOnEarnableTotalRewardInfo(object sender, APTotalRewardInfo apTotalRewardInfo)

    {

        Debug.Log("################# mOnEarnableTotalRewardInfo   queryResult    ################### " +         apTotalRewardInfo.queryResult);

        Debug.Log("################# mOnEarnableTotalRewardInfo   totalCount            ################### " + apTotalRewardInfo.totalCount);     

        Debug.Log("################# mOnEarnableTotalRewardInfo   totalReward    ################### " +         apTotalRewardInfo.totalReward);

   }

}



팝업 광고 연동


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


팝업 광고 요청

유저식별값 설정 , 필수 권한 허용(유니티 연동 시 필수권한체크 및 연동은 매체측에서 진행 해야 합니다) , 구글 계정 수집이
정상적으로 이루어진 경우 아래 API를 통해 광고를 요청하면 팝업 광고가 노출됩니다.

애드팝콘에서 제공하는 팝업 광고를 이용하기 위해 loadPopupAd API를 이용하여 라이브 광고 정보를 불러옵니다.

IgawAdPopcornUnityPluginAOS.getInstance().loadPopupAd ();


팝업 광고 노출

loadPopupAd 호출 결과 광고가 있을 경우(델리게이트 등록 하여 이벤트 확인) , 광고 노출을 원하는 시점에 아래 API를 호출 합니다.

IgawAdPopcornUnityPluginAOS.getInstance().showPopupAd ();


델리게이트 등록 및 해제

팝업 광고 요청에 대한 결과 및 노출 결과를 확인하고 싶을 경우 , setAdpopcornPopupAdEventListner API를 호출 하여 델리게이트를 등록 합니다.

void setDelegate() {

// 오퍼월 팝업광고 이벤트 델리게이트 등록
        IgawAdPopcornUnityPluginAOS.getInstance().setAdpopcornPopupAdEventListener();
        IgawAdPopcornUnityPluginAOS.OnLoadPopupAdFailure += mOnLoadPopupAdFailure;
        IgawAdPopcornUnityPluginAOS.OnLoadPopupAdSuccess += mOnLoadPopupAdSuccess;
        IgawAdPopcornUnityPluginAOS.OnShowPopupAdFailure += mOnShowPopupAdFailure;
        IgawAdPopcornUnityPluginAOS.OnShowPopupAdSuccess += mOnShowPopupAdSuccess;
        IgawAdPopcornUnityPluginAOS.OnPopupAdClose += mOnPopupAdClose;
}

void releaseDelegate () {

// 오퍼월 팝업광고 이벤트 델리게이트 등록 해제
IgawAdPopcornUnityPluginAOS.OnLoadPopupAdFailure -= mOnLoadPopupAdFailure;
        IgawAdPopcornUnityPluginAOS.OnLoadPopupAdSuccess -= mOnLoadPopupAdSuccess;
        IgawAdPopcornUnityPluginAOS.OnShowPopupAdFailure -= mOnShowPopupAdFailure;
        IgawAdPopcornUnityPluginAOS.OnShowPopupAdSuccess -= mOnShowPopupAdSuccess;
        IgawAdPopcornUnityPluginAOS.OnPopupAdClose -= mOnPopupAdClose;
}



오퍼월 스타일 설정


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

Hashtable에 수정하고 싶은 옵션 값을 저장하여 setCustomOfferwallStyle api 을 호출하여 주면 됩니다.

자세한 옵션 사항은 스타일 가이드 문서를 참고 해 주시기 바랍니다. 

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

CAUTION!!!  각 옵션 값은 받을 수 있는 타입이 정해져 있습니다. 정확히 입력하지 않으면 오퍼월이 동작하지 않을 수 있습니다.



IGAW 리워드 서버 연동


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

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


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

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

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


IGAW 리워드서버에서 전달하는 콜백을 수신할 자체서버 구축이 어려운 경우에 추가 연동을 통해서 리워드 지급을 처리할 수 있습니다.


AndroidManifest.xml 

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

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

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


리워드 이벤트 델리게이트 등록 & 구현


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

CAUTION!!!  애드팝콘 v6.0.0부터 이벤트 델리게이트 구성이 변경되었습니다. 아래 변경된 델리게이트 내용대로 연동 진행 부탁 드립니다!


리스너 상세설명

1. OnGetRewardInfo(object sender, APClientRewardItem apClientRewardItem)

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

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

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


2. OnDidGiveRewardItemRequestResult (object sender, APDidGiveRewardItemResult apDidGvieRewardItemResult)

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

void setAdpopcornRewardDelegate() {
    IgawAdPopcornUnityPluginAOS.getInstance().setClientRewardEventListener ();
    IgawAdPopcornUnityPluginAOS.OnGetRewardInfo += mOnGetRewardInfo;
    IgawAdPopcornUnityPluginAOS.OnDidGiveRewardItemRequestResult += mOnDidGiveRewardItemRequestResult;
}

void mOnGetRewardInfo(object sender, APClientRewardItem apClientRewardItem)
{
    string campaignKey = apClientRewardItem.campaignKey;
    string rewardkey = apClientRewardItem.rewardKey;
    string campaignName = apClientRewardItem.campaignName;
    long quantity = apClientRewardItem.quantity;
    string cv = apClientRewardItem.cv;

    // 위 정보를 이용하여 유저에게 리워드를 지급합니다.
    // {리워드 지급 처리}
		
    // didGiveRewardItem API를 호출하여 리워드 지급 처리 완료를 IGAW리워드 서버에 통지합니다.
    Debug.Log ("################# mOnGetRewardInfo   campaignkey    ################### " + campaignKey);
    Debug.Log ("################# mOnGetRewardInfo   rewardkey    ################### " + rewardkey);
    Debug.Log ("################# mOnGetRewardInfo   quantity    ################### " + quantity);
    IgawAdPopcornUnityPluginAOS.getInstance().didGiveRewardItem (cv, rewardkey);
}

void mOnDidGiveRewardItemRequestResult (object sender, APDidGiveRewardItemResult apDidGvieRewardItemResult)
{
    // didGiveRewardItem 함수의 처리 결과가 리턴됩니다.
    // 동일한 rewardkey에 대해서 중복지급방지 처리를 합니다
    bool isSuccess = apDidGvieRewardItemResult.isSuccess;
    string rewardKey = apDidGvieRewardItemResult.completedRewardKey;
    Debug.Log ("################# mOnDidGiveRewardItemRequestResult   rewardkey    ###################" + rewardKey);
}
CAUTION!!!  리워드 델리게이트는 getClientPendingRewardItems api를 호출하여 리워드 정보를 조회한 경우에 호출됩니다.


리워드 정보 조회

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

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

IgaworksUnityPluginAOS.Adpopcorn.getClientPendingRewardItems();

CAUTION!!!  애드팝콘 v6.0.0부터는 오퍼월 오픈/닫기 시점에 자동으로 getClientPendingRewardItems()가 호출됩니다. 이에  기존 버전의 SDK를 사용하고 있던 클라이언트에서는 오퍼월 닫는 시점에 호출해 줄 필요가 없습니다. 이에 수동으로 조회하거나 앱 최초 실행 되는유저의 광고참여완료 여부를 알 수 없기 때문에 오퍼월이 닫히는 시점이나 앱이 최초 실행되는 시점에 위 api를 호출하는 것을 권장합니다.


광고테스트 및 검증 신청


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


테스트 디바이스 등록 


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

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

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



광고 노출 및 리워드 테스트

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

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


검증신청

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

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

[IGAWorks 검수 안내]


광고 라이브 및 정산 절차

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

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

CAUTION!!! 검증이 통과된 후 설정한 테스트 디바이스를 해제 해야만 실제 가용 광고가 노출 됩니다.