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

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


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

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

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

قبل البدء

الخطوة 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، ثم فكّ ضغطها في الدليل الذي تختاره.

لا تتوافق حزمة تطوير البرامج (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) للغة 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) الخاصة بتطبيقات ++C في &quot;إعلانات Google على الأجهزة الجوّالة&quot; إلى مشروع iOS.

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

    sudo gem install cocoapods --pre

  2. أضِف حزمة Google Mobile Ads من حزمة تطوير البرامج (SDK) التي تم فك ضغطها.

    1. أنشِئ Podfile في حال عدم توفّره:

      cd YOUR_APP_DIRECTORY
pod init

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

      pod 'Google-Mobile-Ads-SDK'

    3. ثبِّت وحدة pod، ثم افتح الملف .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، تبدأ الحزمة تلقائيًا في تسجيل الأحداث وخصائص المستخدم في &quot;إحصاءات Google&quot; من تطبيقك. ويمكنك الاطّلاع على هذه البيانات بدون إضافة أي رموز إضافية إلى تطبيقك أو تنفيذ أي إعلانات. في ما يلي الأماكن التي يمكنك الاطّلاع فيها على بيانات الإحصاءات هذه:

يُرجى العِلم أنّه لتمثيل مقياسَي متوسط الأرباح من كل مستخدِم ومتوسط الأرباح لكل مستخدِم يدفع رسومًا بشكل أفضل، قد تحتاج إلى تضمين بيانات من حدث مخصّص في "إحصاءات 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 اختبار التغييرات التي تجريها على واجهة المستخدم أو الميزات أو حملات التفاعل في تطبيقك لمعرفة ما إذا كانت تؤثّر في مقاييسك الرئيسية (مثل الإيرادات والاحتفاظ بالمستخدمين) قبل طرح هذه التغييرات على نطاق واسع.