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

KHÔNG DÙNG NỮA: SDK C++ của Google Mobile Ads không còn được dùng nữa kể từ ngày 17 tháng 6 năm 2024 và không được áp dụng trong các dự án chưa sử dụng SDK này. SDK này sẽ bước vào giai đoạn Kết thúc bảo trì (EoM) kể từ ngày 17 tháng 6 năm 2025. Xin lưu ý rằng các phiên bản SDK phát hành trước ngày EoM sẽ tiếp tục hoạt động, nhưng sẽ không phát hành thêm bản sửa lỗi hoặc thay đổi nào sau ngày EoM đó.

Thay vì SDK C++ của Google Mobile Ads, hãy cân nhắc sử dụng SDK iOS và Android từ AdMob. Để được hỗ trợ, hãy liên hệ với Diễn đàn kỹ thuật về SDK quảng cáo của Google trên thiết bị di động.

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

SDK Google Mobile Ads C++ là một giao diện API mới kết hợp các thay đổi lớn về việc ngừng hoạt động đối với SDK Firebase AdMob C++ cho iOS và Android trong năm 2021 và 2022, bao gồm 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.

SDK C++ Firebase AdMob 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 C++ mới của Google Mobile Ads (firebase::gma) và SDK C++ cũ của Firebase AdMob (firebase::admob) sẽ vẫn nằm trong kho lưu trữ bản dựng cho SDK Firebase C++ trong khoảng thời gian ngừng sử dụng SDK C++ của Firebase AdMob.

Xoá API cũ

Các API sau đây đã bị xoá hoàn toàn khỏi SDK C++ của Google Mobile Ads.

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

NativeExpressAds

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

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++ mới cho Quảng cáo trên thiết bị di động của Google nằm trong không gian tên firebase::gma. Không dùng không gian tên firebase::admob cũ nữa cùng với SDK C++ của Firebase AdMob.

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 tệp lưu trữ bản dựng:

Không dùng nữa SDK C++ của Firebase AdMob	SDK C++ mới của Google Mobile Ads
include/firebase/admob	include/firebase/gma

Thư viện

SDK C++ của Firebase AdMob 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++:

iOS

Ngừng sử dụng SDK C++ của Firebase AdMob	SDK C++ mới của Google Mobile Ads
firebase_admob.xcframework	firebase_gma.xcframework

Android

Không dùng nữa SDK C++ của Firebase AdMob	SDK C++ mới của Google Mobile Ads
libfirebase_admob.a	libfirebase_gma.a

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à thông tin tóm tắt:

• Đổi tên BannerView thành AdView.
• Xoá NativeAdExpressView.
• Không gian tên RewardedVideo được thay thế bằng lớp RewardedAd.
• Xoá và thay thế trình nghe và liệt kê PresentationState bằng 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 theo quảng cáo trong AdRequests:

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

  Thay vào đó, bạn hiệ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ượt tải quảng cáo tiếp theo.

Ngừng sử dụng firebase::admob namespace	firebase::gma namespace mới
AdSizeType (enum)	AdSize::Type (enum)
BannerView	AdView
BannerView::Listener	AdListener AdViewBoundingBoxListener PaidEventListener
BannerView::Position	AdView::Position
BannerView::PresentationState	Đã xoá
ChildDirectedTreatmentState	RequestConfiguration::TagForChildDirectedTreatment
Gender (enum)	Đã xoá
InterstitialAd::Listener	FullScreenContentListener PaidEventListener
KeyValuePair	Đã xoá
NativeExpressAdView	Đã xoá
PollableRewardListener	Đã xoá
RewardItem	AdReward
RewardedVideoAd (không gian tên)	RewardedAd (lớp)
RewardedVideoAd::Listener	FullScreenContentListener PaidEventListener UserEarnedRewardListener
AdMobError (enum)	AdErrorCode (enum)
RewardItem	AdReward

Khởi chạy SDK

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

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

