‏‫الخطوات الأولى


هذا الدليل مخصّص للناشرين الذين يريدون تحقيق الربح من تطبيق C++ باستخدام AdMob بدون استخدام Firebase. إذا كنت تخطّط لإدراج Firebase في تطبيقك أو إذا كنت تتمثّل في التفكير في ذلك، يمكنك الاطّلاع على إصدار AdMob مع Firebase من هذا الدليل بدلاً من ذلك.

يُعدّ دمج حزمة "SDK لإعلانات Google على الأجهزة الجوّالة" بتنسيق C++ في أحد التطبيقات الخطوة الأولى نحو عرض الإعلانات وتحقيق الأرباح. بعد دمج حزمة SDK، يمكنك اختيار شكل إعلان، مثل الإعلان البيني أو الإعلان الذي يضم مكافأة، واتّباع الخطوات اللازمة لتنفيذه.

تُغلِّف حزمة SDK لإعلانات Google على الأجهزة الجوّالة باستخدام C++ حِزم SDK لإعلانات Google على الأجهزة الجوّالة لنظامَي التشغيل iOS وAndroid، ولا تتوفّر إلا على هذين النظامَين الأساسيَين. تستخدِم حزمة تطوير البرامج (SDK) لـ "إعلانات Google" لنظام التشغيل C++ إنشاءات Firebase C++ لتفعيل العمليات غير المتزامنة، لذا فهي تقع في مساحة الاسم firebase::gma.

إذا كانت هذه هي المرة الأولى التي تطّلع فيها على هذا الدليل، ننصحك بتحميل تطبيق اختبار "إعلانات Google للأجهزة الجوّالة" المكتوب بلغة C++ واتّباع الخطوات الواردة فيه.

المتطلبات الأساسية

Android

  • استخدام الإصدار 3.2 من "استوديو Android" أو إصدار أحدث
  • تأكَّد من أنّ ملف إنشاء تطبيقك يستخدم القيم التالية:
    • ‫minSdkVersion بسعة 16 عامًا أو أكثر
    • ‫compileSdkVersion‏ 28 أو أعلى

iOS

  • استخدام Xcode 13 أو إصدار أحدث
  • استهداف الإصدار 10.0 من نظام التشغيل iOS أو إصدار أحدث

إعداد تطبيقك في حسابك على AdMob

سجِّل تطبيقك كتطبيق AdMob من خلال إكمال الخطوات التالية:

  1. سجِّل الدخول إلى حسابك على AdMob أو اشترِك فيه.

  2. سجِّل تطبيقك في AdMob. تنشئ هذه الخطوة معرّفًا فريدًا لتطبيق AdMob يلزم استخدامه لاحقًا في هذا الدليل.

تثبيت حزمة تطوير البرامج لإعلانات Google على الأجهزة الجوّالة باستخدام لغة C++

بما أنّ حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة بلغة C++ تقع في مساحة الاسم firebase::gma، نزِّل حزمة تطوير البرامج (SDK) لبرنامج Firebase بلغة C++، ثم فك ضغطها في دليل من اختيارك.

لا تقتصر حزمة تطوير البرامج (SDK) لنظام C++ من Firebase على نظام أساسي معيّن، ولكنها تتطلّب إعدادات مكتبة خاصة بالنظام الأساسي.

Android

ننصحك باستخدام CMake، ولكن يمكنك العثور على تعليمات لاستخدام ndk-build في دليل البدء المشترَك لـ Firebase C++ SDK لمحاولة ربط libfirebase_app.a وlibfirebase_gma.a بتطبيقك.

  1. في ملف gradle.properties الخاص بمشروعك، حدِّد موقع حزمة SDK المفكَّكة:

    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، المحتوى التالي الذي يتضمّن الاعتمادية على المكتبة لحزمة تطوير البرامج (SDK) لإعلانات 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. مزامنة تطبيقك للتأكّد من توفّر الإصدارات اللازمة لجميع التبعيات

iOS

تشكّل الخطوات الواردة في هذا القسم مثالاً على كيفية إضافة حزمة تطوير البرامج (SDK) لإعلانات Google C++ إلى مشروعك على نظام التشغيل iOS.

  1. يمكنك الحصول على الإصدار 1 من CocoaPods أو إصدار أحدث من خلال تشغيل:

    sudo gem install cocoapods --pre

  2. أضِف مجموعة "إعلانات Google على الأجهزة الجوّالة" من حزمة SDK غير المضغوطة.

    1. أنشئ Podfile في حال عدم توفّر ملف:

      cd APP_DIRECTORY
pod init

    2. أضِف إلى Podfile وحدات Pod لحزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة (C++) و حزمة تطوير البرامج (SDK) لمنصّة Google لمراسلة المستخدمين والحزمة الأساسية لحزمة تطوير البرامج (SDK) لمنصّة Firebase (وهي مطلوبة لحزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة (C++)):

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

    3. ثبِّت وحدات pod، ثم افتح ملف .xcworkspace في Xcode.

      pod install
