[iOS 2.0.x, 2.1.x] 공통 적용 항목 연동

Owned by Jamie Koo (Unlicensed)
Last updated: Oct 17, 2022 by Olivia Kim

공통 적용 항목 연동을 통해 BuzzAd Benefit iOS SDK를 이용하여, 매체사가 원하는 지면에 리워드가 지급되는 광고를 보여줍니다. 광고를 매체사 앱에 자연스럽게 노출시켜 매출을 극대화할 수 있습니다. 해당 문서에서는 SDK 적용 및 초기화를 진행하고, 사용자 정보 관리와 연관된 항목을 설정합니다.

이 문서는 광고 지면의 종류/ 수와 상관없이 연동이 되어야 하는 공통 적용 항목입니다. 

 

다음 과정이 완료되었는지 확인이 필요합니다.

App Id 가 발급 완료되었는지
연동하려는 버전이 확인되었는지

위의 과정 중 완료되지 않은 항목이 있다면, 버즈빌의 운영 매니저에게 문의 바랍니다.

※ 기존 1.X 버전의 BuzzAd SDK가 연동되어 있는 경우 https://buzzvil.atlassian.net/wiki/spaces/BDG/pages/1321468246 에서 주요 변경사항을 확인하실 수 있습니다.

 

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

연동하기

1. SDK 적용하기

Cocoapods 또는 Manual Import 를 사용하여 SDK 를 적용할 수 있습니다. (Cocoapods 사용을 권장합니다.)

Cocoapods 사용하기 (권장)

Podfile에 아래 코드 적용해야 합니다.

pod 'BuzzAdBenefit', '= 2.1.x'

Deployment Target 에 따라 다음의 버전을 사용해야 합니다.

  • 2.1.13 : Deployment Target 9.0

  • 2.1.14 : Deployment Target 10.0

Manual Import

Manual Import는 권장되지 않는 방법입니다. 진행이 필요한 경우 반드시 버즈빌 연동 담당 매니저에게 문의 바랍니다.

[1] 프로젝트에 framework 추가하기

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

  • BuzzAdBenefit Framework

    • BuzzAdBenefit.framework

    • BuzzAdBenefitNative.framework

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

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

  • 아래의 항목은 Dependencies 폴더에서 다운받을 수 있습니다.

    • AFNetworking.framework

    • SDWebImage.framework

    • SDWebImageWebPCoder.framework

    • ReactiveObjC.framework

    • GoogleAds-IMA-iOS-SDK

[2] Run script 추가하기

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

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 초기화하기

[1] YOUR_APP_ID 부분에 위 단계에서 준비한 app_id 삽입

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

AppDelegate의 application:didFinishLaunchingWithOptions에 위의 코드를 추가할 것을 권장합니다. 어떤 이유(내부 정책 등)로 다음 위치에 코드를 적용하지 못할 경우, 반드시 최초로 광고를 요청하는 위치보다 이전에 배치되어야 합니다.

 

 

연동하기

2. 사용자 정보 관리하기

User profile 설정하기

유저가 퍼블리셔 앱에 로그인한 시점에 아래와 같이 UserProfile 을 설정합니다. User ID는 필수 항목이며, 타게팅 정보 (성별, 연령)는 원활한 서비스 운영과 높은 광고 효율을 위한 권장 항목입니다. 해당 값을 입력하는 setUserProfile 함수가 호출되지 않으면 광고가 할당되지 않습니다

[1] userId (필수)

  • 매체사 서비스 유저를 고유하게 구분할 수 있는 식별값입니다. 매체사에서 직접 사용하는 유저의 아이디를 입력할 필요는 없습니다. 하지만, 한 개의 아이디에 한 명의 유저를 고유하게 구분할 수 있어야 합니다.

매체사 서비스에서 고유하게 구분되는 유저에 대하여, userId 값이 복수 개 연동되거나 변경될 가능성이 있을 경우, 반드시 버즈빌의 운영 매니저와 논의해야 합니다.
(예시: 매체사 앱 삭제 후 재설치 시 userId 값이 변경되는 경우)

[2] 광고 타게팅 정보 (권장)

  • gender

    • BABUserGenderMale: 남성

    • BABUserGenderFemale: 여성

  • birthYear : 출생년도

 

App Tracking Transparency 권한 허용하기

iOS 14 이상에서 사용자에게 App Tracking Transparency 권한 허용 팝업을 노출할 경우 다음을 적용합니다. 해당 팝업은 권한 허용 여부를 선택하지 않은 사용자에 한하여 최초 1회만 노출됩니다. App Tracking Transparency에 대한 자세한 내용은 애플 공식 문서를 확인해주세요.

