شروع به کار با AdMob در پروژه C++‎

استفاده از کیت‌های توسعه نرم‌افزار iOS و Android از AdMob را درنظر بگیرید.


این راهنمای شروع سریع برای ناشران و توسعه‌دهندگانی است که می‌خواهند از AdMob برای درآمدزایی از برنامه‌ای که با Firebase ساخته شده است استفاده کنند. اگر قصد ندارید Firebase را در برنامه‌تان بگنجانید، به‌جای آن به راهنمای AdMob خوداتکا مراجعه کنید.

اگر هنوز این کار را نکرده‌اید، با همه مزایای استفاده از AdMob،‏ Firebase، و Google Analytics با هم آشنا شوید.

اگر اولین‌بار است که این راهنما را می‌خوانید، توصیه می‌کنیم برنامه آزمایشی «کیت توسعه نرم‌افزار C++ تبلیغات در تلفن همراه Google» را بارگیری کنید و بااستفاده از آن راهنما را دنبال کنید.

قبل از شروع

  • اگر ازقبل پروژه Firebase و برنامه Firebase ندارید، راهنمای شروع به کار Firebase را دنبال کنید: افزودن Firebase به پروژه C++‎.

  • مطمئن شوید که Google Analytics در پروژه Firebase شما فعال باشد:

    • اگر پروژه Firebase جدیدی ایجاد می‌کنید، Google Analytics را درطول گردش کار ایجاد پروژه فعال کنید.

    • اگر پروژه Firebase موجودی دارید که Google Analytics در آن فعال نیست، می‌توانید Google Analytics را از برگه ادغام‌ها در > تنظیمات پروژه فعال کنید.

    بیشتر بدانید.

مرحله ۱: برنامه را در حساب AdMob خود راه‌اندازی کنید

  1. هر گونه پلاتفرم برنامه خود را به‌عنوان برنامه AdMob ثبت کنید.

    1. به سیستم حساب AdMob وارد شوید یا ثبت‌نام کنید.

    2. هر گونه پلاتفرم برنامه خود را در AdMob ثبت کنید. این مرحله برنامه AdMob را با AdMob شناسه برنامه منحصربه‌فردی ایجاد می‌کند که بعداً در این راهنما به آن نیاز خواهید داشت.

    از شما خواسته می‌شود Mobile Ads کیت توسعه نرم‌افزار را به برنامه‌تان اضافه کنید. دستورالعمل‌های دقیق این کار را در ادامه این راهنما خواهید دید.

  2. هریک از برنامه‌های AdMob خود را به برنامه Firebase مربوطه پیوند دهید.

    این مرحله اختیاری است اما اکیداً توصیه می‌شود. درباره مزایای فعال کردن معیارهای کاربر و پیوند دادن برنامه‌های AdMob به Firebase بیشتر بدانید.

    برای هر گونه پلاتفرم، دو مرحله زیر را در داشبورد برنامه‌ها حساب AdMob خود تکمیل کنید:

    1. فعال کردن سنجه‌های کاربر برای اجازه دادن به AdMob برای پردازش و نمایش داده‌های تجزیه‌وتحلیل گلچین‌شده در حساب AdMob شما. این تنظیم همچنین برای پیوند دادن برنامه AdMob به Firebase الزامی است.

    2. برنامه AdMob خود را به پروژه Firebase موجود و برنامه Firebase مربوطه پیوند دهید.

      مطمئن شوید که همان نام بسته (Android) یا شناسه بسته (iOS) را که برای برنامه Firebase خود وارد کرده‌اید وارد کنید. نام بسته یا شناسه بسته برنامه Firebase خود را در کارت برنامه‌های شما در > تنظیمات پروژه پیدا کنید.

مرحله ۲: «شناسه برنامه» AdMob را به برنامه‌تان اضافه کنید

Android

AdMob شناسه برنامه را با افزودن برچسب <meta-data> به فایل AndroidManifest.xml برنامه خود همان‌طور که در زیر نشان داده شده است اضافه کنید.

<manifest>
    <application>
        <!-- Sample AdMob App ID: ca-app-pub-3940256099942544~3347511713 -->
        <meta-data
            android:name="com.google.android.gms.ads.APPLICATION_ID"
            android:value="ADMOB_APP_ID"/>
    </application>
