새 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`(열거형)	`AdSize::Type`(열거형)
`BannerView`	`AdView`
`BannerView::Listener`	`AdListener` `AdViewBoundingBoxListener` `PaidEventListener`
`BannerView::Position`	`AdView::Position`
`BannerView::PresentationState`	삭제됨
`ChildDirectedTreatmentState`	`RequestConfiguration::TagForChildDirectedTreatment`
`Gender`(열거형)	삭제됨
`InterstitialAd::Listener`	`FullScreenContentListener` `PaidEventListener`
`KeyValuePair`	삭제됨
`NativeExpressAdView`	삭제됨
`PollableRewardListener`	삭제됨
`RewardItem`	`AdReward`
`RewardedVideoAd`(네임스페이스)	`RewardedAd`(클래스)
`RewardedVideoAd::Listener`	`FullScreenContentListener` `PaidEventListener` `UserEarnedRewardListener`
`AdMobError`(열거형)	`AdErrorCode`(열거형)
`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 Mobile Ads 매핑

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)`

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

기존 API 삭제

RewardedVideoAd

NativeExpressAds

SDK 네임스페이스 변경

네임스페이스 firebase::gma