BuzzAd Unity iOS용 SDK 연동 가이드

Owned by Molly Im(임슬아) (Unlicensed)
Last updated: Aug 29, 2022
6 min read

목차

개요

이 연동 가이드는 BuzzAd SDK(BuzzAd-Benefit)를 Unity iOS 프로젝트에 연동하는 방법을 안내합니다.

BuzzAd Unity iOS용 SDK는 오퍼월처럼 다수의 광고를 목록 형식으로 제공하는 피드(Feed) 지면, 사용자의 액션 및 세션의 시작이나 종료 단계에 추가하여 UX에 자연스럽게 녹아드는 인터스티셜(Interstitial) 지면을 제공합니다. 또한 국내 최다 광고 물량을 공급하는 버즈빌의 비보상형 광고, 리워드 기술을 적용한 보상형 광고를 게재하여 Unity iOS 앱의 수익화를 효과적으로 지원합니다.

별도의 커스터마이징이 필요없는 SDK 기본 UI로 연동이 가능한 BuzzAd Unity iOS용 SDK를 탑재해 한 단계 진화된 앱 수익 창출을 시작하세요.

시작하기

SDK 설치와 초기화, 사용자 정보 등록 등 버즈빌의 SDK로 광고 지면을 연동하기 전 완료해야 하는 설정에 대해 알아보세요.

요구 사양

  • deployment target 10 이상

  • Xcode 13 이상

연동용 ID 발급받기

버즈빌의 SDK를 연동하려면 반드시 연동하려는 앱의 고유 식별자(App ID)와 광고 지면의 고유 식별자(Unit ID)가 필요합니다. 버즈빌 BD 매니저 또는 help@buzzvil.com을 통해 ID를 발급받으세요.

  • App ID: 버즈빌의 SDK를 연동하는 앱별로 부여하는 고유 식별자입니다.

  • Unit ID: 버즈빌의 SDK를 통해 생성하는 지면별로 부여하는 고유 식별자입니다.

연동용 코드 준비하기

BuzzAd Unitiy iOS용 SDK를 연동하기 위해서는 SDK가 제공하는 모든 기능을 정의한 파일을 작성해야 합니다. 다음의 절차를 따르세요.

1. 연동할 Unity 프로젝트를 열어 Objective-C 로 된 .mm 파일을 생성하세요. 아래의 코드 예제를 붙여 넣으면 됩니다.

  • 아래 코드를 사용해 SDK가 제공하는 모든 기능을 정의한 후 필요한 지면과 기능을 선택적으로 호출할 수 있으며, 광고 할당에 필요한 App ID, 사용자 프로필 등 필요한 정보를 추가할 수 있습니다.

  • 광고 할당을 위해 사용자 활동 추적 권한 요청 다이얼로그를 띄우는 메서드 shouldShowAppTrackingTransparencyDialog(40번행)가 추가되어 있습니다. 앱에서 이미 권한을 받았다면 제거하거나 옵션을 NO로 변경하세요.

