로딩중입니다
애드팝콘 오퍼월 : 유니티 iOS
4/13/2018 1:59:52 PM

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

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

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

[애드팝콘 서비스 안내]


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

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

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




SDK 다운로드 및 설치


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

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


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

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




코드연동


IDFA 설정

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

AdSupport Framework를 Dependencies에 반드시 추가해 주세요. 


앱키 & 해시키 설정

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

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


리워드서버 연동방식 추가

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

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

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


로그 레벨 설정

setLogLevel  api를 사용하여 SDK에서 노출하는 로그의 수준을 설정할 수 있습니다.

       setLogLevel  API를 이용하여 설정하며 수준을 결정하는 값은 AdPopcornOfferwalPluginIOS 에 정의된 enum을  사용하며

각 수준은 다음과 같습니다.

            

AdPopcornOfferwallPluginIOS.AdPopcornOfferwallLogInfo  : info 수준의 가장 기본적인 로그 만을 노출합니다. 

      AdPopcornOfferwallPluginIOS.AdPopcornOfferwallLogDebug  : info를 포함한 Debug 수준의 로그를 노출합니다.

      AdPopcornOfferwallPluginIOS.AdPopcornOfferwallLogTrace  : 모든 로그를 노출합니다.

AdPopcornOfferwallPluginIOS.SetLogLevel(AdPopcornOF);


유저식별값 입력

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


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


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

AdPopcornOfferwallPluginIOS.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);
	}
    }
}


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

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

GetEarnableTotalRewardInfo api를 이용하여 조회합니다.

public class MySampleScene : MonoBehaviour {

    void GetEarnableRewardInfo() { 

        AdPopcornOfferwallPluginIOS.SetCallbackHandler("MySampleScene");
        AdPopcornOfferwallPluginIOS.offerwallTotalRewardInfo += HandleOfferwallTotalRewardInfo; AdPopcornOfferwallPluginIOS.GetEarnableTotalRewardInfo(true); } void HandleOfferwallTotalRewardInfo(bool queryResult, int totalCount, string totalReward) { // queryResult : 조회 결과 // totalCount : 적립 가능한 캠페인 수 // totalReward : 적립 가능한 리워드 } }

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


오퍼월 액션 이벤트 

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

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

public class MySampleScene : MonoBehaviour {

    void setAdpopcornOfferwallEventDelegate(){
	
	AdPopcornOfferwallPluginIOS.SetCallbackHandler("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 : 클라이언트 리워드 연동

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


리워드서버 연동방식 설정

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

AdPopcornOfferwallPluginIOS.SetUseIgaworksRewardServer(true);


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

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


델리게이트 상세 설명

1. onRewardRequestResult

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

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

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


2. onRewardCompleteResult

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

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

public class MySampleScene : MonoBehaviour {
    
    void SetAdPopcornRewardDelegate() {

        //델리게이트 리스너 등록 
        AdPopcornOfferwallPluginIOS.SetCallbackHandler("MySampleScene"); 
//리워드 델리게이트 등록 AdPopcornOfferwallPluginIOS.onRewardRequestResult += HandleOnRewardRequestResult; AdPopcornOfferwallPluginIOS.onRewardCompleteResult += HandleOnRewardCompleteResult; } void HandleOnRewardRequestResult(string campaignKey, string campaignName, long quantity, string rewardKey) { // 유효한 rewardKey 인지 확인합니다. AdPopcornOfferwallPluginIOS.DidGiveRewardItemWithRewardKey(rewardKey); } void HandleOnRewardCompleteResult(bool isSuccess, string message, int resultCode, string) { // AdPopcornOfferwallPluginIOS.DidGiveRewardItemWithRewardKey의 처리 결과가 전달됩니다. // 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 검수 안내]


광고 라이브 및 정산 절차

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

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

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