콘텐츠로 이동

Unity

애드킷 for AD(X): Unity

애드킷은 Hive SDK와 개별 모듈 사용자가 AD(X)에서 제공하는 Unity 패키지를 적용하는 과정에서 발생하는 오류를 줄이고 편리하게 사용할 수 있도록 제작된 광고 모듈입니다.

이 가이드에서는 애드킷을 지원하는 Hive SDK 버전에 따른 적용 방법과 기능별 API 호출 방법을 안내합니다.

설치

Developers에 접속하여 애드킷을 다운로드하고 적용하세요.

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

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

업데이트

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


적용하기

iOS (Unity 2019.4 이상)

Unity 2019.4 이상에서 iOS 프로젝트 빌드 시 Dynamic Framework로 동작하는 UnityFramework 타깃이 생성됩니다.

  1. EDM4U 설정 Unity의 iOS Resolver Settings(Assets > External Dependency Manager > iOS Resolver > Settings)에서 static_framework 빌드 설정(Link frameworks statically)을 확인합니다. (1.2.171 기준) Facebook SDK는 Dynamic Framework 방식만 제공하는 반면 Podfile 설정은 두 방식 중 하나만 지원합니다. 따라서 Link frameworks statically 활성화 시, Facebook SDK를 사용하려면 아래 주석을 해제해야 합니다.

    string[] frameworksToEmbed = {
        ...
        "FBAudienceNetwork.xcframework",
    
        // 만약 Facebook SDK를 사용한다면 사용하는 SDK 종류에 따라 하단 주석을 해제하세요.
        // "FBAEMKit.xcframework",
        // ...
    };
    

    Warning
    • 반드시 현재 사용하는 Facebook SDK만 주석을 해제해야 합니다.
    • Link frameworks statically 비활성화 상태, 즉 Dynamic Framework 사용 시 주석을 해제하면 충돌이 발생할 수 있습니다.
  2. 프로젝트를 빌드합니다.

    Warning

    Xcode 프로젝트 생성 도중 pod install에 실패한 경우 위에서 Link frameworks statically 설정을 활성화했다면, 생성된 프로젝트 경로에서 직접 pod install을 수행하지 말고 Unity Editor에서 프로젝트를 다시 빌드합니다.

제공 기능

  • 보상형 광고
    • 애드킷 API와 Hive SDK 또는 개별 모듈을 함께 사용하는 경우 호출한 RewardVideo API에 따라 로그 정보 전송 여부가 결정됩니다. 로그 정보는 애널리틱스 서버로 전송되며 이 기능을 지원하는 최소 버전은 다음과 같습니다.
      • Hive SDK v4.11.0
      • Hive SDK v1.17.2
      • 개별 모듈 ModuleManager v2.6.0
      • 개별 모듈 CommonModule v1.5.0
  • Interstitial 타입 광고
  • Adaptive Banner 타입 광고

아래는 애드킷 활용 가이드입니다.

애드킷 초기화

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

유럽과 영국 타겟

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

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

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

Important

Hive SDK를 사용한다면 애드킷 초기화를 완료한 후에 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 : 사용자가 개인정보 활용 및 수집을 동의한 상태
    */
});

애드킷 초기화 시 타기팅 지역이 유럽 및 영국(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를 체크 후 다시 해제하세요.

테스트 광고

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

에러 코드

광고 실패에 대한 코드와 메시지는 AD(X)의 Ad Error 페이지에서 확인하실 수 있습니다.

삭제

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

  • 애드킷 관련
  • /Assets/HIVEAdKit
  • /Assets/HIVEAdKit_Example
  • AD(X) 관련
  • /Assets/ADXLibrary
  • /Assets/GoogleMobileAds
  • /Assets/Plugins/Android/GoogleMobileAdsPlugins
Note

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