</manifest>

iOS

در فایل Info.plist برنامه، کلید GADApplicationIdentifier با مقدار رشته‌ای AdMob شناسه برنامه خودتان را اضافه کنید.

می‌توانید این تغییر را به‌صورت برنامه‌ریزی‌شده انجام دهید:

<!-- Sample AdMob App ID: ca-app-pub-3940256099942544~1458002511 -->
<key>GADApplicationIdentifier</key>
<string>ADMOB_APP_ID</string>

یا آن را در ویرایشگر فهرست دارایی ویرایش کنید:

ویرایشگر فهرست دارایی

مرحله ۳: افزودن «کیت توسعه نرم‌افزار تبلیغات تلفن همراه Google»

ازآنجایی‌که Google Mobile Ads C++ SDK در فضای نام firebase::gma قرار دارد، Firebase C++ SDK را بارگیری کنید، و سپس آن را در دایرکتوری دلخواهتان از حالت فشرده خارج کنید.

‫Firebase C++ SDK مختص پلاتفرم خاصی نیست، اما به پیکربندی‌های کتابخانه مختص پلاتفرم نیاز دارد.

Android

  1. در فایل gradle.properties پروژه، مکان کیت توسعه نرم‌افزار ازحالت فشرده خارج‌شده را مشخص کنید:

    systemProp.firebase_cpp_sdk.dir=FULL/PATH/TO/SDK

  2. محتوای زیر را به فایل settings.gradle پروژه خود اضافه کنید:

    def firebase_cpp_sdk_dir = System.getProperty('firebase_cpp_sdk.dir')

gradle.ext.firebase_cpp_sdk_dir = "$firebase_cpp_sdk_dir"
includeBuild "$firebase_cpp_sdk_dir"

  3. به فایل Gradle واحد (سطح برنامه) خود (معمولاً app/build.gradle)، محتوای زیر را که شامل وابستگی کتابخانه برای «کیت توسعه نرم‌افزار تبلیغات تلفن همراه Google C++‎» است اضافه کنید.

    android.defaultConfig.externalNativeBuild.cmake {
  arguments "-DFIREBASE_CPP_SDK_DIR=$gradle.firebase_cpp_sdk_dir"
}

# Add the dependency for the Google Mobile Ads C++ SDK
apply from: "$gradle.firebase_cpp_sdk_dir/Android/firebase_dependencies.gradle"
firebaseCpp.dependencies {
  gma
}

  4. محتوای زیر را به فایل CMakeLists.txt پروژه خود اضافه کنید.

    # Add Firebase libraries to the target using the function from the SDK.
add_subdirectory(${FIREBASE_CPP_SDK_DIR} bin/ EXCLUDE_FROM_ALL)

# Add the Google Mobile Ads C++ SDK.

# The Firebase C++ library `firebase_app` is required,
# and it must always be listed last.

set(firebase_libs
  firebase_gma
  firebase_app
)

target_link_libraries(${target_name} "${firebase_libs}")

  5. برنامه‌تان را همگام‌سازی کنید تا مطمئن شوید همه وابستگی‌ها نسخه‌های لازم را دارند.

آماده‌اید! برنامه C++ شما برای استفاده از «کیت توسعه نرم‌افزار تبلیغات تلفن همراه Google برای C++» پیکربندی شده است.

iOS

مراحل این بخش نمونه‌ای از نحوه افزودن «کیت توسعه نرم‌افزار تبلیغات تلفن همراه Google C++‎» به پروژه iOS شما است.

  1. با اجرای دستور زیر، CocoaPods نسخه ۱ یا جدیدتر را دریافت کنید:

    sudo gem install cocoapods --pre

  2. ‫Google Mobile Ads pod را از کیت توسعه نرم‌افزار ازحالت فشرده خارج‌شده اضافه کنید.

    1. اگر ازقبل Podfile ندارید، آن را ایجاد کنید:

      cd YOUR_APP_DIRECTORY
pod init

    2. به Podfile، غلاف را برای کیت توسعه نرم‌افزار تبلیغات تلفن همراه Google C++ اضافه کنید:

      pod 'Google-Mobile-Ads-SDK'

    3. واحد را نصب کنید، سپس فایل .xcworkspace را در Xcode باز کنید.

      pod install
