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


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

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

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

قبل البدء

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

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

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

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

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

  1. سجِّل كل إصدار من تطبيقك المتوافق مع نظام أساسي معيّن كتطبيق AdMob.

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

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

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

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

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

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

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

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

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

الخطوة 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، نزِّل حزمة تطوير البرامج (SDK) لبرنامج Firebase بلغة C++، ثم فك ضغطها في دليل من اختيارك.

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

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. أضِف الإطارات التالية من حزمة تطوير البرامج (SDK) لمنصّة Firebase C++ إلى المشروع:

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

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

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

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

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

في ما يلي مثال على كيفية الاتصال بالرقم 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.
  }
}

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

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

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

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

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

إعلان بيني

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

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

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

تمت المكافأة

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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