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

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

SDK C++ Quảng cáo trên thiết bị di động của Google là một giao diện API mới, kết hợp những thay đổi lớn mang tính đột phá đối với SDK C++ Firebase AdMob cho iOS và Android vào năm 2021 và 2022, bao gồm cả việc xoá các API không dùng nữa và một quy trình mới khi làm việc với các loại quảng cáo toàn màn hình.

Firebase AdMob C++ SDK 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 trong tương lai.

Cả SDK Google Mobile Ads C++ mới (firebase::gma) và SDK Firebase AdMob C++ cũ (firebase::admob) sẽ vẫn là một phần của kho lưu trữ bản dựng cho SDK Firebase C++ trong thời gian ngừng cung cấp SDK Firebase AdMob C++.

Xoá API cũ

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

RewardedVideoAd

Không gian 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 có thêm RewardedAdListener để nhận thông báo về phần thưởng cho mặt hàng.

NativeExpressAds

NativeExpressAd của AdMob đã được đánh dấu là không được dùng nữa trong mỗi SDK Firebase AdMob C++. Do đó, NativeExpressAd không có trong SDK C++ mới của Google Mobile Ads.

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

SDK đã được chuyển đến 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 quảng cáo trên thiết bị di động của Google bằng C++ mới nằm trong không gian tên firebase::gma. Không gian tên firebase::admob cũ đã ngừng hoạt động cùng với SDK Firebase AdMob C++.

Cấu trúc thư mục

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

Thư viện

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

Di chuyển lớp, enum và cấu trúc

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

• Đổi tên BannerView thành AdView.
• NativeAdExpressView sẽ bị xoá.
• Không gian tên RewardedVideo được thay thế bằng lớp RewardedAd.
• Liệt kê PresentationState và các trình nghe đã bị xoá và thay thế bằng các trình nghe AdListener và FullScreenContent.

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

  • cấu hình mã nhận dạng thiết bị kiểm thử
  • việc 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 thông số này trong RequestConfiguration. Đây là một chế độ 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 chạy SDK

Mỗi hàm khởi chạy SDK quảng cáo trên thiết bị di động của Google bằng C++ sẽ trả về ngay 2 chỉ báo trạng thái:

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

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

Mặc dù bạn có thể gọi SDK quảng cáo trên thiết bị di động của Google bằng C++ để tải quảng cáo do AdMob phân phát ngay khi hàm khởi chạy trả về, 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ộ chuyển đổi 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 diễn ra không đồng bộ. Do đó, nếu đang sử dụng tính năng dàn xếp quảng cáo trong ứng dụng, bạn nên đợi Future phân giải trước khi cố gắng 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.
}

Thay đổi về AdSize trong AdView

AdSize hiện chứa các thành phần tĩnh có kích thước quảng cáo biểu ngữ thông thường và hỗ trợ kích thước quảng cáo AnchorAdaptive và InlineAdaptive có chiều cao linh động dựa trên chiều rộng đã cho 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à chế độ cấu hình chung

Mã thiết bị thử nghiệm, TagForChildDirectedTreatment và TagForUnderAgeOfConsent (trước đây do ngày sinh xử lý) đã bị xoá khỏi AdRequest và hiện là một phần của RequestConfiguration trên toàn 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 chế độ cài đặt này sau khi được định cấu hình.

firebase::gma::AdRequest vẫn tồn tại vì cung cấp thông tin theo ngữ cảnh để tải quảng cáo, bao gồm cả từ khoá và URL nội dung (không bắt buộc).

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 nhiều danh sách thông tin.

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

• Giờ đây, các thuộc tính bổ sung được liên kết với tên lớp bộ chuyển đổi dàn xếp. Các phần bổ sung được gửi đến 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 một quảng cáo, các ứng dụng có thể chuyển một URL của nội dung mà ứng dụng đang phân phát. Điều này cho phép tính năng nhắm mục tiêu theo từ khoá đối sánh 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

Giờ đây, LoadAd sẽ trả về một 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 thất bại, AdResult sẽ chứa một đối tượng AdError có thông tin ở cấp dịch vụ về vấn đề, 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.
      }
    }
  }
}

AdListener sự kiện trong AdView

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

• 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 đổi kích thước hoặc di chuyển.

Mối liên kết OnPresentationStateChanged lệnh gọi lại Google Mobile Ads AdMob

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

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

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

Firebase AdMob C++ SDK không được dùng nữa đã hỗ trợ quảng cáo có tặng thưởng thông qua một tập hợp các hàm trong không gian tên firebase::admob::rewarded_ad. Các hàm 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ó nền tảng API tương tự như InterstitialAd (xem phần tiếp theo).

Người 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 một FullScreenContentListener mới để theo dõi các sự kiện trong vòng đời của quảng cáo cho những loại quảng cáo này, đồng thời cài đặt một PaidEventListener riêng biệt để theo dõi thời điểm dịch vụ AdMob cho rằng một sự kiện có tính phí đã xảy ra.

RewardedAd có thêm một trình nghe để theo dõi các sự kiện phần thưởng mà người dùng nhận được.

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

Các phương thức đã thay đổi/bị xoá/được thay thế

Bảng dưới đây liệt kê các phương thức cụ thể đã thay đổi trong Google Mobile Ads C++ SDK 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.