• Tham số trả về là tham chiếu đến firebase::Future. Future chứa kết quả của quá trình khởi chạy không đồng bộ của 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 C++ của Google Mobile Ads để 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 khởi chạy đầy đủ. 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 của mình, bạn nên đợi Future được 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 đố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, đồng thời 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 đã cho và hướng hiện tại của màn hình.

Đã thêm hằng số AdSize tĩnh vào firebase::gma::AdSize
AdSize::kBanner	Kích thước quảng cáo biểu ngữ theo Hiệp hội tiếp thị di động (MMA) (320x50 pixel không phụ thuộc vào mật độ)
AdSize::kFullBanner	Kích thước quảng cáo biểu ngữ đầy đủ theo Cục Quảng cáo tương tác (IAB) (468x60 pixel không phụ thuộc vào mật độ)
AdSize::kLargeBanner	Phiên bản cao hơn của kBanner, thường là 320x100
AdSize::kLeaderboard	Kích thước quảng cáo hình chữ nhật dài theo Cục Quảng cáo tương tác (IAB) (728x90 pixel không phụ thuộc vào mật độ)
AdSize::kMediumRectangle	Kích thước quảng cáo dạng hình chữ nhật trung bình theo Cục Quảng cáo tương tác (IAB) (300x250 pixel không phụ thuộc vào mật độ)

Các phương thức tĩnh trong firebase::gma::AdSize để giúp tạo các thực thể của AdSize
GetLandscapeAnchoredAdaptiveBannerAdSize	Tạo AdSize có chiều rộng nhất định và chiều cao do Google tối ưu hoá để tạo quảng cáo biểu ngữ ở chế độ ngang
GetPortraitAnchoredAdaptiveBannerAdSize	Tạo AdSize có chiều rộng nhất định và chiều cao do Google tối ưu hoá để tạo quảng cáo biểu ngữ ở chế độ dọc
GetCurrentOrientationAnchoredAdaptiveBannerAdSize	Tạo AdSize có chiều rộng và chiều cao được Google tối ưu hoá để tạo quảng cáo biểu ngữ theo hướng hiện tại
GetInlineAdaptiveBannerAdSize	Tạo AdSize phù hợp nhất với quảng cáo biểu ngữ, với chiều cao tối đa AdSize này cho phép máy chủ của Google chọn kích thước quảng cáo tối ưu có chiều cao nhỏ hơn hoặc bằng chiều cao tối đa đã chỉ định.
GetLandscapeInlineAdaptiveBannerAdSize	Tạo InlineAdaptive AdSize có chiều rộng đã cho và chiều cao ngang của thiết bị
GetPortraitInlineAdaptiveBannerAdSize	Tạo InlineAdaptive AdSize có chiều rộng đã cho và chiều cao dọc của thiết bị.
GetCurrentOrientationInlineAdaptiveBannerAdSize	Một phương thức tiện lợi để trả về InlineAdaptive AdSize dựa trên hướng giao diện hiện tại có chiều rộng cụ thể.

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

Các mã thiết bị kiểm thử, TagForChildDirectedTreatment và TagForUnderAgeOfConsent (trước đây được xử lý theo ngày sinh) đã bị xoá khỏi AdRequest và hiện là một phần của RequestConfiguration chung. Các ứng dụng có thể gọi firebase::gma::SetRequestConfiguration() từ sớm 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ú ý đối với AdRequest:

• Các thành phần bổ sung hiện được liên kết với tên lớp bộ chuyển đổi dàn xếp. Thông tin bổ sung được gửi đến dịch vụ AdMob phải sử dụng tên lớp mặc định như 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 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á so khớp quảng cáo với nội dung khác đang 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ề 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 không thành công, AdResult sẽ chứa một đối tượng AdError có 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++ của Google Mobile Ads:

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

Liên kết Google Mobile Ads gọi lại OnPresentationStateChanged của AdMob

Loại liệt kê firebase::admob::BannerView::PresentationState và phương thức trình nghe OnPresentationStateChanged không có trong SDK C++ mới của Google Mobile Ads.

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

