เปลี่ยนไปใช้ C++ SDK โฆษณาบนอุปกรณ์เคลื่อนที่ของ Google ใหม่

การเปิดตัว Firebase C++ SDK v9.1.0 เป็นการเปิดตัว Google Mobile Ads C++ SDK ใหม่

Google Mobile Ads C++ SDK เป็น API Surface ใหม่ที่รวมการเปลี่ยนแปลงที่สำคัญ ซึ่งทำให้เกิดการเปลี่ยนแปลงที่ไม่รองรับการทำงานย้อนหลังใน Firebase AdMob C++ SDK สำหรับ iOS และ Android ในปี 2021 และ 2022 ซึ่งรวมถึงการนำ API ที่เลิกใช้งานแล้วออก และโฟลว์ใหม่เมื่อ ทำงานกับโฆษณาประเภทเต็มหน้าจอ

เราได้ทำเครื่องหมายว่า Firebase AdMob C++ SDK (firebase::admob) เวอร์ชันเก่าเลิกใช้งานแล้ว และจะไม่ได้รับการอัปเดตหรือแก้ไขข้อบกพร่องใดๆ อีกต่อไป

ทั้ง Google Mobile Ads C++ SDK ใหม่ (firebase::gma) และ Firebase AdMob C++ SDK เดิม (firebase::admob) จะยังคงเป็นส่วนหนึ่งของที่เก็บถาวรของบิลด์สำหรับ Firebase C++ SDK ในช่วงเวลาที่เลิกใช้งาน Firebase AdMob C++ SDK

การนำ API เดิมออก

เราได้นำ API ต่อไปนี้ออกจาก Google Mobile Ads C++ SDK ทั้งหมด

RewardedVideoAd

เราได้แทนที่เนมสเปซ RewardedVideoAd ของ AdMob ด้วยคลาส RewardedAd RewardedAdทํางานคล้ายกับ InterstitialAd แต่ มี RewardedAdListener เพิ่มเติมเพื่อรับการแจ้งเตือนเกี่ยวกับรางวัลไอเทม

NativeExpressAds

NativeExpressAd ของ AdMob ได้รับการทำเครื่องหมายว่าเลิกใช้งานแล้วในแต่ละ Firebase AdMob C++ SDK ดังนั้น NativeExpressAd จึงไม่ได้รวมอยู่ใน SDK โฆษณาในอุปกรณ์เคลื่อนที่ของ Google C++ ใหม่

การเปลี่ยนแปลงเนมสเปซ SDK

SDK ได้ย้ายไปยังเนมสเปซใหม่และมีโครงสร้างไดเรกทอรีใหม่ดังนี้

เนมสเปซ firebase::gma

แหล่งที่มาของ Google Mobile Ads C++ SDK ใหม่จะอยู่ในfirebase::gma เนมสเปซ เราเลิกใช้งานเนมสเปซ firebase::admob เวอร์ชันเก่าแล้วพร้อมกับ Firebase AdMob C++ SDK

โครงสร้างไดเรกทอรี

ไฟล์ส่วนหัวย้ายไปอยู่ในไดเรกทอรีใหม่ภายในที่เก็บถาวรของบิลด์แล้ว

คลัง

Firebase AdMob C++ SDK จะมีให้ใช้งานเป็นไลบรารีแบบคงที่ภายใน Firebase C++ ที่เก็บถาวรของบิลด์ SDK

การย้ายข้อมูลคลาส enum และโครงสร้าง

ตารางด้านล่างแสดงรายการคลาส การแจงนับ และโครงสร้างที่เฉพาะเจาะจงซึ่งมีการเปลี่ยนแปลงหรือถูกนำออก ไปแล้ว โดยสรุปมีดังนี้

• เปลี่ยนชื่อ BannerView เป็น AdView
• นำ NativeAdExpressView ออกแล้ว
• ระบบจะแทนที่เนมสเปซ RewardedVideo ด้วยคลาส RewardedAd
• ระบบจะนำการแจงนับและ Listener PresentationState ออกและ แทนที่ด้วย Listener AdListener และ FullScreenContent

