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

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

تعرَّف على جميع مزايا استخدام AdMob وFirebase و"إحصاءات Google" معًا إذا لم تكن قد فعلت ذلك بعد.

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

قبل البدء

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

  • تأكّد من تفعيل "إحصاءات Google" في مشروع Firebase:

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

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

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

  1. سجِّل كل صيغة نظام أساسي لتطبيقك كتطبيق AdMob.

    1. سجّل الدخول أو اشترِك للحصول على حساب AdMob.

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

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

  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 على الأجهزة الجوّالة مضمّنة في مساحة الاسم firebase::gma، يُرجى تنزيل حزمة تطوير البرامج (SDK) الخاصة بـ Firebase C++، ثم فكّ ضغط الحزمة إلى أي دليل من اختيارك.

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

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 على الأجهزة الجوّالة.

    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++ لاستخدام حزمة C++ SDK لإعلانات Google على الأجهزة الجوّالة.

iOS

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

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

    sudo gem install cocoapods --pre

  2. أضِف مجموعة "إعلانات Google على الأجهزة الجوّالة" من حزمة تطوير البرامج (SDK) غير المضغوطة.

    1. أنشئ ملف Podfile إذا لم يكن لديك ملف بالفعل:

      cd YOUR_APP_DIRECTORY
pod init

    2. إلى ملف Podfile، أضِف لوحة SDK الخاصة بحزمة C++ لإعلانات Google على الأجهزة الجوّالة:

      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++ لاستخدام حزمة C++ SDK لإعلانات Google على الأجهزة الجوّالة.

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

قبل تحميل الإعلانات، يجب إعداد حزمة تطوير البرامج (SDK) لعرض الإعلانات على الأجهزة الجوّالة من خلال طلب الرقم 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.

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

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

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

إعلان بيني

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

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

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

تمت المكافأة

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

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

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

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

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

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

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

(اختياري) استخدام المزيد من ميزات "إحصاءات Google" وFirebase

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

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

    لمعرفة المزيد من المعلومات، انتقِل إلى دليل استخدام "إحصاءات Google" وFirebase مع تطبيقات AdMob.

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

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

    • تمكِّنك ميزة الإعداد عن بُعد من تغيير سلوك تطبيقك ومظهره بدون نشر تحديث للتطبيق، وذلك بدون أي تكلفة، وذلك لعدد غير محدود من المستخدمين النشطين يوميًا.

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