شروع کنید، شروع کنید

می توانید از AdMob برای نمایش تبلیغات در برنامه های ++C خود استفاده کنید. این راهنما نحوه ادغام با Firebase و تعامل با Google Mobile Ads SDK را به شما نشان می دهد.

اگر اولین باری است که این راهنما را مرور می‌کنید، توصیه می‌شود با استفاده از برنامه آزمایشی AdMob آن را دانلود کرده و دنبال کنید.

ادغام با Firebase

1. برای افزودن AdMob و Firebase به برنامه C++ خود، مراحل Setup for iOS یا Setup for Android را انجام دهید.

2. هدرهای زیر را در کد C++ برنامه خود قرار دهید:

   #include "firebase/admob.h"
   #include "firebase/admob/types.h"
   #include "firebase/app.h"
   #include "firebase/future.h"
   

3. موارد زیر را به کد C++ در برنامه خود اضافه کنید تا کتابخانه AdMob را با شناسه برنامه AdMob خود مقداردهی کنید (این کد باید قبل از ایجاد نمای بنر یا تبلیغ بینابینی اجرا شود):

   #if defined(__ANDROID__)
   // Create the Firebase app.
   firebase::App* app =
       firebase::App::Create(firebase::AppOptions(),
                             your_jni_env,
                             your_android_activity);
   
   // Your Android AdMob app ID.
   const char* kAdMobAppID = "ca-app-pub-XXXXXXXXXXXXXXXX~NNNNNNNNNN";
   #else
   // Create the Firebase app.
   firebase::App* app =
       firebase::App::Create(firebase::AppOptions());
   
   // Your iOS AdMob app ID.
   const char* kAdMobAppID = "ca-app-pub-XXXXXXXXXXXXXXXX~NNNNNNNNNN";
   #endif  // __ANDROID__
   
   // Initialize the AdMob library with your AdMob app ID.
   firebase::admob::Initialize(*app, kAdMobAppID);
   

با Google Mobile Ads SDK تعامل داشته باشید

شناسه‌های واحد تبلیغات را تنظیم کنید

هنگام نوشتن کد ++C که در iOS و Android پشتیبانی می شود، ممکن است لازم باشد از دستورالعمل های پیش پردازنده برای تعریف کدهایی استفاده کنید که فقط باید در یک سیستم عامل خاص کامپایل شوند. برای نمایش بنرها و تبلیغات بینابینی در iOS و Android، توصیه می‌شود برای هر سیستم‌عامل و هر مکان تبلیغات منحصربه‌فرد، یک شناسه واحد تبلیغاتی جدید ایجاد کنید. شناسه‌های واحد تبلیغات زیر برای iOS و Android ایجاد شده‌اند و به گونه‌ای پیکربندی شده‌اند که همیشه تبلیغات آزمایشی را ارائه دهند:

#if defined(__ANDROID__)
// Android ad unit IDs
const char* kBannerAdUnit = "ca-app-pub-3940256099942544/6300978111";
const char* kInterstitialAdUnit = "ca-app-pub-3940256099942544/1033173712";
#else
// iOS ad unit IDs
const char* kBannerAdUnit = "ca-app-pub-3940256099942544/2934735716";
const char* kInterstitialAdUnit = "ca-app-pub-3940256099942544/4411468910";
#endif

یک نمای بنر تنظیم کنید

هدر زیر را به کد C++ برنامه خود اضافه کنید:

#include "firebase/admob/banner_view.h"

یک شی BannerView را اعلام و نمونه سازی کنید:

firebase::admob::BannerView* banner_view;
banner_view = new firebase::admob::BannerView();

یک AdSize ایجاد کنید و نمای بنر را مقداردهی کنید:

firebase::admob::AdSize ad_size;
ad_size.ad_size_type = firebase::admob::kAdSizeStandard;
ad_size.width = 320;
ad_size.height = 50;
// my_ad_parent is a reference to an iOS UIView or an Android Activity.
// This is the parent UIView or Activity of the banner view.
banner_view->Initialize(static_cast<firebase::admob::AdParent>(my_ad_parent), kBannerAdUnit, ad_size);

یک تبلیغ بینابینی تنظیم کنید

هدر زیر را به کد C++ برنامه خود اضافه کنید:

#include "firebase/admob/interstitial_ad.h"

یک شی InterstitialAd را اعلام و نمونه سازی کنید:

firebase::admob::InterstitialAd* interstitial_ad;
interstitial_ad = new firebase::admob::InterstitialAd();

تبلیغات بینابینی را راه اندازی کنید:

// my_ad_parent is a reference to an iOS UIView or an Android Activity.
// This is the parent UIView or Activity of the interstitial ad.
interstitial_ad->Initialize(static_cast<firebase::admob::AdParent>(my_ad_parent), kInterstitialAdUnit);

