콘텐츠로 이동

Unity

Hive Adkit for AD(X): Unity

Hive AdKit은 Hive SDK와 개별모듈 유저가 AD(X)에서 제공하는 Unity 패키지를 적용하는 과정에 발생하는 오류를 수정하고, 사용의 편의를 돕기 위해 제작된 광고모듈입니다. Hive AdKit을 지원하는 버전과 적용 방법을 아래에서 차근차근 살펴보세요.

설치

Hive Developers에 접속하여 AdKit을 다운로드하여 적용하세요.

  1. Hive Developers에서 AdKit 최신 버전을 다운로드 하고 압축 해제하세요.
  2. Unity 툴바의 Assets > Import Package > Custom Package... 에서 .unitypackage 파일을 선택하고 Import 를 클릭하세요.
  3. Import 완료 후 Assets 폴더 하위에 Hive AdKit 및 AD(X) 관련 파일과 폴더가 생성되었는지 확인하세요.
Important

개발 중 AdKit 테스트를 진행할 때에는 반드시 테스트 광고 키를 적용해야 합니다.

업데이트

사용 중인 AdKit은 삭제하고 최신 버전을 설치하여 업데이트 하세요.


적용하기

iOS (Unity 2019.4 이상)

Unity 2019.4 이상에서 iOS 프로젝트 빌드 시 DynamicFramework로 동작하는 UnityFramewok 타겟이 생성됩니다.

  1. EDM4U 설정 (1.2.171 기준) Unity의 iOS Resolver Settings(메뉴: Assets > External Dependency Manager > iOS Resolver > Settings)에서 static_framework 빌드 설정이 되어있는지 확인합니다.

  2. Hive AdKit 1.5.0 버전부터 AppLovinSDK가 Dynamic Framework로 제공됩니다. 따라서, static_framework 사용 시 반드시 아래 작업을 수행해야 합니다.

    Assets/HIVEAdKit/Editor/AdKitPostprocess.cs 파일 iOSAdd_DynamicFrameworks 함수에서 dynamicFramework Import 주석을 해제합니다. 주석 위치는 아래와 같습니다.

    (string Name, string Source) [] dynamicFrameworks = {
        // Hive AdKit 1.5.0 버전부터 AppLovinSDK를 사용할 때, Pod Static을 설정했다면 아래 AppLovinSDK 주석을 해제하세요.
        // ("AppLovinSDK.xcframework", "Pods/AppLovinSDK/applovin-ios-sdk-12.6.1"),
    }
    

    Warning

    반드시 static_framework를 활성화하고 빌드할 때에만 주석을 해제해야 합니다. Dynamic Framework 사용 시 주석을 해제하면 충돌이 발생할 수 있습니다.

  3. 프로젝트를 빌드합니다. 빌드가 끝나면 생성된 프로젝트 루트 경로에서 Podfile을 열어 파일 설정을 확인합니다.

    source 'https://github.com/adxcorp/AdxLibrary_iOS_Release.git'
    source 'https://cdn.cocoapods.org/'
    
    platform :ios, '12.0'
    
    target 'UnityFramework' do
            pod 'ADXLibrary', '2.6.2'
            pod 'Google-Mobile-Ads-SDK', '~> 11.8.0'
    end
    target 'Unity-iPhone' do
    end
    use_frameworks!
    
  4. Xcode 설정을 진행하세요.

iOS: Facebook SDK와 광고 모듈 충돌 해결하기

Facebook SDK는 Dynamic Framework 방식만 제공하는 반면 광고 모듈은 Static Framework 방식만 제공하는데, Podfile 설정은 두 방식 중 하나만 지원합니다. 이에 따라, Unity에서 앱 빌드 시 Facebook SDK를 적용하려면 아래 방법대로 Facebook SDK와 광고 모듈 충돌을 해결해야 합니다.

