로딩중입니다
애드팝콘 오퍼월 : iOS
4/21/2017 2:03:22 PM

애드팝콘 오퍼월 연동하기 : iOS 네이티브


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

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

[애드팝콘 서비스 안내]


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

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

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



SDK 설치


IGAWorks iOS SDK는 CocoaPods 를 이용한 자동설치를 지원합니다.

CocoaPods 를 이용하여 보다 편리하게 SDK를 설치할 수 있습니다.


CocoaPods 설치 및 초기화

CocoaPods가 설치되어 있지 않다면 Mac OSX 의 터미널을 실행하여 CocoaPods를 설치합니다.

$ sudo gem install cocoapods


설치가 완료되면 다음과 같은 터미널 화면을 확인할 수 있습니다.


설치가 완료된 후에 CocoaPods를 초기화 합니다.

$ pod setup


초기화 이후에 다음과 같은 화면이 보이신 다면, cocoapods 설치가 완료된 것입니다.


Podfile 생성 및 편집

CocoaPods 를 적용할 Xcode 프로젝트 파일이 있는 폴더로 이동하여 Podfile를 생성합니다.

$ cd /path/to/MyXcodeProject
$ touch Podfile


터미널에서 vi 에디터를 실행하여 Podfile 의 내용을 다음과 같이 수정한 뒤에 ESC, Shift+Z(2번)를 연속으로 눌러 종료합니다.

platform :ios, '8.0'
target "myProjectName" do
pod 'IgaworksCore'
pod 'AdPopcornOfferwall'
end

CAUTION!!!  platform 의 값 중, '8.0' 의 값은 Xcode 프로젝트에서 지원하는 최소 iOS OS 버전을 의미합니다.


설치 

다음 명령어를 입력하여 SDK를 설치합니다.

$ pod install


설치 확인

다음의 명령어를 실행하여 프로젝트에 설치된 SDK를 확인할 수 있습니다.

$ open MyXCodeProject.wcworkspace



SDK 수동 설치

개발환경에 따라서 Cocoapods를 통한 설치가 어려운 경우, SDK를 프로젝트에 수동으로 설치할 수 있습니다.

수동 설치를 하기 위해서는 [APPENDIX : SDK 수동 설치] 를 참고하여 진행합니다.



코드연동


IDFA 설정

setAppleAdvertisingIdentifier api를 호출하여 SDK에 IDFA 값을 등록합니다.

#import "AppDelegate.h"
#import <AdSupport/AdSupport.h>

@implementation AppDelegate

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

CAUTION!!!  위 api는 AppDelegate의 application: didFinishLaunchingWithOptions : 에서 호출합니다.

CAUTION!!!  위 api를 호출하기 위해서는 AdSupport.framework 가 Dependencies에 추가되어 있어야 합니다.


앱키 & 해시키 설정

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

#import "AppDelegate.h"
#import <AdSupport/AdSupport.h>
#import <IgaworksCore/IgaworksCore.h>

@implementation AppDelegate

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

    // Igaworks appkey, hashkey setting
    [IgaworksCore igaworksCoreWithAppKey:@"YOUR_APP_KEY" andHashKey:@"YOUR_HASH_KEY"];

    return YES;
}

CAUTION!!!  위 api를 호출하기 전에 반드시 IDFA 값이 설정되어야 합니다.


로그 수준 설정

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

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

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


리워드서버 연동방식 추가

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

[IgaworksCore shared].useIgaworksRewardServer = NO;

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


유저식별값 입력

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


주의 사항

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

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

[IgaworksCore setUserId:@"bXlBY2NvdW50X25hbWU="];


오퍼월 광고 노출

openOfferwallWithViewController: delegate: userDataDicionaryForFilter: api를 호출하여 오퍼월을 노출합니다.

#import <IgaworksCore/IgaworksCore.h>
#import <AdPopcornOfferwall/AdPopcornOfferwall.h>
 
-(void)didClickOpenOfferwallBtn 
{
    [AdPopcornOfferwall openOfferWallWithViewController:self delegate:self userDataDictionaryForFilter:nil];
    [AdPopcornOfferwall shared].delegate = self;
}

