Migrasi ke Google Mobile Ads C++ SDK baru

Rilis Firebase C++ SDK v9.1.0 memperkenalkan Google Mobile Ads C++ SDK baru.

Google Mobile Ads C++ SDK adalah platform API baru yang menggabungkan perubahan besar yang dapat menyebabkan gangguan ke Firebase AdMob C++ SDK untuk iOS dan Android pada tahun 2021 dan 2022, termasuk penghapusan API yang tidak digunakan lagi, dan alur baru saat bekerja dengan jenis iklan layar penuh.

Firebase AdMob C++ SDK lama (firebase::admob) telah ditandai sebagai tidak digunakan lagi dan tidak akan menerima update atau perbaikan bug ke depannya.

Google Mobile Ads C++ SDK baru (firebase::gma) dan Firebase AdMob C++ SDK lama (firebase::admob) akan tetap menjadi bagian dari arsip build untuk Firebase C++ SDK selama periode penghentian penggunaan Firebase AdMob C++ SDK.

Penghapusan API lama

API berikut telah dihapus dari Google Mobile Ads C++ SDK secara keseluruhan.

RewardedVideoAd

Namespace RewardedVideoAd AdMob telah diganti dengan class RewardedAd. RewardedAd berperilaku mirip dengan InterstitialAd, tetapi menyertakan RewardedAdListener tambahan untuk menerima notifikasi reward item.

NativeExpressAds

NativeExpressAd AdMob telah ditandai sebagai tidak digunakan lagi di setiap Firebase AdMob C++ SDK. Oleh karena itu, NativeExpressAd tidak disertakan dalam Google Mobile Ads C++ SDK baru.

Perubahan namespace SDK

SDK telah dipindahkan ke namespace baru, dan memiliki struktur direktori baru:

Namespace firebase::gma

Sumber Google Mobile Ads C++ SDK baru ada di namespace firebase::gma. Namespace firebase::admob yang lebih lama tidak digunakan lagi bersama dengan Firebase AdMob C++ SDK.

Struktur direktori

File header telah dipindahkan ke direktori baru di dalam arsip build:

Firebase AdMob C++ SDK yang tidak digunakan lagi Google Mobile Ads C++ SDK baru
include/firebase/admob include/firebase/gma

Library

Firebase AdMob C++ SDK akan disediakan sebagai library statis dalam arsip build Firebase C++ SDK:

iOS

Firebase AdMob C++ SDK yang tidak digunakan lagi Google Mobile Ads C++ SDK baru
firebase_admob.xcframework firebase_gma.xcframework

Android

Firebase AdMob C++ SDK yang tidak digunakan lagi Google Mobile Ads C++ SDK baru
libfirebase_admob.a libfirebase_gma.a

Migrasi class, enum, dan struct

Tabel di bawah ini mencantumkan class, enum, dan struct tertentu yang berubah atau telah dihapus. Berikut ringkasannya:

  • BannerView diganti namanya menjadi AdView.
  • NativeAdExpressView dihapus.
  • Namespace RewardedVideo diganti dengan class RewardedAd.
  • Enumerasi dan pemroses PresentationState dihapus dan diganti dengan pemroses AdListener dan FullScreenContent.

  • Parameter berikut dihapus sebagai parameter konfigurasi per iklan di AdRequests:

    • konfigurasi ID perangkat pengujian
    • penargetan iklan berdasarkan usia

    Namun, kini parameter tersebut dapat dikonfigurasikan di RequestConfiguration yang merupakan setelan global dan akan memengaruhi semua kepadatan iklan berikutnya.

Tidak digunakan lagi firebase::admob namespace Baru firebase::gma namespace
AdSizeType (enum) AdSize::Type (enum)
BannerView AdView
BannerView::Listener AdListener
AdViewBoundingBoxListener
PaidEventListener
BannerView::Position AdView::Position
BannerView::PresentationState Dihapus
ChildDirectedTreatmentState RequestConfiguration::TagForChildDirectedTreatment
Gender (enum) Dihapus
InterstitialAd::Listener FullScreenContentListener
PaidEventListener
KeyValuePair Dihapus
NativeExpressAdView Dihapus
PollableRewardListener Dihapus
RewardItem AdReward
RewardedVideoAd (namespace) RewardedAd (class)
RewardedVideoAd::Listener FullScreenContentListener
PaidEventListener
UserEarnedRewardListener
AdMobError (enum) AdErrorCode (enum)
RewardItem AdReward

Inisialisasi SDK

Setiap fungsi inisialisasi Google Mobile Ads C++ SDK akan langsung menampilkan dua indikator status:

  • Parameter keluar opsional menyampaikan apakah error dependensi terjadi sebelum proses inisialisasi dimulai.

  • Parameter yang ditampilkan adalah referensi ke firebase::Future. Future berisi hasil inisialisasi asinkron dari adaptor mediasi di perangkat.

