새 Google 모바일 광고 C++ SDK로 이전하기

Firebase C++ SDK v9.1.0 출시 버전부터는 새로운 Google 모바일 광고 C++ SDK가 도입됩니다.

Google 모바일 광고 C++ SDK는 새로운 API 노출 영역으로 전체 화면 광고 유형과 작동할 때 지원 중단된 API 삭제 및 새 흐름 등 2021년 및 2022년 iOS 및 Android용 Firebase AdMob C++ SDK의 주요 브레이킹 체인지를 통합합니다.

기존 Firebase AdMob C++ SDK(firebase::admob)는 지원 중단된 것으로 표시되며 앞으로 업데이트 또는 버그 수정이 제공되지 않습니다.

새 Google 모바일 광고 C++ SDK(firebase::gma)와 이전 Firebase AdMob C++ SDK(firebase::admob)는 모두 Firebase AdMob C++ SDK 지원 중단 기간에 Firebase C++ SDK의 빌드 보관 파일의 일부로 유지됩니다.

기존 API 삭제

다음 API는 Google 모바일 광고 C++ SDK에서 완전히 삭제되었습니다.

RewardedVideoAd

AdMob의 RewardedVideoAd 네임스페이스가 RewardedAd 클래스로 대체되었습니다. RewardedAd는 InterstitialAd와 비슷하게 동작하지만 항목 리워드 알림을 받기 위한 추가 RewardedAdListener를 포함합니다.

NativeExpressAds

AdMob의 NativeExpressAd는 각 Firebase AdMob C++ SDK에서 이미 지원 중단으로 표시되었습니다. 따라서 NativeExpressAd는 새 Google 모바일 광고 C++ SDK에 포함되지 않습니다.

SDK 네임스페이스 변경

SDK가 새 네임스페이스로 다시 배치되었으며 디렉터리 구조가 다음과 같이 변경되었습니다.

네임스페이스 firebase::gma

새 Google 모바일 광고 C++ SDK의 소스는 firebase::gma 네임스페이스에 있습니다. 이전 firebase::admob 네임스페이스가 Firebase AdMob C++ SDK와 함께 지원 중단되었습니다.

디렉터리 구조

헤더 파일이 빌드 보관 파일 내의 새 디렉터리로 이동되었습니다.

지원 중단된 Firebase AdMob C++ SDK 새 Google 모바일 광고 C++ SDK
include/firebase/admob include/firebase/gma

라이브러리

Firebase AdMob C++ SDK는 Firebase C++ SDK 빌드 보관 파일 내 정적 라이브러리로 제공됩니다.

iOS

지원 중단된 Firebase AdMob C++ SDK 새 Google 모바일 광고 C++ SDK
firebase_admob.xcframework firebase_gma.xcframework

Android

지원 중단된 Firebase AdMob C++ SDK 새 Google 모바일 광고 C++ SDK
libfirebase_admob.a libfirebase_gma.a

클래스, enum 및 구조체 마이그레이션

아래 표에는 변경되었거나 삭제된 특정 클래스, enum 및 구조체가 나와 있습니다. 요약하자면 다음과 같습니다.

  • BannerView에서 AdView로 이름이 변경되었습니다.
  • NativeAdExpressView가 삭제되었습니다.
  • RewardedVideo 네임스페이스가 RewardedAd 클래스로 대체되었습니다.
  • PresentationState 열거형 및 리스너가 삭제되고 AdListener 및 FullScreenContent 리스너로 대체됩니다.

  • 다음 매개변수는 AdRequests에서 광고별 구성 매개변수로 삭제됩니다.

    • 테스트 기기 ID의 구성
    • 연령에 따른 광고 타겟팅

    이러한 매개변수는 이제 모든 후속 광고 로드에 영향을 미치는 전역 설정인 RequestConfiguration에서 구성할 수 있습니다.

지원 중단된 firebase::admob namespace 새 firebase::gma namespace
AdSizeType(enum) AdSize::Type(enum)
BannerView AdView
BannerView::Listener AdListener
AdViewBoundingBoxListener
PaidEventListener
BannerView::Position AdView::Position
BannerView::PresentationState 삭제됨
ChildDirectedTreatmentState RequestConfiguration::TagForChildDirectedTreatment
Gender(enum) 삭제됨
InterstitialAd::Listener FullScreenContentListener
PaidEventListener
KeyValuePair 삭제됨
NativeExpressAdView 삭제됨
PollableRewardListener 삭제됨
RewardItem AdReward
RewardedVideoAd(네임스페이스) RewardedAd(클래스)
RewardedVideoAd::Listener FullScreenContentListener
PaidEventListener
UserEarnedRewardListener
AdMobError(enum) AdErrorCode(enum)
RewardItem AdReward