• ระบบจะนำพารามิเตอร์ต่อไปนี้ออกตามพารามิเตอร์การกำหนดค่าต่อโฆษณา ใน AdRequests

  • การกำหนดค่ารหัสอุปกรณ์ทดสอบ
  • การกำหนดเป้าหมายโฆษณาตามอายุ

  แต่ตอนนี้คุณสามารถกำหนดค่าพารามิเตอร์เหล่านี้ได้ใน RequestConfiguration ซึ่งเป็นการตั้งค่าส่วนกลางที่จะส่งผลต่อการโหลดโฆษณาทั้งหมดในภายหลัง

การเริ่มต้น SDK

ฟังก์ชันการเริ่มต้นแต่ละรายการของ Google Mobile Ads C++ SDK จะแสดงตัวบ่งชี้สถานะ 2 รายการทันที

• พารามิเตอร์เอาต์ที่ไม่บังคับจะระบุว่าเกิดข้อผิดพลาดเกี่ยวกับ Dependency ก่อน เริ่มกระบวนการเริ่มต้นหรือไม่

• พารามิเตอร์การคืนค่าคือการอ้างอิงถึง firebase::Future Future มีผลลัพธ์ของการเริ่มต้นแบบอะซิงโครนัสของตัวกลาง ในอุปกรณ์

แม้ว่าอาจมีการเรียกใช้ Google Mobile Ads C++ SDK เพื่อโหลดโฆษณาที่แสดงโดย AdMob ทันทีที่ฟังก์ชันการเริ่มต้นทำงานเสร็จ แต่เครือข่ายโฆษณาอื่นๆ จะไม่แสดงโฆษณาจนกว่าจะมีการเริ่มต้นใช้งานสื่อกลางที่เกี่ยวข้องอย่างเต็มรูปแบบ กระบวนการนี้จะเกิดขึ้นแบบอะซิงโครนัส ดังนั้น หากคุณใช้สื่อกลางโฆษณาในแอปพลิเคชัน เราขอแนะนําให้รอจนกว่า Future จะแก้ไขปัญหาได้ก่อนที่จะพยายามโหลดโฆษณา

ก่อน

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

หลัง

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

การเปลี่ยนแปลงใน AdSize ภายใน AdView

AdSize มีสมาชิกแบบคงที่ของขนาดโฆษณาแบนเนอร์ทั่วไป และรองรับขนาดโฆษณา AnchorAdaptive และ InlineAdaptive ซึ่งมีความสูงแบบไดนามิกตามความกว้างที่ระบุและการวางแนวปัจจุบันของหน้าจอ

ก่อน

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

หลัง

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 และการกำหนดค่าส่วนกลาง

ระบบได้นำรหัสอุปกรณ์ทดสอบ TagForChildDirectedTreatment และ TagForUnderAgeOfConsent (ก่อนหน้านี้จัดการตามวันเกิด) ออกจาก AdRequest แล้ว และตอนนี้รหัสเหล่านี้ เป็นส่วนหนึ่งของ RequestConfiguration ทั่วโลก แอปพลิเคชันอาจเรียกใช้ firebase::gma::SetRequestConfiguration()ตั้งแต่เนิ่นๆ ในวงจร ของแอปพลิเคชันเพื่อกำหนดค่าเหล่านี้ การดำเนินการโหลดโฆษณาทั้งหมดหลังจากนี้จะ ใช้การตั้งค่าเหล่านี้เมื่อมีการกำหนดค่า

firebase::gma::AdRequest ยังคงมีอยู่เนื่องจากมีข้อมูลเชิงบริบท สำหรับการโหลดโฆษณา รวมถึงคีย์เวิร์ดและ URL เนื้อหา (ไม่บังคับ)

เราได้แทนที่ AdRequest C-style struct ของ AdMob ด้วยคลาสที่มีเมธอด ซึ่งมอบประสบการณ์การใช้งานที่ดีขึ้นเมื่อกำหนดและต่อท้าย รายการข้อมูลต่างๆ

การเปลี่ยนแปลงที่สำคัญมีดังนี้ AdRequest