firebase::admob::BannerView::Listener OnPresentationStateChanged sự kiện	firebase::gma::AdListener đối tác
kPresentationStateHidden	Khi AdListener::OnAdClosed được gọi hoặc khi AdView::Hide() hoàn tất thành công thao tác không đồng bộ
kPresentationStateVisibleWithoutAd	Không có. Nếu bạn cố gắng gọi AdView::Show() một AdView chưa tải, bạn sẽ gặp lỗi.
kPresentationStateVisibleWithAd	Khi AdListener::OnAdOpened được gọi hoặc khi AdView::Show() hoàn tất thành công hoạt động không đồng bộ của mình với một quảng cáo
kPresentationStateOpenedPartialOverlay	Truy vấn hộp giới hạn sau khi AdListener::OnAdOpened() được gọi để xác định kích thước và vị trí của quảng cáo đang hiển thị. Ngoài ra, hãy truy vấn vị trí của AdView và AdSize và/hoặc theo dõi hộp giới hạn thông qua AdViewBoundingBoxListener.
kPresentationStateCoveringUI	Xem kPresentationStateOpenedPartialOverlay ở trên

RewardedAd hiện là một lớp

SDK C++ của Firebase AdMob không 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 hợp nhất thành một lớp RewardedAd mới. Lớp này sẽ 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).

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 một FullScreenContentListener mới để theo dõi các sự kiện trong vòng đời của quảng cáo cho các loại quảng cáo này và cài đặt một PaidEventListener riêng để theo dõi thời điểm dịch vụ AdMob coi 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

FullScreenContentListener phương thức	Phương thức PaidEventListener	UserEarnedRewardListener phương thức
OnAdClicked	OnPaidEvent	OnUserEarnedReward
OnAdDismissedFullScreenContent
OnAdFailedToShowFullScreenContent
OnAdImpression
OnAdShowedFullScreenContent

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

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

Hạng	API SDK C++ của Firebase AdMob	API SDK C++ của Google Mobile Ads	Lưu ý
BannerView	MoveTo	AdView::SetPosition
	presentation_state	Đã xoá	Được xử lý bằng các sự kiện AdViewListener và kết quả trong tương lai của AdView::Show và AdView::Hide.
	SetListener	AdView::SetAdListener AdView::SetBoundingBoxListener AdView::SetPaidEventListener	Thiết kế trình nghe mới giúp tăng độ trung thực của việc phát hiện các sự kiện trong vòng đời của AdView.
	Listener::OnPresentationStateChanged	Đã xoá	Xem BannerView::SetListener ở trên.
	Listener::OnBoundingBoxChanged	AdViewBoundingBoxListener::OnBoundingBoxChanged
InterstitialAd	Initialize(AdParent parent, const char* ad_unit_id)	Initialize(AdParent parent)	Tham số ad_unit_id hiện là một phần của thao tác LoadAd.
	LoadAd(const AdRequest& request)	LoadAd(const char* ad_unit_id, const AdRequest& request)
	presentation_state	Đã xoá	Chế độ liệt kê presentation_state đã bị xoá. Sử dụng FullScreenContentListener.
	SetListener	SetFullScreenContentListener SetPaidEventListener
	Destroy	Đã xoá	Việc dọn dẹp tài nguyên hiện là một phần của hàm huỷ RewardedAd.
RewardedAd (chính thức là RewardedVideoAd)	Initialize	Initialize(AdParent parent)	AdParent trước đây đã được truyền cho Show nhưng hiện là một phần của quá trình khởi chạy.
	presentation_state	Đã xoá	Xoá enum presentation_state. Sử dụng FullScreenContentListener.
	SetListener	SetFullScreenContentListener SetPaidEventListener Show	Trình nghe UserEarnedReward cũng được xác định khi hiển thị RewardedAd. Hãy xem nội dung bên dưới.
	Show(AdParent parent)	Show(UserEarnedRewardListener* listener)