البدء


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

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

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

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

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

Android

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

iOS

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

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

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

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

  2. تسجيل تطبيقك في AdMob تؤدي هذه الخطوة إلى إنشاء تطبيق على AdMob باستخدام معرّف تطبيق AdMob فريد، وهو أمر ضروري في وقت لاحق من هذا الدليل.

تثبيت حزمة تطوير البرامج (SDK) للغة C++‎ في "إعلانات Google على الأجهزة الجوّالة"

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

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

Android

ننصحك باستخدام CMake، ولكن يمكنك العثور على تعليمات حول ndk-build في دليل بدء استخدام حزمة تطوير البرامج (SDK) بلغة C++ من Firebase العام لربط 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) للغة C++ من "إعلانات Google على الأجهزة الجوّالة".

    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) للغة C++ من "إعلانات Google على الأجهزة الجوّالة" إلى مشروع iOS.

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

    sudo gem install cocoapods --pre

  2. أضِف وحدة Google Mobile Ads من حزمة SDK التي تم فك ضغطها.

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

      cd APP_DIRECTORY
pod init

    2. أضِف إلى ملف Podfile حِزم Google Mobile Ads C++ SDK وGoogle User Messaging Platform SDK وFirebase Core SDK الحدّ الأدنى (المطلوب من خلال حزمة Google Mobile Ads C++ SDK):

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

    3. ثبِّت حِزم pods، ثم افتح الملف .xcworkspace في Xcode.

      pod install
open APP.xcworkspace

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

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

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

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

Android

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

iOS

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

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

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

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

في ما يلي مثال على كيفية استدعاء 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.
  }
}

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

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

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

عرض إعلانات البانر

إعلان بيني

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

عرض الإعلانات البينية

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

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

عرض الإعلانات مقابل مكافآت