البدء

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

هذا الدليل مُخصَّص للناشرين الذين يرغبون في تحقيق دخل من تطبيق C++ باستخدام AdMob ولا يستخدمون Firebase. إذا كنت تخطط لتضمين Firebase في تطبيقك (أو تفكر في ذلك)، راجع إصدار AdMob مع Firebase من هذا الدليل.

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

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

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

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

Android

  • استخدام Android Studio 3.2 أو إصدار أحدث
  • تأكد من أن ملف إصدار تطبيقك يستخدم القيم التالية:
    • 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، يُرجى تنزيل حزمة Firebase C++ SDK، ثم فك ضغطها إلى دليل من اختيارك.

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

Android

  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)، أضف المحتوى التالي، والذي يتضمن تبعية المكتبة لـ 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++ لاستخدام SDK لإعلانات Google على الجوال C++ بدون أي خدمات Firebase أخرى.

iOS

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

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

    sudo gem install cocoapods --pre
    
  2. أضف لوحة إعلانات Google للجوّال من حزمة SDK غير المضغوطة.

    1. أنشئ ملف Podfile إذا لم يكن لديك واحد بالفعل:

      cd your-app-directory
      pod init
      
    2. إلى ملف Podfile، أضف المجموعة لحزمة SDK لإعلانات Google على الجوال C++:

        pod 'Google-Mobile-Ads-SDK'
      
    3. ثبِّت اللوحة، ثم افتح ملف .xcworkspace في Xcode.

      pod install
      open your-app.xcworkspace
      
    4. إضافة أُطر العمل التالية من Firebase C++ SDK إلى المشروع:

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

اكتملت العملية تمت تهيئة تطبيق C++ لاستخدام SDK لإعلانات Google على الجوال C++ بدون أي خدمات Firebase أخرى.

تهيئة رقم تعريف تطبيق AdMob لتطبيقك

Android

اتبع الخطوة 3 من تهيئة تطبيقك كما هو موضح في دليل Android لإعلانات SDK للجوّال ثم ارجع إلى صفحة الخطوات الأولى في C++.

iOS

اتبع خطوة تحديث Info.plist كما هو موضح في دليل iOS لإعلانات الجوّال ثم ارجع إلى صفحة الخطوات الأولى C++.

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

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

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

إعلان بيني

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

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

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

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

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