BuzzAd Benefit 2 iOS 마이그레이션 가이드

본 가이드는 기존 연동 돼있던 BuzzAd Benefit의 버전을 2 버전으로 업데이트에 필요한 내용을 담고 있습니다.

공통 적용 항목

다음 항목들은 공통으로 적용이 필요한 항목입니다.

1. SDK 초기화가 변경되었습니다. 변경

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

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

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

AppDelegate의 application:didFinishLaunchingWithOptions에 위의 코드를 추가할 것을 권장합니다.
1.x 버전의 경우, 최초 광고 요청 전에만 불린다면 자유롭게 코드 위치를 결정할 수 있었습니다.
- 하지만 2.x버전부터 어떤 이유(내부 정책 등)로 다음 위치에 코드를 적용하지 못할 경우, 반드시 최초로 광고를 요청하는 위치보다 이전에 배치되어야 합니다.

2. 프로젝트에 프레임워크를 추가하였습니다.추가

Dependency 확인이 필요하거나 offline 빌드 진행으로 인해 dependency가 필요한 경우에는 담당 매니저에게 문의바랍니다.

3. App Tracking Transparency 획득 권한 위임하기

App Tracking Transparency에 대한 사항은 Apple Developer Documentation에서 찾아보실 수 있습니다.

애플 IDFA 수집 정책이 변경되는 1월부터 적용하는 것을 추천드립니다.

iOS 14 이상에서 사용자에게 App Tracking Transparency 권한 허용 팝업을 노출할 경우 다음을 적용합니다. 해당 팝업은 권한 허용 여부를 선택하지 않은 사용자에 한하여 최초 1회만 노출됩니다.

[1] UserProfile을 등록하실 때, [BuzzAdBenefit setUserProfile:shouldShowAppTrackingTransparencyDialog:] 메서드를 사용하시면 되며, shouldShowAppTrackingTransparencyDialog의 인자를 true로 설정하여 호출하면 됩니다.

[BuzzAdBenefit setUserProfile:shouldShowAppTrackingTransparencyDialog:]

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

4. 커스텀 런처 사용 시, 커스텀 인앱 브라우저를 적용하였습니다.추가

커스텀 런처 사용하지 않을 경우 해당 사항이 없습니다.

기존에 커스텀 런처 사용하고 있는 경우, 하단의 커스텀 인앱브라우저 사용법을 참조하여 커스텀 인앱브라우저를 구현해야합니다.
- 커스텀 런처를 사용할 예정이거나 혹은 1.x 버전에서 이미 사용하고 있을 경우, 아래의 항목을 필수로 적용해야합니다.
커스텀 인앱브라우저 사용법(추가)
- 광고 실행시 사용되는 인앱 브라우저를 커스터마이즈 할 수 있습니다.
  - 예를 들어, 광고 랜딩 페이지 로드 등을 매체사가 지정하는 클래스에서 구현할 수 있습니다.
    - (아래를 클릭하여 확인할 수 있습니다.)

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

구현시 주의사항 :

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

[1] CustomBrowserViewController를 구현합니다.

// Objective-C
@interface CustomBrowserViewController: UIViewController
@end

@implementation CustomBrowserViewController {
  UIViewController *_browserViewController;
}

- (void)viewDidLoad {
  [super viewDidLoad];

  _browserViewController = [BuzzAdBrowser.sharedInstance browserViewController];
  [self.view addSubview:_browserViewController.view];
  [_browserViewController didMoveToParentViewController:self];

  ...
}

@end

// Swift
class CustomBrowserViewController {
  private lazy var browserViewController: UIViewController = {
    BuzzAdBrowser.sharedInstance().browserViewController()
  }()
  
  override func viewDidLoad() {
    super.viewDidLoad()
    
    view.addSubview(browserViewController)
    browserViewController.didMove(toParent: self)
    
    ...
  }
}

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

// Objective-C
@interface BABCustomLauncher : NSObject <BABLauncher>
@end

@implementation BABCustomLauncher
- (void)openWithLaunchInfo:(BABLaunchInfo *)launchInfo {
  [self openWithLaunchInfo:launchInfo delegate:nil];
}

- (void)openWithLaunchInfo:(BABLaunchInfo *)launchInfo delegate:(nullable id<BABLauncherEventDelegate>)delegate {
  // Custom Browser 실행
  CustomBrowserViewController *vc = [[CustomBrowserViewController alloc] init];
  [rootViewController presentViewController:vc animated:YES completion:nil];
}

@end

// Swift
class BABCustomLauncher: NSObject, BABLauncher {
  func open(launchInfo: BABLaunchInfo) {
    open(launchInfo: launchInfo, delegate: nil)
  }
  
  func open(launchInfo: BABLaunchInfo, delegate: BABLauncherEventDelegate?) {
    // Custom Browser 실행
    let vc = CustomBrowserViewController()
    rootViewController.present(vc, animtated: true, completion:nil)
  }
}

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

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

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

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

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