Meskipun Google Mobile Ads C++ SDK dapat dipanggil untuk memuat iklan yang ditayangkan AdMob segera setelah fungsi inisialisasi ditampilkan, jaringan iklan lain tidak akan menayangkan iklan sampai adaptor mediasi yang sesuai telah diinisialisasi sepenuhnya. Proses ini terjadi secara asinkron. Oleh karena itu, jika Anda menggunakan mediasi iklan di aplikasi, sebaiknya tunggu Future selesai sebelum mencoba memuat iklan apa pun.

Sebelum

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;
}

Sesudah

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.
}

Perubahan pada AdSize dalam AdView

AdSize kini berisi anggota statis dari ukuran iklan banner yang umum, dan mendukung ukuran iklan AnchorAdaptive dan InlineAdaptive yang memiliki tinggi dinamis berdasarkan lebar yang diberikan dan orientasi layar saat ini.

Konstanta AdSize statis ditambahkan ke firebase::gma::AdSize

AdSize::kBanner
Ukuran iklan banner Mobile Marketing Association (MMA) (piksel kepadatan mandiri 320x50)

AdSize::kFullBanner
Ukuran iklan banner penuh Interactive Advertising Bureau (IAB) (piksel kepadatan mandiri 468x60)
AdSize::kLargeBanner Versi kBanner yang lebih tinggi, biasanya berukuran 320x100

AdSize::kLeaderboard
Ukuran iklan banner utama Interactive Advertising Bureau (IAB) (piksel kepadatan mandiri 728x90)
AdSize::kMediumRectangle Ukuran iklan kotak sedang Interactive Advertising Bureau (IAB) (piksel kepadatan mandiri 300x250)
Metode statis dalam firebase::gma::AdSize untuk membantu membuat instance AdSize
GetLandscapeAnchoredAdaptiveBannerAdSize Membuat AdSize dengan lebar yang diberikan dan tinggi yang dioptimalkan Google untuk membuat iklan banner dalam mode lanskap
GetPortraitAnchoredAdaptiveBannerAdSize Membuat AdSize dengan lebar yang diberikan dan tinggi yang dioptimalkan Google untuk membuat iklan banner dalam mode potret
GetCurrentOrientationAnchoredAdaptiveBannerAdSize Membuat AdSize dengan lebar yang diberikan dan tinggi yang dioptimalkan Google untuk membuat iklan banner dengan orientasi saat ini
GetInlineAdaptiveBannerAdSize Membuat AdSize yang paling sesuai untuk iklan banner dengan tinggi maksimum

Dengan AdSize, server Google dapat memilih ukuran iklan yang optimal dengan tinggi kurang dari atau sama dengan tinggi maksimum yang ditentukan.

GetLandscapeInlineAdaptiveBannerAdSize Membuat InlineAdaptive AdSize dengan lebar yang diberikan dan tinggi lanskap perangkat
GetPortraitInlineAdaptiveBannerAdSize Membuat InlineAdaptive AdSize dengan lebar yang diberikan dan tinggi potret perangkat.
GetCurrentOrientationInlineAdaptiveBannerAdSize Metode praktis untuk menampilkan InlineAdaptive AdSize dengan orientasi antarmuka saat ini yang diberi lebar tertentu.

Sebelum

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

Sesudah

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 dan konfigurasi global

ID perangkat pengujian, TagForChildDirectedTreatment, dan TagForUnderAgeOfConsent (sebelumnya ditangani berdasarkan tanggal lahir) telah dihapus dari AdRequest dan kini menjadi bagian dari RequestConfiguration global. Aplikasi dapat memanggil firebase::gma::SetRequestConfiguration() lebih awal dalam siklus proses aplikasi untuk mengonfigurasi nilai ini. Semua operasi pemuatan iklan berikutnya akan mengikuti setelan ini setelah dikonfigurasi.

firebase::gma::AdRequest masih ada karena memberikan informasi kontekstual untuk memuat iklan, termasuk kata kunci dan URL konten opsional.

Struct C-style AdRequest AdMob telah diganti dengan class dengan metode yang memberikan pengalaman pengguna yang lebih baik saat menentukan dan menambahkan ke berbagai daftar informasi.

Berikut perubahan AdRequest yang penting:

  • Tambahan kini dikaitkan dengan nama class adaptor mediasi. Tambahan yang dikirim ke layanan AdMob harus menggunakan nama class default seperti yang dijelaskan di bawah ini.
  • Ketika meminta iklan, aplikasi dapat meneruskan URL konten yang ditampilkan. Hal ini memungkinkan penargetan kata kunci agar sesuai dengan iklan beserta konten lain yang ditampilkan.

Sebelum

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.

Sesudah

// 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 kini menampilkan Future yang berisi objek AdResult untuk semua jenis iklan AdView, InterstitialAd, dan RewardedAd. Metode AdResult::is_successful menampilkan true jika permintaan iklan berhasil dipenuhi, atau false jika tidak.

Jika gagal, AdResult akan berisi objek AdError dengan informasi tingkat layanan tentang masalah tersebut, termasuk kode error, pesan error, dan string domain.

Sebelum

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.
    }
  }
}

Sesudah

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.
      }
    }
  }
}

Peristiwa AdListener dalam AdView

