شروع کنید


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

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

کیت توسعه نرم‌افزار Google Mobile Ads C++‎ کیت‌های توسعه نرم‌افزار Google Mobile Ads iOS و Android را دربرمی‌گیرد، و فقط در این پلاتفرم‌ها دردسترس است. کیت توسعه نرم‌افزار Google Mobile Ads C++‎ از ساختارهای Firebase C++‎ برای پشتیبانی از عملیات ناهمگام استفاده می‌کند، بنابراین در فضای نام firebase::gma قرار دارد.

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

پیش‌نیازها

Android

  • از «استودیو Android» نسخه ۳.۲ یا بالاتر استفاده کنید
  • مطمئن شوید فایل ساخت برنامه‌تان از مقادیر زیر استفاده می‌کند:
    • ‫minSdkVersion ۱۶ یا بالاتر
    • compileSdkVersion ۲۸ یا بالاتر

iOS

  • از Xcode 13 یا بالاتر استفاده کنید
  • iOS نسخه ۱۰.۰ یا بالاتر را هدف قرار دهید

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

با تکمیل مراحل زیر، برنامه‌تان را به‌عنوان برنامه AdMob ثبت کنید:

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

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

نصب کردن کیت توسعه نرم‌افزار Google Mobile Ads C++‎

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

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

Android

توصیه می‌کنیم از CMake استفاده کنید، اما می‌توانید دستورالعمل‌های ndk-build را در راهنمای شروع به کار کیت توسعه نرم‌افزار Firebase در ++C عمومی ما برای پیوند دادن libfirebase_app.a و libfirebase_gma.a به برنامه‌تان پیدا کنید.

  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. برنامه‌تان را همگام‌سازی کنید تا مطمئن شوید همه وابستگی‌ها نسخه‌های لازم را دارند.

iOS

مراحل این بخش نمونه‌ای از نحوه افزودن Google Mobile Ads C++ SDK به پروژه iOS شما است.

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

    sudo gem install cocoapods --pre

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

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

      cd APP_DIRECTORY
pod init

    2. به Podfile خود، podهای مربوط به Google Mobile Ads C++ SDK، Google User Messaging Platform SDK، و حداقل Firebase core SDK (موردنیاز GMA C++ SDK) را اضافه کنید:

      pod 'Firebase/CoreOnly'
pod 'Google-Mobile-Ads-SDK'
pod 'GoogleUserMessagingPlatform'

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

      pod install
open APP.xcworkspace

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

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

همه چیز آماده است! برنامه C++‎ شما برای استفاده از Google Mobile Ads C++ SDK بدون هیچ سرویس Firebase دیگری پیکربندی شده است.

پیکربندی شناسه برنامه AdMob برنامه‌تان

Android

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

iOS

مرحله به‌روزرسانی Info.plist را همان‌طور که در راهنمای iOS کیت توسعه نرم‌افزار آگهی‌های تلفن همراه شرح داده شده است دنبال کنید و سپس به این صفحه برگردید.

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

قبل‌از بار کردن آگهی‌ها، از برنامه‌تان بخواهید کیت توسعه نرم‌افزار Google Mobile Ads C++‎ را با فراخوانی firebase::gma::Initialize() مقداردهی اولیه کند. این کار کیت توسعه نرم‌افزار را مقداردهی اولیه می‌کند و پس‌از تکمیل مقداردهی اولیه (یا پس‌از وقفه ۳۰ ثانیه‌ای) firebase::Future را تکمیل می‌کند. این کار فقط یک‌بار باید انجام شود، ترجیحاً هنگام راه‌اندازی برنامه.

آگهی‌ها ممکن است توسط کیت توسعه نرم‌افزار تبلیغات تلفن همراه Google ++C یا کیت‌های توسعه نرم‌افزار شریک میانجی هنگام فراخوانی Initialize() پیش‌بارگیری شوند. اگر لازم است از کاربران ساکن «منطقه اقتصادی اروپا» (EEA) رضایت بگیرید، پرچم‌های خاص درخواست (مانند tag_for_child_directed_treatment یا tag_for_under_age_of_consent) را تنظیم کنید، یا قبل‌از بار کردن آگهی‌ها اقدام دیگری انجام دهید، حتماً این کار را با فراخوانی firebase::gma::SetRequestConfiguration() قبل‌از مقداردهی اولیه Google Mobile Ads C++ SDK انجام دهید. برای اطلاعات بیشتر، راهنمای هدف‌یابی ما را ببینید.

در اینجا مثالی از نحوه فراخوانی 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.
  }
}

انتخاب قالب آگهی

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

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

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

بینابینی

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

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

پاداش

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

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