SDK 초기화

각 Google 모바일 광고 C++ SDK 초기화 함수는 즉시 다음과 같은 두 가지 상태 표시기를 반환합니다.

  • 선택사항인 out 매개변수는 초기화 프로세스가 시작되기 전에 종속 항목 오류가 발생했는지 여부를 전달합니다.

  • 반환 매개변수는 firebase::Future의 참조입니다. Future에는 기기의 미디에이션 어댑터에 대한 비동기 초기화 결과가 포함됩니다.

Google 모바일 광고 C++ SDK를 호출하여 초기화 함수가 반환되는 즉시 AdMob 게재 광고를 로드할 수 있지만 다른 광고 네트워크에서는 해당 미디에이션 어댑터가 완전히 초기화될 때까지 광고를 게재하지 않습니다. 이 프로세스는 비동기식으로 이루어집니다. 따라서 애플리케이션에서 광고 미디에이션을 사용하는 경우 광고 로드를 시도하기 전에 Future가 해결될 때까지 기다려야 합니다.

이전

firebase::App* app = ::firebase::App::Create();
firebase::InitResult result = firebase::admob::Initialize(*app, kAdMobAppID);

if (result != kInitResultSuccess) {
  // Initialization immediately failed, most likely due to a missing dependency.
  // Check the device logs for more information.
  return;
}

이후

using firebase::App;
using firebase::Future;
using firebase::gma::AdapterInitializationStatus;

App* app = ::firebase::App::Create();
firebase::InitResult result;
Future<AdapterInitializationStatus> future =
  firebase::gma::Initialize(*app, &result);

if (result != kInitResultSuccess) {
  // Initialization immediately failed, most likely due to a missing dependency.
  // Check the device logs for more information.
  return;
}

// Poll the future to wait for its completion either in this
// thread, or as part of your game loop by calling
// firebase::gma::InitializeLastResult();
while (future.status() == firebase::kFutureStatusPending) {
  // Initialization on-going, continue to wait.
}

// future.status() is either kFutureStatusComplete or there’s an error

if (future.status() == firebase::kFutureStatusComplete &&
     future.error() == firebase::gma::AdErrorCodeNone) {
  AdapterInitializationStatus* status = future.result();
  // Check status for any mediation adapters you wish to use.
  // ..
} else {
  // Handle initialization error.
}

AdView 내에서 AdSize로 변경

이제 AdSize에 일반 배너 광고 크기의 정적 구성원이 포함되며 특정 너비 및 화면의 현재 방향에 따라 동적 높이가 있는 AnchorAdaptive 및 InlineAdaptive 광고 크기가 지원됩니다.

정적 AdSize 상수가 firebase::gma::AdSize에 추가되었습니다.

AdSize::kBanner
모바일 마케팅 협회(MMA) 배너 광고 크기(320x50 밀도 독립형 픽셀)

AdSize::kFullBanner
인터넷광고협회(IAB) 전체 배너 광고 크기(468x60 밀도 독립형 픽셀)
AdSize::kLargeBanner kBanner의 더 큰 버전, 일반적으로 320x100

AdSize::kLeaderboard
인터넷광고협회(IAB) 리더보드 광고 크기(728x90 밀도 독립형 픽셀)
AdSize::kMediumRectangle 인터넷광고협회(IAB) 중간 직사각형 광고 크기(300x250 밀도 독립형 픽셀)
AdSize의 인스턴스를 구성하는 데 도움이 되는 firebase::gma::AdSize의 정적 메서드
GetLandscapeAnchoredAdaptiveBannerAdSize 지정된 너비 및 Google에 최적화된 높이로 AdSize를 만들어 가로 모드로 배너 광고를 만듭니다.
GetPortraitAnchoredAdaptiveBannerAdSize 지정된 너비 및 Google에 최적화된 높이로 AdSize를 만들어 세로 모드로 배너 광고를 만듭니다.
GetCurrentOrientationAnchoredAdaptiveBannerAdSize 지정된 너비 및 Google에 최적화된 높이로 AdSize를 만들어 현재 방향으로 배너 광고를 만듭니다.
GetInlineAdaptiveBannerAdSize 최대 높이로 배너 광고에 가장 적합한 AdSize를 만듭니다.