Class BannerView::Listener AdMob telah diganti dengan dua class pemroses yang berbeda di Google Mobile Ads C++ SDK:

  • AdListener melacak peristiwa siklus proses iklan dan interaksi pengguna.
  • AdViewBoundingBoxListener dipanggil saat AdView diubah ukurannya atau dipindahkan.

Pemetaan Google Mobile Ads terkait callback OnPresentationStateChanged AdMob

Jenis enumerasi firebase::admob::BannerView::PresentationState dan metode pemroses OnPresentationStateChanged tidak disertakan dalam Google Mobile Ads C++ SDK baru.

Berikut adalah alternatif untuk mendeteksi perubahan status presentasi dalam siklus proses AdView:

Peristiwa firebase::admob::BannerView::Listener OnPresentationStateChanged Ekuivalen firebase::gma::AdListener
kPresentationStateHidden Saat AdListener::OnAdClosed dipanggil, atau saat AdView::Hide() berhasil menyelesaikan operasi asinkronnya
kPresentationStateVisibleWithoutAd Tidak ada. Mencoba memanggil AdView::Show() AdView yang tidak dimuat akan menghasilkan error.
kPresentationStateVisibleWithAd Saat AdListener::OnAdOpened dipanggil, atau saat AdView::Show() berhasil menyelesaikan operasi asinkronnya dengan iklan
kPresentationStateOpenedPartialOverlay Buat kueri kotak pembatas setelah AdListener::OnAdOpened() dipanggil untuk menentukan ukuran dan posisi iklan yang ditampilkan. Atau, buat kueri posisi AdView dan AdSize serta/atau pantau kotak pembatas melalui AdViewBoundingBoxListener.
kPresentationStateCoveringUI Lihat kPresentationStateOpenedPartialOverlay di atas

RewardedAd kini menjadi class

Firebase AdMob C++ SDK yang tidak digunakan lagi memfasilitasi iklan reward melalui kumpulan fungsi di namespace firebase::admob::rewarded_ad. Fungsi ini telah digabungkan ke dalam class RewardedAd baru yang menayangkan iklan dengan platform API yang serupa dengan InterstitialAd (lihat bagian berikutnya).

Pemroses InterstitialAd dan RewardedAd

Iklan interstisial dan iklan reward dianggap sebagai iklan layar penuh. FullScreenContentListener baru dapat diinstal untuk memproses peristiwa siklus proses iklan untuk jenis iklan ini, dan PaidEventListener terpisah dapat diinstal untuk melacak kapan layanan AdMob menganggap pembayaran sudah terjadi.

RewardedAd memiliki pemroses tambahan untuk memantau peristiwa reward yang diperoleh pengguna.

Metode callback iklan layar penuh baru

Metode FullScreenContentListener Metode PaidEventListener Metode UserEarnedRewardListener
OnAdClicked OnPaidEvent OnUserEarnedReward
OnAdDismissedFullScreenContent
OnAdFailedToShowFullScreenContent
OnAdImpression
OnAdShowedFullScreenContent

Metode diubah/dihapus/diganti

Tabel di bawah ini mencantumkan metode tertentu yang diubah dalam Google Mobile Ads C++ SDK baru. Metode dengan parameter yang tercantum tetap ada, tetapi ciri khasnya telah berubah.

Class API Firebase AdMob C++ SDK API Google Mobile Ads C++ SDK Catatan
BannerView MoveTo AdView::SetPosition
presentation_state Dihapus Ditangani oleh peristiwa AdViewListener serta hasil AdView::Show dan AdView::Hide pada masa mendatang.
SetListener AdView::SetAdListener
AdView::SetBoundingBoxListener
AdView::SetPaidEventListener
 Desain pemroses baru meningkatkan fidelitas pendeteksian peristiwa siklus proses AdView.
Listener::OnPresentationStateChanged Dihapus Lihat BannerView::SetListener, di atas.
Listener::OnBoundingBoxChanged AdViewBoundingBoxListener::OnBoundingBoxChanged
InterstitialAd Initialize(AdParent parent, const char* ad_unit_id) Initialize(AdParent parent) Parameter ad_unit_id kini menjadi bagian dari operasi LoadAd.
LoadAd(const AdRequest& request) LoadAd(const char* ad_unit_id, const AdRequest& request)
presentation_state Dihapus Enumerasi presentation_state telah dihapus. Gunakan FullScreenContentListener.
SetListener SetFullScreenContentListener
SetPaidEventListener
Destroy Dihapus Membersihkan resource kini menjadi bagian dari destruktor RewardedAd.
RewardedAd
(secara resmi
RewardedVideoAd) 		Initialize Initialize(AdParent parent) AdParent sebelumnya diteruskan ke Show, tetapi kini menjadi bagian dari inisialisasi.
presentation_state Dihapus Enumerasi presentation_state telah dihapus. Gunakan FullScreenContentListener.
SetListener SetFullScreenContentListener
SetPaidEventListener Show 		Pemroses UserEarnedReward juga ditentukan saat menampilkan RewardedAd. Lihat di bawah.
Show(AdParent parent) Show(UserEarnedRewardListener* listener)