로딩중입니다
애드팝콘 오퍼월 : 유니티 iOS
4/26/2017 4:18:00 PM

애드팝콘 오퍼월 연동하기 : 유니티 iOS


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

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

[애드팝콘 서비스 안내]


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

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

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



SDK 다운로드 및 설치


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

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

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



※ 주의 : 유니티용 애드팝콘만 사용하실 예정이라면 위에 표시된 라이브러리 외 나머지 라이브러리는 삭제해 주시길 부탁드립니다.



코드연동


IDFA 설정

애드팝콘 서비스를 정상적으로 이용하기 위하여 IDFA 값을 등록합니다. Xcode 프로젝트로 이동하여 등록합니다.

// Xcode Project
#import <AdSupport/AdSupport.h>
#import <IgaworksCore/IgaworksCore.h>

- (BOOL)application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary*)launchOptions{
	if (NSClassFromString(@"ASIdentifierManager")){
		NSUUID *ifa = [[ASIdentifierManager sharedManager] advertisingIdentifier];
		BOOL isAppleAdvertisingTrackingEnabled = [[ASIdentifierManager sharedManager] isAdvertisingTrackingEnabled];
		[IgaworksCore setAppleAdvertisingIdentifier:[ifa UUIDString] isAppleAdvertisingTrackingEnabled:isAppleAdvertisingTrackingEnabled];
		NSLog(@"[ifa UUIDString] : %@", [ifa UUIDString]);
	}
}


앱키 & 해시키 설정

IgaworksCoreWithAppkey api를 호출하여 Igaworks 홈페이지에서 애드팝콘 앱 등록 후 발급받은 앱키, 해시키를 설정합니다.

public class MySampleScene : MonoBehaviour {
    // Use this for initialization
    void Start () {
        IgaworksCorePluginIOS.IgaworksCoreWithAppKey("YOUR_APP_KEY", "YOUR_HASH_KEY");
    }
}


로그 수준 설정

SDK에서 노출하는 로그의 수준을 설정할 수 있습니다.

setLogLevel  API를 이용하여 설정하며 수준을 결정하는 값은 IgaworksCorePluginIOS 에 정의된 enum을  사용하며 각 수준은 다음과 같습니다.

  • IgaworksCoreLogInfo  : info 수준의 가장 기본적인 로그 만을 노출합니다. 
  • IgaworksCoreLogDebug  : info를 포함한 Debug 수준의 로그를 노출합니다.
  • IgaworksCoreLogTrace  : 모든 로그를 노출합니다.
IgaworksCorePluginIOS.setLogLevel(IgaworksCorePluginIOS.IgaworksCoreLogTrace);


리워드서버 연동방식 추가

SetUseIgaworksRewardServer api를 호출하여 리워드서버 연동방식을 설정합니다. 애드팝콘 어드민에서 자체서버를 선택한 경우에는 "false"를 입력합니다.

AdPopcornOfferwallPluginIOS.SetUseIgaworksRewardServer(false);
//true : IGAW 리워드서버 이용
//false : 자체 서버 이용

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


유저식별값 입력

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


주의사항

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


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

IgaworksCorePluginIOS.SetUserId("bXlBY2NvdW50X25hbWU=");


오퍼월 광고 노출

openOfferWallWithViewController api를 호출하여 오퍼월을 노출합니다.

public class MySampleScene : MonoBehaviour {

    Rect openOfferwallBtn= new Rect(100,100,200,200);
	
    void OnGUI() {
	if(GUI.Button (openOfferwallBtn, "AdPopcornOfferwall")) {
		AdPopcornOfferwallPluginIOS.OpenOfferWallWithViewController(false, null);
	}
    }
}

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

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

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

public class MySampleScene : MonoBehaviour {

    void LoadAdPopcornRewardedVideoAdInfo() { 
		
	AdPopcornOfferwallPluginIOS.AdPopcornOfferwallSetCallbackHandler ("MySampleScene");
	AdPopcornOfferwallPluginIOS.loadVideoAdSuccess += HandleLoadVideoAdSuccess;
	AdPopcornOfferwallPluginIOS.loadVideoAdFailedWithError += HandleLoadVideoAdFailedWithError;

	AdPopcornOfferwallPluginIOS.LoadVideAd (true);
    }

