Przeprowadź migrację do nowego pakietu SDK do reklam mobilnych Google C++

W wydaniu pakietu SDK Firebase C++ w wersji 9.1.0 wprowadzono nowy pakiet SDK do reklam mobilnych Google w języku C++.

Pakiet SDK do reklam mobilnych Google C++ to nowy interfejs API, który obejmuje najważniejsze zmiany wprowadzone w pakietach SDK Firebase AdMob C++ dla systemów iOS i Android w latach 2021 i 2022, w tym usunięcie przestarzałych interfejsów API i nowy sposób pracy z reklamami pełnoekranowymi typy.

Stary pakiet SDK Firebase AdMob C++ ( firebase::admob ) został oznaczony jako przestarzały i od tej pory nie będzie otrzymywać żadnych aktualizacji ani poprawek błędów.

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

Usuwanie starszego interfejsu API

Następujące interfejsy API zostały w całości usunięte z pakietu SDK do reklam mobilnych Google C++.

RewardedVideoAd

Przestrzeń nazw RewardedVideoAd w AdMob została zastąpiona klasą RewardedAd . RewardedAd zachowuje się podobnie do InterstitialAd , ale zawiera dodatkowego RewardedAdListener , który umożliwia otrzymywanie powiadomień o nagrodach za przedmioty.

NativeExpressAds

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

Zmiana przestrzeni nazw pakietu SDK

Zestaw 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 C++ znajdują się w przestrzeni nazw firebase::gma . Starsza przestrzeń nazw firebase::admob została wycofana wraz z pakietem SDK Firebase AdMob C++.

Struktura katalogów

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

Biblioteka

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

Migracje klas, wyliczeń i struktur

Poniższa tabela zawiera listę konkretnych klas, wyliczeń i struktur, które uległy zmianie lub zostały usunięte. Oto podsumowanie:

• Nazwa BannerView została zmieniona na AdView .
• NativeAdExpressView został usunięty.
• Przestrzeń nazw RewardedVideo zostaje zastąpiona klasą RewardedAd .
• Wyliczenie i odbiorniki PresentationState zostaną usunięte i zastąpione odbiornikami AdListener i FullScreenContent .

• Następujące parametry są usuwane jako parametry konfiguracyjne poszczególnych reklam w AdRequests :

  • konfiguracja identyfikatorów urządzeń testowych
  • targetowanie reklam ze względu na wiek

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

Inicjalizacja SDK

Każda funkcja inicjalizacji pakietu SDK do reklam mobilnych Google C++ natychmiast zwraca dwa wskaźniki stanu:

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

• Parametr zwracany jest odniesieniem do firebase::Future . Future zawiera wyniki asynchronicznej inicjalizacji adapterów mediacji na urządzeniu.

Chociaż pakiet SDK do reklam mobilnych Google C++ może zostać wywołany w celu załadowania reklam wyświetlanych przez AdMob natychmiast po przywróceniu funkcji inicjalizacji, inne sieci reklamowe nie będą wyświetlać reklam, dopóki odpowiadający im adapter mediacji nie zostanie w pełni zainicjowany. Proces ten zachodzi asynchronicznie. Dlatego też, jeśli korzystasz z pośrednictwa reklam w swojej aplikacji, zalecamy zaczekanie na rozwiązanie problemu Future przed próbą załadowania jakichkolwiek reklam.

Zanim

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 popularnych rozmiarów banerów reklamowych i obsługuje rozmiary reklam AnchorAdaptive i InlineAdaptive , które mają dynamiczną wysokość na podstawie danej szerokości i bieżącej orientacji ekranu.

Zanim

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 (wcześniej obsługiwane w przypadku urodzin) zostały usunięte z AdRequest i stanowią teraz część globalnej RequestConfiguration . Aplikacje mogą wywoływać funkcję firebase::gma::SetRequestConfiguration() na początku cyklu życia aplikacji w celu skonfigurowania tych wartości. Wszystkie kolejne operacje ładowania reklam będą uwzględniać te ustawienia po ich skonfigurowaniu.

firebase::gma::AdRequest nadal istnieje, ponieważ zapewnia informacje kontekstowe do ładowania reklam, w tym słowa kluczowe i opcjonalny adres URL zawartości.

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

Oto godne uwagi zmiany AdRequest :

• Dodatki są teraz powiązane z nazwą klasy adaptera mediacji. Dodatki wysyłane do usługi AdMob powinny używać domyślnej nazwy klasy określonej poniżej.
• Żądając reklamy, aplikacje mogą przekazać adres URL udostępnianych treści. Umożliwia to kierowanie na słowa kluczowe w celu dopasowania reklamy do innej wyświetlanej treści.

Zanim

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

W przypadku niepowodzenia AdResult zawiera obiekt AdError z informacjami na poziomie usługi dotyczącymi problemu, w tym kodem błędu, komunikatem o błędzie i ciągami domeny.

Zanim

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

Zdarzenia AdListener w AdView

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

• AdListener śledzi cykl życia reklamy i zdarzenia interakcji użytkownika.
• AdViewBoundingBoxListener jest wywoływany po zmianie rozmiaru lub przeniesieniu AdView .

AdMob OnPresentationStateChanged wywołanie zwrotne mapowania reklam mobilnych Google

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

Poniżej przedstawiono alternatywne sposoby wykrywania zmian stanu prezentacji w cyklu życia AdView :

RewardedAd jest teraz klasą

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

Słuchacze InterstitialAd i RewardedAd

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

RewardedAd ma dodatkowego słuchacza do monitorowania zdarzeń związanych z nagrodami zdobytymi przez użytkowników.

Nowe metody wywołania zwrotnego reklam pełnoekranowych

Metody zmienione/usunięte/zastąpione

W poniższej tabeli wymieniono konkretne metody zmienione w nowym pakiecie SDK do reklam mobilnych Google C++. Metody z wymienionymi parametrami pozostały, ale ich sygnatury uległy zmianie.