#import <Foundation/Foundation.h> #import "UnityFramework/UnityFramework.h" #import <BuzzAdBenefit/BuzzAdBenefit.h> @interface BuzzvilPlugin : NSObject <BZVBuzzAdInterstitialDelegate> @property (nonatomic, strong, readonly) BZVBuzzAdFeed *buzzAdFeed; @property (nonatomic, strong, readonly) BZVBuzzAdInterstitial *buzzAdInterstitial; @end @implementation BuzzvilPlugin + (BuzzvilPlugin*)sharedInstance { static BuzzvilPlugin *sharedInstance = nil; static dispatch_once_t onceToken; dispatch_once(&onceToken, ^{ NSLog(@"Creating BuzzvilPlugin Instance"); sharedInstance = [[BuzzvilPlugin alloc] init]; }); return sharedInstance; } - (instancetype)init { if (self = [super init]) { [self initHelper]; } return self; } - (void)initHelper { NSLog(@"BuzzvilPlugin Initialized!"); // Initialize BuzzAdBenefit BZVConfig *config = [BZVConfig configWithBlock:^(BZVConfigBuilder * _Nonnull builder) { builder.appId = @"YOUR_APP_ID"; builder.defaultFeedConfig = [BZVFeedConfig configWithBlock:^(BZVFeedConfigBuilder * _Nonnull builder) { builder.unitId = @"YOUR_FEED_UNIT_ID"; builder.shouldShowAppTrackingTransparencyDialog = YES; }]; }]; [BuzzAdBenefit initializeWithConfig:config]; // Set UserProfile // 로그인을 요청하는 코드입니다. [BuzzAdBenefit loginWithBlock:^(BZVLoginRequestBuilder * _Nonnull builder) { builder.userId = @"UNITY_USER"; builder.birthYear = 1996; builder.gender = BZVUserGenderMale; // 남성 사용자 } onSuccess:^{ } onFailure:^(NSError * _Nonnull error) { }]; _buzzAdFeed = [BZVBuzzAdFeed feedWithBlock:^(BZVBuzzAdFeedBuilder * _Nonnull builder) {}]; } - (void)showFeed { BZVFeedViewController *feedViewController = [_buzzAdFeed viewController]; // navigation에 push [UnityGetGLViewController() presentViewController:feedViewController animated:YES completion:nil]; } - (void)showInterstitialAdDialog:(NSString *)unitId { _buzzAdInterstitial = [BZVBuzzAdInterstitial interstitialWithBlock:^(BZVBuzzAdInterstitialBuilder * _Nonnull builder) { builder.unitId = unitId; builder.type = BZVBuzzAdInterstitialDialog; }]; _buzzAdInterstitial.delegate = self; [_buzzAdInterstitial load]; } - (void)showInterstitialAdBottomSheet:(NSString *)unitId { _buzzAdInterstitial = [BZVBuzzAdInterstitial interstitialWithBlock:^(BZVBuzzAdInterstitialBuilder * _Nonnull builder) { builder.unitId = unitId; builder.type = BZVBuzzAdInterstitialBottomSheet; }]; _buzzAdInterstitial.delegate = self; [_buzzAdInterstitial load]; } #pragma mark - BZVBuzzAdInterstitialDelegate - (void)BZVBuzzAdInterstitialDidFailToLoadAd:(nonnull BZVBuzzAdInterstitial *)interstitial withError:(nonnull NSError *)error { // 할당된 광고가 없으면 호출됩니다. } - (void)BZVBuzzAdInterstitialDidLoadAd:(nonnull BZVBuzzAdInterstitial *)interstitial { // 할당된 광고가 있으면 호출됩니다. // Interstitial 광고를 화면에 표시합니다. [interstitial presentOnViewController:UnityGetGLViewController()]; } - (void)BZVBuzzAdInterstitialDidDismiss:(UIViewController *)viewController { // Interstitial 지면이 종료되면 호출됩니다. // 필요에 따라 추가 기능을 구현하세요. } @end NSString* CreateNSString (const char* string) { if (string) return [NSString stringWithUTF8String:string]; else return [NSString stringWithUTF8String:""]; } extern "C" { void InitBuzzPlugin() { BuzzvilPlugin.sharedInstance; } void ShowFeedIOS() { [BuzzvilPlugin.sharedInstance showFeed]; } void ShowInterstitialAdDialogIOS(const char* unitId) { [BuzzvilPlugin.sharedInstance showInterstitialAdDialog:CreateNSString(unitId)]; } void ShowInterstitialAdBottomSheetIOS(const char* unitId) { [BuzzvilPlugin.sharedInstance showInterstitialAdBottomSheet:CreateNSString(unitId)]; } }

SDK 초기화 메서드 호출 후 등록해야 하는 ID와 사용자 프로필 정보에 대해서는 아래 표를 참고하세요.

필수/권장

항목

설명

필수/권장

항목

설명

필수

appId

버즈빌의 SDK를 연동하는 앱별로 부여하는 고유 식별자입니다.

필수

userId

사용자 고유 식별자입니다. 서비스 도중 변하지 않는 고정 값입니다.

앱을 삭제 후 재설치하여 사용자의 ID 값이 변경되거나 다른 사유로 인해 고정 ID를 사용하지 못하는 경우 버즈빌 BD 매니저 또는 help@buzzvil.com에 문의하세요.

권장

gender

사용자의 성별입니다.

  • BZVUserGenderFemale: 남성

  • BZVUserGenderMale: 여성

권장

birthyear

사용자의 출생연도입니다.

 

2. C# 파일에서 .mm 파일에서 생성한 함수를 연결하는 코드(8~17번행)를 작성하세요.

  • 아래 코드 예제의 8~17번행 중 필요한 코드만 사용하면 됩니다.

앱이 시작될 때 InitBuzzPlugin()(초기화 메서드)을 호출하는 것을 권장합니다.

