Hive Adkit for AD(X): Unity

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

설치

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

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

업데이트

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

적용하기

iOS (Unity 2019.4 이상)

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

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

에디터에서 Podfile을 열어 파일 설정을 확인합니다.


        source 'https://github.com/adxcorp/AdxLibrary_iOS_Release.git'
        source 'https://cdn.cocoapods.org/'
               
        platform :ios, '12.0'
               
        target 'UnityFramework' do
            pod 'ADXLibrary/UnityPlugin', '2.5.4'
            pod 'Google-Mobile-Ads-SDK', '~> 11.2'
        end
        target 'Unity-iPhone' do
        end
        use_frameworks!

source 'https://github.com/adxcorp/AdxLibrary_iOS_Release.git'

source 'https://cdn.cocoapods.org/'

platform :ios, '12.0'

target 'UnityFramework' do

pod 'ADXLibrary/UnityPlugin', '2.5.4'

pod 'Google-Mobile-Ads-SDK', '~> 11.2'

end

target 'Unity-iPhone' do

end

use_frameworks!

Xcode 설정을 진행하세요.

제공 기능

보상형 광고
- 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 메시지를 작성하세요.

GDPR 메시지 작성 완료 후, 아래와 같이 InitializeWithShowADXConsent로 Hive Adkit을 초기화합니다.


// 유럽 & 영국 지역을 타겟팅하여 상용 배포시
int debugState = 0;
HIVEAdKit.InitializeWithShowADXConsent(appId, debugState, null);

/* 
 * 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 로그 예시 : <UMP SDK>To enable debug mode for this device, set: UMPDebugSettings.testDeviceIdentifiers = @[ABCDEFGHIJKLMNOPQRSTUVWXYZ]
 */
 
int debugState = 1;
string testDeviceId = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";

List<string> testDevices = new List<string>();
testDevices.Add(testDeviceId);
 
HIVEAdKit.InitializeWithShowADXConsent(appId, debugState, testDevices);

// 유럽 & 영국 지역을 타겟팅하여 상용 배포시

int debugState = 0;

HIVEAdKit.InitializeWithShowADXConsent(appId, debugState, null);

* 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 로그 예시 : <UMP SDK>To enable debug mode for this device, set: UMPDebugSettings.testDeviceIdentifiers = @[ABCDEFGHIJKLMNOPQRSTUVWXYZ]

int debugState = 1;

string testDeviceId = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";

List<string> testDevices = new List<string>();

testDevices.Add(testDeviceId);

HIVEAdKit.InitializeWithShowADXConsent(appId, debugState, testDevices);

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

그 외 지역 타겟

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


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

* 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));

// 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, "광고 창구 정보");
}

// 보상형 광고 초기화

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, "광고 창구 정보");
}

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)
                                                    .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);

EventHandlers eventHandlers = new EventHandlers.Builder()

.OnAdLoaded(OnBannerAdLoadedCB)

.OnAdOpening(OnAdOpeningCB)

.OnAdClosed(OnAdClosedCB)

.OnAdFailedToLoad(OnAdFailedToLoadCB)

.OnAdClick(OnAdClickCB)

.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가 작성되었습니다. 수시 업데이트되는 항목이니 잊지 말고 확인해주세요.

SKAdNetwork 업데이트 확인하기
- https://github.com/adxcorp/ADXLibrary_Integration/wiki/SKAdNetwork-ID-List

Android 11 업데이트

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

Unity 에러 로그 예시

AndroidManifest.xml: AAPT: error: unexpected element <queries> found in <manifest>.

1	AndroidManifest.xml: AAPT: error: unexpected element <queries> found in <manifest>.

Unity-Android 11 대응 가이드
- https://developers.google.com/ar/develop/unity/android-11-build

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+)을 변경하는 방법은 아래와 같습니다.

Custom Base Gradle Template을 사용하도록 변경합니다.
- Build Settings > Project Settings > Player > Custom Base Gradle Template를 체크합니다.
- Assets/Plugins/Android/baseProjectTemplate.gradle이 생성됩니다.
Gradle Plugin 버전을 변경합니다. Assets/Plugins/Android/baseProjectTemplate.gradle 파일을 열어 다음과 같이 버전을 변경합니다: com.android.tools.build:gradle:4.2.0
Gradle을 다운로드합니다. 6.7.1 버전은 여기에서 다운로드 합니다. 다운로드 후, 원하는 경로(예시: ~/Users/honggd/gradle-6.7.1)에 압축을 해제합니다.
Unity에서 Gradle 설치 경로를 변경합니다.
1. Preferences > External Tools > Gradle Installed with Unity 체크 해제합니다.
2. Gradle 압축을 해제한 경로(예시: ~/Users/honggd/gradle-6.7.1)로 설정합니다.
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

Hive Adkit for AD(X): Unity

설치

업데이트

적용하기

iOS (Unity 2019.4 이상)

제공 기능

Hive AdKit 초기화

유럽과 영국 타겟

그 외 지역 타겟

부가정보 설정기능

Rewarded 타입 광고

Interstitial 타입 광고

Adaptive Banner 타입 광고

iOS 14 업데이트

Android 11 업데이트

ADX Proguard 설정

Unity Integrate Notice

Gradle & Gradle Plug-in 버전 설정

테스트 광고

삭제

시작하기

SDK 개발

콘솔 가이드

다운로드

API 문서

지원