[1] 이전 단계의 setUserProfile의 인자로 shouldShowAppTrackingTransparencyDialog 값을 true로 설정하여 호출합니다.

[2] 앱의 info.plist 파일에 NSUserTrackingUsageDescription 값을 추가하여, 권한 허용 팝업에서 사용자에게 보여줄 메세지를 설정할 수 있습니다.

[3] Feed 연동시 App Tracking Trasparency 권한 허용을 위한 추가 기능을 사용할 수 있습니다. 자세한 내용은 이곳에서 확인할 수 있습니다.

SKAdNetwork 설정하기

iOS 14 이상에서 설치형 광고에 대한 전환을 추적하기 위해서는 애플의 SKAdNetwork를 지원해야 합니다. BuzzAd SDK는 SKAdNetwork를 지원하고 있습니다. info.plist에 버즈빌의 SKAdNetwork Identifier(67369282zy.skadnetwork)를 추가하면 전환 추적 기능을 사용할 수 있습니다. SK AdNetwork에 대한 자세한 내용은 애플 공식 문서를 확인해주세요.

 

NotificationCenter 설정하기

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

UserProfile 설정과 광고 요청 시점간 간격이 짧은 경우, 위의 notification을 observe 하여 세션키 등록을 확인한 후 광고 요청을 수행할 수 있습니다.

 

User preference 설정하기

앞선 단계를 통해, 유저가 로그인에 성공한 시점에 다음을 설정합니다.

autoplayType은 동영상 광고의 자동 재생에 대한 설정입니다. 기본값은 Wifi 환경에서만 자동 재생하도록 설정되어 있습니다. 선택 가능한 설정값은 다음과 같습니다.

  • BABVideoAutoPlayOnWifi: Wifi 환경에서만 자동 재생됩니다. (기본값)

    • 외부 포인트 연동이 완료 되지 않은 경우, 자동 재생하지 않습니다.

  • BABVideoAutoPlayEnabled: 항상 자동 재생됩니다.

  • BABVideoAutoPlayDisabled: 자동 재생을 사용하지 않습니다.

 

사용자 정보 삭제하기

외부 인증을 통한 로그인이 만료되는 시점 혹은 앱 사용 종료로 설정값 삭제가 필요할 경우, 다음을 설정합니다. 

 

 

연동하기

3. (선택) 액션형 광고 송출하기

다음 항목에 대한 확인이 필요합니다.

연동하기 - [1. SDK 적용하기], [2. 사용자 정보 관리하기] 가 모두 완료 되었는지 확인

해당 항목은 필수가 아닌 선택으로 진행하는 항목입니다. 액션형 광고를 송출하지 않는 경우, 아래의 항목을 적용하지 않아도 됩니다. 액션형 광고를 송출하기 위해서는 아래의 해당 항목을 반드시 적용해야 합니다.

액션형 광고를 송출할 경우, 다음 항목들을 적용해야 합니다.

CTA 버튼의 상태 변화 적용 (광고 영역을 커스터마이즈지 않은 경우, 자동으로 적용 완료)
유저 문의하기 (VOC) 페이지 사용
커스텀 런처 사용시, 커스텀 인앱브라우저를 적용 (해당 사항이 있는 경우에만 적용)

 

CTA 버튼의 상태 변화 적용(변경)하기

노출형 광고의 경우, 광고 노출 → 광고 클릭 → 광고 적립 의 단계로 진행됩니다. 광고 클릭 후에 적립이 완료되기 때문에, 적립 완료 콜백을 확인한 뒤, CTA 버튼의 상태도 ‘적립 완료’ 로 변경합니다.

하지만, 액션형 광고 (isActionType) 의 경우,

(기존) 포인트 적립 시점이 광고 클릭 직후가 아닌 ‘참여 내역 확인 후' 입니다. 유저가 광고 참여를 완료한 뒤, 광고 지면으로 돌아왔어도, CTA 버튼의 상태를 '적립 완료' 로 표시할 수 없었습니다. 적립 완료 콜백이 존재하지 않아, 광고 노출 → 광고 클릭 두 단계로 진행(이후 서버 적립은 생략)되었습니다. CTA 버튼의 상태는 참여 전 → '참여 확인 중 (is clicked)’ 로 구분되어야 했습니다.

