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

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


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

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

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

قبل البدء

  • إذا لم يكن لديك مشروع Firebase وتطبيق 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) الخاصة بتطبيقات ++C في Firebase، ثم فك ضغطها في دليل من اختيارك.

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

اكتملت عملية الإعداد. تم ضبط تطبيق 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. ثبِّت pod، ثم افتح ملف .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():

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.

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

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

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

إعلان بيني

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

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

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

تمت المكافأة

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

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

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

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

استكشِف طرقًا إضافية لقياس المقاييس ودمج ميزات Firebase مع AdMob.

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

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

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

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

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

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

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

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

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

    • تتيح لك ميزة Remote Config تغيير طريقة عمل تطبيقك ومظهره بدون الحاجة إلى نشر تحديث للتطبيق.

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