Przejdź na nowy pakiet SDK do reklam mobilnych Google w języku C++


Wraz z wydaniem pakietu SDK Firebase C++ w wersji 9.1.0 wprowadzamy nowy pakiet SDK do reklam mobilnych Google w C++.

Pakiet SDK do reklam mobilnych Google w C++ to nowy interfejs API, który zawiera najważniejsze zmiany powodujące niezgodność wprowadzone w pakietach SDK Firebase AdMob w C++ na iOS i Androida w latach 2021 i 2022, w tym usunięcie wycofanych interfejsów API i nowy proces obsługi typów reklam pełnoekranowych.

Stary pakiet SDK Firebase AdMob C++ (firebase::admob) został oznaczony jako wycofany i nie będzie już otrzymywać aktualizacji ani poprawek błędów.

Zarówno nowy pakiet SDK do reklam mobilnych Google w C++ (firebase::gma), jak i stary pakiet SDK Firebase AdMob w C++ (firebase::admob) pozostaną częścią archiwów kompilacji pakietu SDK Firebase C++ w okresie wycofywania pakietu SDK Firebase AdMob w C++.

Usunięcie starszego interfejsu API

Z pakietu SDK do reklam mobilnych Google w C++ zostały całkowicie usunięte te interfejsy API.

RewardedVideoAd

Przestrzeń nazw RewardedVideoAd AdMob została zastąpiona klasą RewardedAd. RewardedAd działa podobnie do InterstitialAd, ale zawiera dodatkowy element RewardedAdListener, który umożliwia otrzymywanie powiadomień o nagrodach.

NativeExpressAds

Klasa NativeExpressAd AdMob została już oznaczona jako wycofana w każdym pakiecie SDK Firebase AdMob C++. Dlatego NativeExpressAd nie jest uwzględniony w nowym pakiecie SDK do reklam mobilnych Google w C++.

Zmiana przestrzeni nazw pakietu SDK

Pakiet SDK został przeniesiony do nowej przestrzeni nazw i ma nową strukturę katalogów:

Przestrzeń nazw firebase::gma

Źródła nowego pakietu SDK do reklam mobilnych Google w C++ znajdują się w przestrzeni nazw firebase::gma. Starsza przestrzeń nazw firebase::admob została wycofana wraz z pakietem SDK Firebase AdMob w C++.

Struktura katalogu

Pliki nagłówkowe zostały przeniesione do nowego katalogu w archiwum kompilacji:

Wycofany pakiet SDK Firebase AdMob C++ Nowy pakiet SDK do reklam mobilnych Google w C++
include/firebase/admob include/firebase/gma

Biblioteka

Pakiet SDK Firebase AdMob C++ będzie dostępny jako biblioteka statyczna w archiwum kompilacji pakietu SDK Firebase C++:

iOS

Wycofany pakiet SDK Firebase AdMob C++ Nowy pakiet SDK do reklam mobilnych Google w C++
firebase_admob.xcframework firebase_gma.xcframework

Android

Wycofany pakiet SDK Firebase AdMob C++ Nowy pakiet SDK do reklam mobilnych Google w C++
libfirebase_admob.a libfirebase_gma.a

Migracje klas, typów wyliczeniowych i struktur

W tabeli poniżej znajdziesz listę konkretnych klas, typów wyliczeniowych i struktur, które zostały zmienione lub usunięte. Wygląda to tak:

  • Nazwa BannerView została zmieniona na AdView.
  • Element NativeAdExpressView został usunięty.
  • Przestrzeń nazw RewardedVideo została zastąpiona klasą RewardedAd.
  • Wyliczenie i detektory PresentationState zostały usunięte i zastąpione przez detektory AdListener i FullScreenContent.
  • Te parametry zostały usunięte jako parametry konfiguracji poszczególnych reklam w AdRequests:

    • konfiguracja identyfikatorów urządzeń testowych,
    • kierowanie reklam na podstawie wieku,

    Zamiast tego te parametry można teraz skonfigurować w RequestConfiguration, co jest ustawieniem globalnym, które będzie miało wpływ na wszystkie kolejne wczytywania reklam.