(변경) 액션형 광고도 노출형과 같이, 적립 완료 콜백이 적용 됩니다. 적립 완료 콜백을 확인한 뒤, CTA 버튼을 ‘적립 완료’ 로 변경해야 합니다. 참여 전 → 참여 확인 중 (is clicked) → 참여 완료 (is participated) 의 단계로 구분 가능합니다.

자세한 내용은 광고 참여 상태에 따른 CTA 등 소재 표시 분기 처리 방법 문서를 참고 바랍니다.

 

유저 문의하기 (VOC: Voice Of Customer) 페이지 사용

버즈빌은 비디오, 앱 인스톨, 페이스북 페이지 좋아요 등 유저가 광고에 지정된 액션을 완료하는 경우, 노출형 광고보다 높은 리워드를 제공합니다. 어떤 상황에 의해 리워드가 미지급 될 경우, 유저가 미적립에 관련된 문의를 보냅니다. 이런 문의의 접수 및 처리를 자동화 하기 위해 SDK에 미리 만들어 놓은 문의하기 웹 페이지를 제공하고 있습니다. 아래의 단계를 통해 문의하기 페이지를 사용할 수 있습니다.

문의하기 페이지는 연동되어 있는 지면(유닛) 기준이 아닌, 앱을 기준으로 조회할 수 있습니다.
문의하기 페이지의 위치를 강제하지 않습니다. 지면 내부/ 앱 내의 적절한 위치에 배치할 수 있습니다.

 

[1] 문의하기 페이지 로드를 위한 유저 진입 아이콘 및 탭을 디자인 합니다.

[2] 1번의 아이콘 혹은 탭이 클릭될 때 [BuzzAdBenefit showInquiryPageOnViewController:viewController] 호출합니다.

[+] Feed 또는 Interstitial 의 경우, 문의하기에 사용되는 기본 아이콘 및 기능을 제공받을 수 있습니다. (아래를 클릭하여 확인할 수 있습니다.)

  • Feed - 툴바를 커스터마이즈하지 않고 기본 툴바를 사용하는 경우, 이미지 예시 중 2번과 같이 이미 포함된 아이콘 및 문의하기 기능이 활성화 됩니다.

  • Intersitital - InterstitialAdConfig에 showInquiryButton = YES 설정하면, 이미지 예시 중 1번과 같이 이미 포함된 아이콘 및 문의하기 기능이 활성화 됩니다.

 

커스텀 런처 사용시, 커스텀 인앱브라우저를 적용

기존에 커스텀 런처 사용하고 있는 경우, 하단의 커스텀 인앱브라우저 사용법을 참조하여 커스텀 인앱브라우저를 구현해야합니다. (커스텀 런처를 사용하지 않을 경우 해당 사항 없습니다.)

커스텀 런처를 사용할 예정이거나, 1.X 버전에서 이미 사용하고 있을 경우, 아래의 항목을 필수로 적용해야 합니다.

 

[1] 커스텀 인앱브라우저 사용법

광고 실행시 사용되는 인앱브라우저를 커스터마이즈 할 수 있습니다. 예를 들어, 광고 랜딩 페이지 로드 등을 매체사가 지정하는 클래스에서 구현할 수 있습니다. (아래를 클릭하여 확인할 수 있습니다.)

구현시 주의사항 :

  • BuzzAdBrowser에서 제공하는 ViewController를 사용하여 인앱브라우저를 구현해야 합니다. 사용하지 않을 경우, 일부 광고(액션형 광고, 체류 리워드 광고)가 제대로 동작하지 않습니다.

[1] CustomBrowserViewController를 구현합니다.

 

[2] BABLauncher를 상속하는 커스텀 런처 클래스를 작성합니다.


[3] BuzzAdBenefit에 Launcher를 세팅합니다.

 

[+] 광고 또는 컨텐츠를 미리 판단하는 방법

커스텀 런처 사용시 광고 또는 컨텐츠인지 미리 판단하여 동작을 구분할 수 있습니다. (아래를 클릭하여 확인할 수 있습니다.)

 

[+] Article의 sourceUrl 사용법

파트너의 컨텐츠를 등록하여 내리는 경우, Article의 sourceUrl 을 확인하여 브라우저 랜딩이 아닌 직접 앱 이동으로 동작을 정의할 수 있습니다. (아래를 클릭하여 확인할 수 있습니다.)

 

 

 

추가 정보

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

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

 

 

다음 과정으로 넘어가기

→ 광고 지면 타입 연동하기 (타입별 링크 이용)

- Native Type (링크)
- Feed Type (링크)
- Interstitial Type (링크)