البدء

هذا الدليل مخصص للناشرين الذين يريدون تحقيق الربح من تطبيق 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

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

iOS

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

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

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

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

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

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

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

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

Android

نوصي باستخدام CMake، ولكن يمكنك العثور على تعليمات حول إنشاء ndk في دليل بدء استخدام حزمة 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 لإعلانات 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. يمكنك مزامنة تطبيقك للتأكّد من توفّر الإصدارات اللازمة على جميع الارتباطات.

iOS

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

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

    sudo gem install cocoapods --pre

  2. أضِف مجموعة إعلانات Google للأجهزة الجوّالة من حزمة تطوير البرامج (SDK) التي تم فك ضغطها.

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

      cd APP_DIRECTORY
pod init

    2. إلى Podfile، أضِف المجموعة لحزمة SDK لإعلانات Google على الأجهزة الجوّالة C++:

      pod 'Google-Mobile-Ads-SDK'

    3. ثبِّت مجموعة الإعلانات المتسلسلة، ثم افتح الملف .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

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

iOS

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

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

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

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

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

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

إعلان بيني

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

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

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

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

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