Wycofane: firebase::admob namespace Nowy firebase::gma namespace
AdSizeType (typ wyliczeniowy) AdSize::Type (typ wyliczeniowy)
BannerView AdView
BannerView::Listener AdListener
AdViewBoundingBoxListener
PaidEventListener
BannerView::Position AdView::Position
BannerView::PresentationState Usunięto
ChildDirectedTreatmentState RequestConfiguration::TagForChildDirectedTreatment
Gender (typ wyliczeniowy) Usunięto
InterstitialAd::Listener FullScreenContentListener
PaidEventListener
KeyValuePair Usunięto
NativeExpressAdView Usunięto
PollableRewardListener Usunięto
RewardItem AdReward
RewardedVideoAd (przestrzeń nazw) RewardedAd (zajęcia)
RewardedVideoAd::Listener FullScreenContentListener
PaidEventListener
UserEarnedRewardListener
AdMobError (typ wyliczeniowy) AdErrorCode (typ wyliczeniowy)
RewardItem AdReward

Inicjowanie pakietu SDK

Każda funkcja inicjowania pakietu SDK do reklam mobilnych Google w C++ natychmiast zwraca 2 wskaźniki stanu:

  • Opcjonalny parametr wyjściowy informuje, czy przed rozpoczęciem procesu inicjowania wystąpił błąd zależności.

  • Zwracany parametr jest odwołaniem do firebase::Future. Future zawiera wyniki asynchronicznej inicjalizacji adapterów zapośredniczenia na urządzeniu.

Pakiet SDK do reklam mobilnych Google w C++ może zostać wywołany, aby wczytać reklamy wyświetlane przez AdMob, gdy tylko funkcja inicjowania zwróci wynik, ale inne sieci reklamowe nie będą wyświetlać reklam, dopóki ich adapter zapośredniczenia nie zostanie w pełni zainicjowany. Ten proces odbywa się asynchronicznie. Dlatego jeśli używasz zapośredniczenia reklam w aplikacji, zalecamy poczekać na rozwiązanie Future, zanim spróbujesz wczytać reklamy.

Przed

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

Po

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

Zmiany w AdSize w AdView

AdSize zawiera teraz statyczne elementy typowych rozmiarów banerów reklamowych i obsługuje rozmiary reklam AnchorAdaptive i InlineAdaptive, które mają dynamiczną wysokość zależną od podanej szerokości i bieżącej orientacji ekranu.

Dodano statyczne stałe AdSize do firebase::gma::AdSize

AdSize::kBanner

Rozmiar banera reklamowego Mobile Marketing Association (MMA) (320 x 50 pikseli niezależnych od gęstości)

AdSize::kFullBanner

Pełny baner reklamowy zgodny ze standardem IAB (Interactive Advertising Bureau) (468 x 60 pikseli niezależnych od gęstości)
AdSize::kLargeBanner Wyższa wersja formatu kBanner, zwykle 320 x 100

AdSize::kLeaderboard

Rozmiar reklamy typu długi baner zgodny ze standardem Interactive Advertising Bureau (IAB) (728 x 90 pikseli niezależnych od gęstości)
AdSize::kMediumRectangle Rozmiar reklamy zgodny ze standardem IAB (Interactive Advertising Bureau) – średni prostokąt (300 x 250 pikseli niezależnych od gęstości)
Metody statyczne w firebase::gma::AdSize, które pomagają tworzyć instancje AdSize
GetLandscapeAnchoredAdaptiveBannerAdSize Tworzy obiekt AdSize o podanej szerokości i wysokości zoptymalizowanej przez Google, aby utworzyć baner reklamowy w trybie poziomym.
GetPortraitAnchoredAdaptiveBannerAdSize Tworzy obiekt AdSize o podanej szerokości i wysokości zoptymalizowanej przez Google, aby utworzyć baner reklamowy w trybie portretowym.
GetCurrentOrientationAnchoredAdaptiveBannerAdSize Tworzy obiekt AdSize o podanej szerokości i wysokości zoptymalizowanej przez Google, aby utworzyć baner reklamowy o bieżącej orientacji.
GetInlineAdaptiveBannerAdSize Tworzy obiekt AdSize, który najlepiej nadaje się do banerów reklamowych o określonej maksymalnej wysokości.

