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

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


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

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

اگر اولین‌بار است که این راهنما را می‌خوانید، توصیه می‌کنیم برنامه آزمایشی Google Mobile Ads C++ SDK را بارگیری کنید و مراحل را با آن دنبال کنید.

قبل از شروع

  • اگر ازقبل پروژه 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 مختص پلاتفرم نیست، اما به پیکربندی‌های کتابخانه مختص پلاتفرم نیاز دارد.

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 Mobile Ads C++ SDK است.

    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 Mobile Ads C++‎ به پروژه iOS شما است.

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

    sudo gem install cocoapods --pre

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

    1. اگر Podfile ندارید، یکی ایجاد کنید:

      cd YOUR_APP_DIRECTORY
pod init

    2. به Podfile خود، pod را برای Google Mobile Ads C++ SDK اضافه کنید:

      pod 'Google-Mobile-Ads-SDK'

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

      pod install
open YOUR_APP.xcworkspace

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

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

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

مرحله ۴: مقداردهی اولیه «کیت توسعه نرم‌افزار تبلیغات تلفن همراه» 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 به‌نام ecommerce_purchase را در محاسبه درآمد برای این سنجه‌ها لحاظ کنید (با نحوه انجام این کار آشنا شوید).

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

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

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

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

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

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

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

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