HIVEAdKit/Editor/AdKitPostprocess.cs 파일 iOSAdd_DynamicFrameworks 함수에서 사용하는 Facebook SDK 주석을 제거하여 Dynamic SDK를 임베딩합니다.

    (string Name, string Source) [] dynamicFrameworks = {
        // Hive AdKit 1.5.0 버전부터 AppLovinSDK를 사용할 때, Pod Static을 설정했다면 아래 AppLovinSDK 주석을 해제하세요.
        // ("AppLovinSDK.xcframework", "Pods/AppLovinSDK/applovin-ios-sdk-12.6.1"),

        // 만약 Facebook SDK를 사용한다면 사용하는 SDK 종류에 따라 하단 주석을 해제하세요.
        // ("FBAEMKit.xcframework","Pods/FBAEMKit/XCFrameworks"),
        // ("FBSDKCoreKit_Basics.xcframework","Pods/FBSDKCoreKit_Basics/XCFrameworks"),
        // ("FBSDKCoreKit.xcframework","Pods/FBSDKCoreKit/XCFrameworks"),
        // ("FBSDKLoginKit.xcframework","Pods/FBSDKLoginKit/XCFrameworks"),
        // ("FBSDKShareKit.xcframework","Pods/FBSDKShareKit/XCFrameworks"),
        // ("FBSDKGamingServicesKit.xcframework","Pods/FBSDKGamingServicesKit/XCFrameworks")
    };
Warning

반드시 현재 사용하는 Facebook SDK만 주석을 해제해야 합니다.

제공 기능

  • 보상형 광고
    • AD(X)는 광고의 노출에 대한 API를 제공하지 않고 AdMob의 가이드를 따르도록 안내합니다.
    • Hive AdKit API와 Hive SDK, 혹은 개별모듈을 함께 사용하는 경우 호출된 RewardVideo API에 따라서 로그 정보 전송 여부가 결정됩니다. 로그 정보는 Hive 애널리틱스 서버로 전송되며 해당 기능을 지원하는 최소 버전은 다음과 같습니다.
      • Hive SDK v4.11.0
      • Hive SDK v1.17.2
      • 개별모듈 ModuleManager v2.6.0
      • 개별모듈 CommonModule v1.5.0
  • Interstitial 타입 광고
  • Adaptive Banner 타입 광고

아래는 Hive AdKit 활용 가이드입니다.

Hive AdKit 초기화

모든 타입의 광고를 초기화, 로딩, 노출하기 전 필수적으로 수행해야 하는 단계입니다.

유럽과 영국 타겟

게임이 유럽 및 영국(EEA & UK)을 타겟팅하는 경우 GDPR(유럽 연합 일반 데이터 보호 규칙) 동의 팝업을 노출해야 합니다. Hive Adkit은 GDPR 동의 팝업 노출을 위해 Google UMP(User Messaging Platform)를 지원합니다. Google UMP를 사용하기 위해, 먼저 GDPR 메시지 작성 가이드를 참고하여 GDPR 메시지를 작성하세요.

Hive SDK 사용 시 AuthV4.setup이 IDFA 메시지를 노출하므로 작성은 IDFA 메시지 작성은 기본적으로 선택사항입니다. 하지만, GDPR 메시지를 사용할 경우 IDFA 메시지 및 ATT 알림에 관한 상세 설명을 따라 IDFA 메시지를 작성해야 합니다.

GDPR 메시지와 IDFA 메시지를 작성했다면, 아래와 같이 InitializeWithShowADXConsent로 Hive Adkit을 초기화합니다.

Important

만약 Hive SDK를 사용한다면 Hive AdKit 초기화를 완료한 후에 AuthV4.setup를 실행해야 합니다. ATT(APP Tracking Transparency) 동의 알림을 노출한 후에 GDPR 동의 화면이 나타난다면 Apple 앱 심사에서 앱이 거절될 수 있습니다.