이 AdSize를 사용하면 Google 서버가 지정된 최대 높이보다 작거나 같은 최적의 광고 크기를 선택할 수 있습니다.

GetLandscapeInlineAdaptiveBannerAdSize 지정된 너비 및 기기의 가로 모드 높이로 InlineAdaptive AdSize를 만듭니다.
GetPortraitInlineAdaptiveBannerAdSize 지정된 너비 및 기기의 세로 모드 높이로 InlineAdaptive AdSize를 만듭니다.
GetCurrentOrientationInlineAdaptiveBannerAdSize 특정 너비로 현재 인터페이스 방향을 고려하여 InlineAdaptive AdSize을 반환하는 편리한 메서드입니다.

이전

firebase::admob::BannerView* banner_view = new firebase::admob::BannerView();

firebase::admob::AdSize ad_size;
ad_size.ad_size_type = firebase::admob::kAdSizeStandard;
ad_size.width = 320;
ad_size.height = 50;

// ad_parent is a reference to an iOS UIView or an Android Activity.
// banner_ad_unit is your ad unit id for banner ads.
banner_view->Initialize(ad_parent, banner_ad_unit, ad_size);

이후

firebase::gma::AdView* ad_view = new firebase::gma::AdView();

// ad_parent is a reference to an iOS UIView or an Android Activity.
// banner_ad_unit is your ad unit id for banner ads.
banner_view->Initialize(ad_parent, banner_ad_unit, firebase::gma::AdSize.kBanner);

AdRequest 및 전역 구성

이전에 생일로 처리된 테스트 기기 ID, TagForChildDirectedTreatment 및 TagForUnderAgeOfConsent가 AdRequest에서 삭제되었으며 이제 전역 RequestConfiguration의 일부입니다. 애플리케이션은 애플리케이션의 수명 주기 초기에 firebase::gma::SetRequestConfiguration()을 호출하여 이러한 값을 구성할 수 있습니다. 설정이 구성되면 이후 모든 광고 로드 작업이 이러한 설정을 따릅니다.

firebase::gma::AdRequest는 키워드와 선택적 콘텐츠 URL을 포함한 광고 로드에 필요한 맥락상 정보를 제공하므로 계속 존재합니다.

AdMob의 AdRequest C스타일 구조체를 다양한 정보 목록을 정의하고 추가할 때 더 나은 사용자 환경을 제공하는 메서드의 클래스로 대체했습니다.

주목할 만한 AdRequest 변경사항은 다음과 같습니다.

  • 이제 부가 정보는 미디에이션 어댑터 클래스 이름과 연결됩니다. AdMob 서비스로 전송되는 부가 정보는 아래에 정의된 기본 클래스 이름을 사용해야 합니다.
  • 광고를 요청할 때 앱은 제공하는 콘텐츠의 URL을 전달할 수 있습니다. 이렇게 하면 키워드 타겟팅을 통해 광고와 콘텐츠를 일치시킬 수 있습니다.

이전

firebase::admob::AdRequest request;

// Keywords to be used in targeting.
const char* keywords[] = {"GMA", "C++", "Fun"};
request.keyword_count = sizeof(keywords) / sizeof(keywords[0]);
request.keywords = keywords;

// "Extra" key value pairs.
static const firebase::admob::KeyValuePair extras[] = {
      {"extra_name", "extra_value"}};
request.extras_count = sizeof(extras) / sizeof(extras[0]);
request.extras = kRequestExtras;

// Devices that should be served test ads.
const char* test_device_ids[] ={ "123", "4567", "890" };
request.test_device_id_count =
      sizeof(test_device_ids) / sizeof(test_device_ids[0]);
request.test_device_ids = test_device_ids;

// Sample birthday to help determine the age of the user.
request.birthday_day = 10;
request.birthday_month = 11;
request.birthday_year = 1975;

// Load Ad with the AdRequest.

이후

// Do once after Google Mobile Ads C++ SDK initialization.
// These settings will affect all Ad Load operations.
firebase::gma::RequestConfiguration configuration;
configuration.max_ad_content_rating =
      firebase::gma::RequestConfiguration::kMaxAdContentRatingPG;
