بدء استخدام 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 من علامة التبويب عمليات الدمج ضمن > إعدادات المشروع.

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

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

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

    2. سجِّل كل إصدار من إصدارات تطبيقك على كل منصة في AdMob. تؤدي هذه الخطوة إلى إنشاء تطبيق 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، نزِّل حزمة 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():

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

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

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

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

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

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

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

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

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

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