목차
GDPR: 권장 구현
5월 25일부터 GDPR(General Data Protection Regulation, 일반데이터보호규정)이 유럽 연합에서 시행됩니다. 개발자에게는 GDPR 준수를 위한 2가지 옵션이 있습니다.
-
옵션 1(권장): 퍼블리셔는 사용자 수준에서 GDPR 동의 과정을 제어한 후 Vungle에 사용자의 선택을 전달합니다. 이를 위해 개발자는 자체 메커니즘을 사용하여 사용자의 동의를 수집한 다음 Vungle API를 사용하여 사용자의 동의 상태를 업데이트하거나 쿼리할 수있습니다. 자세한 내용은 GDPR 권장 구현 지침 섹션을 참조하십시오.
- 옵션 2: Vungle이 요구사항을 처리하도록 허용합니다. Vungle은 유럽 사용자를 위해 광고를 재생하기 전에 동의 대화 상자를 표시하고 이후 광고에 대한 해당 사용자의 동의 여부를 기억합니다.
시작하기 전에
- Vungle iOS SDK v.6은 iOS 8 이상을 지원합니다.
- Vungle iOS SDK v.6은 iOS 11 베타/GM Seed로 테스트되었습니다.
- Vungle iOS SDK v.6은 32비트와 64비트 앱을 모두 지원합니다.
- 통합을 하려면 Vungle 계정이 있어야 합니다. 아직 계정이 없는 경우, 계정을 생성한 후에 계속 진행합니다.
- iOS SDK는 Xcode 9.0 이상을 지원합니다.
1단계. Vungle 프레임워크를 Xcode 프로젝트에 추가
프로젝트에 VungleSDK.framework 추가
Cocoapod 사용 또는 수동 통합으로 Vungle을 Xcode 프로젝트에 추가할 수 있습니다.
Cocoapod
Cocoapod를 통해 Vungle SDK를 사용할 수 있습니다. 프로젝트의 podfile에 다음 줄을 추가하여 Vungle을 프로젝트에 추가합니다.
pod "VungleSDK-iOS", "6.2.0"
그런 다음 빠른 포드 설치 실행을 통해 프로젝트를 최신 버전의 iOS SDK로 업데이트합니다. 이제 "2단계. iOS 상태 막대 제거"로 이동할 수 있습니다.
수동 통합
Vungle SDK v6을 다운로드합니다. Vungle SDK를 이전 버전에서 업데이트하는 경우 새 SDK를 추가하기 전에 먼저 VungleSDK.framework 디렉토리를 완전히 제거하십시오.
압축을 푼 파일을 찾은 다음 VungleSDK.framework
를 프레임워크의 Xcode로 끌어다 놓습니다. VungleSDK.framework
폴더를 그룹(노란색 폴더)으로 추가해야 하며 참조(파란색 폴더)로서 추가하면 안 됩니다.
기타 필요한 프레임워크 추가
Vungle SDK에서는 프로젝트와 연결될 몇 가지 다른 네이티브 프레임워크가 필요합니다. 그러므로 프로젝트 탐색기에서 프로젝트를 클릭하고 General → Linked Frameworks and Libraries로 이동합니다.
다수의 이러한 프레임워크가 대부분의 Xcode 프로젝트에서 기본 설정으로 이미 포함되어 있습니다. 포함되어 있지 않은 다음의 프레임워크는 반드시 추가해야 합니다.
AdSupport.framework
AudioToolbox.framework
AVFoundation.framework
CFNetwork.framework
CoreGraphics.framework
CoreMedia.framework
-
libz.dylib
또는libz.tbd
-
MediaPlayer.framework
QuartzCore.framework
StoreKit.framework
SystemConfiguration.framework
참고: Vungle SDK V.6은 iOS 7을 지원하지 않습니다. 배포 대상에 iOS 7이 있다면 Vungle iOS SDK v.4.1 이하 버전을 사용하고 다음 프레임워크를 포함하십시오.
UIKit.framework
WebKit.framework
Foundation.framework
VungleSDK 프레임워크가 연결된 프레임워크 및 라이브러리에 표시되는지 확인합니다.
“-ObjC” 링커 플래그 추가
프로젝트 탐색기에서 프로젝트를 클릭하고 Build Settings → Linking → Other Linker Flags로 이동합니다. 기타 링커 플래그에 -ObjC를 추가합니다.
2단계. iOS 상태 막대 제거
필수 단계는 아니지만, iOS 상태 막대를 삭제하면 Vungle의 광고 상호작용 및 표시가 원활하게 작동하므로 권장되는 단계입니다. 상태 막대를 제거하려면 Info.plist
를 열고 컨트롤러 기반 상태 표시줄 보기 키를 추가한 후 이를 아니요로 설정합니다.
3단계. 코드 추가
SDK 초기화
자동 캐시된 플레이스먼트를 사용하는 경우 앱이 시작되자마자 SDK를 초기화하면 SDK가 자동 캐시된 플레이스먼트에 광고를 캐시할 수 있는 충분한 시간이 주어집니다. SDK를 초기화하려면 앱 ID가 필요합니다. Vungle 대시보드에서 앱 ID를 찾을 수 있습니다.
- (BOOL)startWithAppId:(nonnull NSString *)appID error:(NSError **)error;
샘플 코드:
#import <VungleSDK/VungleSDK.h>
...
NSError* error;
NSString* appID = @"Your_AppID_Here"; VungleSDK* sdk = [VungleSDK sharedSDK]; [sdk startWithAppId:appID error:&error];
SDK가 성공적으로 초기화되면 다음과 같은 콜백 메서드가 호출됩니다.
- (void)vungleSDKDidInitialize;
이 설명서의 "델리게이트 콜백" 섹션을 참조합니다.
다음 속성을 사용하여 SDK 초기화의 상태를 확인할 수도 있습니다.
@property (atomic, readonly, getter=isInitialized) BOOL initialized;
SDK를 초기화된 후 Vungle 대시보드에서 자동 캐시로 플레이스먼트를 선택한 경우, SDK는 자동으로 해당 플레이스먼트에 광고를 캐시합니다. 이 기능을 사용하는 경우 조회 수가 가장 높은 플레이스먼트를 자동 캐시로 설정하는 것이 좋습니다.
광고가 성공적으로 캐시되면 자동 캐시된 플레이스먼트와 일치하는 플레이스먼트 참조 ID로 vungleAdPlayabilityUpdate
콜백 메서드가 호출됩니다. (이 설명서에서 "플레이스먼트의 광고 가용성 확인" 섹션을 참조하십시오.)
플레이스먼트에 광고 로드
자동 캐시된 플레이스먼트 외의 다른 플레이스먼트에는 loadPlacementWithID
메서드를 호출하여 광고를 로드합니다.
- (BOOL)loadPlacementWithID:(NSString *)placementID error:(NSError **)error;
샘플 코드:
NSError* error;
VungleSDK* sdk = [VungleSDK sharedSDK]; [sdk loadPlacementWithID:"<Your_PlacementID>" error:&error];
(이 설명서에서 "플레이스먼트의 광고 가용성 확인" 섹션을 참조합니다.)
플레이스먼트의 광고 가용성 확인
SDK가 플레이스먼트에 광고를 캐시하고 나면 다음과 같은 콜백 메서드가 호출됩니다.
- (void)vungleAdPlayabilityUpdate:(BOOL)isAdPlayable placementID:(nullable NSString *)placementID error:(nullable NSError *)error;
샘플 코드:
- (void)vungleAdPlayabilityUpdate:(BOOL)isAdPlayable placementID:(NSString *)placementID error:(nullable NSError *)error {
if([placementID isEqualToString:@"<Your_PlacementID>"]) {
self.playButtonPlacement1.enabled = isAdPlayable;
}
}
참고: 자동 캐시된 플레이스먼트의 경우, 광고를 사용할 수 있을 때만 이 콜백 메서드가 호출됩니다. SDK는 자동 캐시된 플레이스먼트에 대한 광고를 계속 요청합니다. 다른 플레이스먼트에서는 "로드 실패"(isAdPlayable
가 '아니요'를 반환)의 경우 이 콜백 메서드가 호출됩니다.
다음 속성을 사용하여 플레이스먼트의 광고 가용성을 확인할 수도 있습니다.
- (BOOL)isAdCachedForPlacementID:(nonnull NSString *)placementID;
광고 재생
플레이스먼트에 대한 광고가 준비되면 다음과 같은 방법으로 광고를 재생할 수 있습니다.
- (BOOL)playAd:(UIViewController *)controller options:(nullable NSDictionary *)options placementID:(nullable NSString *)placementID error:( NSError *__autoreleasing _Nullable *_Nullable)error;
샘플 코드:
VungleSDK* sdk = [VungleSDK sharedSDK]; NSError *error; [self.sdk playAd:self options:nil placementID:@"<Your_PlacementID_1>" error:&error]; if (error) { NSLog(@"Error encountered playing ad: %@", error); }
Flex Feed 광고
Vungle SDK v.5.3부터 Flex Feed 광고를 지원합니다. 이는 전체 화면이 필요 없는 최초의 광고 형식입니다. 대신, 퍼블리셔가 앱 내 광고 컨테이너의 정확한 크기와 위치를 결정합니다. 이러한 광고 컨테이너는 컬렉션 뷰 또는 테이블 뷰에 위치할 수 있습니다.
Flex Feed 광고 로드하기
Flex Feed 광고 로드 방법은 전체 화면 광고 로드와 동일하지만, 플레이스먼트가 Flex Feed를 지원하도록 구성해야 합니다. 플레이스먼트에 Flex Feed를 사용하도록 설정하려면 Vungle 계정 관리자에게 문의하십시오.
Flex Feed 광고 표시하기
Flex Feed 광고를 표시하는 방법은 전체 화면 광고 표시 방법과 다릅니다. Flex Feed 광고에서는 광고 컨테이너를 먼저 생성해야 합니다. 이 컨테이너는 UIView
입니다. 해당 UIView
는 화면 어느 곳에나 배치할 수 있습니다. 광고가 컨테이너의 크기에 맞게 늘어나지만 해상도가 너무 낮으면 광고의 가시성이 저하되니 참고하시기 바랍니다. 그런 다음 함수를 호출하여 addAdViewToView
Flex Feed 광고와 컨테이너를 연결해야 합니다.
함수 개요:
/** * Pass in an UIView which acts as a container for the ad experience. This view container may be placed in random positions. * @param publisherView container view in which an ad will be displayed * @param options A reference to an instance of NSDictionary with customized ad playback options * @param placementID The placement defined on the Vungle dashboard * @param error An optional double reference to an NSError. In case this method returns `NO` it will be non-nil * @return YES/NO in case of success/error while presenting an AdUnit */ - (BOOL)addAdViewToView:(UIView *)publisherView withOptions:(nullable NSDictionary *)options placementID:(nullable NSString *)placementID error:( NSError *__autoreleasing _Nullable *_Nullable)error;
샘플 코드:
NSError *error; NSDictionary *options = @{}; VungleSDK* sdk = [VungleSDK sharedSDK]; [sdk addAdViewToView:_FlexFeedViewArea withOptions:options placementID: error:&error]; if (error) { NSLog(@"Error encountered while playing an ad: %@", error); }
Flex Feed 광고 닫기
Flex Feed 광고의 특성으로 인해 사용자는 광고를 닫지 않고 동영상 보기를 중단할 수 있습니다. 그러므로 광고가 화면에 더 이상 표시되지 않는 경우 SDK에 광고를 해제하도록 지시해야 합니다. 이렇게 하려면 finishedDisplayingAd
함수를 호출하십시오. 이 함수는 Flex Feed 및 Flex View 광고에서만 작동합니다. 이 함수는 플레이스먼트에서 작동하지 않으며, 현재 재생 중인 네이티브 광고를 닫기만 합니다.
함수 개요:
/** * This method must be called when the publisher is confident that they are finished displaying the ad unit. * This signals to the SDK that a new ad may be fetched or a different ad may be displayed. This will * be called in conjunction with `addViewToView:containedInViewController:withOptions:placementID:error:` */ - (void)finishedDisplayingAd;
샘플 코드:
//Ad is no longer on screen VungleSDK* sdk = [VungleSDK sharedSDK]; [sdk finishedDisplayingAd];
델리게이트 콜백
VungleSDKDelegate
를 통해 SDK에서 콜백을 받을 수 있습니다. SDK 이벤트에 대한 알림을 받는 델리게이트에는 네 가지 콜백 메서드가 있습니다.
다음을 사용하여 델리게이트를 첨부 및 분리할 수 있습니다.
// Attach [[VungleSDK sharedSDK] setDelegate:yourDelegateInstance]; // Detach [[VungleSDK sharedSDK] setDelegate:nil];
참고: 메모리 누수를 피하려면, 등록된 델리게이트 중 사용하지 않는 것은 적절히 분리하는 것이 중요합니다.
SDK가 동영상 광고를 재생하려고 할 때 다음 메서드가 호출됩니다. 게임 재생, 음향 효과, 애니메이션 등을 일시 중지하기에 좋은 메서드입니다.
- (void)vungleWillShowAdForPlacementID:(nullable NSString *)placementID;
SDK가 광고를 닫으려고 할 때 다음 메서드가 호출됩니다. 사용자에게 보상을 제공하고 게임 재생, 음향 효과, 애니메이션 등을 재개할 때 사용하는 메서드입니다.
- (void)vungleWillCloseAdWithViewInfo:(VungleViewInfo *)info placementID:(NSString *)placementID;
SDK가 광고를 닫을 때 다음 메서드가 호출됩니다.
- (void)vungleDidCloseAdWithViewInfo:(VungleViewInfo *)info placementID:(NSString *)placementID;
VungleViewInfo
에는 광고 재생 결과의 확인을 위한 다음 속성이 포함됩니다.
@interface VungleViewInfo : NSObject //Represents a BOOL whether or not the video can be considered a completed view. @property (nonatomic, readonly) NSNumber *completedView; //The time in seconds that the user watched the video. @property (nonatomic, readonly) NSNumber *playTime; //Represents a BOOL whether or not the user clicked the download button. @property (nonatomic, readonly) NSNumber *didDownload; @end
SDK가 광고 가용성 상태를 변경하면 다음 메서드가 호출됩니다. isAdPlayable 부울은 특정 placementID의 새로운 재생 가능성을 보여줍니다.
- (void)vungleAdPlayabilityUpdate:(BOOL)isAdPlayable placementID:(nullable NSString *)placementID error:(nullable NSError *)error;
(이 설명서에서 "플레이스먼트의 광고 가용성 확인" 섹션을 참조합니다.)
SDK가 성공적으로 초기화되면 다음과 같은 콜백 메서드가 호출됩니다.
- (void)vungleSDKDidInitialize;
사용자 지정 옵션
이 옵션을 사용하여 재생을 위한 광고 환경을 사용자 정의할 수 있습니다.
참고: 경우에 따라 보상형 광고가 인센티브화 광고로 불리기도 합니다. 두 용어는 항상 같은 종류의 광고를 나타냅니다. SDK 코드와 리포팅 API에서는 '인센티브화'라는 용어를 사용합니다.
옵션 키 |
기본 값/유형 |
설명 |
|
autorotate
비트 마스크로 방향을 나타내는 NSNumber |
광고의 방향을 설정합니다. 앱이 세로 방향인 경우에도 광고를 자동으로 회전하도록 설정할 것을 권장합니다. 이런 방식으로 사용자가 최대 크기의 동영상을 보게끔 선택하여 더 나은 사용자 경험을 누릴 수 있습니다. 방향 전환을 프로젝트 레벨이 아닌 보기 제어 수준에서 설정하여 더 나은 사용자 경험을 구현할 수 있습니다. |
|
nil
|
사용자의 ID를 설정합니다. 이 값은 Vungle 서버로 전달된 다음, 플레이스먼트가 "보상형"으로 설정된 경우 서버 간 콜백 시스템을 통해 서버로 전송됩니다. |
|
nil
|
사용자가 보상형 광고를 시청 도중에 닫을 때 표시되는 경고 대화 상자의 제목으로 사용되는 문자열입니다. |
|
"정말 이 광고를 건너뛰시겠습니까? 이 광고를 건너뛰면 보상을 받지 못할 수 있습니다.
|
사용자가 보상형 광고를 시청 도중에 닫을 때 표시되는 경고 대화 상자의 본문 텍스트로 사용되는 문자열입니다. |
|
"닫기"
|
사용자가 보상형 광고를 시청 도중에 닫을 때 표시되는 경고 대화 상자의 닫기 버튼에 사용되는 문자열 제목입니다. |
|
"계속"
|
사용자가 보상형 광고를 시청 도중에 닫을 때 표시되는 경고 대화 상자의 닫기 버튼에 사용되는 문자열 제목입니다. |
VunglePlayAdOptionKeyFlexViewAutoDismissSeconds |
|
지정된 시간(초)이 지난 후 Flex View 광고가 자동적으로 해제되게 하려면 이 옵션을 사용하십시오. |
VunglePlayAdOptionKeyOrdinal |
|
Vungle에서 서수 데이터 보고를 받는 경우 이 필드를 이용하여 미디에이션 서수를 내보내십시오. 게임 세션에서 해당 광고의 표시 순서를 나타내는 정수 값입니다(예를 들어, 이번 세션에서 이미 두 개의 광고가 표시되고 Vungle의 광고가 세 번째로 보여지는 경우, '3'을 내보냅니다). 서수 데이터에 대한 자세한 내용은 여기를 참조하십시오. |
NSDictionary *options = @{VunglePlayAdOptionKeyOrientations: @(UIInterfaceOrientationMaskLandscape), VunglePlayAdOptionKeyUser: @"userGameID", VunglePlayAdOptionKeyIncentivizedAlertBodyText : @"If the video isn't completed you won't get your reward! Are you sure you want to close early?", VunglePlayAdOptionKeyIncentivizedAlertCloseButtonText : @"Close", VunglePlayAdOptionKeyIncentivizedAlertContinueButtonText : @"Keep Watching", VunglePlayAdOptionKeyIncentivizedAlertTitleText : @"Careful!"}; // Pass in dict of options, play ad NSError *error; [self.sdk playAd:self options:options placementID: error:&error]; if (error) { NSLog(@"Error encountered playing ad: %@", error); }
음소거 옵션
Vungle SDK 인스턴스는 소리가 비활성화된 상태에서 광고를 재생할 수 있는 옵션을 제공합니다. playAd()
를 발급하기 전에 음소거된 속성을 true로 설정할 수 있습니다.
샘플 코드:
VungleSDK* sdk = [VungleSDK sharedSDK]; self.sdk.muted = true;
참고: 이 옵션은 표준 광고 유형에만 적용됩니다. 다이나믹 템플릿 광고에서는 대시보드에서 음소거 옵션을 구성할 수 있습니다.
GDPR 권장 구현 지침
Vungle API를 사용하여 업데이트하거나 사용자 동의 상태를 쿼리하려면(GDPR: 권장 구현의 옵션 1 참조) 다음 함수를 사용하십시오.
// This function sets the consent status that will be recorded in Vungle SDK. Accepted values: 'VungleConsentAccepted' or 'VungleConsentDenied'.
// To set the user's consent status to opted in:
[[VungleSDK sharedSDK] updateConsentStatus:VungleConsentAccepted];
// To set the user's consent status to opted out:
[[VungleSDK sharedSDK] updateConsentStatus:VungleConsentDenied];
// To find out what the user's current consent status is:
// (Check against enum values: 'VungleConsentAccepted' or 'VungleConsentDenied'.) [[VungleSDK sharedSDK] getCurrentConsentStatus];
VungleConsentStatus
는 다음과 같은 두 가지 상태를 포함하는 열거형입니다.
VungleConsentAccepted
VungleConsentDenied
또한 SDK에는 초기 상태가 'unknown'(알 수 없음)으로 표시되어 사용자 데이터 수집을 선택 또는 선택 해제하라는 메시지가 표시됩니다. 이 메시지는 유럽에서 발생하는 IP 주소에서만 표시됩니다.
디버그
SDK 정보가 필요하면 다음 속성을 사용하여 가져올 수 있습니다.
- (NSDictionary *)debugInfo;
SDK에서 로그를 출력하려면 다음 방법을 사용합니다.
- (void)setLoggingEnabled:(BOOL)enable;
VungleSDKLogger 프로토콜
@protocol VungleSDKLogger - (void)vungleSDKLog:(NSString*)message; @end
VungleSDK 싱글톤은 VungleSDKLogger 프로토콜에 따라 로깅 이벤트를 첨부된 클래스에 전송합니다. 로그 이벤트에는 콘솔로도 인쇄되는 NSString 값이 포함됩니다(로깅이 켜져 있는 경우). 로거를 첨부하려면, 다음을 사용합니다.
[sdk attachLogger:yourLoggerInstance];
위에서 언급한 것처럼 Vungle SDK로부터 첨부된 로거를 제거하는 것이 중요합니다. 다음의 접근 방식을 사용하여 로거를 분리할 수 있습니다.
[sdk detachLogger:yourLoggerInstance];
assetLoader 프로토콜
@protocol VungleAssetLoader /** * 구체화된 경로 또는 닐에 대한 (가공되지 않은) 이미지 데이터를 포함하는 유효한 NSData를 반환해야 합니다. */ - (NSData*)vungleLoadAsset:(NSString*)path; /** * 구체화된 경로 또는 닐에 대한 유효한 UIImage를 반환해야 합니다. */ - (UIImage*)vungleLoadImage:(NSString*)path; @end