/* ADPOPCORN OFFERWAL DELEGATES START */
-(void)willOpenOfferWall {
    //Offerwall will be opened
}
-(void)didOpenOfferWall {
    //Offerwall did opened
}
-(void)willCloseOfferWall {
    //Offerwall will bel closed
}
-(void)didCloseOfferWall {
    //Offerwall did closed
}
/* ADPOPCORN OFFERWAL DELEGATES END */


비디오 광고 로드 및 노출

애드팝콘에서 제공하는 비디오 광고를 이용하기 위해서는 광고 정보를 로드해야 합니다.

loadVideoAd api를 이용하여 라이브 중인 비디오 광고 정보를 로드합니다.

-(void)loadAdPopcornVideoAd {
    [AdPopcornOfferwall loadVideoAd:self];
}

/* LOAD VIDEO AD DELEGATES START */
-(void)loadVideoAdSuccess {
    //VideoAd Loading Succeeded
}

-(void)loadVideoAdFailedWithError:(APError*)error {
    //VideoAd Loading Failed
    //APError errorCode
    //    EXCEPTION = 200
    //    ABUSING = 500
    //    CAN_NOT_FIND_AVAILABLE_CAMPAIGN = 1000;
    //    INVALID_APP_KEY = 1400;
    //    UNKNOWN_EXCEPTION = 9999;    
}
/* LOAD VIDEO AD DELEGATES END */


showVideoAd api를 이용하요 로드된 비디오 광고 정보를 노출합니다.

-(void)showAdPopcornVideoAd{
    [AdPopcornOfferwall showVideoAdWithViewController:self delegate:self];
}

/* SHOW VIDEO AD DELEGATES START */
- (void)willOpenVideoAd{
   //Video Ad will be opened
}

- (void)didOpenVideoAd{
   //Video Ad did opened
}

- (void)willCloseVideoAd{
   //Video Ad will be closed
}	

- (void)didCloseVideoAd{
   //Video Ad did closed
}

- (void)showVideoAdFailedWithError:(APError *)error{
   //Video Ad Showing Failed
   //APError errorCode
   //   TERMINATED_OR_INVALID_CAMPAIGN = 980;
   //   TERMINATED_OR_INVALID_CAMPAIGN = 999;
   //   ALREADY_COMPLETED_CAMPAIGN = 2000;
}
/* SHOW VIDEO AD DELEGATES END */


기타설정


오퍼월 스타일 설정

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

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

#import <AdPopcornOfferwall/AdPopcornStyle.h>