커스텀 런처 사용 시 광고 또는 컨텐츠인지 미리 판단하고 싶을 경우

// Objective-C
- (void)openWithLaunchInfo:(BABLaunchInfo *)launchInfo delegate:(nullable id<BABLauncherEventDelegate>)delegate {
  // 광고 또는 컨텐츠인지 미리 판단하고 싶을 경우, 다음을 이용하여 확인
  if (launchInfo.ad != nil) {
    // 광고
  } else if (launchInfo.article != nil){
    // 컨텐츠
  }
}

// Swift
func open(launchInfo: BABLaunchInfo, delegate: BABLauncherEventDelegate?) {
  // 광고 또는 컨텐츠인지 미리 판단하고 싶을 경우, 다음을 이용하여 확인
  if let ad = launchInfo.ad {
    // 광고
  } else if let article = launchInfo.article {
    // 컨텐츠
  }
}

[+] Article의 sourceUrl 사용법

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

커스텀 런처 사용 시 Article의 sourceUrl 사용법

// Objective-C
- (void)openWithLaunchInfo:(BABLaunchInfo *)launchInfo delegate:(nullable id<BABLauncherEventDelegate>)delegate {
  if (launchInfo.article != nil) {
    NSString *sourceUrl = launchInfo.article.sourceUrl;
    ...
  }
}

// Swift
func open(launchInfo: BABLaunchInfo, delegate: BABLauncherEventDelegate?) {
  if let article = launchInfo.article {
    let sourceUrl = article.sourceUrl
    ...
  }
}

Native Type 적용 항목

광고 참여 상태에 따른 CTA 등 소재 표시 분기 처리 방법

버즈빌에서 내려가는 광고는 기본적으로 모두 리워드가 할당되어 있습니다. 광고마다 리워드 적립 주기(기본 2시간)가 설정되어 있고, 사용자가 리워드 적립 주기 내에 동일 광고를 다시 참여하는 경우 리워드는 적립되지 않습니다. 따라서 광고 렌더링시 다음과 같은 방법으로 분기 처리를 하여 기획 의도에 맞는 UI를 사용자에게 보여주어야 합니다.

예를 들어 어떤 광고가 IPU(시간당 노출 제한)이 없이, 리워드 적립 주기는 1시간인 경우, 최초 참여시에는 리워드가 지급 되고 이후 1시간 내에 동일 광고가 노출 되었을 때, 이 광고는 리워드 지급이 되지 않는 상태이므로 CTA 등 UI를 "참여완료" 또는 "0P" 등으로 변경하여 사용자에게 리워드가 지급되지 않는 광고임을 알려주어야 합니다.

분기 처리시 사용되는 필드변경

1.x
- 분기 처리시 사용되는 필드
  - Ad 객체의 reward_status: 버즈빌 서버에서 광고를 할당할 때 해당 광고에 대하여 리워드 적립 주기 내에 현재 사용자의 적립 내역이 존재하면 "received" 값을 넣어줍니다. (주의: reward_status가 "received"여도 reward의 값은 원래 리워드 금액이 그대로 기록되어 있습니다.)
  - Ad 객체의 is_participated: 현재 할당 받은 광고들의 참여 상태를 sync하기 위한 값입니다. 광고 참여가 일어나면 해당 광고 및 메모리 상의 동일 광고들의 is_participated값이 true로 바뀌며 onParticipate 콜백이 호출됩니다. (주의: 버즈빌 서버에서 광고의 reward_status가 "received"로 내려온 경우에도 이번 할당에서 참여를 다시 하기 전까지 is_participated는 "false"로 설정되어 있습니다.)
- 분기 처리 예시 pseudo code
```
if ad.reward_status == "received" || ad.is_participated == true {
  // 리워드 적립 주기 내에 이미 참여했던 광고
  rewardLabel.text = "참여완료" // Or rewardLabel.text = "0P"
} else {
  if ad.reward > 0 {
    // 리워드가 있고 아직 참여하지 않은 광고
    rewardLabel.text = ad.reward + "P"
  } else {
    // 리워드가 없는 광고. (현재 Benefit은 리워드형 광고만 내보내고 있으므로 )
    rewardLabel.text = "0P"
  }
}
```
2.x
- 광고의 리워드 관련
  - Ad 객체의 totalReward
    - 해당 광고에 할당된 총 리워드 양을 나타냅니다. 리워드 적립 주기가 지나지 않아 광고에 리워드가 할당되지 않는 경우에는 0으로 내려오게 됩니다.
  - Ad 객체의 availableReward
    - 해당 광고에 남아있는 총 리워드 양을 나타냅니다. 유저가 광고에서 특정 액션을 취하지 않아 받아가지 못한 리워드가 있을때 0보다 큰 값을 갖게됩니다.
