بدء استخدام AdMob في مشروع C++

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. زامِن تطبيقك للتأكّد من أنّ جميع مصادر الاعتمادية تتضمّن الإصدارات اللازمة.

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

iOS

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

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

   sudo gem install cocoapods --pre

2. أضِف وحدة Google Mobile Ads من حزمة 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.

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

قبل تحميل الإعلانات، عليك إعداد حزمة SDK Mobile Ads من خلال استدعاء firebase::gma::Initialize().

يستدعي هذا الأمر firebase::Future الذي يكتمل عند انتهاء عملية الإعداد (أو بعد انتهاء مهلة مدتها 30 ثانية). استدعِ هذه الطريقة مرة واحدة فقط وفي أسرع وقت ممكن، ويُفضّل عند تشغيل التطبيق.

في ما يلي مثال على كيفية استدعاء Initialize():

// 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.
}

// 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.
  }
}

الخطوة 5: اختيار شكل إعلان لتنفيذه في تطبيقك

يوفّر AdMob عددًا من أشكال الإعلانات المختلفة، لذا يمكنك اختيار الشكل الذي يناسب تجربة المستخدم في تطبيقك. انقر على زر شكل الإعلان للاطّلاع على تعليمات التنفيذ التفصيلية في مستندات AdMob.

بانر

إعلانات مستطيلة تظهر في أعلى شاشة الجهاز أو أسفلها

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

إعلان بيني

إعلانات بملء الشاشة تغطي واجهة التطبيق إلى أن يغلقها المستخدم

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

تمت المكافأة

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

يمكن أن تساعد الإعلانات التي تمنح مكافآت (أو الإعلانات المستندة إلى المكافأة) في تحقيق الربح من مستخدمي ألعاب المحتوى المجاني.

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

مواضيع أخرى تهمّك

عرض مقاييس سلوك المستخدمين وبيانات الإحصاءات

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

• في بطاقة مقاييس سلوك المستخدمين في حسابك على AdMob (لوحة البيانات الرئيسية أو التطبيقات )، يمكنك عرض مقاييس سلوك المستخدمين المنسّقة المستندة إلى بيانات الإحصاءات التي تم جمعها، مثل متوسط مدة الجلسة، متوسط الإيرادات من كل مستخدم، والاحتفاظ بالمستخدمين.

• في لوحة بيانات الإحصاءات في وحدة تحكّم Firebase، يمكنك عرض الإحصاءات المجمّعة وملخّصات المقاييس الرئيسية. إذا أضفت حزمة تطوير البرامج (SDK) لخدمة Google Analytics، يمكنك أيضًا تحديد الإحالات الناجحة للحملات الإعلانية و إنشاء شرائح جمهور مخصّصة في وحدة تحكّم Firebase.

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

(اختياري) استخدام المزيد من ميزات Google Analytics وFirebase

استفِد من المزيد من الفرص والميزات لتحسين تحقيق الربح من التطبيقات وتعزيز تفاعل المستخدمين:

• إضافة حزمة تطوير البرامج (SDK) لبرنامج Firebase واستخدامهاGoogle Analytics

  • تنفيذ تسجيل الأحداث المخصّصة في تطبيقك

  • تحديد الإحالات الناجحة للحملات الإعلانية المخصّصة custom ad campaigns.

  • تضمين بيانات حدث ecommerce_purchase في عملية احتساب الإيرادات لمقياسَي متوسط الإيرادات من كل مستخدم ومتوسط الإيرادات لكل مستخدم يدفع رسومًا

  لمزيد من المعلومات، يُرجى الانتقال إلى دليل استخدام Google Analytics وFirebase مع تطبيقات AdMob.

• استخدام منتجات Firebase الأخرى في تطبيقك

  بعد إضافة حزمة تطوير البرامج (SDK) لخدمة Google Analytics، استخدِم منتجات Firebase الأخرى لتحسين الإعلانات في تطبيقك.

  • Remote Config تتيح لك تغيير طريقة عمل تطبيقك ومظهره بدون نشر تحديث للتطبيق، وبدون أي تكلفة، لعدد غير محدود من المستخدمين النشطين يوميًا.

  • A/B Testing يمنحك إمكانية اختبار تغييرات واجهة مستخدم تطبيقك أو ميزاته أو حملات التفاعل لمعرفة ما إذا كانت تؤثر في مقاييسك الرئيسية (مثل الإيرادات والاحتفاظ بالمستخدمين) قبل طرح التغييرات على نطاق واسع.