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:

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)