یک درخواست تبلیغات AdMob ایجاد کنید

کتابخانه AdMob به شما امکان می‌دهد اطلاعات هدف‌یابی سفارشی را برای یک درخواست تبلیغاتی ارائه دهید. این کار با تنظیم اعضای یک ساختار AdRequest انجام می شود. ساختار سپس به BannerView::LoadAd() یا InterstitialAd::LoadAd() منتقل می شود.

برای اطلاعات کلی در مورد هدف‌یابی و سفارشی‌سازی درخواست‌های تبلیغاتی، راهنمای هدف‌یابی iOS و Android ما را بررسی کنید.

در اینجا ساختار AdRequest مورد استفاده توسط BannerView و InterstitialAd برای درخواست تبلیغات است:

struct AdRequest {
  const char **test_device_ids;
  unsigned int test_device_id_count;
  const char **keywords;
  unsigned int keyword_count;
  const KeyValuePair *extras;
  unsigned int extras_count;
  int birthday_day;
  int birthday_month;
  int birthday_year;
  Gender gender;
  ChildDirectedTreatmentState tagged_for_child_directed_treatment;
};

ساختار AdRequest را اعلام و مقداردهی اولیه کنید:

// Initialize all the AdRequest struct member values to zero.
firebase::admob::AdRequest my_ad_request = {};

کد زیر مقادیر اعضای ساختار AdRequest را برای افزودن اطلاعات هدف به درخواست تبلیغ تنظیم می کند:

// If the app is aware of the user's gender, it can be added to the
// targeting information. Otherwise, "unknown" should be used.
my_ad_request.gender = firebase::admob::kGenderUnknown;

// The user's birthday, if known. Note that months are indexed from one.
my_ad_request.birthday_day = 10;
my_ad_request.birthday_month = 11;
my_ad_request.birthday_year = 1976;

// Additional keywords to be used in targeting.
static const char* kKeywords[] = {"AdMob", "C++", "Fun"};
my_ad_request.keyword_count = sizeof(kKeywords) / sizeof(kKeywords[0]);
my_ad_request.keywords = kKeywords;

// "Extra" key value pairs can be added to the request as well.
static const firebase::admob::KeyValuePair kRequestExtras[] = {
    {"the_name_of_an_extra", "the_value_for_that_extra"}};
my_ad_request.extras_count = sizeof(kRequestExtras) / sizeof(kRequestExtras[0]);
my_ad_request.extras = kRequestExtras;

// Register the device IDs associated with any devices that will be used to
// test your app. Below are sample test device IDs used for making the ad request.
static const char* kTestDeviceIDs[] =
    {"2077ef9a63d2b398840261c8221a0c9b",
     "098fe087d987c9a878965454a65654d7"};
my_ad_request.test_device_id_count =
    sizeof(kTestDeviceIDs) / sizeof(kTestDeviceIDs[0]);
my_ad_request.test_device_ids = kTestDeviceIDs;

ساختار AdRequest را به BannerView::LoadAd() و Interstitial::LoadAd() کنید:

banner_view->LoadAd(my_ad_request);
interstitial_ad->LoadAd(my_ad_request);

Note: A single `AdRequest` struct can be reused for multiple calls.

از Futures برای نظارت بر وضعیت تکمیل فراخوانی متدها استفاده کنید

آتی راهی برای تعیین وضعیت تکمیل تماس های قبلی BannerView یا روش InterstitialAd در اختیار شما قرار می دهد. به عنوان مثال، هنگامی که با متد InterstitialAd::LoadAd() فراخوانی می شود، یک Future جدید ایجاد و برگردانده می شود. برنامه‌ها می‌توانند وضعیت آینده را برای تعیین زمان بارگیری آگهی بررسی کنند. پس از تکمیل Future، تبلیغ بینابینی آماده نمایش در نقطه توقف طبیعی بعدی در برنامه شما است.