// 유럽 & 영국 지역을 타겟팅하여 상용 배포시
int debugState = 0;
HIVEAdKit.InitializeWithShowADXConsent(appId, debugState, null, adkitConsentState =>
{
    /*
    * adkitConsentState : AD(X)의 사용자 개인정보 활용 및 수집상태
    * - 0 : 동의여부가 존재하지 않는 상태
    * - 1 : 동의여부가 필요없는 지역
    * - 2 : 사용자가 개인정보 활용 및 수집을 거부한 상태
    * - 3 : 사용자가 개인정보 활용 및 수집을 동의한 상태
    */
});

/* 
 * GDPR 동의 팝업 테스트 debugState을 1로 설정하고 testDeviceId를 설정해야 GDPR 테스트 팝업이 노출됩니다.
 * Test Device의 기기 ID(testDeviceId)는 Android Logcat과 Xcode 콘솔 로그에서 확인할 수 있습니다.
 * testDeviceId는 테스트 시에만 사용합니다. 상용 배포 시에는 testDeviceId를 null로 지정해야 합니다. 
 * Android 로그 예시 : Use new ConsentDebugSettings.Builder().addTestDeviceHashedId("ABCDEFGHIJKLMNOPQRSTUVWXYZ") to set this as a debug device.
 * Xcode 로그 예시 : To enable debug mode for this device, set: UMPDebugSettings.testDeviceIdentifiers = @[ABCDEFGHIJKLMNOPQRSTUVWXYZ]
 */

int debugState = 1;
string testDeviceId = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
List testDevices = new List();
testDevices.Add(testDeviceId);

HIVEAdKit.InitializeWithShowADXConsent(appId, debugState, testDevices, adkitConsentState =>
{
    /*
    * adkitConsentState : AD(X)의 사용자 개인정보 활용 및 수집상태
    * - 0 : 동의여부가 존재하지 않는 상태
    * - 1 : 동의여부가 필요없는 지역
    * - 2 : 사용자가 개인정보 활용 및 수집을 거부한 상태
    * - 3 : 사용자가 개인정보 활용 및 수집을 동의한 상태
    */
});

Hive AdKit 초기화 시 타겟팅 지역이 유럽 및 영국(EEA & UK) 지역으로 판단되면 아래와 같이 GDPR 동의 화면이 자동으로 표시됩니다.

iOS 환경에서는 유럽 및 영국 외 지역에서 IDFA 설명 메시지를 자동으로 표시합니다.

그 외 지역 타겟

게임이 유럽과 영국 외 지역을 타겟팅할 때에는 InitializeWithSetConsentState로 초기화합니다.

/*
 * AD(X)의 사용자 개인정보 활용 및 수집상태를 설정
 * 0 : 동의여부가 존재하지 않는 상태
 * 1 : 동의여부가 필요없는 지역                                                                                                         
 * 2 : 사용자가 개인정보 활용 및 수집을 거부한 상태
 * 3 : 사용자가 개인정보 활용 및 수집을 동의한 상태
 */
int consentState = 1;
HIVEAdKit.InitializeWithSetConsentState(appId, consentState);

부가정보 설정기능

// GameData Example
[Serializable]
public class SendInfo 
{
    public int level;
    public int gold;
}
SendInfo addtionalInfo = new SendInfo();
addtionalInfo.level = 1;
addtionalInfo.gold = 100;
// JSON Obejct 형태로 전송
HIVEAdKit.SetAdditionalInfo(JsonUtility.ToJson(addtionalInfo));

Rewarded 타입 광고

// 보상형 광고 초기화
// 보상형 광고 초기화
EventHandlers eventHandlers = new EventHandlers.Builder()
                                                .OnAdLoaded(OnAdLoadedCB)
                                                .OnAdOpening(OnAdOpeningCB)
                                                .OnAdClosed(OnAdClosedCB)
                                                .OnAdFailedToLoad(OnAdFailedToLoadCB)
                                                .OnAdFailedToShow(OnAdFailedToShowCB)
                                                .OnAdReward(OnAdRewardCB)
                                                .OnPaidEvent(OnPaidEventCB)
                                                .Build();