Ten parametr AdSize umożliwia serwerom Google wybór optymalnego rozmiaru reklamy o wysokości mniejszej lub równej określonej wysokości maksymalnej.

GetLandscapeInlineAdaptiveBannerAdSize Tworzy obiekt InlineAdaptive AdSize o podanej szerokości i wysokości poziomej urządzenia
GetPortraitInlineAdaptiveBannerAdSize Tworzy obiekt InlineAdaptive AdSize o podanej szerokości i wysokości urządzenia w orientacji pionowej.
GetCurrentOrientationInlineAdaptiveBannerAdSize Wygodna metoda zwracania InlineAdaptive AdSize przy bieżącej orientacji interfejsu i określonej szerokości.

Przed

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

Po

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 i konfiguracja globalna

Identyfikatory urządzeń testowych, TagForChildDirectedTreatment i TagForUnderAgeOfConsent (które wcześniej były obsługiwane przez datę urodzenia), zostały usunięte z AdRequest i są teraz częścią globalnego RequestConfiguration. Aplikacje mogą wywoływać metodę firebase::gma::SetRequestConfiguration() na wczesnym etapie cyklu życia, aby skonfigurować te wartości. Po skonfigurowaniu tych ustawień wszystkie kolejne operacje wczytywania reklam będą je uwzględniać.

firebase::gma::AdRequest nadal istnieje, ponieważ dostarcza informacji kontekstowych na potrzeby wczytywania reklam, w tym słów kluczowych i opcjonalnego adresu URL treści.

Struktura AdMob w stylu C AdRequest została zastąpiona klasą z metodami, które zapewniają lepsze wrażenia użytkownika podczas definiowania i dołączania do różnych list informacji.

Oto najważniejsze zmiany w AdRequest:

  • Dodatki są teraz powiązane z nazwą klasy adaptera zapośredniczenia. Dodatki wysyłane do usługi AdMob powinny używać domyślnej nazwy klasy, jak określono poniżej.
  • Podczas wysyłania żądania reklamy aplikacje mogą przekazywać adres URL wyświetlanych treści. Dzięki temu kierowanie na słowa kluczowe może dopasować reklamę do innych wyświetlanych treści.

Przed

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.

Po

// 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 zwraca teraz Future zawierający obiekt AdResult dla wszystkich typów reklam AdView, InterstitialAd i RewardedAd. Metoda AdResult::is_successful zwraca wartość true, jeśli żądanie reklamy zostało zrealizowane, lub false, jeśli nie zostało zrealizowane.

W przypadku niepowodzenia AdResult zawiera obiekt AdError z informacjami o problemie na poziomie usługi, w tym kod błędu, komunikat o błędzie i ciągi znaków domeny.

Przed

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

Po

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

AdListener zdarzenia w: AdView

Klasa BannerView::Listener AdMob została zastąpiona w pakiecie SDK do reklam mobilnych Google w C++ 2 odrębnymi klasami detektorów:

  • AdListener śledzi cykl życia reklamy i zdarzenia interakcji użytkownika.
  • Funkcja AdViewBoundingBoxListener jest wywoływana, gdy rozmiar elementu AdView zostanie zmieniony lub gdy zostanie on przeniesiony.

Mapowania wywołań zwrotnych Google Mobile Ads w AdMob OnPresentationStateChanged

Typ wyliczeniowy firebase::admob::BannerView::PresentationState i metoda detektora OnPresentationStateChanged nie są uwzględnione w nowym pakiecie SDK do reklam mobilnych Google w C++.

Oto alternatywne sposoby wykrywania zmian stanu prezentacji w cyklu życia obiektu AdView:

firebase::admob::BannerView::Listener OnPresentationStateChanged zdarzenie firebase::gma::AdListener odpowiednik
kPresentationStateHidden Gdy wywoływana jest funkcja AdListener::OnAdClosed lub gdy AdView::Hide() pomyślnie kończy operację asynchroniczną
kPresentationStateVisibleWithoutAd Brak. Próba wywołania AdView::Show() niezaładowanego AdView spowoduje błąd.
kPresentationStateVisibleWithAd Gdy wywoływana jest metoda AdListener::OnAdOpened lub gdy metoda AdView::Show() pomyślnie kończy operację asynchroniczną z reklamą
kPresentationStateOpenedPartialOverlay Po wywołaniu metody AdListener::OnAdOpened() wyślij zapytanie o ramkę ograniczającą, aby określić rozmiar i położenie wyświetlanej reklamy. Możesz też sprawdzić pozycję AdView i AdSize lub monitorować ramkę ograniczającą za pomocą AdViewBoundingBoxListener.
kPresentationStateCoveringUI Zobacz: kPresentationStateOpenedPartialOverlay powyżej

RewardedAd jest teraz klasą

Wycofany pakiet SDK Firebase AdMob C++ obsługiwał reklamy z nagrodą za pomocą zbioru funkcji w przestrzeni nazw firebase::admob::rewarded_ad. Te funkcje zostały połączone w nową klasę RewardedAd, która wyświetla reklamy z interfejsem API podobnym do InterstitialAd (patrz następna sekcja).

InterstitialAd i RewardedAd detektorów

Zarówno reklamy pełnoekranowe, jak i reklamy z nagrodą są uważane za reklamy pełnoekranowe. Można zainstalować nowy element FullScreenContentListener, aby nasłuchiwać zdarzeń cyklu życia reklamy w przypadku tych typów reklam, oraz osobny element PaidEventListener, aby śledzić, kiedy usługa AdMob uzna, że wystąpiło zdarzenie płatne.

RewardedAd ma dodatkowy detektor do monitorowania zdarzeń po otrzymaniu nagrody przez użytkowników.

Nowe metody wywołania zwrotnego reklam pełnoekranowych

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

Metody zmienione, usunięte lub zastąpione

W tabeli poniżej znajdziesz listę metod, które uległy zmianie w nowym pakiecie SDK do reklam mobilnych Google w języku C++. Metody z wymienionymi parametrami pozostają, ale ich sygnatury uległy zmianie.

Klasa Interfejs API pakietu SDK Firebase AdMob C++ Interfejs API pakietu SDK do reklam mobilnych Google w C++ Uwagi
BannerView MoveTo AdView::SetPosition
presentation_state Usunięto Obsługiwane przez zdarzenia AdViewListener oraz wyniki AdView::Show i AdView::Hide w przyszłości.
SetListener AdView::SetAdListener
AdView::SetBoundingBoxListener
AdView::SetPaidEventListener
Nowy projekt detektora zwiększa dokładność wykrywania zdarzeń cyklu życia AdView.
Listener::OnPresentationStateChanged Usunięto Zobacz BannerView::SetListener powyżej.
Listener::OnBoundingBoxChanged AdViewBoundingBoxListener::OnBoundingBoxChanged
InterstitialAd Initialize(AdParent parent, const char* ad_unit_id) Initialize(AdParent parent) Parametr ad_unit_id jest teraz częścią operacji LoadAd.
LoadAd(const AdRequest& request) LoadAd(const char* ad_unit_id, const AdRequest& request)
presentation_state Usunięto Wyliczenie presentation_state zostało usunięte. Użyj FullScreenContentListener.
SetListener SetFullScreenContentListener
SetPaidEventListener
Destroy Usunięto Czyszczenie zasobów jest teraz częścią destruktora RewardedAd.
RewardedAd
(formalnie
RewardedVideoAd)
Initialize Initialize(AdParent parent) Wartość AdParent była wcześniej przekazywana do Show, ale teraz jest częścią inicjowania.
presentation_state Usunięto Wyliczenie presentation_state zostało usunięte. Użyj FullScreenContentListener.
SetListener SetFullScreenContentListener
SetPaidEventListener Show
Podczas wyświetlania elementu RewardedAd definiowany jest też detektor UserEarnedReward. Szczegółowe informacje znajdziesz poniżej.
Show(AdParent parent) Show(UserEarnedRewardListener* listener)