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

ننصحك باستخدام حزمتَي SDK لـ iOS و Android من AdMob.

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

إذا لم تكن قد فعلت ذلك بعد، فتعرّف على كل مزايا استخدام AdMob وFirebase وGoogle Analytics معًا.

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

قبل البدء

• إذا لم يكن لديك مشروع وتطبيق على Firebase، اتّبِع دليل بدء استخدام Firebase: إضافة Firebase إلى مشروع C++‎.

• تأكَّد من تفعيل Google Analytics في مشروع Firebase:

  • إذا كنت بصدد إنشاء مشروع جديد في Firebase، فعِّل Google Analytics أثناء خطوات إنشاء المشروع.

  • إذا كان لديك مشروع حالي على Firebase لم يتمّ تفعيل Google Analytics فيه، يمكنك تفعيل Google Analytics من علامة التبويب عمليات الدمج ضمن settings > إعدادات المشروع.

الخطوة 1: إعداد تطبيقك في حسابك على AdMob

1. سجِّل كل إصدار من إصدارات تطبيقك على كل منصة كتطبيق على AdMob.

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

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

   سيُطلب منك إضافة حزمة SDK Mobile Ads إلى تطبيقك. يمكنك الاطّلاع على تعليمات مفصّلة لهذه المهمة لاحقًا في هذا الدليل.

2. اربط كل تطبيق من تطبيقاتك على AdMob بتطبيق Firebase المقابل.

   هذه الخطوة اختيارية ولكن يُنصح بها بشدة. مزيد من المعلومات عن الـ مزايا لتفعيل مقاييس سلوك المستخدمين وربط تطبيقاتك AdMob بمنصة Firebase

   لكل إصدار من إصدارات التطبيق على كل منصة، أكمل الخطوتَين التاليتَين في لوحة بيانات التطبيقات في حسابك على AdMob:

   1. فعِّل مقاييس سلوك المستخدمين للسماح لـ AdMob بمعالجة بيانات الإحصاءات المنسّقة وعرضها في حسابك على AdMob. هذا الإعداد مطلوب أيضًا لربط تطبيقك على AdMob بمنصة Firebase.

   2. اربط تطبيقك AdMob بمشروع Firebase الحالي وتطبيق Firebase المقابل.

      تأكَّد من إدخال اسم الحزمة (Android) أو رقم تعريف الحزمة (iOS) نفسه الذي أدخلته لتطبيق Firebase. يمكنك العثور على اسم الحزمة أو رقم تعريف الحزمة لتطبيق Firebase في بطاقة تطبيقاتك ضمن settings > إعدادات المشروع.

الخطوة 2: إضافة معرّف AdMob تطبيقك إلى تطبيقك

Android

أضِف معرّف تطبيقك AdMob إلى ملف AndroidManifest.xml في تطبيقك عن طريق إضافة علامة <meta-data> كما هو موضّح أدناه.

<manifest>
    <application>
        <!-- Sample AdMob App ID: ca-app-pub-3940256099942544~3347511713 -->
        <meta-data
            android:name="com.google.android.gms.ads.APPLICATION_ID"
            android:value="ADMOB_APP_ID"/>
    </application>
</manifest>

iOS

في ملف Info.plist في تطبيقك، أضِف مفتاح GADApplicationIdentifier بقيمة سلسلة تمثّل معرّف تطبيقك AdMob.

يمكنك إجراء هذا التغيير آليًا:

<!-- Sample AdMob App ID: ca-app-pub-3940256099942544~1458002511 -->
<key>GADApplicationIdentifier</key>
<string>ADMOB_APP_ID</string>

أو يمكنك تعديله في محرر قائمة الخصائص:

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

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

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

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. أضِف المحتوى التالي إلى ملف 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.

بانر

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

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

إعلان بيني

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

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

تمت المكافأة

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  • تضمين بيانات الأحداث ecommerce_purchase في احتساب الإيرادات لمقياسَي متوسط الأرباح من كل مستخدم (ARPU) ومتوسط الإيرادات لكل مستخدم يدفع رسومًا (ARPPU).

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

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

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

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

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