open YOUR_APP.xcworkspace

    4. چارچوب‌های زیر را از Firebase C++ SDK به پروژه اضافه کنید:

      • xcframeworks/firebase.xcframework
      • xcframeworks/firebase_gma.xcframework

آماده‌اید! برنامه C++ شما برای استفاده از «کیت توسعه نرم‌افزار تبلیغات تلفن همراه Google برای C++» پیکربندی شده است.

مرحله ۴: مقداردهی اولیه کیت توسعه نرم‌افزار تبلیغات تلفن همراه Google

پیش‌از بار کردن آگهی‌ها، کیت توسعه نرم‌افزار Mobile Ads را با فراخوانی firebase::gma::Initialize() مقداردهی اولیه کنید.

این تماس firebase::Future را برمی‌گرداند که پس‌از پایان مقداردهی اولیه (یا پس‌از ۳۰ ثانیه مهلت زمانی) تکمیل می‌شود. این روش را فقط یک‌بار و در اولین فرصت ممکن، ترجیحاً در زمان راه‌اندازی برنامه، فراخوانی کنید.

در اینجا نمونه‌ای از نحوه تماس با Initialize() آورده شده است:

Android

// Initialize the Google Mobile Ads library
firebase::InitResult result;
Future<AdapterInitializationStatus> future =
  firebase::gma::Initialize(jni_env, j_activity, &result);

if (result != kInitResultSuccess) {
  // Initialization immediately failed, most likely due to a missing dependency.
  // Check the device logs for more information.
  return;
}

// Monitor the status of the future.
// See "Use a Future to monitor the completion status of a method call" below.
if (future.status() == firebase::kFutureStatusComplete &&
    future.error() == firebase::gma::kAdErrorCodeNone) {
  // Initialization completed.
} else {
  // Initialization on-going, or an error has occurred.
}

iOS

// Initialize the Google Mobile Ads library.
firebase::InitResult result;
Future<AdapterInitializationStatus> future =
  firebase::gma::Initialize(&result);

if (result != kInitResultSuccess) {
  // Initialization immediately failed, most likely due to a missing dependency.
  // Check the device logs for more information.
  return;
}

// Monitor the status of the future.
// See "Use a Future to monitor the completion status of a method call" below.
if (future.status() == firebase::kFutureStatusComplete &&
    future.error() == firebase::gma::kAdErrorCodeNone) {
  // Initialization completed.
} else {
  // Initialization on-going, or an error has occurred.
}

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

Future روشی برای تعیین وضعیت تکمیل تماس‌های روش ناهمزمان دراختیارتان قرار می‌دهد.

برای مثال، وقتی برنامه شما firebase::gma::Initialize() را فرا می‌خواند، firebase::Future جدیدی ایجاد و برگردانده می‌شود. سپس برنامه شما می‌تواند status() Future را نظرسنجی کند تا مشخص شود مقداردهی اولیه چه زمانی تکمیل شده است. پس‌از تکمیل، برنامه شما می‌تواند result() را برای دریافت AdapterInitializationStatus فراخوانی کند.

روش‌هایی که Future را برمی‌گردانند روش «آخرین نتیجه» مربوطه را دارند که برنامه‌ها می‌توانند از آن برای بازیابی جدیدترین Future برای کنش معینی استفاده کنند. برای مثال، firebase::gma::Initialize() روش متناظری به‌نام firebase::gma::InitializeLastResult() دارد که Future را برمی‌گرداند و برنامه شما می‌تواند از آن برای بررسی وضعیت آخرین تماس با firebase::gma::Initialize() استفاده کند.

اگر وضعیت Future کامل باشد و کد خطای آن firebase::gma::kAdErrorCodeNone باشد، عملیات با موفقیت تکمیل شده است.

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

// Registers the OnCompletion callback. user_data is a pointer that is passed verbatim
// to the callback as a void*. This allows you to pass any custom data to the callback
// handler. In this case, the app has no data, so you must pass nullptr.
firebase::gma::InitializeLastResult().OnCompletion(OnCompletionCallback,
  /*user_data=*/nullptr);

