البدء


هذا الدليل مخصّص للناشرين الذين يريدون تحقيق الربح من تطبيق 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 يتضمّن معرّف تطبيق على AdMob فريدًا، وهو معرّف مطلوب لاحقًا في هذا الدليل.

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

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

لا تتوافق حزمة تطوير البرامج (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) للغة 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 الأساسية البسيطة (التي تتطلّبها حزمة GMA 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) لـ "إعلانات Google على الأجهزة الجوّالة" الخاصة بتطبيقات ++C بدون أي خدمات أخرى من Firebase.

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

Android

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

iOS

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

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

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

قد يتم التحميل المُسبَق للإعلانات من خلال حزمة "SDK لإعلانات Google على الأجهزة الجوّالة" الخاصة بتطبيقات C++‎ أو حِزم SDK الخاصة بشركاء التوسّط عند طلب Initialize(). إذا كنت بحاجة إلى الحصول على موافقة المستخدمين في المنطقة الاقتصادية الأوروبية، أو ضبط أي علامات خاصة بالطلبات (مثل 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. في بعض الحالات، سيتم تشغيل دالة الرجوع في سلسلة محادثات مختلفة، لذا تأكَّد من أنّ الرمز البرمجي آمن للاستخدام في سلاسل المحادثات. يستخدم مقتطف الرمز هذا مؤشر دالة لإجراء معاودة الاتصال:

// 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 عددًا من أشكال الإعلانات المختلفة، ما يتيح لك اختيار الشكل الأنسب لتجربة المستخدم في تطبيقك.

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

استخدام "إعلانات البانر"

إعلان بيني

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

استخدام الإعلانات البينية

تمت المكافأة

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

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