البدء

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

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

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

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

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

Android

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

iOS

  • استخدام Xcode 13 أو إصدار أحدث
  • استهداف iOS 10.0 أو إصدار أحدث

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

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

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

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

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

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

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

Android

ننصح باستخدام CMake، ولكن يمكنك العثور على تعليمات حول إنشاء ndk في دليل البدء العام لحزمة تطوير البرامج (SDK) بلغة Firebase 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، أضِف المحتوى التالي الذي يتضمّن تبعية المكتبة لحزمة تطوير البرامج 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

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

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

    sudo gem install cocoapods --pre
    
  2. أضِف مجموعة الإعلانات المتسلسلة الخاصة بإعلانات Google على الأجهزة الجوّالة من حزمة تطوير البرامج (SDK) غير المضغوطة.

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

      cd APP_DIRECTORY
      pod init
      
    2. إلى ملفك Podfile، أضف المجموعات المتسلسلة لحزمة تطوير البرامج C++ لإعلانات Google على الأجهزة الجوّالة، وحزمة SDK لمنصة Google User Messaging Platform، وحزمة SDK الأساسية البسيطة لمنصة Firebase (مطلوبة من خلال حزمة GMA C++ SDK):

      pod 'Firebase/CoreOnly'
      pod 'Google-Mobile-Ads-SDK'
      pod 'GoogleUserMessagingPlatform'
      
    3. ثبِّت مجموعات الإعلانات المتسلسلة، ثم افتح ملف .xcworkspace في Xcode.

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

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

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

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

Android

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

iOS

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

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

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

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

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

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

إعلان بيني

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

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

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

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

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