BuzzAd-Benefit iOS SDK 연동 가이드

Created by Jamie Koo (Unlicensed)
Last updated: May 10, 2022 by Olivia Kim

본 연동 가이드는 BuzzAd-Benefit SDK를 iOS Application 내에 삽입함으로써 퍼블리셔가 원하는 지면에 리워드가 지급되는 광고를 띄우기 위함입니다. 네이티브 광고와 동영상 광고를 지원하며, 커스텀 UI 요소를 통해 광고가 퍼블리셔 앱에 자연스럽게 녹아들게 하면서 동시에 매출을 극대화할 수 있습니다.


Index

Getting Started

SDK를 앱에 연동하기 전, 아래 사항을 먼저 준비해야 합니다.

  • Buzzvil의 BD 매니저를 통해 전달받은 app_id

  • BD 매니저를 통해 전달받은 unit_id (원하는 Type 에 맞는 unit_id 수령)

  • Buzzvil 서버로부터 포인트 적립 요청을 받을 수 있는 매체사 API 서버

 

Installation

다음 샘플 코드를 통해, 실제 구현에 사용된 예제를 참고할 수 있습니다: github sample code (링크)

1. Cocoapods 사용 (권장)

Podfile에 아래 코드 추가

  • pod 'BuzzAdBenefit', '연동하려는 버전'을 입력해 주세요.

1 pod 'BuzzAdBenefit', '~> 1.3.0'

 

2. Manual Import

cocoa pods 를 사용하지 않을 경우 아래의 방법으로 진행 가능합니다.

step 1) 프로젝트에 framework 추가

[프로젝트 메뉴] -> [General] -> [Embedded Binaries] 섹션에 다음 framework들을 추가합니다.

  • BuzzAdBenefit.framework

  • BuzzAdBenefitNative.framework

  • BuzzAdBenefitInterstitial.framework (Interstitial type을 사용할 경우)

  • BuzzAdBenefitFeed.framework (Feed type을 사용할 경우)

  • AFNetworking.framework

  • SDWebImage.framework

  • libwebp.framework

(AFNetworking.framework, SDWebImage.framework, libwebp.framework는 본 저장소 Dependencies 폴더에서 다운받을 수 있습니다.)

 

step 2) Run script 추가

[프로젝트 메뉴] -> [Build Phases] 탭에서 '+' 버튼을 눌러 New Run Script Phase를 추가하고 아래 스크립트를 붙여 넣습니다. 이 과정은 universal framework로 빌드된 바이너리에서 불필요한 architecture들을 떼어내기 위해 필요합니다.

 

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 APP_PATH="${TARGET_BUILD_DIR}/${WRAPPER_NAME}" find "$APP_PATH" -name '*.framework' -type d | while read -r FRAMEWORK; do FRAMEWORK_EXECUTABLE_NAME=$(defaults read "$FRAMEWORK/Info.plist" CFBundleExecutable) FRAMEWORK_EXECUTABLE_PATH="$FRAMEWORK/$FRAMEWORK_EXECUTABLE_NAME" EXTRACTED_ARCHS=() for ARCH in $ARCHS; do echo "Extracting $ARCH from $FRAMEWORK_EXECUTABLE_NAME" lipo -extract "$ARCH" "$FRAMEWORK_EXECUTABLE_PATH" -o "$FRAMEWORK_EXECUTABLE_PATH-$ARCH" EXTRACTED_ARCHS+=("$FRAMEWORK_EXECUTABLE_PATH-$ARCH") done echo "Merging extracted architectures: ${ARCHS}" lipo -o "$FRAMEWORK_EXECUTABLE_PATH-merged" -create "${EXTRACTED_ARCHS[@]}" rm "${EXTRACTED_ARCHS[@]}" echo "Replacing original executable with thinned version" rm "$FRAMEWORK_EXECUTABLE_PATH" mv "$FRAMEWORK_EXECUTABLE_PATH-merged" "$FRAMEWORK_EXECUTABLE_PATH" done

 

SDK Initialization

Step 1: Initialize BuzzAdBenefit

AppDelegate의 application:didFinishLaunchingWithOptions에 아래 코드를 추가할 것을 권장하나, 최초 광고 요청 전에만 불린다면 자유롭게 코드 위치를 결정할 수 있습니다.

  • YOUR_APP_ID 부분에 위 단계에서 준비한 app_id 삽입