// 인스턴스 생성
RewardVideoAd = HIVEAdKit.RewardVideo.Initialize(rewardVideoUnitId, eventHandlers);

// 보상형 광고 로드
// HIVE 애널리틱스 서버로 광고 창구 정보를 전송합니다.
if( HIVEAdKit.RewardVideo.IsInitialzed(RewardVideoAd) ) {
    HIVEAdKit.RewardVideo.LoadAd(RewardVideoAd, "광고 창구 정보");
}

// 보상형 광고 재생
// HIVE 애널리틱스 서버로 광고 창구 정보를 전송합니다.
if( HIVEAdKit.RewardVideo.IsLoaded(RewardVideoAd) ) {
    HIVEAdKit.RewardVideo.Show(RewardVideoAd, "광고 창구 정보");
}

Interstitial 타입 광고

EventHandlers eventHandlers = new EventHandlers.Builder()
                                                .OnAdLoaded(OnAdLoadedCB)
                                                .OnAdOpening(OnAdOpeningCB)
                                                .OnAdClosed(OnAdClosedCB)
                                                .OnAdFailedToLoad(OnAdFailedToLoadCB)
                                                .OnAdClick(OnAdClickCB)
                                                .OnPaidEvent(OnPaidEventCB)
                                                .Build();
// 인스턴스 생성
InterstitialAd = HIVEAdKit.Interstitial.Initialize(InterstitialAdUnitId, eventHandlers);
// 전면 광고 로드
// HIVE 애널리틱스 서버로 광고 창구 정보를 전송합니다.
if( HIVEAdKit.Interstitial.IsInitialzed(InterstitialAd) ) {
    HIVEAdKit.Interstitial.Load(InterstitialAd, "광고 창구 정보");
}
// 전면 광고 노출
// HIVE 애널리틱스 서버로 광고 창구 정보를 전송합니다.
if( HIVEAdKit.Interstitial.IsLoaded(InterstitialAd) ) {
    HIVEAdKit.Interstitial.Show(InterstitialAd, "광고 창구 정보");
}

Adaptive Banner 타입 광고

EventHandlers eventHandlers = new EventHandlers.Builder()
                                                    .OnAdLoaded(OnBannerAdLoadedCB)
                                                    .OnAdOpening(OnAdOpeningCB)
                                                    .OnAdClosed(OnAdClosedCB)
                                                    .OnAdFailedToLoad(OnAdFailedToLoadCB)
                                                    .OnAdClick(OnAdClickCB)
                                                    .OnPaidEvent(OnPaidEventCB)
                                                    .Build();
HIVEAdKit.AdaptiveBanner.AdPosition bannerPosition = HIVEAdKit.AdaptiveBanner.AdPosition.Top;
HIVEAdKit.AdaptiveBanner.AdSize adaptiveSize = HIVEAdKit.AdaptiveBanner.AdSize.AD_SIZE_320x50;
// 인스턴스 생성
AdaptiveBannerAd = HIVEAdKit.AdaptiveBanner.Initialize(AdaptiveBannerAdUnitId, adaptiveSize, bannerPosition, eventHandlers);
// 로드 및 노출
// HIVE 애널리틱스 서버로 광고 창구 정보를 전송합니다.
HIVEAdKit.AdaptiveBanner.LoadAd(AdaptiveBannerAd, "광고 창구 정보");
// 제거
HIVEAdKit.AdaptiveBanner.Destroy(AdaptiveBannerAd);

iOS 14 업데이트

iOS 14 이상 버전에 대응하는 AD(X)의 SKAdNetwork 목록입니다. 2021년 01월 29일 진행된 업데이트를 기준으로 AdKitPostprocess가 작성되었습니다. 수시 업데이트되는 항목이니 잊지 말고 확인해주세요.