// The OnCompletion callback function.
static void OnCompletionCallback(
  const firebase::Future<AdapterInitializationStatus>& future, void* user_data) {
  // Called when the Future is completed for the last call to firebase::gma::Initialize().
  // If the error code is firebase::gma::kAdErrorCodeNone,
  // then the SDK has been successfully initialized.
  if (future.error() == firebase::gma::kAdErrorCodeNone) {
    // success!
  } else {
    // failure.
  }
}

مرحله ۵: انتخاب قالب آگهی برای پیاده‌سازی در برنامه

‫AdMob قالب‌های آگهی مختلفی را ارائه می‌دهد، بنابراین می‌توانید قالبی را انتخاب کنید که بهترین تناسب را با تجربه کاربری برنامه شما داشته باشد. برای مشاهده دستورالعمل‌های دقیق پیاده‌سازی در اسناد AdMob، روی دکمه قالب آگهی کلیک کنید.

آگهی‌های مستطیلی که در بالا یا پایین صفحه‌نمایش دستگاه نشان داده می‌شوند

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

پیاده‌سازی آگهی‌های برنمایی

بینابینی

آگهی‌های تمام‌صفحه که تا زمانی که کاربر آن‌ها را نبندد، واسط برنامه را می‌پوشانند

بهترین زمان استفاده از آگهی‌های بینابینی در وقفه‌های طبیعی جریان اجرای برنامه است، مثلاً بین سطوح یک بازی یا درست پس‌از تکمیل یک تکلیف.

پیاده‌سازی آگهی‌های بینابینی

پاداش‌داده‌شده

آگهی‌هایی که به کاربران برای تماشای ویدیوهای کوتاه و تعامل با آگهی‌ها و نظرسنجی‌های قابل‌بازی پاداش می‌دهند

آگهی‌های پاداش‌دار (یا «پاداش‌محور») می‌توانند به درآمدزایی از کاربران رایگان کمک کنند.

پیاده‌سازی آگهی‌های پاداش‌دار

موضوعات موردعلاقه دیگر

راه‌های بیشتری برای اندازه‌گیری سنجه‌ها و ادغام ویژگی‌های Firebase با AdMob کاوش کنید.

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

پس‌از مقداردهی اولیه، کیت توسعه نرم‌افزار Mobile Ads به‌طور خودکار شروع به ثبت رویدادهای تحلیل و دارایی‌های کاربر از برنامه‌تان می‌کند. می‌توانید این داده‌ها را بدون افزودن کد اضافی به برنامه‌تان یا پیاده‌سازی آگهی مشاهده کنید. در اینجا می‌توانید این داده‌های Analytics را ببینید:

توجه داشته باشید که برای نمایش بهتر سنجه‌های ARPU و ARPPU، ممکن است بخواهید داده‌های رویداد سفارشی Analytics به‌نام ecommerce_purchase را در محاسبه درآمد برای این سنجه‌ها بگنجانید (با نحوه انجام این کار آشنا شوید).

(اختیاری) استفاده از ویژگی‌های بیشتر Google Analytics و Firebase

از فرصت‌ها و ویژگی‌های بیشتری برای بهبود درآمدزایی برنامه و تعامل کاربر استفاده کنید:

  • افزودن و استفاده از کیت توسعه نرم‌افزار Firebase برای Google Analytics

    برای کسب اطلاعات بیشتر، به راهنمای استفاده از Google Analytics و Firebase با AdMob برنامه مراجعه کنید.

  • استفاده از دیگر محصولات Firebase در برنامه

    پس‌از افزودن کیت توسعه نرم‌افزار Firebase برای Google Analytics، از دیگر محصولات Firebase برای بهینه‌سازی آگهی‌ها در برنامه‌تان استفاده کنید.

    • Remote Config به شما امکان می‌دهد رفتار و ظاهر برنامه‌تان را بدون انتشار به‌روزرسانی برنامه تغییر دهید.

    • A/B Testing به شما امکان می‌دهد تغییرات در واسط کاربری، ویژگی‌ها، یا پویش‌های تعامل برنامه‌تان را آزمایش کنید تا ببینید آیا این تغییرات بر سنجه‌های کلیدی شما (مثل درآمد و حفظ کاربر) تأثیر می‌گذارند یا نه، قبل‌از اینکه تغییرات را به‌طور گسترده اعمال کنید.