1 2 3 // Objective-C BABConfig *config = [[BABConfig alloc] initWithAppId:YOUR_APP_ID]; [BuzzAdBenefit initializeWithConfig:config];

 

1 2 3 // Swift let config = BABConfig(appId: YOUR_APP_ID) BuzzAdBenefit.initialize(with: config)

 

Step 2: Set UserProfile of the user

유저가 퍼블리셔 앱에 로그인한 시점에 아래와 같이 UserProfile 을 세팅합니다.

※ 주의사항

User ID와 타게팅 정보 (성별, 연령)는 원활한 서비스 운영을 위해 제공해야 할 필수 항목입니다. 해당 값을 입력하는 setUserProfile 함수가 호출되지 않으면 광고가 할당되지 않습니다

  • userId (Required): 매체사 서비스 유저를 unique 하게 구분할 수 있는 식별값

    • 매체사 서비스에서 유니크하다고 판단되는 유저에 대하여, userId 값이 복수 개 연동되거나 변경될 가능성이 있을 경우 사전에 BD 매니저와 논의해야 합니다.

    • 예: 매체사 앱 삭제 후 재설치 시 userId 값이 변경되는 경우

  • gender

    • BABUserGenderMale: 남성

    • BABUserGenderFemale: 여성

  • birthYear: 출생년도


1 2 3 // Objective-C BABUserProfile *userProfile = [[BABUserProfile alloc] initWithUserId:YOUR_SERVICE_USER_ID birthYear:1985 gender:BABUserGenderMale]; [BuzzAdBenefit setUserProfile:userProfile];
1 2 3 // Swift let userProfile = BABUserProfile(userId: YOUR_SERVICE_USER_ID, birthYear: 1985, gender: BABUserGenderMale) BuzzAdBenefit.setUserProfile(userProfile)

 

※ 주의사항

Step 1, 2를 통해 세션키 등록이 완료되면 BABSessionRegisteredNotification notification이 호출됩니다. 세션키는 SDK가 광고를 요청하고 받아오기 위해서 필요한 서버 API Key로서 세션키가 없는 경우 광고 로드가 불가능합니다.

Step 2 와 광고 요청 시점간 간격이 짧은 경우 이 notification을 observe하여 세션키 등록을 확인한 후 광고 요청을 수행할 수 있습니다.

 

1 2 // Objective-C [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(loadBABAd) name:BABSessionRegisteredNotification object:nil];
1 2 // Swift NotificationCenter.default.addObserver(self, selector: #selector(loadBABAd), name: NSNotification.Name.BABSessionRegistered, object: nil)

 

iOS 14 이상에서 사용자에게 App Tracking Transparency 권한 허용 팝업을 노출하려면 setUserProfile의 인자로 shouldShowAppTrackingTransparencyDialog 값을 true로 하여 호출하면 됩니다(SDK 1.3.3 이상). 그리고 앱의 info.plist 파일에 NSUserTrackingUsageDescription 값을 추가하여 권한 허용 팝업에서 사용자에게 보여질 메세지를 넣어줍니다.

해당 팝업은 아직 권한 허용 여부를 선택하지 않은 사용자에 한하여 최초 1회만 노출됩니다.

Step 3: Set UserPreference of the user

유저가 퍼블리셔 앱에 로그인한 시점에 UserPreference를 빌드하여 BuzzAdBenefit SDK에 해당 값을 세팅합니다.

  • autoplayType: 동영상 광고에 대한 자동재생 옵션을 설정합니다. AutoplayType 의 설정값은 아래와 같습니다.

    • BABVideoAutoPlayEnabled: 동영상 광고가 Wifi, LTE 환경 모두에서 항상 자동재생됨

    • BABVideoAutoPlayOnWifi: 동영상 광고가 Wifi 네트워크 환경에서만 자동재생됨 (Default)

    • BABVideoAutoPlayDisabled: 동영상 광고가 자동재생되지 않음


1 2 3 // Objective-C BABUserPreference *userPreference = [[BABUserPreference alloc] initWithAutoPlayType:BABVideoAutoPlayEnabled]; [BuzzAdBenefit setUserPreference:userPreference];

 

