遷移到新的 Google 行動廣告 C++ SDK

Firebase C++ SDK v9.1.0 的發布引入了新的 Google 行動廣告 C++ SDK。

Google 行動廣告C++ SDK 是一個新的API 介面，融合了2021 年和2022 年對適用於iOS 和Android 的Firebase AdMob C++ SDK 所做的重大突破性更改，包括刪除已棄用的API，以及處理全螢幕廣告時的新流程類型。

舊的 Firebase AdMob C++ SDK ( firebase::admob ) 已被標記為已棄用，並且今後不會收到任何更新或錯誤修復。

在 Firebase AdMob C++ SDK 棄用期間，新版 Google 行動廣告 C++ SDK ( firebase::gma ) 和舊版 Firebase AdMob C++ SDK ( firebase::admob ) 都會保留在 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 將作為 Firebase C++ SDK 建置檔案中的靜態函式庫提供：

類別、枚舉和結構遷移

下表列出了已更改或已刪除的特定類別、枚舉和結構。總結如下：

• BannerView已重新命名為AdView 。
• NativeAdExpressView已刪除。
• RewardedVideo命名空間被RewardedAd類別取代。
• PresentationState枚舉和偵聽器被刪除並替換為AdListener和FullScreenContent偵聽器。

• 以下參數作為AdRequests中的每個廣告配置參數被刪除：

  • 測試設備ID的配置
  • 根據年齡定位廣告

  相反，現在可以在RequestConfiguration中配置這些參數，這是一個全域設置，將影響所有後續廣告載入。

SDK初始化

每個 Google 行動廣告 C++ SDK 初始化函數都會立即傳回兩個狀態指示燈：

• 可選的輸出參數表示在初始化過程開始之前是否發生依賴性錯誤。

• 傳回參數是對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廣告尺寸，它們具有基於給定寬度和螢幕當前方向的動態高度。

前

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顯著變化：

• Extras 現在與中介適配器類別名稱關聯。傳送至 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現在傳回一個Future ，其中包含所有AdView 、 InterstitialAd和RewardedAd廣告類型的AdResult物件。如果廣告要求成功完成，則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追蹤廣告生命週期和使用者互動事件。
• 當調整AdView大小或移動 AdViewBoundingBoxListener 時，將會呼叫AdViewBoundingBoxListener 。

AdMob OnPresentationStateChanged回呼 Google 行動廣告映射

新的 Google 行動廣告 C++ SDK 中不包含firebase::admob::BannerView::PresentationState枚舉類型和OnPresentationStateChanged偵聽器方法。

以下是偵測AdView生命週期中呈現狀態變化的替代方法：

RewardedAd現在是一個類

已棄用的 Firebase AdMob C++ SDK 透過firebase::admob::rewarded_ad命名空間中的一組函數促進獎勵廣告。這些函數已合併到一個新的RewardedAd類別中，該類別透過與InterstitialAd類似的 API 介面來提供廣告（請參閱下一節）。

InterstitialAd和RewardedAd監聽器

插頁式廣告和激勵廣告都被視為全螢幕廣告。可以安裝新的FullScreenContentListener來偵聽這些廣告類型的廣告生命週期事件，並且可以安裝單獨的PaidEventListener來追蹤 AdMob 服務何時認為發生了付費事件。

RewardedAd有一個額外的監聽器來監控使用者獲得的獎勵事件。

新的全螢幕廣告回檔方法

方法已更改/刪除/替換

下表列出了新版 Google 行動廣告 C++ SDK 中更改的具體方法。列出參數的方法仍然存在，但其簽名已更改。