• ตอนนี้ส่วนเสริมจะเชื่อมโยงกับชื่อคลาสอะแดปเตอร์สื่อกลางแล้ว Extras ที่ส่งไปยังAdMob บริการควรใช้ชื่อคลาสเริ่มต้นตามที่กำหนดไว้ด้านล่าง
• เมื่อขอโฆษณา แอปอาจส่ง URL ของเนื้อหาที่แสดง ซึ่งจะช่วยให้การกำหนดเป้าหมายตามคีย์เวิร์ดจับคู่โฆษณากับเนื้อหาอื่นๆ ที่แสดงได้

ก่อน

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.

หลัง

// 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 จะแสดง Future ที่มีออบเจ็กต์ AdResult สำหรับโฆษณาทุกประเภท AdView, InterstitialAd และ RewardedAd เมธอด AdResult::is_successful จะแสดงผล true หากคำขอโฆษณา สำเร็จ หรือ false หากไม่สำเร็จ

หากไม่สำเร็จ AdResult จะมีออบเจ็กต์ AdError ที่มีข้อมูลระดับบริการเกี่ยวกับปัญหา รวมถึงรหัสข้อผิดพลาด ข้อความแสดงข้อผิดพลาด และสตริงโดเมน

ก่อน

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

หลัง

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 เหตุการณ์ภายใน AdView

BannerView::Listener คลาสของ AdMob ถูกแทนที่ด้วยคลาส Listener ที่แตกต่างกัน 2 คลาสใน Google Mobile Ads C++ SDK ดังนี้

• AdListener จะติดตามเหตุการณ์วงจรโฆษณาและการโต้ตอบของผู้ใช้
• AdViewBoundingBoxListener จะเรียกใช้เมื่อมีการปรับขนาดหรือย้าย AdView

การแมป OnPresentationStateChanged Callback Google Mobile Ads ของ AdMob

firebase::admob::BannerView::PresentationStateประเภทที่แจงนับและ OnPresentationStateChangedเมธอด Listener จะไม่รวมอยู่ใน Google Mobile Ads C++ SDK ใหม่

ต่อไปนี้คือวิธีอื่นๆ ในการตรวจหาการเปลี่ยนแปลงสถานะการนำเสนอใน วงจรของ AdView

ตอนนี้ RewardedAd เป็นชั้นเรียนแล้ว

Firebase AdMob C++ SDK ที่เลิกใช้งานแล้วช่วยให้แสดงโฆษณาที่มีการให้รางวัลผ่าน ชุดฟังก์ชันในเนมสเปซ firebase::admob::rewarded_ad ฟังก์ชันเหล่านี้ รวมกันเป็นRewardedAd คลาสใหม่ที่แสดงโฆษณา ด้วย API ที่คล้ายกับ InterstitialAd (ดูส่วนถัดไป)

ผู้ฟัง InterstitialAd และ RewardedAd

ทั้งโฆษณาคั่นระหว่างหน้าและโฆษณาที่มีการให้รางวัลถือเป็นโฆษณาแบบเต็มหน้าจอ คุณสามารถติดตั้งFullScreenContentListenerใหม่เพื่อฟังเหตุการณ์วงจรโฆษณาสำหรับโฆษณาประเภทนี้ และติดตั้ง PaidEventListener แยกต่างหากเพื่อติดตามเมื่อบริการ AdMob พิจารณาว่ามีเหตุการณ์แบบชำระเงินเกิดขึ้น

RewardedAd มี Listener เพิ่มเติมเพื่อตรวจสอบเหตุการณ์รางวัลที่ผู้ใช้ได้รับ

เมธอดเรียกกลับของโฆษณาแบบเต็มหน้าจอใหม่

เปลี่ยน/นำออก/แทนที่วิธีการ

ตารางด้านล่างแสดงรายการเมธอดที่เฉพาะเจาะจงซึ่งมีการเปลี่ยนแปลงใน Google Mobile Ads C++ SDK เวอร์ชันใหม่ เมธอดที่มีพารามิเตอร์ที่ระบุจะยังคงอยู่ แต่ลายเซ็นมีการเปลี่ยนแปลง