configuration.tag_for_child_directed_treatment =
      firebase::gma::RequestConfiguration::kChildDirectedTreatmentTrue;
configuration.tag_for_under_age_of_consent =
      firebase::gma::RequestConfiguration::kUnderAgeOfConsentFalse;
configuration.test_device_ids.push_back("1234");
configuration.test_device_ids.push_back("4567");
configuration.test_device_ids.push_back("890");
firebase::gma::SetRequestConfiguration(configuration);

// Then, more information must be provided via an AdRequest when
// loading individual ads.
firebase::gma::AdRequest ad_request;

// "Extra" key value pairs.
ad_request.add_keyword("GMA");
ad_request.add_keyword("C++");
ad_request.add_keyword("Fun");

// Content URL.
ad_request.set_content_url("www.example.com");

// Mediation Adapter Extras.
#if defined(Android)
const char* ad_network_extras_class_name =
    "com/google/ads/mediation/admob/AdMobAdapter";
#else  // iOS
const char* ad_network_extras_class_name = "GADExtras";
#endif

ad_request.add_extra(ad_network_extras_class_name, "extra_name", "extra_value");

// Load Ad with the AdRequest. See next section.

AdResults

LoadAd에서 이제 모든 AdView, InterstitialAd, RewardedAd 광고 유형의 AdResult 객체가 포함된 Future를 반환합니다. AdResult::is_successful 메서드는 광고 요청이 성공적으로 처리된 경우 true를, 처리되지 않은 경우 false를 반환합니다.

실패할 경우 AdResult에는 오류 코드, 오류 메시지, 도메인 문자열 등 문제에 관한 서비스 수준의 정보가 있는 AdError 객체가 포함됩니다.

이전

firebase::Future<AdResult> future;

void load_ad() {
  // Assume an already created AdRequest object.
  future = ad_view->LoadAd(ad_request);
}

void your_game_loop() {
  if (future.status() == firebase::kFutureStatusComplete) {
    if(future.error() != firebase::admob::kAdMobErrorNone) {
      // There was either an internal SDK issue that caused the Future to
      // fail its completion, or AdMob failed to fulfill the ad request.
      // Details are unknown other than the Future’s error code returned
      // from future.error().
    } else {
      // The ad loaded successfully.
    }
  }
}

이후

firebase::Future<AdResult> future;

void load_ad() {
  // Assumes a previously created AdRequest object.
  // See "AdRequest and Global Configuration" above.
  future = ad_view->LoadAd(ad_request);
}

void your_game_loop() {
  // Check the future status in your game loop:
  if (future.status() == firebase::kFutureStatusComplete) {
    if(future.error() != firebase::admob::kAdErrorCodeNone) {
      // There was an internal SDK issue that caused the Future to fail.
    } else {
      // Future completed successfully.  Check the GMA result.
      const AdResult* ad_result = future.result();
      if ( ad_result->is_successful() != true ) {
        // GMA failed to serve an ad. Gather information about the error.
        const AdError& ad_error = ad_result->ad_error();
        AdErrorCode error_code = ad_error.code();
        const std::string error_domain = ad_error.domain();
        const std::string error_message = ad_error.message();
      } else {
        // The ad loaded successfully.
      }
    }
  }
}

AdView 내의 AdListener 이벤트

AdMob의 BannerView::Listener 클래스가 Google 모바일 광고 C++ SDK에서 두 개의 서로 다른 리스너 클래스로 대체되었습니다.

  • AdListener는 광고 수명 주기 및 사용자 상호작용 이벤트를 추적합니다.
  • AdViewBoundingBoxListener는 AdView의 크기가 조절되거나 이동될 때 호출됩니다.

AdMob OnPresentationStateChanged 콜백 Google 모바일 광고 매핑

firebase::admob::BannerView::PresentationState 열거형 유형과 OnPresentationStateChanged 리스너 메서드는 새로운 Google 모바일 광고 C++ SDK에 포함되지 않습니다.

다음은 AdView의 수명 주기에서 프레젠테이션 상태 변경을 감지하는 다른 방법입니다.