    void HandleLoadVideoAdSuccess() { }
    void HandleLoadVideoAdFailedWithError (string errorCode) {
	// 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 호출 결과를 확인할 수 있습니다.
public class MySampleScene : MonoBehaviour {

    void ShowAdPopcornRewardedVideoAd() { 

        AdPopcornOfferwallPluginIOS.AdPopcornOfferwallSetCallbackHandler ("MySampleScene");
        AdPopcornOfferwallPluginIOS.willOpenVideoAd += HandleWillOpenVideoAd;
        AdPopcornOfferwallPluginIOS.didOpenVideoAd += HandleDidOpenVideoAd;
        AdPopcornOfferwallPluginIOS.willCloseVideoAd += HandleWillCloseVideoAd;
        AdPopcornOfferwallPluginIOS.didCloseVideoAd += HandleDidCloseVideoAd;
        AdPopcornOfferwallPluginIOS.showVideoAdFailedWithError += HandleShowVideoAdFailedWithError;
        AdPopcornOfferwallPluginIOS.ShowVideoAdWithViewController (true);
    }

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


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


오퍼월 액션 이벤트 

오퍼월 종료 등의 액션에 대한 이벤트 델리게이트를 제공합니다.

AdPopcornOfferwallSetCallbackHandler api를 호출하여 델리게이트를 수신할 대상을 등록하고 구현하여 사용합니다.

public class MySampleScene : MonoBehaviour {

    void setAdpopcornOfferwallEventDelegate(){
	
	AdPopcornOfferwallPluginIOS.AdPopcornOfferwallSetCallbackHandler ("MySampleScene");

	AdPopcornOfferwallPluginIOS.offerWallWillOpen += HandleOfferWallWillOpen;
	AdPopcornOfferwallPluginIOS.offerWallOpened += HandleOfferWallOpened;
	AdPopcornOfferwallPluginIOS.offerWallWillClose += HandleOfferWallWillClose;
	AdPopcornOfferwallPluginIOS.offerWallClosed += HandleOfferWallClosed;
    }

    void HandleOfferWallWillOpen(){}
    void HandleOfferWallOpened(){}
    void HandleOfferWallWillClose(){}
    void HandleOfferWallClosed(){}
}


애드팝콘 오퍼월 스타일 API

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

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

public class MySampleScene : MonoBehaviour {

void changeOfferWallColorTheme () {

// 오퍼월 테마 색상 변경

// AdPopcornOfferwallPluginIOS.SetAdPopcornThemeColor(float red, float green, float blue)
AdPopcornOfferwallPluginIOS.SetAdPopcornThemeColor(255, 255, 255);

// 오퍼월 로고 변경

// AdPopcornOfferwallPluginIOS.SetAdPopcornOfferwallTitleLogoPath(String path);
AdPopcornOfferwallPluginIOS.SetAdPopcornOfferwallTitleLogoPath(“AdpopcornOfferwall.bundle/Contents/Resourcs/image/customLogo.png”);

// 오퍼월 타이틀 변경

// AdPopcornOfferwallPluginIOS.SetAdPopcornOfferwallTitle(String title);
AdPopcornOfferwallPluginIOS.SetAdPopcornOfferwallTitle(“충전소”);

// 오퍼월 타이틀 색상 변경

// AdPopcornOfferwallPluginIOS.SetAdPopcornOfferwallTitleColor(float red, float green, float blue)
AdPopcornOfferwallPluginIOS.SetAdPopcornOfferwallTitleColor(0, 100, 50)

// 오퍼월 Top/bottom bar 색상 변경  

// AdPopcornOfferwallPluginIOS.SetAdPopcornOfferwallTitleBackgroundColor(float red, float green, float blue)
AdPopcornOfferwallPluginIOS.SetAdPopcornOfferwallTitleBackgroundColor(100, 100, 100);

        }
}



IGAW 리워드 서버 연동


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

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


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

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



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


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


리워드서버 연동방식 설정

SetUseIgaworksRewardServer api를 호출하여 리워드서버 연동방식을 설정합니다.
애드팝콘 어드민에서 IGAWORKS 서버를 선택한 경우에는 ture를 입력합니다.

AdPopcornOfferwallPluginIOS.SetUseIgaworksRewardServer(true);


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

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


델리게이트 상세 설명

1. onRewardRequestResult

onRewardRequestResult 델리게이트로 IGAW 리워드서버에 있는 처리되지 않은 리워드정보가 전달됩니다.

리워드정보는 key=value의 형태를 가진 하나의 문자열로 전달되며 이 데이터를 split하여 리워드 처리에 사용합니다.


  1.  campaignKey : 유저가 완료한 캠페인의 식별키
  2.  campaignName : 유저가 완료한 캠페인의 이름
  3.  rewardKey : 완료 트랜잭션 아이디
  4.  quantity : 유저에게 지급해야 할 가상화폐의 양


위 정보에서 split한 rewardKey의 유효성 확인을 위해 DidGiveRewardItemWithRewardKey api를 호출합니다.


2. onRewardCompleteResult

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

호출결과가 성공일 때에만 유저에게 리워드를 지급하도록 처리합니다.

public class MySampleScene : MonoBehaviour {
    
    void SetAdPopcornRewardDelegate() {

        //델리게이트 리스너 등록 
        IgaworksCorePluginIOS.SetCallbackHandler("MySampleScene"); 

        //리워드 델리게이트 등록
        AdPopcornOfferwallPluginIOS.onRewardRequestResult += HandleOnRewardRequestResult;
        AdPopcornOfferwallPluginIOS.onRewardCompleteResult += HandleOnRewardCompleteResult;
    }

    void HandleOnRewardRequestResult(string rewardInfo) {
        // rewardInfo : isSuccess=1&message=Success&itemName=1포인트&itemKey=(null)&campaignName=REGISTRATION TYPE CAMPAIGN for TEST&campaignKey=1296784231&rewardKey=RzBVMIkF-15x5Y5qpU4vawj-33gdK3LKoaRx7p15NmjjdgnCc9uKlFSRjZypYzTLlrRe2BHByfM4x0AlP6X2n0vth4EYV-kUZ&quantity=1

        // 유효한 rewardKey 인지 확인합니다.
        AdPopcornOfferwallPluginIOS.DidGiveRewardItemWithRewardKey($rewardKey);
    }

    void HandleOnRewardCompleteResult(string result) {
        // AdPopcornOfferwallPluginIOS.DidGiveRewardItemWithRewardKey 의 처리 결과가 전달됩니다.
        // result : isSuccess=1&message=Success&resultCode=1&completedRewardKey=RzBVMIkF-15x5Y5qpU4vawj-33gdK3LKoaRx7p15NmjjdgnCc9uKlFSRjZypYzTLlrRe2BHByfM4x0AlP6X2n0vth4EYV-kUZ

        // RewardCompleteResult resultCode
        //    1 : Succeed
        //    100 : Error
        //    200 : Unknown Exception
        //    1400 : Invalid Appkey
        //    1410 : Incorrect reward server type
        //    3000 : Invalid Hashkey

        // 본 델리게이트의 수신 결과가 성공일 때에만 유저에게 리워드 지급 처리를 합니다.
        // 한번 지급 처리한 completedRewardKey에 대해서는 다시 리워드를 지급하면 안됩니다.
    }
}


리워드 정보 수동 조회

GetClientPendingRewardItems api를 호출하여 원하는 시점에 리워드정보를 조회할 수 있습니다.

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

AdPopcornOfferwallPluginIOS.GetClientPendingRewardItems();



광고테스트 및 검증 신청


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


테스트 디바이스 등록 

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

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

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



광고 노출 및 리워드 테스트

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

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


검증신청

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

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

[IGAWorks 검수 안내]


광고 라이브 및 정산 절차

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

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