- 광고의 참여 여부 관련
  - Ad 객체의 isParticipated
    - 현재 할당 받은 광고들의 참여 상태를 sync하기 위한 값입니다. 광고 참여가 일어나면 해당 광고 및 메모리 상의 동일 광고들의 isParticipated값이 true로 바뀌며 onParticipate 콜백이 호출됩니다.
  - Ad 객체의 isClicked
    - 현재 할당 받은 광고의 클릭 여부를 나타내기 위한 값입니다. 광고를 클릭한 적이 있으면 true로 변경됩니다. 일부 액션형 광고의 경우 서버에서 참여 여부를 실시간으로 판단할 수 없습니다. 이 경우에는 isParticipated 값이 true가 아니므로, Click이 발생한 경우 “참여 확인 중” 이라는 CTA로 변경하여 유저 혼선을 줄일 수 있습니다.
- 분기 처리 예시 pseudo code

if ad.isClicked && ad.isActionType && !ad.isParticipated {
  // 클릭은 했지만 참여가 완료되지 않은 액션형 광고
  rewardLabel.text = "참여 확인 중"
} else {
  if ad.totalReward > 0 && ad.isParticipated {
    // 리워드 적립 주기 내에 이미 참여했던 광고
    rewardLabel.text = "참여 완료"
  } else if ad.availableReward > 0 {
    // 리워드가 있고 아직 참여하지 않은 광고
    rewardLabel.text = ad.reward + "P"
  } else {
    // 리워드가 없는 광고. (현재 Benefit은 리워드형 광고만 내보내고 있으므로 )
    rewardLabel.text = "0P"
  }
}

Feed Type 적용 항목

1. `autoLoadingEnabled` 설정이 추가되었습니다. 추가

FeedConfig 설정에서 autoLoadingEnabled값을 true로 설정 시, Feed의 Scroll이 일정 이상 내려가면 더 많은 광고 노출을 위해 광고 할당을 추가로 진행합니다.

(단, 광고 물량 상황에 따라, autoLoading으로 추가되는 광고가 없을 수 있습니다.)

// Objective-C
BABFeedConfig *config = [[BABFeedConfig alloc] initWithUnitId:YOUR_FEED_UNIT_ID];
// 더 많은 광고 할당을 추가로 하기 위한 설정입니다.
config.autoLoadingEnabled = YES;

// Swift
let config = BABFeedConfig(unitId: YOUR_FEED_UNIT_ID)
// 더 많은 광고 할당을 추가로 하기 위한 설정입니다.
config.autoLoadingEnabled = true

그 외에 노출형 광고만 연동하는 경우, 많은 광고 노출을 위해 적용을 권장합니다.

컨텐츠 노출하기가 설정되어 있을 경우, 오토로딩 기능은 자동으로 활성화 됩니다.

2. 디자인 커스터마이징 전 확인 사항이 추가되었습니다.추가

다음의 이미지 예시를 참고하여 커스터마이징 적용을 부탁드립니다.

3. 피드(Feed) 에러화면 커스터마이징이 추가되었습니다. 추가

보여줄 광고가 없는 상황에 피드 에러 화면을 노출할 수 있습니다. 피드 에러화면을 커스터마이징하여 유저에게 조금 더 자연스러운 UX를 제공할 수 있습니다.

[1] 이미지, 타이틀, 디스크립션을 커스터마이징하는 경우

Feed Error - 이미지, 타이틀, 디스크립션을 사용

[1] BABFeedDefaultErrorView를 상속받고 클래스에서 제공하는 프로퍼티들의 getter를 설정해줍니다.

// Objective-C
@interface CustomErrorView : BABFeedDefaultErrorView
@end

@implementation CustomErrorView

- (UIImage *)errorImage {
    return [UIImage imageWithName:@"Custom Error Image"];
}

- (NSString *)errorTitleText {
    return @"Custom Error Title";
}

- (NSString *)errorDescriptionText {
    return @"Custom Error Description";
}

@end

// Swift
class CustomErrorView : BABFeedDefaultErrorView {
    override var errorImage: UIImage {
        get { return UIImage(named: "Custom Error Image") }
        set { self.errorImage = newValue }
    }
    override var errorTitleText: String {
        get { return "Custom Error Title" }
        set { self.errorTitleText = newValue }
    }
    override var errorDescriptionText: String {
        get { return "Custom Error Description" }
        set { self.errorDescriptionText = newValue }
    }
}

[2] BABFeedConfig를 통해 errorViewClass를 지정합니다.

// Objective-C
BABFeedConfig *config = [[BABFeedConfig alloc] initWithUnitId:YOUR_FEED_UNIT_ID];
config.errorViewClass = [CustomErrorView class];

// Swift
let config = BABFeedConfig(unitId: FEED_UNIT_ID)
config.errorViewClass = CustomErrorView.self

[2] 에러화면 전체를 커스터마이징하는 경우

Feed Error - 화면 전체를 사용

[1] BABFeedErrorView를 상속받는 class를 interface builder 또는 코드를 통해 구현합니다.