البدء

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

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

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

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

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

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 على الأجهزة الجوّالة ++

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

إنّ حزمة تطوير البرامج (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. إلى ملف Grala الخاص بالوحدة (على مستوى التطبيق) (عادةً 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. يجب مزامنة التطبيق لضمان توفّر الإصدارات اللازمة في جميع المهام التابعة.

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

iOS

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

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

    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. أضِف أُطر العمل التالية من حزمة تطوير البرامج (SDK) الخاصة بمنصة Firebase C++ إلى المشروع:

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

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

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

Android

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

iOS

اتّبِع خطوة تعديل ملف Info.plist كما هو موضّح في دليل حزمة تطوير البرامج (SDK) لإعلانات الأجهزة الجوّالة، ثم ارجع إلى صفحة بدء استخدام +C.

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

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

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

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

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

إعلان بيني

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

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

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

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

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