Android 11 업데이트

Android 11을 지원하면서 AD(X)의 라이브러리 AndroidManifest.xml 파일에 태그가 추가되었습니다. Unity에서 빌드하는 과정에 아래와 같은 에러 로그를 확인할 경우, Unity-Android 11 대응 가이드를 확인해주세요.

  • Unity 에러 로그 예시
AndroidManifest.xml: AAPT: error: unexpected element <queries> found in <manifest>.

ADX Proguard 설정

라이브러리 AAR 파일에 Proguard 규칙 포함하여 배포되므로 별도로 설정없이 자동으로 설정됩니다.  

Unity Integrate Notice

GoogleMobileAdsSettings에 입력한 App ID가 삭제되는 경우 Unity > Assets > Google Mobile Ads > **Settings**에서 **Delay app measure**를 체크 후 다시 해제하여 주시기 바랍니다.

Gradle & Gradle Plug-in 버전 설정

Hive AdKit 1.4.4 이상 적용 시 Gradle 버전 6.7.1 이상을 권장합니다. 권장 버전 이하 사용 시 AdMob Unity 플러그인에서 "This feature requires ASM7" 오류가 발생하며 아래 방법중 하나로 해결할 수 있습니다.

  • Gradle과 Gradle Plugin 버전 변경(권장)
  • Unity 엔진 업데이트
  • android.enableDexingArtifactTransform=false를 주석 처리

Gradle과 Gradle Plugin 버전(Gradle 6.7.1+, Gradle Plugin 4.2.0+)을 변경하는 방법은 아래와 같습니다.

  1. Custom Base Gradle Template을 사용하도록 변경합니다.
    • Build Settings > Project Settings > Player > Custom Base Gradle Template를 체크합니다. Assets/Plugins/Android/baseProjectTemplate.gradle*이 생성됩니다.
  2. Gradle Plugin 버전을 변경합니다. Assets/Plugins/Android/baseProjectTemplate.gradle 파일을 열어 다음과 같이 버전을 변경합니다: com.android.tools.build:gradle:4.2.0
  3. Gradle을 다운로드합니다. 6.7.1 버전은 여기에서 다운로드 합니다. 다운로드 후, 원하는 경로(예시: ~/Users/honggd/gradle-6.7.1)에 압축을 해제합니다.
  4. Unity에서 Gradle 설치 경로를 변경합니다.
    1. Preferences > External Tools > Gradle Installed with Unity 체크 해제합니다.
    2. Gradle 압축을 해제한 경로(예시: ~/Users/honggd/gradle-6.7.1)로 설정합니다.
  5. Player > Other Settings > Identification > Target API Level에서 Target API Level이 33이상인지 확인 후 빌드합니다.

테스트 광고

개발 중에는 테스트 광고를 클릭해도 광고주에게 비용이 청구되지 않도록 설정하는 것이 중요합니다. 테스트 모드가 아닌 상태로 광고를 지나치게 많이 클릭하면 무효 활동으로 인식되고 이로 인해 해당 계정은 신고 대상이 될 수 있으니 주의하세요. 테스트 광고 이용 방법은 Google 개발자 사이트에서 확인할 수 있습니다.

삭제

Hive AdKit for AD(X)를 삭제하려면, 아래 목록의 파일과 폴더를 삭제합니다.

  • Hive AdKit 관련
  • /Assets/HIVEAdKit
  • /Assets/HIVEAdKit_Example
  • AD(X) 관련
  • /Assets/ADXLibrary
  • /Assets/GoogleMobilesAds
  • /Assets/MoPub
  • /Assets/Plugins/Android/GoogleMobileAdsPlugins
Note

AD(X) 관련 파일의 목록은 AdKit에 포함된 AD(X) 버전에 따라 달라질 수 있습니다.