1 2 3 // Swift let userPreference = BABUserPreference(autoPlayType: BABVideoAutoPlayEnabled) BuzzAdBenefit.setUserPreference(userPreference)

 

Step 4. Delete user setting

유저가 퍼블리셔 앱에서 로그아웃하는 시점에 UserProfile 및 UserPreferences 설정값을 지워 유저의 사용 정보를 삭제합니다.


1 2 3 // Objective-C [BuzzAdBenefit setUserProfile:nil]; [BuzzAdBenefit setUserPreference:nil];

 

1 2 3 // Swift BuzzAdBenefit.setUserProfile(nil) BuzzAdBenefit.setUserPreference(nil)

 

Step 5. Proceed to the next step

BuzzAd Benefit 광고를 노출시킬 공간에 적합한 연동 타입을 선택하여 나머지 연동을 진행합니다.

  • Type A - Native Ads : 인앱 디자인과 자연스럽게 어우러지도록 광고를 노출시키고자 하는 경우

  • Type B - Feed : 버튼 등 별도의 진입 경로를 통해 광고 목록을 노출시키고자 하는 경우

  • Type C - Interstitial : 버즈빌이 사전에 만들어 놓은 레이아웃을 활용하여 Dialog 또는 BottomSheet 형태로 전면 광고를 노출하고자 하는 경우

 

Advanced Usage

광고 실행 Customization - Custom Launcher 사용

광고 실행을 Customize 할 수 있습니다. 예를 들어, 광고 랜딩 페이지 로드 등을 매체사가 지정하는 Class에서 구현할 수 있습니다.

※ 주의사항

Launcher에서 제공하는 클릭 URI는 임의로 Decoding 해서 로드하면 안됩니다. 이 경우 서버에서의 동작이 달라져 광고 관련 통계가 제대로 집계되지 않을 수 있습니다.

  1. BABLauncher 를 구현합니다.
    openUrl:object:userInfo 메소드의 인자로 넘어오는 object는 BABAd 또는 BABArticle 객체를 담고 있습니다.


    1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 // Objective-C @interface BABCustomLauncher : NSObject <BABLauncher> @end @implementation BABCustomLauncher - (void)openUrl:(NSURL *)url object:(id)object userInfo:(nullable NSDictionary *)userInfo { if ([object isKindOfClass:BABAd.class]) { BABAd *ad = object; NSString *unitId = ad.unitId; NSString *title = ad.creative.title; } ... [UIApplication.sharedApplication openURL:url options:@{} completionHandler:nil]; } @end

     

    1 2 3 4 5 6 7 8 9 10 11 12 // Swift class BABCustomLauncher: NSObject, BABLauncher { func open(_ url: URL, object: Any?, userInfo: [AnyHashable : Any]? = nil) { if let ad = object as? BABAd { let unitId = ad.unitId let title = ad.creative.title } ... UIApplication.shared.open(url, options: nil, completionHandler: nil) } }



  2. BuzzAdBenefit에 Launcher를 세팅합니다.


    1 2 3 // Objective-C BABCustomLauncher *launcher = [[BABCustomLauncher alloc] init]; [BuzzAdBenefit setLauncher:launcher];

     

    1 2 3 // Swift let adLauncher = BABCustomLauncher() BuzzAdBenefit.setLauncher(launcher)

※ 주의사항

다양한 광고의 특성상 광고를 클릭했을 때 딥링크가 동작하여 인앱 브라우저에서 광고주의 앱으로 이탈하게 되는 경우가 있을 수 있습니다. 따라서 Launcher 사용시 유저가 광고 클릭 후 광고주 앱 화면에서 뒤로가기 혹은 Back 버튼을 눌렀을 때, 처음 광고가 보이는 화면으로 제대로 돌아올 수 있도록 인앱 브라우저의 동작이 구현 되어야 합니다.

이렇게 광고주 앱으로 이탈하게 되는 딥링크 URL 광고의 경우 ad.creative.isDeeplink의 값이 YES로 return 되게 됩니다.

 

Custom launcher 사용시 딥링크 광고 처리 가이드