open APP.xcworkspace

    4. أضِف الإطارات التالية من حزمة تطوير البرامج (SDK) لمنصّة Firebase C++ إلى المشروع:

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

إذًا أنت على أتمّ استعداد. تم ضبط تطبيقك المكتوب بلغة C++ لاستخدام حزمة تطوير البرامج (SDK) لإعلانات Google للأجهزة الجوّالة المكتوبة بلغة C++ بدون أي خدمات أخرى من Firebase.

ضبط رقم تعريف تطبيق AdMob لتطبيقك

Android

اتّبِع الخطوة 3 من ضبط إعدادات تطبيقك على النحو الموضّح في دليل حزمة SDK لإعلانات Google على الأجهزة الجوّالة لنظام التشغيل Android ثم ارجع إلى هذه الصفحة.

iOS

اتّبِع خطوة تعديل ملف Info.plist كما هو موضّح في دليل حزمة تطوير البرامج (SDK) لإعلانات الأجهزة الجوّالة لنظام التشغيل iOS، ثم عُد مجددًا إلى هذه الصفحة.

إعداد حزمة "SDK لإعلانات Google على الأجهزة الجوّالة"

قبل تحميل الإعلانات، اطلب من تطبيقك إعداد حزمة تطوير برامج "SDK لإعلانات Google على الأجهزة الجوّالة" باستخدام لغة C++ من خلال استدعاء firebase::gma::Initialize() الذي يعدّل حزمة SDK ويُكمل firebase::Future بعد اكتمال عملية الإعداد (أو بعد firebase::Future وقت انتظار مدته 30 ثانية). يجب إجراء ذلك مرة واحدة فقط، ويُفضّل إجراء ذلك عند تشغيل التطبيق.

قد يتم تحميل الإعلانات مسبقًا باستخدام حزمة SDK لإعلانات Google على الأجهزة الجوّالة المكتوبة بلغة C++ أو حِزم SDK لشركاء التوسّط عند استدعاء Initialize(). إذا كنت بحاجة إلى الحصول على موافقة من المستخدِمين في المنطقة الاقتصادية الأوروبية (EEA)، عليك ضبط أيّ علامات خاصة بالطلب (مثل tag_for_child_directed_treatment أو tag_for_under_age_of_consent) أو اتّخاذ إجراء آخر قبل تحميل الإعلانات، وتأكّد من إجراء ذلك من خلال استدعاء firebase::gma::SetRequestConfiguration() قبل إعداد حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة باستخدام لغة C++. لمزيد من المعلومات، يُرجى الاطّلاع على دليل الاستهداف.

في ما يلي مثال على كيفية الاتصال بالرقم 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. في بعض الحالات، سيتم تشغيل دالة الاستدعاء في سلسلة محادثات مختلفة، لذا تأكَّد من أنّ رمزك آمن في سلسلة المحادثات. يستخدم مقتطف الرمز البرمجي هذا مؤشر دالة لسلسلة الرسائل المرسَلة إلى دالة callback:

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

اختيار شكل الإعلان

تم الآن استيراد حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة باستخدام لغة C++، وأصبحت مستعدًا لتطبيق إعلان. توفّر AdMob عددًا من أشكال الإعلانات المختلفة، ما يتيح لك اختيار الشكل الذي يليه أنسب تجربة للمستخدِم في تطبيقك.

إعلانات مستطيلة تظهر في أعلى أو أسفل شاشة الجهاز تبقى إعلانات البانر معروضة على الشاشة أثناء تفاعل المستخدمين مع التطبيق، ويمكن إعادة تحميلها تلقائيًا بعد فترة زمنية معيّنة. إذا كنت مبتدئًا في مجال الإعلانات على الأجهزة المتحرّكة، يمكنك البدء باستخدام هذه الإعلانات.

تنفيذ إعلانات البانر

إعلان بيني

الإعلانات التي تظهر بملء الشاشة وتغطي واجهة التطبيق إلى أن يغلقها المستخدم ومن الأفضل استخدامها في فواصل عرض طبيعية خلال مسار تنفيذ التطبيق، مثلاً بين مستويات لعبة أو بعد إكمال مهمة مباشرةً.

تنفيذ الإعلانات البينية

تم منح المكافأة

هي إعلانات تكافئ المستخدمين على مشاهدة فيديوهات قصيرة وتفاعلهم مع إعلانات تشغيل إصدار بسيط من اللعبة ومع الاستطلاعات. تُستخدَم لتحقيق الربح من التطبيقات المجانية.

تنفيذ الإعلانات التي تضم مكافأة