البدء


هذا الدليل مخصّص للناشرين الذين يريدون تحقيق الربح من تطبيق 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 Mobile Ads C++‎ التجريبي واتّباع التعليمات الواردة فيه.

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

Android

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

iOS

  • استخدام الإصدار 13 من Xcode أو إصدار أحدث
  • استهداف الإصدار 10.0 من نظام التشغيل iOS أو إصدار أحدث

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

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

  1. سجِّل الدخول إلى حسابك على AdMob أو أنشئ حسابًا.

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

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

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

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

Android

ننصحك باستخدام CMake، ولكن يمكنك العثور على تعليمات ndk-build في دليل البدء العام لحزمة تطوير البرامج (SDK) لبرنامج Firebase C++‎ لربط 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++‎ من "SDK لإعلانات Google على الأجهزة الجوّالة" إلى مشروعك على iOS.

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

    sudo gem install cocoapods --pre

  2. أضِف مجموعة إعلانات متسلسلة من "SDK لإعلانات Google على الأجهزة الجوّالة" من حزمة SDK التي تم فك ضغطها.

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

      cd APP_DIRECTORY
pod init

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

      pod 'Firebase/CoreOnly'
pod 'Google-Mobile-Ads-SDK'
pod 'GoogleUserMessagingPlatform'

    3. ثبِّت مجموعات Pods، ثم افتح ملف .xcworkspace في Xcode.

      pod install
open APP.xcworkspace

    4. أضِف إطارات العمل التالية من حزمة Firebase C++ SDK إلى المشروع:

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

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

ضبط معرّف تطبيق يستخدم AdMob الخاص بتطبيقك

Android

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

iOS

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

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

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

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

إعلان بيني

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

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

تمت المكافأة

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

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