- (void)changeOfferwallTheme {
	
// 오퍼월 테마 색상 변경
[AdPopcornStyle sharedInstance].adPopcornCustomThemeColor = [UIColor blueColor];

// 오퍼월 로고 변경
[AdPopcornStyle sharedInstance].adPopcornCustomOfferwallTitleLogoPath = 
@”AdPopcornOfferwall.bundle/Contents/Resources/images/test.png”;

// 오퍼월 타이틀 변경
[AdPopcornStyle sharedInstance].adPopcornCustomOfferwallTitle = @”Test Offerwall”;

// 오퍼월 타이틀 색상 변경
[AdPopcornStyle sharedInstance].adPopcornCustomOfferwallTitleColor = [UIColor redColor];

// 오퍼월 Top/bottom bar 색상 변경 
[AdPopcornStyle sharedInstance].adPopcornCustomOfferwallTitleBackgroundColor = [UIColor whiteColor];



IGAW 리워드 서버 연동


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

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


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

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


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


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


리워드서버 연동방식 설정

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

[IgaworksCore shared].useIgaworksRewardServer = YES;


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

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


리스너 상세 설명

1. onRewardRequestResult: withMessage: items:

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

리워드 정보는 RewardInfo.h 에 정의된 모델 형식의 (NSArray *)items 파라미터로 전달되며 NSArray에 포함된 정보는 다음과 같습니다.


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

IGAW 리워드 서버에 해당 사실을 전달하기 위해 AdPopcornOfferwall.h 의 didGiveRewardItemWithRewardKey API를 호출합니다.


2. onRewardCompleteResult:withMessage: resultCode: withCompletedRewardKey:

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

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

#import <IgaworksCore/IgaworksCore.h>
#import <AdPopcornOfferwall/AdPopcornOfferwall.h>
#import <AdPopcornOfferwall/RewardInfo.h>
 
@interface ViewController() <AdPopcornOfferwallClientRewardDelgate>
@end
 
@implementation ViewController

-(void)viewDidLoad { 
    [super viewDidLoad];
    [AdPopcornOfferwall shared].clienRewardDelegate = self;
}

-(void)onRewardRequestResult:(BOOL)isSuccess withMessage:(NSString *)message items:(NSArray *)items{
    
    for (RewardInfo *item in items) {
	    
        NSString *campaignKey = item.campaignKey;
        NSString *campaignName = item.campaignName;
        NSString *rewardKey = item.RTID;
        NSUInteger quantity = item.quantity;
        		
	//유효한 RewardKey 인지 확인합니다.
	[AdPopcornOfferwall didGiveRewardItemWithRewardKey:item.RTID];
    }
}

- (void)onRewardCompleteResult:(BOOL)isSuccess withMessage:(NSString *)message resultCode:(NSUInteger)resultCode withCompletedRewardKey:(NSString *)completedRewardKey {
  // RewardCompleteResult resultCode
  //    1 : Succeed
  //    100 : Error
  //    200 : Unknown Exception
  //    1400 : Invalid Appkey
  //    1410 : Incorrect reward server type
  //    3000 : Invalid Hashkey

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

@end 


리워드 정보 수동 조회

리워드 델리게이트는 오퍼월이 시작되거나 종료될 때 호출되며 IGAW 리워드서버에 처리되지 않은 리워드 정보가 있을 때, 정보가 전달됩니다.

위 시점 외에 리워드 정보를 조회하고자 할 경우에는 getClientPendingRewardItems api를 호출하여 원하는 시점에 리워드정보를 조회할 수 있습니다.

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

[AdPopcornOfferwall getClientPendingRewardItems];



APPENDIX : SDK 수동설치

CocoaPods 가 아닌 수동으로 직접 SDK를 설치하는 방법입니다.


SDK 다운로드 및 설치

[SDK 다운로드 센터]에서 최신 IOS 네이티브 SDK 패키지를 다운로드 합니다.

다운로드 받은 .zip 파일을 압축해제하여 IgaworksCore, AdPopcornOfferwall 프레임워크를 Xcode 프로젝트에 복사하여 추가합니다.


번들 리소스 추가

애드팝콘 오퍼월의 UI를 표현하기 위해 번들 리소스를 추가합니다.

AdpopcornOfferwall.framework > Version > A > Resources 폴더의 Bundle 파일을 Xcode 프로젝트에 복사하여 추가합니다.


Dependencies 추가

애드팝콘 오퍼월 SDK에 필요한 필수 프레임워크를 추가합니다.


프레임워크 목록
  1. AdSupport
  2. AVFoundation
  3. AVKit
  4. CoreGraphics
  5. CoreMedia
  6. CoreTelephony
  7. CoreText
  8. iAd
  9. ImageIO
  10. libxml2.dylib
  11. MediaPlayer
  12. MessageUI
  13. SafariServices
  14. Security
  15. SystemConfiguration
  16. UIKit



빌드 옵션 설정

Build Settings Pane > Linking > Other Linker Flags 섹션에 -all_load 혹은 -force_load 옵션을 추가합니다.

-force_load 옵션을 사용할 때에는 추가한 SDK 프레임워크의 경로를 명시하여야 합니다.




광고테스트 및 검증신청


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


테스트 디바이스 등록 

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

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

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


광고 노출 및 리워드 테스트

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

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


검증신청

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

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

[IGAWorks 검수 안내]


광고 라이브 및 정산 절차

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

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