외부 앱으로 랜딩되는 딥링크 광고의 경우 redirect 과정을 거쳐 최종적으로 타겟 앱(또는 앱스토어)으로 이동하게 됩니다. 이 경우 사용자가 다시 본 앱으로 돌아왔을 때 redirect가 일어났던 인앱 브라우저가 빈 페이지인 상태로 열려있게 됩니다. 따라서 자연스러운 UX를 위하여 외부 앱으로 랜딩되는 광고의 경우 인앱 브라우저를 닫아 사용자가 본 앱으로 돌아왔을 때 빈 화면을 보지 않도록 처리해야 합니다. 이 때 아래 2가지 방법 중 하나를 선택하여 구현합니다.

  1. 인앱 브라우저 내에서 일어나는 redirect를 모니터하여 http/https가 아닌 scheme이 호출된 경우 타겟 앱이 열린 뒤 인앱 브라우저는 자동으로 닫히도록 구현합니다.

  2. Ad 안의 Creative 객체가 가진 isDeeplink 필드(ad.creative.isDeeplink)를 이용하여 사용자가 인앱 브라우저가 열려있는 상태에서 본 앱을 이탈했을 때 인앱 브라우저가 자동으로 닫히도록 구현합니다. 버즈빌에서는 각 광고의 랜딩 타입을 미리 체크하여 딥링크 광고인 경우 isDeeplink를 true로, 일반 웹 랜딩 광고인 경우 isDeeplink를 false로 내려주고 있습니다. 따라서 isDeeplink가 true인 광고가 인앱 브라우저로 열려있는 상태에서 본 앱이 백그라운드로 내려간 경우 타겟 앱으로 이동한 것으로 판단하여 인앱 브라우저를 닫아야 합니다.

 

Custom launcher 사용시 Article의 sourceUrl 사용법

컨텐츠의 경우 url scheme에 따라 랜딩 방식을 다르게 처리하고 싶다면(ex. 앱 안에서 브라우저 오픈 없이 다른 화면으로 이동되는 컨텐츠) 다음과 같은 방법으로 NativeArticle 객체의 sourceUrl을 가져와 분기 처리를 할 수 있습니다.

 

1 2 3 4 5 6 7 8 // Objective-C - (void)openUrl:(NSURL *)url object:(id)object userInfo:(nullable NSDictionary *)userInfo { if ([object isKindOfClass:BABArticle.class]) { BABArticle *article = object; NSString *sourceUrl = article.sourceUrl; ... } }

 

1 2 3 4 5 6 7 // Swift func open(_ url: URL, object: Any?, userInfo: [AnyHashable : Any]? = nil) { if let article = object as? BABArticle { let sourceUrl = article.sourceUrl ... } }

 

광고 로드 실패시 에러 정보 확인

광고 로드 실패시 불리는 콜백의 파라미터로 넘어오는 BABError 객체의 code 프로퍼티를 통해 해당 에러의 정보를 확인할 수 있습니다.

 

1 2 3 4 5 6 7 typedef enum { BABUnknownError = 0, BABServerError, BABInvalidRequest, BABRequestTimeout, BABEmptyResponse } BABErrorCode;

 

액션형 광고에 대한 유저 VOC 페이지

BuzzAd Benefit SDK는 비디오, 앱 인스톨, 페이스북 페이지 좋아요 등 다양한 유저 액션에 리워드를 지급하는 광고를 제공합니다. 그리고 이런 광고의 경우 종종 리워드 미적립을 이유로 유저가 VOC를 보내기도 합니다. 이러한 유저 VOC에 대한 접수 및 처리를 자동화 하기 위해 SDK에서는 미리 만들어 놓은 웹 페이지를 제공하고 있습니다. 아래의 단계를 통해 해당 기능을 사용하실 수 있습니다.

 

  1. 아래 예시와 같이 VOC 페이지 로드를 위한 유저 진입 Icon/Tab을 디자인 합니다.

    단, Type B - Feed를 사용하시면서 Toolbar를 Customize 하지 않고 Default Toolbar를 사용하시는 경우 예시 중 2번과 같은 아이콘이 이미 디자인에 포함되어 있습니다.




  2. 1번의 Icon/Tab이 클릭될 때 [BuzzAdBenefit showInquiryPageOnViewController:viewController] 호출합니다.