Di chuyển sang SDK C++ quảng cáo trên thiết bị di động của Google mới

Việc phát hành SDK Firebase C++ v9.1.0 giới thiệu SDK C++ quảng cáo trên thiết bị di động của Google mới.

SDK C++ quảng cáo trên thiết bị di động của Google là một bề mặt API mới kết hợp các thay đổi quan trọng được thực hiện đối với SDK Firebase AdMob C++ dành cho iOS và Android vào năm 2021 và 2022, bao gồm cả việc xóa các API không còn được dùng nữa và một quy trình mới khi làm việc với quảng cáo toàn màn hình các loại.

SDK Firebase AdMob C++ cũ ( firebase::admob ) đã được đánh dấu là không dùng nữa và sẽ không nhận được bất kỳ bản cập nhật hoặc bản sửa lỗi nào kể từ bây giờ.

Cả SDK C++ quảng cáo trên thiết bị di động của Google mới ( firebase::gma ) và SDK Firebase AdMob C++ cũ ( firebase::admob ) sẽ vẫn là một phần của bản lưu trữ bản dựng cho SDK Firebase C++ trong thời gian ngừng sử dụng SDK Firebase AdMob C++.

Xóa API cũ

Các API sau đây đã bị xóa toàn bộ khỏi SDK C++ quảng cáo trên thiết bị di động của Google.

RewardedVideoAd

Vùng chứa tên RewardedVideoAd của AdMob đã được thay thế bằng lớp RewardedAd . RewardedAd hoạt động tương tự như InterstitialAd nhưng bao gồm RewardedAdListener bổ sung để nhận thông báo về phần thưởng vật phẩm.

NativeExpressAds

NativeExpressAd của AdMob đã được đánh dấu là không được dùng nữa trong mỗi SDK AdMob C++ của Firebase. Do đó, NativeExpressAd không được đưa vào SDK C++ quảng cáo trên thiết bị di động của Google mới.

Thay đổi không gian tên SDK

SDK đã chuyển sang một không gian tên mới và có cấu trúc thư mục mới:

Không gian tên firebase::gma

Các nguồn của SDK C++ quảng cáo trên thiết bị di động của Google mới nằm trong vùng tên firebase::gma . Không gian tên firebase::admob cũ hơn đã không được dùng nữa cùng với SDK Firebase AdMob C++.

Cấu trúc thư mục

Các tệp tiêu đề đã được chuyển đến một thư mục mới bên trong kho lưu trữ bản dựng:

Thư viện

SDK Firebase AdMob C++ sẽ được cung cấp dưới dạng thư viện tĩnh trong kho lưu trữ bản dựng SDK Firebase C++:

Di chuyển lớp, enum và struct

Bảng bên dưới liệt kê các lớp, enum và cấu trúc cụ thể đã thay đổi hoặc đã bị xóa. Đây là một bản tóm tắt:

• BannerView được đổi tên thành AdView .
• NativeAdExpressView bị xóa.
• Không gian tên RewardedVideo được thay thế bằng lớp RewardedAd .
• Bảng liệt kê và trình nghe PresentationState bị xóa và thay thế bằng trình nghe AdListener và FullScreenContent .

• Các tham số sau đây sẽ bị xóa dưới dạng tham số cấu hình cho mỗi quảng cáo trong AdRequests :

  • cấu hình ID thiết bị thử nghiệm
  • nhắm mục tiêu quảng cáo dựa trên độ tuổi

  Thay vào đó, giờ đây bạn có thể định cấu hình các tham số này RequestConfiguration . Đây là cài đặt chung sẽ ảnh hưởng đến tất cả các lần tải quảng cáo tiếp theo.

Khởi tạo SDK

Mỗi chức năng khởi chạy SDK C++ quảng cáo trên thiết bị di động của Google ngay lập tức trả về hai chỉ báo trạng thái:

• Tham số out tùy chọn cho biết liệu có xảy ra lỗi phụ thuộc hay không trước khi quá trình khởi tạo bắt đầu.

• Tham số trả về là tham chiếu đến firebase::Future . Future chứa kết quả khởi tạo không đồng bộ của bộ điều hợp dàn xếp trên thiết bị.

Mặc dù SDK C++ quảng cáo trên thiết bị di động của Google có thể được gọi để tải quảng cáo do AdMob phân phát ngay khi chức năng khởi chạy hoạt động trở lại, nhưng các mạng quảng cáo khác sẽ không phân phát quảng cáo cho đến khi bộ điều hợp dàn xếp tương ứng của chúng được khởi chạy hoàn toàn. Quá trình này xảy ra không đồng bộ. Do đó, nếu bạn đang sử dụng dàn xếp quảng cáo trong ứng dụng của mình, chúng tôi khuyên bạn nên đợi Future giải quyết trước khi thử tải bất kỳ quảng cáo nào.