경기 firebase::admob::BannerView::Listener OnPresentationStateChanged개 firebase::gma::AdListener 대응 함수
kPresentationStateHidden AdListener::OnAdClosed가 호출되거나 AdView::Hide()가 비동기 작업을 성공적으로 완료하는 경우
kPresentationStateVisibleWithoutAd 없음 로드 취소된 AdView를 AdView::Show()에 호출하려고 하면 오류가 발생합니다.
kPresentationStateVisibleWithAd AdListener::OnAdOpened가 호출되거나 AdView::Show()가 광고와 함께 비동기 작업을 성공적으로 완료하는 경우
kPresentationStateOpenedPartialOverlay AdListener::OnAdOpened()가 호출된 후 경계 상자를 쿼리하여 표시되는 광고의 크기와 위치를 결정합니다. 또는 AdView의 위치와 AdSize를 쿼리하거나 AdViewBoundingBoxListener를 통해 경계 상자를 모니터링합니다.
kPresentationStateCoveringUI 위의 kPresentationStateOpenedPartialOverlay를 참조하세요.

RewardedAd는 지금의 클래스임

지원 중단된 Firebase AdMob C++ SDK에서 firebase::admob::rewarded_ad 네임스페이스의 함수 컬렉션을 통해 보상형 광고를 게재했습니다. 이러한 함수는 InterstitialAd과 유사한 API 노출 영역이 있는 광고를 제공하는 새로운 RewardedAd 클래스로 병합되었습니다(다음 섹션 참조).

InterstitialAd 및 RewardedAd 리스너

전면 광고와 보상형 광고는 모두 전체 화면 광고로 간주됩니다. 이러한 광고 유형의 광고 수명 주기 이벤트를 수신 대기하기 위해 새 FullScreenContentListener를 설치할 수 있고, AdMob 서비스가 유료 이벤트가 발생한 것으로 간주했을 때 추적할 수 있도록 별도의 PaidEventListener를 설치할 수 있습니다.

RewardedAd에는 사용자가 획득한 리워드 이벤트를 모니터링하는 추가 리스너가 있습니다.

새로운 전체 화면 광고 콜백 메서드

FullScreenContentListener 메서드 PaidEventListener 메서드 UserEarnedRewardListener 메서드
OnAdClicked OnPaidEvent OnUserEarnedReward
OnAdDismissedFullScreenContent
OnAdFailedToShowFullScreenContent
OnAdImpression
OnAdShowedFullScreenContent

변경/삭제/대체된 메서드

아래 표에는 새 Google 모바일 광고 C++ SDK에서 변경된 특정 메서드가 나와 있습니다. 매개변수가 나열된 메서드는 유지되지만 서명이 변경되었습니다.

클래스 Firebase AdMob C++ SDK API Google 모바일 광고 C++ SDK API 참고
BannerView MoveTo AdView::SetPosition
presentation_state 삭제됨 AdViewListener 이벤트, AdView::Show 및 AdView::Hide 향후 결과에 의해 처리됩니다.
SetListener AdView::SetAdListener
AdView::SetBoundingBoxListener
AdView::SetPaidEventListener
 새로운 리스너 설계는 AdView 수명 주기 이벤트를 감지하는 품질을 높입니다.
Listener::OnPresentationStateChanged 삭제됨 위의 BannerView::SetListener를 참조하세요.
Listener::OnBoundingBoxChanged AdViewBoundingBoxListener::OnBoundingBoxChanged
InterstitialAd Initialize(AdParent parent, const char* ad_unit_id) Initialize(AdParent parent) 이제 ad_unit_id 매개변수가 LoadAd 작업의 일부가 됩니다.
LoadAd(const AdRequest& request) LoadAd(const char* ad_unit_id, const AdRequest& request)
presentation_state 삭제됨 presentation_state 열거형이 삭제되었습니다. FullScreenContentListener를 사용합니다.
SetListener SetFullScreenContentListener
SetPaidEventListener
Destroy 삭제됨 이제 리소스 정리가 RewardedAd 소멸자의 일부입니다.
RewardedAd
(공식적으로
RewardedVideoAd) 		Initialize Initialize(AdParent parent) AdParent가 이전에 Show로 전달되었지만 이제 초기화의 일부입니다.
presentation_state 삭제됨 presentation_state 열거형이 삭제되었습니다. FullScreenContentListener를 사용합니다.
SetListener SetFullScreenContentListener
SetPaidEventListener Show 		RewardedAd를 표시할 때 UserEarnedReward 리스너도 정의됩니다. 아래를 참조하세요.
Show(AdParent parent) Show(UserEarnedRewardListener* listener)