اکثر متدها در BannerView و InterstitialAd دارای یک روش «آخرین نتیجه» متناظر هستند که برنامه‌ها می‌توانند از آن برای بازیابی جدیدترین Future برای یک اقدام معین استفاده کنند. برای مثال، متد InterstitialAd::LoadAd( InterstitialAd::LoadAd() دارای یک متد متناظر به نام InterstitialAd::LoadAdLastResult() است. یک Future برمی گرداند که می تواند برای بررسی وضعیت آخرین فراخوانی متد InterstitialAd::LoadAd() استفاده شود.

به طور مشابه، برنامه‌ها می‌توانند از BannerView::InitializeLastResult() برای دریافت Future که وضعیت (و کد خطا، در صورت وجود) آخرین تماس با BannerView::Initialize() را نشان می‌دهد، استفاده کنند. اگر وضعیت آن کامل است و کد خطای آن firebase::admob::kAdMobErrorNone است، می‌توانید با فراخوانی BannerView::Show() نمای بنر را قابل مشاهده کنید:

if (banner_view->InitializeLastResult().status() ==
    firebase::kFutureStatusComplete &&
    banner_view->InitializeLastResult().error() ==
    firebase::admob::kAdMobErrorNone) {
  banner_view->Show();
}

هنگامی که وضعیت Future برای آخرین تماس با BannerView::Show() تکمیل شد، آنگاه آماده بارگذاری آگهی در نمای بنر هستید:

if (banner_view->ShowLastResult().status() ==
    firebase::kFutureStatusComplete &&
    banner_view->ShowLastResult().error() ==
    firebase::admob::kAdMobErrorNone) {
  banner_view->LoadAd(my_ad_request);
}

برای تبلیغات بینابینی، از InterstitialAd::InitializeLastResult() استفاده کنید تا Future نشان دهنده وضعیت (و کد خطا، در صورت وجود) آخرین فراخوانی InterstitialAd::Initialize() باشد. اگر وضعیت آن کامل است و کد خطای آن firebase::admob::kAdMobErrorNone است، پس آماده بارگیری آگهی بینابینی هستید:

if (interstitial_ad->InitializeLastResult().status() ==
    firebase::kFutureStatusComplete &&
    interstitial_ad->InitializeLastResult().error() ==
    firebase::admob::kAdMobErrorNone) {
  interstitial_ad->LoadAd(my_ad_request);
}

پس از تکمیل وضعیت Future برای آخرین تماس با روش InterstitialAd::LoadAd() ، آنگاه آماده نمایش آگهی بینابینی در نقطه توقف طبیعی بعدی در برنامه خود هستید:

if (interstitial_ad->LoadAdLastResult().status() ==
    firebase::kFutureStatusComplete &&
    interstitial_ad->LoadAdLastResult().error() ==
    firebase::admob::kAdMobErrorNone) {
  interstitial_ad->Show();
}

همچنین می‌توانید تماس‌هایی را برای فراخوانی پس از تکمیل Future ثبت کنید. این قطعه کد از یک نشانگر تابع برای پاسخ به تماس استفاده می کند:

// Initialize the interstitial ad.
interstitial_ad->Initialize(static_cast<firebase::admob::AdParent>(my_ad_parent), kInterstitialAdUnit);

// Registers the OnCompletion callback. user_data is a pointer that is passed verbatim
// to the callback as a void*. In this example, we pass the interstitial ad object to be
// used in the OnCompletionCallback function.
interstitial_ad->InitializeLastResult().OnCompletion(OnCompletionCallback, interstitial_ad /*user_data*/);

// The OnCompletion callback function.
static void OnCompletionCallback(const firebase::Future<void>& future, void* user_data) {
  // Called when the Future is completed for the last call to the InterstitialAd::Initialize()
  // method. If the error code is firebase::admob::kAdMobErrorNone, then you're ready to
  // load the interstitial ad.
  firebase::admob::InterstitialAd *interstitial_ad = static_cast<firebase::admob::InterstitialAd*>(user_data);
  if (future.error() == firebase::admob::kAdMobErrorNone) {
    interstitial_ad->LoadAd(my_ad_request);
  }
}

از شنونده استفاده کنید تا از رویدادهای چرخه عمر تبلیغات مطلع شوید

AdMob یک کلاس انتزاعی BannerView::Listener ارائه می‌کند که می‌توانید آن را گسترش دهید و به BannerView::SetListener() تا از تغییرات وضعیت نمایش بنر و کادر محدود مطلع شوید. یک کلاس انتزاعی مشابه InterstitialAd::Listener نیز برای تبلیغات بینابینی ارائه شده است که می توان آن را گسترش داد تا از تغییرات در وضعیت ارائه یک آگهی بینابینی مطلع شود.

در زیر نمونه ای از پیاده سازی کلاسی است که کلاس BannerView::Listener را گسترش می دهد (یک پیاده سازی مشابه را می توان برای تبلیغات بینابینی استفاده کرد):

class ExampleBannerViewListener
    : public firebase::admob::BannerView::Listener {
public:
  ExampleBannerViewListener() {}

  void OnPresentationStateChanged(
      firebase::admob::BannerView* banner_view,
      firebase::admob::BannerView::PresentationState state) override {
    // This method gets called when the banner view's presentation
    // state changes.
  }

  void OnBoundingBoxChanged(
      firebase::admob::BannerView* banner_view,
      firebase::admob::BoundingBox box) override {
    // This method gets called when the banner view's bounding box
    // changes.
  }
};

بعدش چی

با نحوه کسب درآمد از برنامه خود با AdMob آشنا شوید و مطمئن شوید که شناسه های واحد تبلیغات آزمایشی استفاده شده در این راهنما را با شناسه های واحد تبلیغات خود جایگزین کنید.