Trước

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

Sau đó

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

Những thay đổi đối với AdSize trong AdView

AdSize hiện chứa các thành phần tĩnh của các kích thước quảng cáo biểu ngữ phổ biến và hỗ trợ các kích thước quảng cáo AnchorAdaptive và InlineAdaptive có chiều cao động dựa trên chiều rộng nhất định và hướng hiện tại của màn hình.

Trước

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

Sau đó

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 và cấu hình chung

ID thiết bị thử nghiệm, TagForChildDirectedTreatment và TagForUnderAgeOfConsent (trước đây được xử lý theo ngày sinh) đã bị xóa khỏi AdRequest và hiện là một phần của RequestConfiguration cầu. Các ứng dụng có thể gọi firebase::gma::SetRequestConfiguration() ngay từ đầu trong vòng đời của ứng dụng để định cấu hình các giá trị này. Tất cả các thao tác tải quảng cáo tiếp theo sẽ tuân theo các cài đặt này sau khi chúng được định cấu hình.

firebase::gma::AdRequest vẫn tồn tại vì nó cung cấp thông tin theo ngữ cảnh để tải quảng cáo, bao gồm từ khóa và URL nội dung tùy chọn.

Cấu trúc kiểu C AdRequest của AdMob đã được thay thế bằng một lớp có các phương thức mang lại trải nghiệm người dùng tốt hơn khi xác định và thêm vào các danh sách thông tin khác nhau.

Dưới đây là những thay đổi AdRequest đáng chú ý:

• Các tính năng bổ sung hiện được liên kết với tên lớp của bộ chuyển đổi dàn xếp. Các phần bổ sung được gửi tới dịch vụ AdMob phải sử dụng tên lớp mặc định như được xác định bên dưới.
• Khi yêu cầu quảng cáo, ứng dụng có thể chuyển URL của nội dung mà chúng đang phân phát. Điều này cho phép nhắm mục tiêu theo từ khóa khớp quảng cáo với nội dung khác đang được hiển thị.

Trước

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.

Sau đó

// 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 hiện trả về Future chứa đối tượng AdResult cho tất cả các loại quảng cáo AdView , InterstitialAd và RewardedAd . Phương thức AdResult::is_successful trả về true nếu yêu cầu quảng cáo được thực hiện thành công hoặc false nếu không.

Khi không thành công, AdResult chứa đối tượng AdError với thông tin cấp dịch vụ về sự cố, bao gồm mã lỗi, thông báo lỗi và chuỗi miền.

Trước

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

Sau đó

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

Sự kiện AdListener trong AdView

Lớp BannerView::Listener của AdMob đã được thay thế bằng hai lớp trình nghe riêng biệt trong SDK C++ quảng cáo trên thiết bị di động của Google:

• AdListener theo dõi vòng đời quảng cáo và các sự kiện tương tác của người dùng.
• AdViewBoundingBoxListener được gọi khi AdView được thay đổi kích thước hoặc di chuyển.

AdMob OnPresentationStateChanged thay đổi lệnh gọi lại ánh xạ Quảng cáo trên thiết bị di động của Google

Loại liệt kê firebase::admob::BannerView::PresentationState và phương thức trình nghe OnPresentationStateChanged không được đưa vào SDK C++ quảng cáo trên thiết bị di động của Google mới.

Sau đây là những cách khác để phát hiện các thay đổi trạng thái trình bày trong vòng đời của AdView :

RewardedAd hiện là một lớp học

SDK Firebase AdMob C++ không còn được dùng nữa đã hỗ trợ quảng cáo có tặng thưởng thông qua tập hợp các chức năng trong vùng tên firebase::admob::rewarded_ad . Các chức năng này đã được kết hợp thành một lớp RewardedAd mới để phân phát quảng cáo có bề mặt API tương tự như InterstitialAd (xem phần tiếp theo).

Trình nghe InterstitialAd và RewardedAd

Cả quảng cáo xen kẽ và quảng cáo có tặng thưởng đều được coi là quảng cáo toàn màn hình. Bạn có thể cài đặt FullScreenContentListener mới để theo dõi các sự kiện trong vòng đời quảng cáo cho các loại quảng cáo này và có thể cài đặt một PaidEventListener riêng biệt để theo dõi thời điểm dịch vụ AdMob được coi là sự kiện trả phí đã xảy ra.

RewardedAd có một trình xử lý bổ sung để theo dõi các sự kiện phần thưởng do người dùng kiếm được.

Phương thức gọi lại quảng cáo toàn màn hình mới

Phương thức đã thay đổi/xóa/thay thế

Bảng bên dưới liệt kê các phương pháp cụ thể đã thay đổi trong SDK C++ quảng cáo trên thiết bị di động của Google mới. Các phương thức có tham số được liệt kê vẫn giữ nguyên nhưng chữ ký của chúng đã thay đổi.