// NewBehaviorScript.cs using System.Collections; using System.Collections.Generic; using UnityEngine; public class NewBehaviourScript : MonoBehaviour { #if UNITY_IOS [DllImport("__Internal")] internal static extern void InitBuzzPlugin(); [DllImport("__Internal")] internal static extern void ShowFeedIOS(); [DllImport("__Internal")] internal static extern void ShowInterstitialAdDialogIOS(string unitId); [DllImport("__Internal")] internal static extern void ShowInterstitialAdBottomSheetIOS(string unitId); #endif // Start is called before the first frame update void Start() { // your code } // Update is called once per frame void Update() { // your code } }

피드 지면

피드는 목록 형태의 광고 지면입니다. 오퍼월처럼 대량 광고 게재가 가능하고 네이티브 지면처럼 앱 UI와 어울리는 디자인을 구현할 수 있다는 장점이 있습니다.

피드 지면을 호출하는 방법, 그리고 광고 노출과 사용자 경험 최적화를 지원하는 기능들을 확인해 보세요.

준비 사항

  • 시작하기 적용 완료

  • 호출하고자 하는 CS File에 함수에 대한 선언

  • 피드 지면에 사용할 Unit ID(이하 unitId)

피드 지면 호출하기

다음의 절차를 따라 피드 지면을 호출하세요.

1. 피드 지면을 호출하고자 하는 C# 파일에 함수를 선언하세요. 이를 통해 생성한 plugin의 함수를 호출할 수 있습니다.

#if UNITY_IOS [DllImport("__Internal")] internal static extern void ShowFeedIOS(); #endif

코드의 구현 내용은 연동용 코드 준비하기 토픽의 BenefitPlugin.mm에서 확인할 수 있습니다.

SDK 연동 완료하기

Unity에서 연동을 위한 모든 코드를 작성한 후 iOS 빌드 절차를 수행하여 연동을 완료하세요.

Xcode 프로젝트 생성하기

Unity 프로젝트에서 다음의 절차를 따라 Xcode 프로젝트를 설정하세요.

  1. “Build Settings” 창의 Platform 영역에서 iOS를 선택하세요.

  2. 창 오른쪽 하단의 Switch Platform > Build를 클릭하세요.

  • Xcode 프로젝트가 생성됩니다.

Cocoapods로 SDK 연동하기

Cocoapods를 사용하기 위한 설정을 해야 합니다.

다음의 절차를 따라 Cocoapods로 SDK를 연동하세요.

  1. 생성된 Xcode 프로젝트의 root 경로에 아래의 명령어를 입력하세요.

  • 새로운 Podfile이 생성됩니다.

 

2. Podfile을 아래와 같이 작성하고 저장하세요.

 

3. 터미널 창에 아래의 명령어를 입력하세요.

 

4. xcworkspace 확장자를 가진 프로젝트 파일이 생성됩니다. 이 프로젝트 파일을 통해 Xcode를 실행하세요.

사용자의 활동 추적 권한 기능

BuzzAd Unity iOS용 SDK는 iOS 14 이상에서 사용자의 활동 추적 권한(App Tracking Transparency)을 획득하기 위해 활동 추적 권한 허용 다이얼로그와 배너를 제공합니다.

활동 추적 권한 허용 다이얼로그

iOS 14 이상의 기기에서 활동 추적 권한을 제공하지 않은 사용자가 피드 지면에 진입할 때 다이얼로그가 나타납니다.

활동 추적 권한 허용 안내 배너

활동 추적 권한 제공을 거부한 사용자에게는 피드 해더 영역에 더 많은 리워드 획득 기회를 안내하는 배너가 표시됩니다.

문제 해결하기

Xcode에서 빌드하는 도중 자주 발생하는 문제의 해결 방법을 확인해 보세요.

Signing 오류가 발생합니다

  • 오류 원인: Xcode 에서 파일 트리 중 가장 상위에 있는 root 프로젝트에서 Signing 관련 설정이 필요합니다.

  • 해결 방법: 프로젝트 설정 메뉴에서 Signing & Capabilities를 클릭한 후 Automatically manage signing를 선택하세요. Team 설정

@import가 동작하지 않습니다

  • 오류 원인: C++ 모듈이 비활성화되어 있습니다.

  • 해결 방법 1: Unity Framework의 “Build Settings” 창에서 Enable Modules를 Yes로 설정하세요.

  • 해결 방법 2: Unity Framework의 “Build Settings” 창에서 Other C++ Flags에 -fcxx-modules를 추가하세요.

앱 크래시가 발생합니다

  • 오류 원인: iOS 14 이상에서 개인 정보 사용에 대한 정상 적인 접근을 위한 설정이 필요합니다.

  • 해결 방법: 활동 추적 권한 팝업 노출하기 토픽을 참고하여 info.plist에 key와 value를 추가하세요.